OPAL - Bytecode Representation 2.0.1

final def !=(arg0: Any): Boolean

Definition Classes: AnyRef → Any

final def ##(): Int

Definition Classes: AnyRef → Any

final def ==(arg0: Any): Boolean

Definition Classes: AnyRef → Any

def alwaysResultsInException(pc: Int, cfJoins: IntTrieSet, anInvocation: (Int) ⇒ Boolean, aThrow: (Int) ⇒ Boolean): Boolean

Tests if the straight-line sequence of instructions that starts with the given pc always ends with an ATHROW instruction or a method call that always throws an exception.

Tests if the straight-line sequence of instructions that starts with the given pc always ends with an ATHROW instruction or a method call that always throws an exception. The call sequence furthermore has to contain no complex logic. Here, complex means that evaluating the instruction may result in multiple control flows. If the sequence contains complex logic, false will be returned.

One use case of this method is, e.g., to check if the code of the default case of a switch instruction always throws some error (e.g., an UnknownError or AssertionError).

switch(...) {
 case X : ....
 default :
     throw new AssertionError();
}

This is a typical idiom used in Java programs and which may be relevant for certain analyses to detect.

pc: The program counter of an instruction that strictly dominates all succeeding instructions up until the next instruction (as determined by #cfJoins where two or more paths join. If the pc belongs to an instruction where multiple paths join, false will be returned.
anInvocation: When the analysis finds a method call, it calls this method to let the caller decide whether the called method is an (indirect) way of always throwing an exception. If true is returned the analysis terminates and returns true; otherwise the analysis continues.
aThrow: If all (non-exception) paths will always end in one specific ATHROW instruction then this function is called (callback) to let the caller decide if the "expected" exception is thrown. This analysis will return with the result of this call.
returns: true if the bytecode sequence starting with the instruction with the given pc always ends with an org.opalj.br.instructions.ATHROW instruction. false in all other cases (i.e., the sequence does not end with an athrow instruction or the control flow is more complex.)

Annotations: @inline()
Note: If complex control flows should also be considered it is possible to compute a methods org.opalj.br.cfg.CFG and use that one.

final def asInstanceOf[T0]: T0

Definition Classes: Any

val attributes: Attributes

Definition Classes: Code → CommonAttributes

def belongsToSubroutine(): Array[Int]

Calculates for each instruction the subroutine to which it belongs to – if any.

Calculates for each instruction the subroutine to which it belongs to – if any. This information is required to, e.g., identify the subroutine contexts that need to be reset in case of an exception in a subroutine.

returns: Basically a map that maps the pc of each instruction to the id of the subroutine. For each instruction (with a specific pc) the pc of the first instruction of the subroutine it belongs to is returned. The pc 0 identifies the instruction as belonging to the core method. The pc -1 identifies the instruction as dead by compilation.

Note: Calling this method only makes sense for Java bytecode that actually contains org.opalj.br.instructions.JSR and org.opalj.br.instructions.RET instructions.

def cfJoins(implicit classHierarchy: ClassHierarchy = PreInitializedClassHierarchy): IntTrieSet

Returns the set of all program counters where two or more control flow paths may join.

Example

 0: iload_1
 1: ifgt    6
 2: iconst_1
 5: goto 10
 6: ...
 9: iload_1
10: return // <= PATH JOIN: the predecessors are the instructions 5 and 9.

In case of exception handlers the sound overapproximation is made that all exception handlers with a fitting type may be reached on multiple paths.

def cfPCs(implicit classHierarchy: ClassHierarchy = PreInitializedClassHierarchy): (PCs, PCs, IntMap[PCs])

Returns the set of all program counters where two or more control flow paths join or fork.

Example

 0: iload_1
 1: ifgt    6 // <= PATH FORK
 2: iconst_1
 5: goto 10
 6: ...
 9: iload_1
10: return // <= PATH JOIN: the predecessors are the instructions 5 and 9.

In case of exception handlers the sound overapproximation is made that all exception handlers may be reached on multiple paths.

returns: A triple which contains (1) the set of pcs of those instructions where multiple control-flow paths join; (2) the pcs of the instructions which may result in multiple different control-flow paths and (3) for each of the later instructions the set of all potential targets.

def clone(): AnyRef

Attributes: protected[java.lang]
Definition Classes: AnyRef
Annotations: @native() @throws( ... )

final def codeSize: Int

Annotations: @inline()

def collect[B <: AnyRef](f: PartialFunction[Instruction, B]): List[PCAndAnyRef[B]]

Collects all instructions for which the given function is defined.

Usage scenario

Use this function if you want to search for and collect specific instructions and when you do not immediately require the program counter/index of the instruction in the instruction array to make the decision whether you want to collect the instruction.

Examples

Example usage to collect the declaring class of all get field accesses where the field name is "last".

collect({
 case GETFIELD(declaringClass, "last", _) ⇒ declaringClass
})

Example usage to collect all instances of a "DUP" instruction.

code.collect({ case dup @ DUP ⇒ dup })

returns: The result of applying the function f to all instructions for which f is defined combined with the index (program counter) of the instruction in the code array.

def collectFirst[B](f: PartialFunction[Instruction, B]): Option[B]

def collectFirstWithIndex[B](f: PartialFunction[PCAndInstruction, B]): Option[B]

Applies the given function to the first instruction for which the given function is defined.

def collectInstructions[B <: AnyRef](f: PartialFunction[Instruction, B]): List[B]

Collects all instructions for which the given function is defined.

Collects all instructions for which the given function is defined. The order in which the instructions are collected is reversed when compared to the order in the instructions array.

def collectInstructionsWithPC[B <: AnyRef](f: PartialFunction[PCAndInstruction, B]): List[PCAndAnyRef[B]]

Collects all instructions for which the given function is defined.

def collectPair[B <: AnyRef](f: PartialFunction[(Instruction, Instruction), B]): List[PCAndAnyRef[B]]

Finds a pair of consecutive instructions that are matched by the given partial function.

Example Usage

(pc, _) ← body.findPair {
     case (
         INVOKESPECIAL(receiver1, _, SingleArgumentMethodDescriptor((paramType: BaseType, _))),
         INVOKEVIRTUAL(receiver2, name, NoArgumentMethodDescriptor(returnType: BaseType))
     ) if (...) ⇒ (...)
     } yield ...

def collectUntil[B <: AnyRef](f: PartialFunction[PCAndInstruction, B]): PCAndAnyRef[List[B]]

Collects the results of the evaluation of the partial function until the partial function is not defined.

returns: The program counter of the instruction for which the given partial function was not defined along with the list of previous results. The results are sorted in descending order w.r.t. the PC.

def collectWithIndex[B](f: PartialFunction[PCAndInstruction, B])(implicit arg0: ClassTag[B]): Chain[B]

Applies the given function f to all instruction objects for which the function is defined.

Applies the given function f to all instruction objects for which the function is defined. The function is passed a tuple consisting of the current program counter/index in the code array and the corresponding instruction.

Example

Example usage to collect the program counters (indexes) of all instructions that are the target of a conditional branch instruction:

code.collectWithIndex({
 case (pc, cbi: ConditionalBranchInstruction) ⇒
     Seq(cbi.indexOfNextInstruction(pc, code), pc + cbi.branchoffset)
 }) // .flatten should equal (Seq(...))

def compareAttributes(other: Attributes, config: SimilarityTestConfiguration): Option[AnyRef]

Compares this element's attributes with the given one.

returns: None, if both attribute lists are similar; Some(<description of the difference>) otherwise.

Attributes: protected[this]
Definition Classes: CommonAttributes

def copy(maxStack: Int = this.maxStack, maxLocals: Int = this.maxLocals, instructions: Array[Instruction] = this.instructions, exceptionHandlers: ExceptionHandlers = this.exceptionHandlers, attributes: Attributes = this.attributes): Code

final def eq(arg0: AnyRef): Boolean

Definition Classes: AnyRef

def equals(arg0: Any): Boolean

Definition Classes: AnyRef → Any

val exceptionHandlers: ExceptionHandlers

def exceptionHandlersFor(pc: PC): Chain[ExceptionHandler]

Returns a view of all potential exception handlers (if any) for the instruction with the given program counter (pc).

Returns a view of all potential exception handlers (if any) for the instruction with the given program counter (pc). Finally handlers (catchType == None) are not returned but will stop the evaluation (as all further exception handlers have no further meaning w.r.t. the runtime)! In case of identical caught exceptions only the first of them will be returned. No further checks (w.r.t. the typehierarchy) are done.

pc: The program counter of an instruction of this Code array.

final def exists(p: (Int, Instruction) ⇒ Boolean): Boolean

Iterates over all instructions until an instruction is found that matches the given predicate.

Annotations: @inline()

def filter[B](f: (PC, Instruction) ⇒ Boolean): IntArraySet

def finalize(): Unit

Attributes: protected[java.lang]
Definition Classes: AnyRef
Annotations: @throws( classOf[java.lang.Throwable] )

def find(f: (Instruction) ⇒ Boolean): Option[PC]

Tests if an instruction matches the given filter.

Tests if an instruction matches the given filter. If so, the index of the first matching instruction is returned.

def findSequence[B <: AnyRef](windowSize: Int)(f: PartialFunction[Queue[Instruction], B]): List[PCAndAnyRef[B]]

Finds a sequence of instructions that are matched by the given partial function.

returns: List of pairs where the first element is the pc of the first instruction of a matched sequence and the second value is the result of the evaluation of the partial function.

Note: If possible, use one of the more specialized methods, such as, collectPair. The pure iteration overhead caused by this method is roughly 10-20 times higher than this one.

def firstLineNumber: Option[Int]

Returns the smallest line number (if any).

Note

The line number associated with the first instruction (pc === 0) is not necessarily the smallest one.

public void foo(int i) {
  super.foo( // The call has the smallest line number.
    i+=1; // THIS IS THE FIRST OPERATION...
  )
}

def flatMap[B, That](f: (PCAndInstruction) ⇒ GenTraversableOnce[B])(implicit bf: CanBuildFrom[Nothing, B, That]): That

Definition Classes: Code → FilterMonadic

def foldLeft[T](start: T)(f: (T, Int, Instruction) ⇒ T): T

final def forall(f: (Int, Instruction) ⇒ Boolean): Boolean

Annotations: @inline()

def foreach[U](f: (PCAndInstruction) ⇒ U): Unit

Definition Classes: Code → FilterMonadic

final def foreachInstruction[U](f: (Instruction) ⇒ U): Unit

Iterates over all instructions and calls the given function f for every instruction.

Annotations: @inline()

final def foreachTypeAnnotation[U](f: (TypeAnnotation) ⇒ U): Unit

Definition Classes: CommonAttributes

final def getClass(): Class[_]

Definition Classes: AnyRef → Any
Annotations: @native()

def handlerInstructionsFor(pc: Int): Chain[Int]

The list of pcs of those instructions that may handle an exception if the evaluation of the instruction with the given pc throws an exception.

In case of multiple finally handlers only the first one will be returned and no further exception handlers will be returned. In case of identical caught exceptions only the first of them will be returned. No further checks (w.r.t. the type hierarchy) are done.

If different exceptions are handled by the same handler, the corresponding pc is returned multiple times.

def handlersFor(pc: Int, justExceptions: Boolean = false): Chain[ExceptionHandler]

Returns a view of all handlers (exception and finally handlers) for the instruction with the given program counter (pc) that may catch an exception; as soon as a finally handler is found no further handlers will be returned!

In case of multiple exception handlers that are identical (in particular in case of the finally handlers) only the first one is returned as that one is the one that will be used by the JVM at runtime. No further checks (w.r.t. the type hierarchy) are done.

pc: The program counter of an instruction of this Code array.

def handlersForException(pc: Int, exception: ObjectType)(implicit classHierarchy: ClassHierarchy = ...): Chain[ExceptionHandler]

Returns the handlers that may handle the given exception.

The (known/given) type hierarchy is taken into account as well as the order between the exception handlers.

def hashCode(): Int

Definition Classes: AnyRef → Any
Annotations: @native()

def haveSameLineNumber(firstPC: Int, secondPC: Int): Option[Boolean]

Returns Some(true) if both pcs have the same line number.

Returns Some(true) if both pcs have the same line number. If line number information is not available None is returned.

val instructions: Array[Instruction]

Definition Classes: Code → CodeSequence

def instructionsCount: Int

Counts the number of instructions.

Note: The number of instructions is always smaller or equal to the size of the code array.
,
This operation has complexity O(n).

def instructionsOption: Some[Array[Instruction]]

Definition Classes: Code → InstructionsContainer

final def isInstanceOf[T0]: Boolean

Definition Classes: Any

def isModifiedByWide(pc: Int): Boolean

True if the instruction with the given program counter is modified by wide.

pc: A valid index in the code array.

Annotations: @inline()

final def iterate[U](f: (Int, Instruction) ⇒ U): Unit

Iterates over all instructions and calls the given function f for every instruction.

Annotations: @inline()

def iterator: Iterator[Instruction]

def kindId: Int

This attribute's kind id.

Definition Classes: Code → Attribute

def lineNumber(pc: Int): Option[Int]

Returns the line number associated with the instruction with the given pc if it is available.

pc: Index of the instruction for which we want to get the line number.
returns: Some line number or None if no line-number information is available.

def lineNumberTable: Option[LineNumberTable]

Returns the line number table - if any.

Note: A code attribute is allowed to have multiple line number tables. However, all tables are merged into one by OPAL at class loading time.
,
Depending on the configuration of the reader for ClassFiles this attribute may not be reified.

def liveVariables(predecessorPCs: Array[PCs], finalPCs: PCs, cfJoins: PCs): LiveVariables

Performs a live variable analysis restricted to a method's locals.

returns: For each instruction (identified by its pc) the set of variables (register values) which are live (identified by their index) is determined. I.e., if you need to know if the variable with the index 5 is (still) live at instruction j with pc 37 it is sufficient to test if the bit set stored at index 37 contains the value 5.

def liveVariables(implicit classHierarchy: ClassHierarchy): LiveVariables

Computes for each instruction which variables are live; see liveVariables(predecessorPCs: Array[PCs], finalPCs: PCs, cfJoins: BitSet) for further details.

def localVariable(pc: Int, index: Int): Option[LocalVariable]

Returns the local variable stored at the given local variable index that is live at the given instruction (pc).

def localVariableTable: Option[LocalVariables]

Collects (the merged if necessary) local variable table.

Note: A code attribute is allowed to have multiple local variable tables. However, all tables are merged into one by OPAL at class loading time.
,
Depending on the configuration of the reader for ClassFiles this attribute may not be reified.

def localVariableTypeTable: Iterable[LocalVariableTypes]

Collects all local variable type tables.

Note: Depending on the configuration of the reader for ClassFiles this attribute may not be reified.

def localVariablesAt(pc: Int): Map[Int, LocalVariable]

Returns the set of local variables defined at the given pc base on debug information.

returns: A mapping of the index to the name of the local variable. The map is empty if no debug information is available.

def map[B, That](f: (PCAndInstruction) ⇒ B)(implicit bf: CanBuildFrom[Nothing, B, That]): That

Definition Classes: Code → FilterMonadic

def matchPair(f: (Instruction, Instruction) ⇒ Boolean): Chain[Int]

Matches pairs of two consecutive instructions.

Matches pairs of two consecutive instructions. For each matched pair, the program counter of the first instruction is returned.

Example Usage

for {
 classFile ← project.view.map(_._1).par
 method @ MethodWithBody(body) ← classFile.methods
 pc ← body.matchPair({
     case (
         INVOKESPECIAL(receiver1, _, TheArgument(parameterType: BaseType)),
         INVOKEVIRTUAL(receiver2, name, NoArgumentMethodDescriptor(returnType: BaseType))
     ) ⇒ { (receiver1 eq receiver2) && (returnType ne parameterType) }
     case _ ⇒ false
     })
 } yield (classFile, method, pc)

def matchTriple(matchMaxTriples: Int = Int.MaxValue, f: (Instruction, Instruction, Instruction) ⇒ Boolean): Chain[Int]

Finds a sequence of 3 consecutive instructions for which the given function returns true, and returns the PC of the first instruction in each found sequence.

matchMaxTriples: Is the maximum number of triples that is passed to f. E.g., if matchMaxTriples is "1" only the first three instructions are passed to f.

def matchTriple(f: (Instruction, Instruction, Instruction) ⇒ Boolean): Chain[Int]

Finds all sequences of three consecutive instructions that are matched by f.

val maxLocals: Int

val maxStack: Int

final def ne(arg0: AnyRef): Boolean

Definition Classes: AnyRef

def nextNonGotoInstruction(pc: Int): Int

Returns the next instruction that will be executed at runtime that is not a org.opalj.br.instructions.GotoInstruction.

Returns the next instruction that will be executed at runtime that is not a org.opalj.br.instructions.GotoInstruction. If the given instruction is not a org.opalj.br.instructions.GotoInstruction, the given instruction is returned.

Annotations: @tailrec()

final def notify(): Unit

Definition Classes: AnyRef
Annotations: @native()

final def notifyAll(): Unit

Definition Classes: AnyRef
Annotations: @native()

final def pcOfNextInstruction(currentPC: Int): Int

Returns the program counter of the next instruction after the instruction with the given counter (currentPC).

currentPC: The program counter of an instruction. If currentPC is the program counter of the last instruction of the code block then the returned program counter will be equivalent to the length of the Code/Instructions array.

Definition Classes: Code → CodeSequence
Annotations: @inline()

final def pcOfPreviousInstruction(currentPC: Int): Int

Returns the program counter of the previous instruction in the code array.

Returns the program counter of the previous instruction in the code array. currentPC must be the program counter of an instruction.

This function is only defined if currentPC is larger than 0; i.e., if there is a previous instruction! If currentPC is larger than instructions.size the behavior is undefined.

Definition Classes: Code → CodeSequence
Annotations: @inline()

def predecessorPCs(implicit classHierarchy: ClassHierarchy): (Array[PCs], PCs, PCs)

Computes for each instruction the set of predecessor instructions as well as all instructions without predecessors.

Computes for each instruction the set of predecessor instructions as well as all instructions without predecessors. Those instructions with multiple predecessors are also returned.

returns: (1) An array which contains for each instruction the set of all predecessors, (2) the set of all instructions which have only predecessors; i.e., no successors and (3) the set of all instructions where multiple paths join. ´(Array[PCs]/*PREDECESSOR_PCs*/, PCs/*FINAL_PCs*/, PCs/*CF_JOINS*/)´. Note, that in case of completely broken code, set 2 may contain other instructions than return and athrow instructions. If the code contains jsr/ret instructions, the full blown CFG is computed.

def programCounters: IntIterator

Returns an iterator to iterate over the program counters (pcs) of the instructions of this Code block.

See also: See the method foreach for an alternative.

def runtimeInvisibleTypeAnnotations: TypeAnnotations

Definition Classes: CommonAttributes

def runtimeVisibleTypeAnnotations: TypeAnnotations

Definition Classes: CommonAttributes

def similar(other: Code, config: SimilarityTestConfiguration): Boolean

def similar(other: Attribute, config: SimilarityTestConfiguration): Boolean

Returns true if this attribute and the given one are guaranteed to be indistinguishable at runtime.

Definition Classes: Code → Attribute
Note: If this class is implemented as a proper case class, this method can often be implemented by forwarding to the default equals method.

def slidingCollect[B <: AnyRef](windowSize: Int)(f: PartialFunction[PCAndAnyRef[Queue[Instruction]], B]): List[B]

Slides over the code array and tries to apply the given function to each sequence of instructions consisting of windowSize elements.

Scenario

If you want to search for specific patterns of bytecode instructions. Some "bug patterns" are directly related to specific bytecode sequences and these patterns can easily be identified using this method.

Example

Search for sequences of the bytecode instructions PUTFIELD and ALOAD_O in the method's body and return the list of program counters of the start of the identified sequences.

code.slidingCollect(2)({
     case (pc, Seq(PUTFIELD(_, _, _), ALOAD_0)) ⇒ (pc)
}) should be(Seq(...))

windowSize: The size of the sequence of instructions that is passed to the partial function. It must be larger than 0. **Do not use this method with windowSize "1"**; it is more efficient to use the collect or collectWithIndex methods instead.
returns: The list of results of applying the function f for each matching sequence.

Note: If possible, use one of the more specialized methods, such as, collectPair. The pure iteration overhead caused by this method is roughly 10-20 times higher than this one.

def stackDepthAt(atPC: Int, cfg: CFG[Instruction, Code]): Int

Computes the stack depth for the instruction with the given pc (atPC).

Computes the stack depth for the instruction with the given pc (atPC). I.e, computes the stack depth before executing the instruction! This function is intended to be used if and only if the stack depth is only required for a single instruction; it recomputes the stack depth for all instructions whenever the function is called.

returns: the stack depth or -1 if the instruction is invalid/dead.

Annotations: @throws( ... )
Note: If the CFG is already available, it should be passed as the computation is potentially the most expensive part.

def stackDepthAt(atPC: Int, classHierarchy: ClassHierarchy = ...): Int

Annotations: @throws( ... )

def stackMapTable: Option[StackMapTable]

The JVM specification mandates that a Code attribute has at most one StackMapTable attribute.

Note: Depending on the configuration of the reader for ClassFiles this attribute may not be reified.

def stackMapTablePCs(implicit classHierarchy: ClassHierarchy): IntArraySet

Computes the set of PCs for which a stack map frame is required.

Computes the set of PCs for which a stack map frame is required. Calling this method (i.e., the generation of stack map tables in general) is only defined for Java > 5 code; i.e., cocde which does not use JSR/RET; therefore the behavior for Java 5 or earlier code is deliberately undefined.

classHierarchy: The computation of the stack map table generally requires the presence of a complete type hierarchy.
returns: The sorted set of PCs for which a stack map frame is required.

final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes: AnyRef

def toString(): String

A complete representation of this code attribute (including instructions, attributes, etc.).

Definition Classes: Code → AnyRef → Any

final def wait(): Unit

Definition Classes: AnyRef
Annotations: @throws( ... )

final def wait(arg0: Long, arg1: Int): Unit

Definition Classes: AnyRef
Annotations: @throws( ... )

final def wait(arg0: Long): Unit

Definition Classes: AnyRef
Annotations: @native() @throws( ... )

def withFilter(p: (PCAndInstruction) ⇒ Boolean): FilteredCode

Definition Classes: Code → FilterMonadic

Packages

Code

Companion object Code

final class Code extends Attribute with CommonAttributes with InstructionsContainer with CodeSequence[Instruction] with FilterMonadic[PCAndInstruction, Nothing]

Type Members

Value Members

Example

Example

Usage scenario

Examples

Example Usage

Example

Example Usage

Scenario

Example

Inherited from FilterMonadic[PCAndInstruction, Nothing]

Inherited from CodeSequence[Instruction]

Inherited from InstructionsContainer

Inherited from CommonAttributes

Inherited from Attribute

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Code 

Companion object Code

final class Code extends Attribute with CommonAttributes with InstructionsContainer with CodeSequence[Instruction] with FilterMonadic[PCAndInstruction, Nothing]

Type Members

Value Members

Example

Example

Usage scenario

Examples

Example Usage

Example

Example Usage

Scenario

Example

Inherited from FilterMonadic[PCAndInstruction, Nothing]

Inherited from CodeSequence[Instruction]

Inherited from InstructionsContainer

Inherited from CommonAttributes

Inherited from Attribute

Inherited from AnyRef

Inherited from Any

Ungrouped

Code