Packages

  • package root
    Definition Classes
    root
  • package org
    Definition Classes
    root
  • package opalj

    OPAL is a Scala-based framework for the static analysis, manipulation and creation of Java bytecode.

    OPAL is a Scala-based framework for the static analysis, manipulation and creation of Java bytecode. OPAL is designed with performance, scalability and adaptability in mind.

    Its main components are:

    • a library (Common) which provides generally useful data-structures and algorithms for static analyses.
    • a framework for implementing lattice based static analyses (Static Analysis Infrastructure)
    • a framework for parsing Java bytecode (Bytecode Infrastructure) that can be used to create arbitrary representations.
    • a library to create a one-to-one in-memory representation of Java bytecode (Bytecode Disassembler).
    • a library to create a representation of Java bytecode that facilitates writing simple static analyses (Bytecode Representation - org.opalj.br).
    • a scalable, easily customizable framework for the abstract interpretation of Java bytecode (Abstract Interpretation Framework - org.opalj.ai).
    • a library to extract dependencies between code elements and to facilitate checking architecture definitions.
    • a library for the lightweight manipulation and creation of Java bytecode (Bytecode Assembler).

    General Design Decisions

    Thread Safety

    Unless explicitly noted, OPAL is thread safe. I.e., the classes defined by OPAL can be considered to be thread safe unless otherwise stated. (For example, it is possible to read and process class files concurrently without explicit synchronization on the client side.)

    No null Values

    Unless explicitly noted, OPAL does not null values I.e., fields that are accessible will never contain null values and methods will never return null. If a method accepts null as a value for a parameter or returns a null value it is always explicitly documented. In general, the behavior of methods that are passed null values is undefined unless explicitly documented.

    No Typecasts for Collections

    For efficiency reasons, OPAL sometimes uses mutable data-structures internally. After construction time, these data-structures are generally represented using their generic interfaces (e.g., scala.collection.{Set,Map}). However, a downcast (e.g., to add/remove elements) is always forbidden as it would effectively prevent thread-safety.

    Assertions

    OPAL makes heavy use of Scala's Assertion Facility to facilitate writing correct code. Hence, for production builds (after thorough testing(!)) it is highly recommend to build OPAL again using -Xdisable-assertions.

    Definition Classes
    org
  • package ai

    Implementation of an abstract interpretation (ai) framework – also referred to as OPAL.

    Implementation of an abstract interpretation (ai) framework – also referred to as OPAL.

    Please note that OPAL/the abstract interpreter just refers to the classes and traits defined in this package (ai). The classes and traits defined in the sub-packages (in particular in domain) are not considered to be part of the core of OPAL/the abstract interpreter.

    Definition Classes
    opalj
    Note

    This framework assumes that the analyzed bytecode is valid; i.e., the JVM's bytecode verifier would be able to verify the code. Furthermore, load-time errors (e.g., LinkageErrors) are – by default – completely ignored to facilitate the analysis of parts of a project. In general, if the presented bytecode is not valid, the result is undefined (i.e., OPAL may report meaningless results, crash or run indefinitely).

    See also

    org.opalj.ai.AI - Implements the abstract interpreter that processes a methods code and uses an analysis-specific domain to perform the abstract computations.

    org.opalj.ai.Domain - The core interface between the abstract interpretation framework and the abstract domain that is responsible for performing the abstract computations.

  • trait ValuesDomain extends AnyRef

    Defines the concept of a value in a Domain.

    Defines the concept of a value in a Domain.

    Definition Classes
    ai
    See also

    Domain For an explanation of the underlying concepts and ideas.

  • DomainIllegalValue
  • DomainReferenceValue
  • DomainReturnAddressValue
  • DomainReturnAddressValues
  • DomainTypedValue
  • DomainValue
  • IllegalValue
  • RETValue
  • ReferenceValue
  • ReturnAddressValue
  • ReturnAddressValues
  • TypedValue
  • Value

trait Value extends ValueInformation

Abstracts over a concrete operand stack value or a value stored in one of the local variables/registers.

Use Of Value/Dependencies On Value

In general, subclasses and users of a Domain should not have/declare a direct dependency on Value. Instead they should use DomainValue as otherwise extensibility of a Domain may be hampered or even be impossible. The only exceptions are, of course, classes that directly inherit from this class.

Refining Value

If you directly extend/refine this trait (i.e., in a subclass of the Domain trait you write something like trait Value extends super.Value), make sure that you also extend all classes/traits that inherit from this type (this may require a deep mixin composition and that you refine the type DomainType accordingly). However, OPAL was designed such that extending this class should – in general – not be necessary. It may also be easier to encode the desired semantics – as far as possible – as part of the domain.

Implementing Value

Standard inheritance from this trait is always supported and is the primary mechanism to model an abstract domain's lattice w.r.t. some special type of value. In general, the implementation should try to avoid creating new instances of values unless strictly required to model the domain's semantics. This will greatly improve the overall performance as this framework heavily uses reference-based equality checks to speed up the evaluation.

Self Type
DomainValue
Source
ValuesDomain.scala
Note

OPAL does not rely on any special equality semantics w.r.t. values and never directly or indirectly calls a Value's equals method. Hence, a domain can encode equality such that it best fits its need. However, some of the provided domains rely on the following semantics for equals: Two domain values have to be equal (==) iff they represent the same information. This includes additional information, such as, the value of the origin. E.g., a value (AnIntegerValue) that represents an arbitrary Integer value has to return true if the domain value with which it is compared also represents an arbitrary Integer value (AnIntegerValue). However, it may still be necessary to use multiple objects to represent an arbitrary integer value if, e.g., constraints should be attached to specific values. For example, after a comparison of an integer value with a predefined value (e.g., AnIntegerValue < 4) it is possible to constrain the respective value on the subsequent paths (< 4 on one path and >= 4 on the other path). To make that possible, it is however necessary to distinguish the AnIntegervalue from some other AnIntegerValue to avoid constraining unrelated values.

public void foo(int a,int b) {
    if(a < 4) {
        z = a - 2 // here a is constrained (< 4), b and z are unconstrained
    }
    else {
        z = a + 2 // here a is constrained (>= 4), b and z are unconstrained
    }
}

In general, equals is only defined for values belonging to the same domain. If values need to be compared across domains, they need to be adapted to a target domain first.

Linear Supertypes
ValueInformation, AnyRef, Any
Known Subclasses
IllegalValue, RETValue, ReferenceValue, ReturnAddressValue, ReturnAddressValues, TypedValue, DefaultArrayValue, DefaultMObjectValue, DefaultSObjectValue, ADoubleValue, AFloatValue, ABooleanValue, AByteValue, ACharValue, AShortValue, AnIntegerValue, ALongValue, ANullValue, AnArrayValue, AnObjectValue, MObjectValueLike, SObjectValueLike, DefaultArrayValue, DefaultMObjectValue, InitializedObjectValue, UninitializedObjectValue, DoubleValue, FloatValue, BooleanValue, ByteValue, CharValue, ComputationalTypeIntegerValue, IntegerValue, ShortValue, LongValue, ArrayValueLike, NullValueLike, ObjectValueLike, ReferenceValueLike, SReferenceValue, InitializedArrayValue, ClassValue, ConcreteArrayValue, DefaultClassValue, AnIntegerValue, IntegerRange, AnIntegerValue, BaseTypesBasedSet, ByteSet, CharSet, IntegerSet, ShortSet, U15BitSet, U7BitSet, AnIntegerValue, ConcreteIntegerValue, ALongValue, LongSet, ALongValue, ConcreteLongValue, DefaultMObjectValue, DefaultSObjectValue, DefaultStringValue, AnIntegerValueLike, IntegerLikeValue, IntegerRangeLike, AnIntegerValueLike, BaseTypesBasedSetLike, ByteSetLike, CharSetLike, IntegerLikeValue, IntegerSetLike, ShortSetLike, U15BitSetLike, U7BitSetLike, AnIntegerValue, IntegerLikeValue, TheIntegerValue, ALongValueLike, LongSetLike, LongValue, ALongValue, LongValue, TheLongValue, ArrayValue, MObjectValue, MultipleReferenceValues, NonNullSingleOriginReferenceValue, NonNullSingleOriginSReferenceValue, NullValue, ObjectValue, SObjectValue, SingleOriginReferenceValue, TheReferenceValue, StringBuilderValue, StringValue
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Value
  2. ValueInformation
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Abstract Value Members

  1. abstract def computationalType: ComputationalType

    The computational type of the value if this object represents a legal value.

    The computational type of the value if this object represents a legal value.

    The precise computational type is, e.g., needed to calculate the effect of generic stack manipulation instructions (e.g., DUP_... and SWAP) on the stack as well as to calculate the jump targets of RET instructions and to determine which values are actually copied by, e.g., the dup_XX instructions.

    Definition Classes
    ValueInformation
    Exceptions thrown

    IllegalStateException if this value is illegal or void.

    Note

    The computational type has to be precise/correct.

  2. abstract def doJoin(pc: Int, value: DomainValue): Update[DomainValue]

    Joins this value and the given value.

    Joins this value and the given value.

    Join is called whenever an instruction is evaluated more than once and, hence, the values found on the paths need to be joined. This method is, however, only called if the two values are two different objects ((this ne value) === true), but both values have the same computational type.

    This basically implements the join operator of complete lattices.

    Example

    For example, joining a DomainValue that represents the integer value 0 with a DomainValue that represents the integer value 1 may return a new DomainValue that precisely captures the range [0..1] or that captures all positive integer values or just some integer value.

    Contract

    this value is always the value that was previously used to perform subsequent computations/analyses. Hence, if this value subsumes the given value, the result has to be either NoUpdate or a MetaInformationUpdate. In case that the given value subsumes this value, the result has to be a StructuralUpdate with the given value as the new value. Hence, this join operation is not commutative. If a new (more abstract) abstract value is created that represents both values the result always has to be a StructuralUpdate. If the result is a StructuralUpdate the framework will continue with the interpretation.

    The termination of the abstract interpretation directly depends on the fact that at some point all (abstract) values are fixed and don't change anymore. Hence, it is important that the type of the update is only a org.opalj.ai.StructuralUpdate if the value has changed in a way relevant for future computations/analyses involving this value. In other words, when two values are joined it has to be ensured that no fall back to a previous value occurs. E.g., if you join the existing integer value 0 and the given value 1 and the result would be 1, then it must be ensured that a subsequent join with the value 0 will not result in the value 0 again.

    Conceptually, the join of an object with itself has to return the object itself. Note, that this is a conceptual requirement as such a call (this.doJoin(..,this)) will not be performed by the abstract interpretation framework; this case is handled by the join method. However, if the join object is also used by the implementation of the domain itself, it may be necessary to explicitly handle self-joins.

    Performance

    In general, the domain should try to minimize the number of objects that it uses to represent values. That is, two values that are conceptually equal should – whenever possible – use only one object. This has a significant impact on functions such as join.

    pc

    The program counter of the instruction where the paths converge.

    value

    The "new" domain value with which this domain value should be joined. The given value and this value are guaranteed to have the same computational type, but are not reference equal.

    Attributes
    protected[this]
  3. abstract def hasCategory2ComputationalType: Boolean

    Returns true if and only if the value has the computational type 2; false in all other cases (including the case where this value is illegal!).

    Returns true if and only if the value has the computational type 2; false in all other cases (including the case where this value is illegal!).

    Definition Classes
    ValueInformation
  4. abstract def isArrayValue: Answer

    Returns Yes if the value is _not null_ and the least upper type bound is an ArrayType; the value is Unknown if the least upper type bound is ArrayType but the value may be null; in all other cases No is returned; in particular if the value is known to be null.

    Returns Yes if the value is _not null_ and the least upper type bound is an ArrayType; the value is Unknown if the least upper type bound is ArrayType but the value may be null; in all other cases No is returned; in particular if the value is known to be null. No is also returned if the value's type is Object or Seriablizable or Cloneable.

    Definition Classes
    ValueInformation
  5. abstract def isIllegalValue: Boolean

    Returns true iff this value is not a legal value according to the JVM specification.

    Returns true iff this value is not a legal value according to the JVM specification. Such values cannot be used to perform any computations and will generally not occur in static analyses unless the analysis or the bytecode is buggy.

    Definition Classes
    ValueInformation
    Note

    An IsIllegalValue can always be distinguished from a void value.

  6. abstract def isPrimitiveValue: Boolean

    Returns true in case of a value with primitive type.

    Returns true in case of a value with primitive type.

    Definition Classes
    ValueInformation
    Exceptions thrown

    IllegalStateException if this value is illegal.

  7. abstract def isReferenceValue: Boolean

    Returns true if the value has a reference type.

    Returns true if the value has a reference type.

    Definition Classes
    ValueInformation
    Exceptions thrown

    IllegalStateException if this value is illegal.

  8. abstract def isVoid: Boolean

    Returns true if this value represents void.

    Returns true if this value represents void.

    Definition Classes
    ValueInformation
  9. abstract def summarize(pc: Int): DomainValue

    Creates a summary of this value.

    Creates a summary of this value.

    In general, creating a summary of a value may be useful/required for values that are potentially returned by a called method and which will then be used by the calling method. For example, it may be useful to precisely track the flow of values within a method to be able to distinguish between all sources of a value (E.g., to be able to distinguish between a NullPointerException created by instruction A and another one created by instruction B (A != B).)

    However, from the caller perspective it may be absolutely irrelevant where/how the value was created in the called method and, hence, keeping all information would just waste memory and a summary may be sufficient.

    Note

    This method is predefined to facilitate the development of project-wide analyses.

  10. abstract def toCanonicalForm: ValueInformation

    Returns a ValueInformation object that just captures the basic information as defined by this value framework.

    Returns a ValueInformation object that just captures the basic information as defined by this value framework. The returned value information object will be independent of the underlying representation from which it was derived.

    Definition Classes
    ValueInformation
  11. abstract def verificationTypeInfo: VerificationTypeInfo

    The type of this value as used by the org.opalj.br.StackMapTable attribute.

    The type of this value as used by the org.opalj.br.StackMapTable attribute.

    Definition Classes
    ValueInformation
    Exceptions thrown

    IllegalStateException if this value represents void or a return address value.

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def PCIndependent: Int
    Annotations
    @inline()
  5. def abstractsOver(other: DomainValue): Boolean

    Returns true iff the abstract state represented by this value abstracts over the state of the given value.

    Returns true iff the abstract state represented by this value abstracts over the state of the given value. In other words if every possible runtime value represented by the given value is also represented by this value.

    The abstract state generally encompasses every information that would be considered during a join of this value and the other value and that could lead to a true Update.

    This method is reflexive, I.e., every value abstracts over itself.

    TheIllegalValue only abstracts over itself.

    Note

    abstractsOver is only defined for comparable values where both values have the same computational type.

    ,

    The default implementation uses the join method of this domain value. Overriding this method is, hence, primarily meaningful for performance reasons.

    See also

    isMorePreciseThan

  6. def adapt(target: TargetDomain, valueOrigin: Int): (target)#DomainValue

    Adapts this value to the given domain (default: throws a domain exception that adaptation is not supported).

    Adapts this value to the given domain (default: throws a domain exception that adaptation is not supported). This method needs to be overridden by concrete Value classes to support the adaptation for a specific domain.

    Supporting the adapt method is primarily necessary when you want to analyze a method that is called by the currently analyzed method and you need to adapt this domain's values (the actual parameters of the method) to the domain used for analyzing the called method.

    Additionally, the adapt method is OPAL's main mechanism to enable dynamic domain-adaptation. I.e., to make it possible to change the abstract domain at runtime if the analysis time takes too long using a (more) precise domain.

    Annotations
    @throws("Adaptation of this value is not supported.")
    Note

    The abstract interpretation framework does not use/call this method. This method is solely predefined to facilitate the development of project-wide analyses.

  7. def asDomainReferenceValue: DomainReferenceValue

    Returns the represented reference value iff this value represents a reference value.

  8. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  9. def asPrimitiveValue: IsPrimitiveValue[_ <: BaseType]
    Definition Classes
    ValueInformation
  10. def asReferenceValue: IsReferenceValue
    Definition Classes
    ValueInformation
  11. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native() @IntrinsicCandidate()
  12. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  14. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native() @IntrinsicCandidate()
  15. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native() @IntrinsicCandidate()
  16. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  17. def isMorePreciseThan(other: DomainValue): Boolean

    Returns true iff the abstract state represented by this value is strictly more precise than the state of the given value.

    Returns true iff the abstract state represented by this value is strictly more precise than the state of the given value. In other words if every possible runtime value represented by this value is also represented by the given value, but both are not equal; in other words, this method is irreflexive.

    The considered abstract state generally encompasses every information that would be considered during a join of this value and the other value and that could lead to a StructuralUpdate.

    other

    Another DomainValue with the same computational type as this value. (The IllegalValue has no computational type and, hence, a comparison with an IllegalValue is not well defined.)

    Note

    It is recommended to overwrite this method for performance reasons, as the default implementation relies on join.

    See also

    abstractsOver

  18. def join(pc: Int, that: DomainValue): Update[DomainValue]

    Checks that the given value and this value are compatible with regard to its computational type and – if so – calls doJoin.

    Checks that the given value and this value are compatible with regard to its computational type and – if so – calls doJoin.

    See doJoin(PC,DomainValue) for details.

    pc

    The program counter of the instruction where the paths converge or Int.MinValue if the join is done independently of an instruction.

    that

    The "new" domain value with which this domain value should be joined. The caller has to ensure that the given value and this value are guaranteed to be two different objects.

    returns

    MetaInformationUpdateIllegalValue or the result of calling doJoin.

    Note

    It is in general not recommended/needed to override this method.

  19. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @IntrinsicCandidate()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @IntrinsicCandidate()
  22. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  23. def toString(): String
    Definition Classes
    AnyRef → Any
  24. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  25. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  26. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])

Deprecated Value Members

  1. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable]) @Deprecated
    Deprecated

Inherited from ValueInformation

Inherited from AnyRef

Inherited from Any

Ungrouped