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.

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.

The set of base values (IsReferenceValue) this value abstracts over. This set is never empty and contains this value if this value does not (further) abstract over other reference values; otherwise it only contains the base values, but not this value.

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

Returns the type of the upper type bound if the upper type bound contains exactly one element. That is, the function is only always defined iff the type is precise.

In general an IsReferenceValue abstracts over all potential values and this information is sufficient for subsequent analyses; but in some cases, analyzing the set of underlying values may increase the overall precision and this set is returned by this function. In other words: if baseValues is nonEmpty, then the properties returned by this value are derived from the base values, but still maybe more specific. For example,

Object o = _;
if(...) o = f() else o = g();
// when we reach this point, we generally don't know if the values returned by f and g
// are non-null; hence, o is potentially null.
if(o != null)
 // Now, we know that o is not null, but we still don't know if the values returned
 // by f OR g were null and we cannot establish that when we don't know to which value
 // o is actually referring to.
 u(o);

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.

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.

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

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.

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.

If Yes the value is known to always be null at runtime. In this case the upper bound is (has to be) empty. If the answer is Unknown then the analysis was not able to statically determine whether the value is null or is not null. In this case the upper bound is expected to be non-empty. If the answer is No then the value is statically known not to be null. In this case, the upper bound may precisely identify the runtime type or still just identify an upper bound.

Returns true if the type information is precise. I.e., the type returned by upperTypeBound precisely models the runtime type of the value. If, isPrecise returns true, the type of this value can generally be assumed to represent a class type (not an interface type) or an array type. However, this domain also supports the case that isPrecise returns true even though the associated type identifies an interface type or an abstract class type. The later case may be interesting in the context of classes that are generated at run time.

Returns true in case of a value with primitive type.

Returns true if the value has a reference type.

Tests if the type of this value is potentially a subtype of the specified reference type under the assumption that this value is not null. This test takes the precision of the type information into account. That is, if the currently available type information is not precise and the given type has a subtype that is always a subtype of the current upper type bound, then Unknown is returned. Given that it may be computationally intensive to determine whether two types have a common subtype it may be better to just return Unknown in case that this type and the given type are not in a direct inheritance relationship.

Basically, this method implements the same semantics as the ClassHierarchy's isSubtypeOf method, but it additionally checks if the type of this value could be a subtype of the given supertype. I.e., if this value's type identifies a supertype of the given supertype and that type is not known to be precise, the answer is Unknown.

For example, assume that the type of this reference value is java.util.Collection and we know/have to assume that this is only an upper bound. In this case an answer is No if and only if it is impossible that the runtime type is a subtype of the given supertype. This condition holds, for example, for java.io.File which is not a subclass of java.util.Collection and which does not have any further subclasses (in the JDK). I.e., the classes java.io.File and java.util.Collection are not in an inheritance relationship. However, if the specified supertype would be java.util.List the answer would be unknown.

Returns true if this value represents void.

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.

The least upper type bound of the value.

None if and only if the underlying value is null.

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.

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.

The upper bound of the value's type. The upper bound is empty if this value is null (i.e., isNull == Yes). The upper bound is only guaranteed to contain exactly one type if the type is precise. (i.e., isPrecise == true). Otherwise, the upper type bound may contain one or more types that are not known to be in an inheritance relation, but which will correctly approximate the runtime type.

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