This project's class hierarchy.

Usually, just a redirect to the Project's class hierarchy or the default class hierarchy.

Enables matching of DomainValues that are array values.

Creates a non-null object that represent a ArithmeticException and that has the given origin. If the ArithmeticException was created by the VM while evaluating an instruction with the program counter pc you use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Creates a non-null object that represent a ArrayIndexOutOfBoundsException and that has the given origin. If the ArrayIndexOutOfBoundsException was created by the VM while evaluating an instruction with the program counter pc you use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Creates a non-null object that represent a ArrayStoreException and that has the given origin. If the ArrayStoreException was created by the VM while evaluating an instruction with the program counter pc you use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Creates a new DomainValue that represents an array value with unknown values and where the specified type may also just be an upper type bound (unless the component type is a primitive type or an array of primitives.)

Typical Usage

This factory method is (typically) used to create a domain value that represents an array if we know nothing specific about the array. E.g., if you want to analyze a method that takes an array as a parameter.

Summary

The properties of the value are:

• Type: Upper Bound (unless the elementType is a base type)
• Null: Unknown
• Size: Unknown
• Content: Unknown

Creates a non-null object that represent a ClassCastException and that has the given origin. If the ClassCastException was created by the VM while evaluating an instruction with the program counter pc you use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Factory method to create a DomainValue that represents a runtime value of type "Class<T>" and that was created by the instruction with the specified program counter.

This function is called by OPAL when a class constant (LDC(_W) instruction) is put on the stack.

The domain may ignore the information about the value and the origin (vo).

Summary

The properties of the domain value are:

• Initialized: Yes and the type represented by the class is the given type.
• Type: java.lang.Class<t:Type>
• Null: No

The class tag can be used to create type safe arrays or to extract the concrete type of the domain value.

val DomainReferenceValue(v) = value // of type "DomainValue"
// v is now of the type DomainReferenceValue

The class tag for the type DomainValue.

Required to generate instances of arrays in which values of type DomainValue can be stored in a type-safe manner.

Initialization

In the sub-trait or class that fixes the type of DomainValue it is necessary to implement this abstract val using:

val DomainValueTag : ClassTag[DomainValue] = implicitly

(As of Scala 2.10 it is necessary that you do not use implicit in the subclass - it will compile, but fail at runtime.)

Creates a non-null object that represent an IllegalMonitorStateException and that has the given origin. If the IllegalMonitorStateException was created by the VM while evaluating an instruction with the program counter pc you should use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Creates a domain value from the given value information that represents a properly domain value. A representation of a proper value is created even if the value information is provided for an uninitialized value.

Factory method to create a DomainValue that represents an initialized reference value of the given type and that was created (explicitly or implicitly) by the instruction with the specified program counter.

General Remarks

The given type usually identifies a class type (not an interface type) that is not abstract, but in some cases (e.g. consider java.awt.Toolkit()) it may be useful/meaningful to relax this requirement and to state that the class precisely represents the runtime type – even so the class is abstract. However, such decisions need to be made by the domain.

This method is used by the OPAL framework to create reference values that are normally internally created by the JVM (in particular exceptions such as NullPointerException and ClassCastException). However, it can generally be used to create initialized objects/arrays.

Summary

The properties of the domain value are:

• Initialized: Yes
• Type: precise (i.e., this type is not an upper bound, the type correctly models the runtime type.)
• Null: No (This value is not null.)

The result of the merge of two incompatible values has to be reported as a MetaInformationUpdate[DomainIllegalValue].

Called by the AI framework for each load constant method handle (org.opalj.br.instructions.LoadMethodHandle) instruction to get a representation of/a DomainValue that represents the handle.

Called by the framework for each load constant method type (org.opalj.br.instructions.LoadMethodType) instruction to get a domain-specific representation of the method descriptor as a MethodType.

Creates a non-null object that represent a NegativeArraySizeException and that has the given origin. If the NegativeArraySizeException was created by the VM while evaluating an instruction with the program counter pc you use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

The lengths per dimension are found in the following order: ..., count1, [count2, ...] ->

Factory method to create a new domain value that represents a newly created array (non-null) with the size determined by count that is empty.

Typical Usage

This factory method is (implicitly) used, e.g., by OPAL when a newarray instruction is found.

Summary

The properties of the value are:

• Type: Precise
• Null: No
• Size: Count
• Content: Symbol("Empty")' (i.e., default values w.r.t. to the array's component type)

Creates a new DomainValue that represents a new, uninitialized instance of an object of the given type. The object was created by the (NEW) instruction with the specified program counter.

OPAL calls this method when it evaluates newobject instructions. If the bytecode is valid a call of one of the (super) object's constructors will subsequently initialize the object.

Summary

The properties of the domain value are:

• Initialized: no (only the memory is allocated for the object)
• Type: precise (i.e., this type is not an upper bound, the type correctly models the runtime type.)
• Null: no (This value is not null.)

Represents a non-null reference value with the given type as an upper type bound.

The domain may ignore the information about the value and the origin (vo).

Summary

The properties of the domain value are:

• Initialized: Yes (the constructor was called)
• Type: Upper Bound
• Null: No (This value is not null.)

Creates a non-null object that represent a NullPointerException and that has the given origin. If the NullPointerException was created by the VM while evaluating an instruction with the program counter pc you should use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Factory method to create a DomainValue that represents value null and and that was created (explicitly or implicitly) by the instruction with the specified program counter.

The domain may ignore the information about the value and the origin (pc).

Summary

The properties of the domain value are:

• Initialized: N/A
• Type: Null
• Null: Yes

Factory method to create a DomainValue that represents either an class-/interface value that has the given types as an upper bound or the value null. However, the information whether the value is null or not is not available. Furthermore, the type may also just be an upper bound and it is not known if the value is properly initialized.

Summary

The properties of the domain value are:

• Initialized: Yes (An Object with multiple bounds can only exist due to a merge, in this case, the objects must have been initialized beforehand or the value is not used at all and actually represents a dead variable.)
• Type: Upper Bound
• Null: Unknown
• Content: Unknown

Factory method to create a DomainValue that represents either an class-/interface value that has the given type or the value null. However, the information whether the value is null or not is not available. Furthermore, the type may also just be an upper bound and it is not known if the value is properly initialized.

Summary

The properties of the domain value are:

• Initialized: Unknown (I.e., it is not guaranteed that the constructor was called; unless NewObject was overridden and returns DomainValues that are distinguishable!)
• Type: Upper Bound
• Null: Unknown
• Content: Unknown

Creates an update object that characterizes a reference id update.

Basically, just a wrapper for a MetaInformationUpdate; the purpose is to better communicate the underlying purpose.

Factory method to create a DomainValue that represents either a reference value that has the given type and is initialized or the value null. However, the information whether the value is null or not is not available. Furthermore, the type may also just be an upper bound.

The domain may ignore the information about the value and the origin, but it has to remain possible for the domain to identify the component type of an array.

Summary

The properties of the domain value are:

• Initialized: Yes (if non-null the constructor was called/the array was initialized)
• Type: Upper Bound
• Null: Unknown
• Content: Unknown

Factory method to create an instance of a ReturnAddressValue.

Factory method to create a DomainValue that represents the given string value and that was created by the instruction with the specified program counter.

This function is called by OPAL-AI when a string constant (LDC(_W) instruction) is put on the stack.

The domain may ignore the information about the value and the origin (vo).

Summary

The properties of the domain value are:

• Initialized: Yes and the String's value is the given value. The string may be empty (""), but it is never null.
• Type: java.lang.String
• Null: No

The result of merging two values should never be reported as a StructuralUpdate if the computed value is an IllegalValue. The JVM semantics guarantee that the value will not be used and, hence, continuing the interpretation is meaningless.

The singleton instance of the IllegalValue.

The singleton instance of ReturnAddressValues

Creates a non-null object that represent a Throwable object and that has the given origin. If the Throwable was created by the VM while evaluating an instruction with the program counter pc you should use the method ValueOriginForImmediateVMException to translate that pc to the appropriate ValueOrigin.

Creates a new DomainValue that represents the this value of a constructor before the super constructor is called. Hence, the value origin is necessarily always -1.

OPAL calls this method when it creates the initial locals for constructors.

Summary

The properties of the domain value are:

• Initialized: no (only the memory is allocated for the object)
• Type: upper bound
• Null: no (This value is not null.)

Returns the array's length or throws a NullPointerException if the given reference is null.

Loads the value stored in the array at the given index or throws an exception (NullPointerException or IndexOutOfBoundsException).

Stores the given value in the array at the given index or throws an exception (NullPointerException, ArrayStoreException or IndexOutOfBoundsException).

Returns the given value as a DomainReferenceValue. Basically just performs a type cast and is intended to be used to communicate that the value has to be a reference value (if the underlying byte code is valid.)

Computes the effective upper-type bound which is the (single) final type in the utb if it contains one. In this case the other types have to be in a super-/subtype relation and were added "just" as a result of explicit CHECKCAST instructions.

Iterates over the origin(s) of the given value if the information is available.

Tests if subtype is known to be subtype of supertype. See org.opalj.br.ClassHierarchy's isSubtypeOf method for details.

Determines the common null-ness property of the given reference values.

Determines if the runtime object type referred to by the given values is always the same. I.e., it determines if all values are precise and have the same upperTypeBound.

Null values are ignored when determining the precision; i.e., if all values represent Null true will be returned.

Tests if subtype is known to be subtype of supertype. See org.opalj.br.ClassHierarchy's isSubtypeOf method for details.

Tries to determine – under the assumption that the given value is not null – if the runtime type of the given reference value could be a subtype of the specified reference type supertype. I.e., if the type of the value is not precisely known, then all subtypes of the value's type are also taken into consideration when analyzing the subtype relation and only if we can guarantee that none is a subtype of the given supertype the answer will be No.

Merges two computations that both resulted in at most one DomainValue or at most one ExceptionValue.

If values are merged the merged value will use the specified pc.

Merges two computations that both return some DomainValue and some ExceptionValues. If values are merged the merged value will use the specified pc.

Merges the given domain value v1 with the domain value v2 and returns the merged value which is v1 if v1 is an abstraction of v2, v2 if v2 is an abstraction of v1 or some other value if a new value is computed that abstracts over both values.

This operation is commutative.

Merges two computations that both resulted in at most one ExceptionValue each.

If values are merged the merged value will use the specified pc.

Merges those exceptions that have the same upper type bound. This ensures that per upper type bound only one ValuesDomain.DomainValue (which may be a MultipleReferenceValues) is used. For those values that are merged, the given pc is used.

Creates a multi-dimensional array.

Creates a new array.

Returns the next unused time stamp.

Returns the origin(s) of the given value if the information is available.

Returns the origin(s) of the given value if the information is available.

Returns a string representation of the properties associated with the instruction with the respective program counter.

Associating properties with an instruction and maintaining those properties is, however, at the sole responsibility of the Domain.

This method is predefined to facilitate the development of support tools and is not used by the abstract interpretation framework.

Domains that define (additional) properties should (abstract) override this method and should return a textual representation of the property.

Implementers are expected to "override" this method and to call super.providesOriginInformationFor to make it possible to stack several domain implementations which provide origin information.

Returns Yes if both DomainReferenceValues definitively identify the same object at runtime.

Using this domain, it is in general not possible to determine that two values are definitively not reference equal unless they are type incompatible.

Compares the given values for reference inequality. Returns No if both values point to the same instance and returns Yes if both objects are known not to point to the same instance. The latter is, e.g., trivially the case when both values have a different concrete type. Otherwise Unknown is returned.

If both values are representing the null value the org.opalj.Answer is Yes.

Called by OPAL when two values were compared for reference equality and we are going to analyze the branch where the comparison succeeded.

Called by OPAL when two values were compared for reference equality and we are going to analyze the branch where the comparison failed.

Refines the "null"ness property (isNull == No) of the given value.

Calls refineIsNull on the given ReferenceValue and replaces every occurrence on the stack/in a register with the updated value.

Updates the "null"ness property (isNull == Yes) of the given value.

Calls refineIsNull on the given ReferenceValue and replaces every occurrence on the stack/in a register with the updated value.

Returns Yes if given value is never null, Unknown if the values is maybe null and No otherwise.

Determines the nullness-property of the given value.

Called by the abstract interpreter when the type bound of the top most stack value needs to be refined. This method is only called by the abstract interpreter iff an immediately preceding subtype query (typeOf(value) <: bound) returned Unknown. This method must not be ignored – w.r.t. refining the top-most stack value; it is e.g., used by org.opalj.br.instructions.CHECKCAST instructions.

A domain that is able to identify aliases can use this information to propagate the information to the other aliases.

Sets the is null property of the top-most stack value to Yes. This method is called by the framework when the top-most operand stack value has to be null, but a previous isNull check returned Unknown. E.g., after a org.opalj.br.instructions.CHECKCAST that fails or if a InstanceOf check has succeeded.

This method can be ignored; i.e., the return value can be (operands,locals). However, a domain that tracks alias information can use this information to propagate the information to the other aliases.

Creates a summary of the given domain values by summarizing and joining the given values. For the precise details regarding the calculation of a summary see Value.summarize(...).

Converts – if possible – a given DomainValue to a Java object that is appropriately initialized.

Implementation

Every domain that supports the creation of a Java object's based on a domain value is expected to implement this method and to test if it can create a precise representation of the given value. If not, the implementation has to delegate the responsibility to the super method to creat an abstract representation.

abstract override def toJavaObject(value : DomainValue): Option[Object] = {
 if(value...)
     // create and return Java object
 else
     super.toJavaObject(value)
}

Calculates the most specific common upper type bound of the upper type bounds of all values. NullValues are ignored unless all values are representing Null.

Defines a total order on reference values with a single origin by subtracting both origins.