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 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.

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

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 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.

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

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.

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.

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

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

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 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 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.

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 multianewarray instruction is found.

Summary

The properties of the value are:

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

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.)

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 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.)

Called by the abstract interpreter when the abstract interpretation of a method has ended. The abstract interpretation of a method ends if either the fixpoint is reached or the interpretation was aborted.

By default this method does nothing.

Domains that override this method are expected to also call super.abstractInterpretationEnded(aiResult).

This method is called after all values which differ have been joined, but before joinPostProcessing will be called.

This methods is called after the evaluation of the instruction with the given pc with respect to targetPC, but before the values are propagated (joined) and before it is checked whether the interpretation needs to be continued. I.e., if the operands (newOperands) or locals (newLocals) are further refined then the refined operands and locals are joined (if necessary).

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.)

This method is called immediately before a join operation with regard to the specified pc is performed.

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.

Called by the framework after evaluating the instruction with the given pc. I.e., the state of all potential successor instructions was updated and the flow method was called – potentially multiple times – accordingly.

By default this method does nothing.

Called by the framework after performing a computation to inform the domain about the result. That is, after evaluating the effect of the instruction with currentPC on the current stack and register and (if necessary) joining the updated stack and registers with the stack and registers associated with the instruction successorPC. (Hence, this method is ONLY called for return instructions if the return instruction throws an IllegalMonitorStateException.) This function basically informs the domain about the instruction that may be evaluated next. The flow function is called for every possible successor of the instruction with currentPC. This includes all branch targets as well as those instructions that handle exceptions.

In some cases it will even be the case that flow is called multiple times with the same pair of program counters: (currentPC, successorPC). This may happen, e.g., in case of a switch instruction where multiple values have the same body/target instruction and we do not have precise information about the switch value. E.g., as in the following snippet:

switch (i) {  // pc: X => Y (for "1"), Y (for "2"), Y (for "3")
case 1:
case 2:
case 3: System.out.println("Great.");            // pc: Y
default: System.out.println("Not So Great.");    // pc: Z
}

The flow function is also called after instructions that are domain independent such as dup and load instructions which just manipulate the registers and stack in a generic way. This enables the domain to precisely follow the evaluation progress and in particular to perform control-flow dependent analyses.

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.

Joins the given operand stacks and local variables.

In general there should be no need to refine this method. Overriding this method should only be done for analysis purposes.

Performance

This method heavily relies on reference comparisons to speed up the overall process of performing an abstract interpretation of a method. Hence, a computation should – whenever possible – return (one of) the original object(s) if that value has the same abstract state as the result. Furthermore, if all original values capture the same abstract state as the result of the computation, the "left" value/the value that was already used in the past should be returned.

Enables the customization of the behavior of the base join method.

This method in particular enables, in case of a MetaInformationUpdate, to raise the update type to force the continuation of the abstract interpretation process.

Methods should always override this method and should call the super method.

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.

This function can be called when the instruction successorPC needs to be scheduled. The function will test if the instruction is already scheduled and – if so – returns the given worklist. Otherwise the instruction is scheduled in the correct (subroutine-)context.

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 the given Java object to a corresponding DomainValue by creating an DomainValue that represents an initialized (array/object) value.

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)
}

Replaces all occurrences of oldValue (using reference-quality) with newValue. If no occurrences are found, the original operands and locals data structures are returned.

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.