Package

org.opalj.ai

domain

Permalink

package domain

This package contains definitions of common domains that can be used for the implementation of analyses.

Types of Domains

In general, we distinguish two types of domains. First, domains that define a general interface (on top of the one defined by Domain), but do not directly provide an implementation. Hence, whenever you develop a new Domain you should consider implementing/using these domains to maximize reusability. Second, Domains that implement a specific interface (trait). In this case, we further distinguish between domains that provide a default implementation (per interface only one of these Domains can be used to create a final Domain) and those that can be stacked and basically refine the overall functionality.

Examples

class MyDomain extends Domain with ...
    with DefaultHandlingOfMethodResults with RecordThrownExceptions

Thread Safety

Unless explicitly documented, a domain is never thread-safe. The general programming model is to use one Domain object per code block/method and therefore, thread-safety is not required for Domains that are used for the evaluation of methods. However domains that are used to adapt/transfer values should be thread safe (see ValuesCoordinatingDomain for further details).

Source
package.scala
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. domain
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. trait AsDomainValue extends AnyRef

    Permalink

    Mixed in by domains that support the conversation of a Java Object into a DomainValue.

    Mixed in by domains that support the conversation of a Java Object into a DomainValue.

    See also

    AsJavaObject for further information on limitations.

  2. trait AsJavaObject extends AnyRef

    Permalink

    Mixed in by domains that support the conversation of a DomainValue into a respective Java object.

    Mixed in by domains that support the conversation of a DomainValue into a respective Java object. This Java object can then be used to perform method invocations.

    Limitation

    Using AsJavaObject will only work reasonably iff the respective class is either in the classpath of the JVM or a class loader (initialized with the project's classpath) is used. The latter, however, does not work for classes on the bootclasspath (e.g., java.lang.String). In that case it is necessary to check that the code of the analyzed application is compatible with the one on the class path. To avoid accidental imprecision in the analysis you should use this features only for stable classes belonging to the core JDK (java.lang....)

  3. trait ConcreteIntegerValues extends AnyRef

    Permalink

    Provides information about an integer value's precise value, if this information is available.

    Provides information about an integer value's precise value, if this information is available.

    Note

    This functionality is not required by the OPAL core.

    ,

    The information about an integer value's range that is required by the abstract interpreter is defined by the Domain trait.

  4. trait ConcreteLongValues extends AnyRef

    Permalink

    Provides information about a long value's precise value, if this information is available.

    Provides information about a long value's precise value, if this information is available.

    Note

    This abstract interpreter never requires knowledge about the precise value of a value with computational type long.

  5. trait ConstantFieldValuesResolution extends Domain

    Permalink

    Resolves references to final static fields that have simple constant values.

    Resolves references to final static fields that have simple constant values.

    Note

    A typical Java compiler automatically resolves all simple references and, hence, this trait has for Java projects in general no effect. If we analyze other languages that compile to the JVM platform, the effect might be different.

  6. trait CurrentCode extends TheCode with CustomInitialization

    Permalink

    Provides information about the code block that is currently analyzed.

    Provides information about the code block that is currently analyzed.

    Core Properties

    • "Automatically reset" when the domain is used to analyze another method.
    • "Concurrent Usage": "No"
  7. trait DefaultDomainValueBinding extends ValuesDomain

    Permalink

    Final binding of a Domain's type DomainValue as well as all subtypes of it that are also defined by Domain.

    Final binding of a Domain's type DomainValue as well as all subtypes of it that are also defined by Domain.

    The type DomainValue is set to the type org.opalj.ai.Domain.Value.

  8. trait DefaultExceptionsFactory extends ExceptionsFactory

    Permalink

    Default implementation of the ExceptionsFactory trait that relies on the ReferenceValuesFactory.

  9. trait DefaultHandlingForReturnInstructions extends ReturnInstructionsDomain

    Permalink

    Provides default implementations for a Domain's return methods that always throw an IllegalMonitorStateExceptoin.

    Provides default implementations for a Domain's return methods that always throw an IllegalMonitorStateExceptoin.

    You can mix in this trait if you are not interested in a method's return values or if you need some default implementations.

  10. trait DefaultHandlingForThrownExceptions extends ReturnInstructionsDomain

    Permalink

    Basic implementation of a Domain's abruptMethodExecution method that does nothing.

    Basic implementation of a Domain's abruptMethodExecution method that does nothing.

    Note

    Mix-in this trait if the analysis does not need to do anything special in case of an exception or if you have multiple stackable traits and you need a base implementation. Example:

    MySpecialDomain
        extends ...
        with DefaultHandlingForThrownExceptions
        with RecordThrownExceptions
        with ...
  11. trait DefaultHandlingOfMethodResults extends DefaultHandlingForThrownExceptions with DefaultHandlingOfVoidReturns with DefaultHandlingForReturnInstructions

    Permalink

    A Domain that does nothing if a method returns ab-/normally.

    A Domain that does nothing if a method returns ab-/normally.

    Note

    This trait's methods are generally not intended to be overridden. If you need to do some special processing just directly implement the respective method and mixin the traits that ignore the rest.

  12. trait DefaultHandlingOfVoidReturns extends ReturnInstructionsDomain

    Permalink

    Basic implementation of a Domains returnVoid method that does nothing.

  13. trait DefaultRecordMethodCallResults extends RecordMethodCallResults with RecordLastReturnedValues with RecordAllThrownExceptions

    Permalink

    Records the results of the evaluation of the current method such that the results can directly be adapted to the calling context and can be used by the caller to continue the abstract interpretation of the calling method.

  14. trait DomainId extends AnyRef

    Permalink

    Common super trait of all domains have an id to identify them.

  15. sealed abstract class DomainValues extends AnyRef

    Permalink

    Encapsulates a domain and some values created by the respective domain.

    Encapsulates a domain and some values created by the respective domain.

    Using the class DomainValues enables type-safety when we need to store and pass on a Domain object and some of its values.

  16. trait GeneralizedArrayHandling extends ReferenceValuesDomain

    Permalink

    This (partial-)domain abstracts over the concrete methods for performing array operations and provides an interface at a higher abstraction level.

  17. trait GlobalLogContextProvider extends LogContextProvider

    Permalink
  18. trait IgnoreSynchronization extends MonitorInstructionsDomain

    Permalink

    Provides a default implementation for the instructions related to synchronization.

  19. case class ImpossibleRefinement(value: AnyRef, refinementGoal: String) extends AIException with Product with Serializable

    Permalink

    Thrown to indicate that a refinement of some value was not possible.

  20. trait LogContextProvider extends AnyRef

    Permalink

    Provides log context information.

  21. trait MethodCallResults extends AnyRef

    Permalink

    Trait that can be mixed in if information is needed about all returned values and the thrown exceptions.

    Trait that can be mixed in if information is needed about all returned values and the thrown exceptions. This information is, however, only available after the evaluation of a method has completed.

  22. trait MethodCallsHandling extends MethodCallsDomain

    Permalink

    Support for handling method invocations.

  23. trait MonitorInstructionsTracker extends MonitorInstructionsDomain with CustomInitialization

    Permalink

    Tracks if a monitor(enter|exit) instruction was executed.

    Tracks if a monitor(enter|exit) instruction was executed.

    This knowledge is of interest to decide, e.g., whether a return instruction may throw an IllegalMonitorStateException or not.

  24. trait Origin extends AnyRef

    Permalink

    Provides information about the origin of a value.

    Provides information about the origin of a value.

    Usage

    To get origin information this trait needs be implemented by a domain. I.e., just mixing in this trait will not provide origin information about values.

    Implementation

    This trait should be inherited from by all domains that make information about the origin of a value available (see org.opalj.ai.domain.l1.ReferenceValues as an example).

  25. trait PerInstructionPostProcessing extends CoreDomainFunctionality

    Permalink

    Provides the generic infrastructure to register a function that updates the operands and locals associated with an instruction that will be evaluated "next".

    Provides the generic infrastructure to register a function that updates the operands and locals associated with an instruction that will be evaluated "next". For example, let's assume that we are currently processing instruction X and that instruction Y is the successor instruction. In this case, the framework will first determine the effect of function X on the stack/locals. After that, all registered updaters will be called. All registered updaters will be discarded as soon the evaluation of instruction X has completed.

  26. trait PostEvaluationMemoryManagement extends CoreDomainFunctionality

    Permalink

    Provides the possibility to further update the memory layout (registers and operands) after the execution of an instruction, but before any potential join is performed.

    Provides the possibility to further update the memory layout (registers and operands) after the execution of an instruction, but before any potential join is performed.

    Note

    If this domain is mixed in then the domain cannot be used to simultaneously analyze multiple different methods at the same time.

  27. trait PredefinedClassHierarchy extends TheClassHierarchy

    Permalink

    This class uses OPAL's preInitializedClassHierarchy (see ClassHierarchy for details) for class hierarchy related queries.

    This class uses OPAL's preInitializedClassHierarchy (see ClassHierarchy for details) for class hierarchy related queries.

    Use this trait ONLY if you just want to do some testing.

  28. trait RecordAllThrownExceptions extends RecordThrownExceptions

    Permalink

    Records all exceptions thrown by a method.

    Records all exceptions thrown by a method. I.e., for each instruction that throws an exception (or multiple exceptions) all exceptions are recorded.

    Note

    This domain is only effective if the calculation of joins is fast. Otherwise it can significantly hamper overall performance!

    ,

    This domain requires that DomainValues that represent thrown exceptions have meaningful equals and hashCode methods. (Depending on the purpose of the abstract interpretation, reference equality may be sufficient.)

  29. trait RecordCFG extends CoreDomainFunctionality with CustomInitialization with ai.ReturnInstructionsDomain

    Permalink

    Records the abstract interpretation time control-flow graph (CFG).

    Records the abstract interpretation time control-flow graph (CFG). This CFG is always (still) a sound approximation of the generally incomputable real CFG.

    Usage (Mixin-Composition Order)

    This domain overrides the flow method and requires that it is mixed in before every other domain that overrides the flow method and which may manipulate the worklist. E.g., the mixin order should be:

    class MyDomain extends Domain with RecordCFG with FlowManipulatingDomain

    If the mixin order is not correct, the CFG may not be complete/concrete.

    Core Properties

    • Thread-safe: No; i.e., the domain can only be used by one abstract interpreter at a time. However, using the collected results is thread-safe!
    • Reusable: Yes; all state directly associated with the analyzed code block is reset by the method initProperties.
    • No Partial Results: If the abstract interpretation was aborted the results have no meaning and must not be used; however, if the abstract interpretation is later continued and successfully completed the results are correct.
  30. trait RecordConstraints extends ReifiedConstraints

    Permalink

    Mixin this trait if you want to reify the constraints that are stated by the abstract interpretation framework.

    Mixin this trait if you want to reify the constraints that are stated by the abstract interpretation framework. This is particularly useful for testing and debugging purposes.

  31. trait RecordDefUse extends RecordCFG

    Permalink

    Collects the abstract interpretation time definition/use information.

    Collects the abstract interpretation time definition/use information. I.e., makes the information available which value is accessed where/where a used value is defined. In general, all local variables are identified using Ints where the Int identifies the expression (by means of it's pc) which evaluated to the respective value. In case of a parameter the Int value is equivalent to the value -parameterIndex. In case of exception values the Int value identifies the exception handler that caught the respective exception. This information can then be used – in combination with the AICFG - to identify the origin instruction that caused the exception. A more precise propagation of def/use information related to exceptions is – as part of this very generic domain – not possible. If we would propagate def-use information beyond the handler, we would not be able to distinguish between the handlers anymore and therefore we would not be able to identify where a caught exception is eventually used.

    General Usage

    This trait finalizes the collection of the def/use information after the abstract interpretation has successfully completed and the control-flow graph is available. The information is automatically made available, when this plug-in is mixed in.

    Special Values

    Parameters

    The parameters given to a method have negative int values (the first parameter has the value -1, the second -2 if the first one is a value of computational type category one and -3 if the first value is of computational type category two and so forth). I.e., in case of a method def (d : Double, i : Int), the second parameter will have the index -3.

    Core Properties

    Reusability

    An instance of this domain can be reused to successively perform abstract interpretations of different methods. The domain's inherited initProperties method – which is always called by the AI framework – resets the entire state related to the method.

  32. trait RecordJoinedThrownExceptions extends RecordThrownExceptions

    Permalink

    Records the exception that is thrown by an instruction.

    Records the exception that is thrown by an instruction. If an instruction throws multiple exceptions. The exceptions are joined using the Domain#DomainValue's join method.

    This trait can be used to record the thrown exceptions independently of the precision of the domain.

  33. trait RecordLastReturnedValues extends RecordReturnedValues

    Permalink

    Records the last value that is returned by a specific return instruction.

    Records the last value that is returned by a specific return instruction.

    Recording just the last value that is returned by a (a|i|l|f|d)return instruction is often sufficient (e.g., in case of a domain that performs all computations at the type level). The "last" value encodes all necessary information.

  34. trait RecordMethodCallResults extends MethodCallResults with RecordReturnedValues with RecordThrownExceptions

    Permalink

    Records the results of the evaluation of the current method such that the results can directly be adapted to the calling context and can be used by the caller to continue the abstract interpretation of the calling method.

  35. trait RecordReturnFromMethodInstructions extends ai.ReturnInstructionsDomain

    Permalink

    Records the program counters of all instructions that lead to a (ab)normal return from the method.

    Records the program counters of all instructions that lead to a (ab)normal return from the method. I.e., every instruction that may throw an exception or causes a normal return from method may be recorded. Examples of instructions that may be recorded: (X)return, throw, invoke(XXX), get|put(static|field), checkcast, (a)new(array),... . Instructions such as swap or dup(XXX), however, never directly lead to a method return (they will never result in an exception) and will not be recorded.

    If you are interested in recording the values use: RecordReturnedValues, RecordThrownExceptions.

    Usage

    This domain can be stacked on top of other traits that handle return instructions and abrupt method executions.

  36. trait RecordReturnedValue extends RecordReturnedValuesInfrastructure

    Permalink

    Record the value returned by a method across all return instructions.

    Record the value returned by a method across all return instructions.

    Usage

    This domain can be stacked on top of other traits that handle return instructions that return some value.

    Usage

    A domain that mixes in this trait should only be used to analyze a single method.

  37. trait RecordReturnedValueInfrastructure extends RecordReturnedValuesInfrastructure

    Permalink

    Generic infrastructure to record the value returned by the method (calculated across all return instructions)

    Generic infrastructure to record the value returned by the method (calculated across all return instructions)

    Usage

    This domain can be stacked on top of other traits that handle return instructions that return some value.

    Usage

    A domain that mixes in this trait should only be used to analyze a single method.

  38. trait RecordReturnedValues extends RecordReturnedValuesInfrastructure with CustomInitialization

    Permalink

    Generic infrastructure to record the values returned by the method.

    Generic infrastructure to record the values returned by the method. (Note that the computational type of the value(s) is not recorded. It is directly determined by the signature of the method that is analyzed or can be extracted using the respective method.)

    Usage

    This domain can be stacked on top of other traits that handle return instructions that return some value.

    Usage

    A domain that mixes in this trait should only be used to analyze a single method.

  39. trait RecordReturnedValuesInfrastructure extends ai.ReturnInstructionsDomain

    Permalink

    Infrastructure to record returned values.

  40. trait RecordThrownExceptions extends ai.ReturnInstructionsDomain

    Permalink

    Generic infrastructure to record the exceptions thrown by a method.

    Generic infrastructure to record the exceptions thrown by a method. This trait can be used to record the thrown exceptions independently of the precision of the domain.

    Usage

    This domain can be stacked on top of other traits that handle abruptMethodExecutions.

  41. trait RecordVoidReturns extends ReturnInstructionsDomain

    Permalink

    Records the program counters of all return (void) instructions that are reached.

    Records the program counters of all return (void) instructions that are reached.

    Usage

    Typical usage:

    class MyDomain extends ...DefaultHandlingOfVoidReturns with RecordVoidReturns

    This domain forwards all instruction evaluation calls to the super trait.

    Core Properties

    • Needs to be stacked upon a base implementation of the domain ReturnInstructionsDomain.
    • Collects information directly associated with the analyzed code block.
    • Not thread-safe.
    • Not reusable.
  42. trait ReifiedConstraints extends IntegerValuesDomain with ReferenceValuesDomain

    Permalink

    Mixin this trait to reify the stated constraints.

    Mixin this trait to reify the stated constraints. This trait need to be mixed in after all traits that actually handle constraints.

    This is particularly useful for testing and debugging purposes.

    Core Properties

    • Needs to be stacked upon a base implementation of the domains: IntegerValuesDomain and ReferenceValuesDomain].
    • Collects state directly associated with the analyzed code block.
    • Not thread-safe.
    • Not reusable (I.e., a new instance needs to be created per method.)
  43. trait ReturnInstructionsDomain extends ai.ReturnInstructionsDomain

    Permalink

    Adds support for handling return instructions in a generic manner.

  44. trait SpecialMethodsHandling extends MethodCallsHandling

    Permalink

    Hard-codes some part of the semantics of some very high-profile (native) methods of the JDK (for example, System.arraycopy).

    Hard-codes some part of the semantics of some very high-profile (native) methods of the JDK (for example, System.arraycopy).

    Mixin Order

    This method should be mixed in (lexically) after those domains that provide the basic handling of unresolved methods (e.g., using "just" type information) but before those that actually invoke a method!

  45. trait TheCode extends AnyRef

    Permalink

    Provides information about the code block that is currently analyzed.

    Provides information about the code block that is currently analyzed.

    Core Properties

    • Defines the public interface.
  46. trait TheMethod extends TheCode

    Permalink

    Provides information about the method that is currently analyzed.

    Provides information about the method that is currently analyzed.

    Usage

    A domain that implements this trait usually defines a parameter that is set at construction time.

    E.g.,

    class MyDomain{val method : Method} extends Domain with TheMethod

    Core Properties

  47. trait TheProject extends TheClassHierarchy with LogContextProvider with ThePropertyStore

    Permalink

    Provides information about the underlying project.

    Provides information about the underlying project.

    Usage

    If a (partial-) domain needs information about the project declare a corresponding self-type dependency.

    trait MyIntegerValuesDomain extends IntegerValues { this : TheProject =>

    Providing Information about a Project

    A domain that provides information about the currently analyzed project should inherit from this trait and implement the respective method.

    Core Properties

    Note

    It is recommended that the domain that provides the project information does not use the override access flag. This way the compiler will issue a warning if two implementations are used to create a final domain.

  48. trait ThePropertyStore extends AnyRef

    Permalink

    This trait is mixed in by those (partial) domains that require access to the project's property store.

  49. trait ThrowAllPotentialExceptionsConfiguration extends Configuration

    Permalink

    A configuration that forces abstract interpretation to always create an exception if it is not possible to deduce that a specific exception will not be thrown.

    A configuration that forces abstract interpretation to always create an exception if it is not possible to deduce that a specific exception will not be thrown.

    Usage

    If you need to adapt a setting just override the respective method in your domain or create a class that inherits from Configuration.

    Core Properties

    • Concrete base implementation of the Configuration trait that can be used to create a final domain.
    • Thread safe.
  50. trait ThrowNoPotentialExceptionsConfiguration extends Configuration

    Permalink

    A configuration that forces abstract interpretation to never create an exception if it is not possible to deduce that the specific exception is guaranteed to be thrown.

    A configuration that forces abstract interpretation to never create an exception if it is not possible to deduce that the specific exception is guaranteed to be thrown.

    Usage

    If you need to adapt a setting just override the respective method in your domain or create a class that inherits from Configuration.

    Core Properties

    • Concrete base implementation of the Configuration trait that can be used to create a final domain.
    • Thread safe.
  51. trait ValuesCoordinatingDomain extends CorrelationalDomain with Configuration

    Permalink

    Can be mixed in to create a Domain that is intended to be used to coordinate the exchange of values between different domains.

    Can be mixed in to create a Domain that is intended to be used to coordinate the exchange of values between different domains.

    This domain does not prescribe the semantics of any values, but instead implements methods that perform computations.

    This domain directly inherits from Domain and can, thus, directly be used to create a final domain.

    Core Properties

Value Members

  1. object DomainValues

    Permalink

    Factory for creating DomainValues objects.

  2. final val EmptyUpperTypeBound: UIDSet[ReferenceType]

    Permalink
  3. object Origin

    Permalink
  4. object Origins

    Permalink
  5. object PerformAI extends BaseAI

    Permalink

    A base abstract interpreter that can be used with any domain that has no special requirements on the abstract interpreter and which provides some convenience factory methods to run the abstract interpretation if the domain provide the necessary information.

    A base abstract interpreter that can be used with any domain that has no special requirements on the abstract interpreter and which provides some convenience factory methods to run the abstract interpretation if the domain provide the necessary information.

    The base interpreter can be interrupted by calling the interrupt method of the AI's thread.

    See also

    BoundedInterruptableAI for an abstract interpreter that can easily be interrupted and which also interrupts itself if a certain threshold is exceeded.

  6. object PredefinedClassHierarchy

    Permalink
  7. object SpecialMethodsHandling

    Permalink
  8. def analyzedEntity(domain: Domain): String

    Permalink

    Tries to determine the name of the method/class that is analyzed; the result depends on the mixed-in domain.

  9. package l0

    Permalink
  10. package l1

    Permalink

    Commonly useful methods.

  11. package l2

    Permalink
  12. package la

    Permalink
  13. package li

    Permalink
  14. package tracing

    Permalink

Inherited from AnyRef

Inherited from Any

Ungrouped