Top Description Inners Fields Constructors Methods
org.apache.bcel.util

public Class InstructionFinder

extends Object
Class Inheritance
Imports
java.util.ArrayList, .Arrays, .HashMap, .Iterator, .List, .Locale, .Map, java.util.regex.Matcher, .Pattern, org.apache.bcel.Const, org.apache.bcel.generic.ClassGenException, .InstructionHandle, .InstructionList
InstructionFinder is a tool to search for given instructions patterns, i.e., match sequences of instructions in an instruction list via regular expressions. This can be used, e.g., in order to implement a peep hole optimizer that looks for code patterns and replaces them with faster equivalents.

This class internally uses the java.util.regex package to search for regular expressions. A typical application would look like this: 



  InstructionFinder f   = new InstructionFinder(il);
  String            pat = "IfInstruction ICONST_0 GOTO ICONST_1 NOP (IFEQ|IFNE)";

  for (Iterator i = f.search(pat, constraint); i.hasNext(); ) {
  InstructionHandle[] match = (InstructionHandle[])i.next();
  ...
  il.delete(match[1], match[5]);
  ...
  }
See Also
org.apache.bcel.generic.Instruction, InstructionList

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
InstructionFinder.CodeConstraint

Code patterns found may be checked using an additional user-defined constraint object whether they really match the needed criterion.

Field Summary

Modifier and TypeField and Description
private InstructionHandle[]
handles

private final InstructionList
il

private String
ilString

private static final Map<String, String>
map

private static final int
NO_OPCODES

private static final int
OFFSET

Constructor Summary

AccessConstructor and Description
public
InstructionFinder(final InstructionList
instruction list to search for given patterns
il)

Method Summary

Modifier and TypeMethod and Description
private static String

Returns:

translated regular expression string
compilePattern(final String
The pattern to compile
pattern)

Replace symbolic names of instructions with the appropriate character and remove all white space from string.

public final InstructionList

Returns:

the inquired instruction list
getInstructionList()

private InstructionHandle[]

Returns:

the matched piece of code as an array of instruction (handles)
getMatch(final int matchedFrom, final int matchLength)

private static char
makeChar(final short opcode)

Convert opcode number to char.

private static String

Returns:

encoded string for a pattern such as "BranchInstruction".
mapName(final String
instruction pattern in lower case
pattern)

Map symbolic instruction names like "getfield" to a single character.

private static String
precompile(final short from, final short to, final short extra)

public final void
reread()

Reread the instruction list, e.g., after you've altered the list upon a match.

public final Iterator<InstructionHandle[]>

Returns:

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area
search(final String
the instruction pattern to search for, where case is ignored
pattern)

Start search beginning from the start of the given instruction list.

public final Iterator<InstructionHandle[]>

Returns:

instruction handle or 'null' if the match failed
search(final String
the instruction pattern to search for, case is ignored
pattern, final InstructionFinder.CodeConstraint
constraints to be checked on matching code
constraint)

Start search beginning from the start of the given instruction list.

public final Iterator<InstructionHandle[]>

Returns:

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area
search(final String
the instruction pattern to search for, where case is ignored
pattern, final InstructionHandle
where to start the search in the instruction list
from)

Start search beginning from 'from'.

public final Iterator<InstructionHandle[]>

Returns:

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area
search(final String
the instruction pattern to search for, where case is ignored
pattern, final InstructionHandle
where to start the search in the instruction list
from, final InstructionFinder.CodeConstraint
optional CodeConstraint to check the found code pattern for user-defined constraints
constraint)

Search for the given pattern in the instruction list.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

handlesback to summary
private InstructionHandle[] handles
ilback to summary
private final InstructionList il
ilStringback to summary
private String ilString
mapback to summary
private static final Map<String, String> map
NO_OPCODESback to summary
private static final int NO_OPCODES
OFFSETback to summary
private static final int OFFSET

Constructor Detail

InstructionFinderback to summary
public InstructionFinder(final InstructionList il)
Parameters
il:InstructionList

instruction list to search for given patterns

Method Detail

compilePatternback to summary
private static String compilePattern(final String pattern)

Replace symbolic names of instructions with the appropriate character and remove all white space from string. Meta characters such as +, * are ignored.

Parameters
pattern:String

The pattern to compile

Returns:String

translated regular expression string

getInstructionListback to summary
public final InstructionList getInstructionList()
Returns:InstructionList

the inquired instruction list

getMatchback to summary
private InstructionHandle[] getMatch(final int matchedFrom, final int matchLength)
Returns:InstructionHandle[]

the matched piece of code as an array of instruction (handles)

makeCharback to summary
private static char makeChar(final short opcode)

Convert opcode number to char.

mapNameback to summary
private static String mapName(final String pattern)

Map symbolic instruction names like "getfield" to a single character.

Parameters
pattern:String

instruction pattern in lower case

Returns:String

encoded string for a pattern such as "BranchInstruction".

precompileback to summary
private static String precompile(final short from, final short to, final short extra)
rereadback to summary
public final void reread()

Reread the instruction list, e.g., after you've altered the list upon a match.

searchback to summary
public final Iterator<InstructionHandle[]> search(final String pattern)

Start search beginning from the start of the given instruction list.

Parameters
pattern:String

the instruction pattern to search for, where case is ignored

Returns:Iterator<InstructionHandle[]>

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area

searchback to summary
public final Iterator<InstructionHandle[]> search(final String pattern, final InstructionFinder.CodeConstraint constraint)

Start search beginning from the start of the given instruction list. Check found matches with the constraint object.

Parameters
pattern:String

the instruction pattern to search for, case is ignored

constraint:InstructionFinder.CodeConstraint

constraints to be checked on matching code

Returns:Iterator<InstructionHandle[]>

instruction handle or 'null' if the match failed

searchback to summary
public final Iterator<InstructionHandle[]> search(final String pattern, final InstructionHandle from)

Start search beginning from 'from'.

Parameters
pattern:String

the instruction pattern to search for, where case is ignored

from:InstructionHandle

where to start the search in the instruction list

Returns:Iterator<InstructionHandle[]>

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area

searchback to summary
public final Iterator<InstructionHandle[]> search(final String pattern, final InstructionHandle from, final InstructionFinder.CodeConstraint constraint)

Search for the given pattern in the instruction list. You can search for any valid opcode via its symbolic name, e.g. "istore". You can also use a super class or an interface name to match a whole set of instructions, e.g. "BranchInstruction" or "LoadInstruction". "istore" is also an alias for all "istore_x" instructions. Additional aliases are "if" for "ifxx", "if_icmp" for "if_icmpxx", "if_acmp" for "if_acmpxx". Consecutive instruction names must be separated by white space which will be removed during the compilation of the pattern. For the rest the usual pattern matching rules for regular expressions apply.

Example pattern: 

search("BranchInstruction NOP ((IfInstruction|GOTO)+ ISTORE Instruction)*");

If you alter the instruction list upon a match such that other matching areas are affected, you should call reread() to update the finder and call search() again, because the matches are cached.

Parameters
pattern:String

the instruction pattern to search for, where case is ignored

from:InstructionHandle

where to start the search in the instruction list

constraint:InstructionFinder.CodeConstraint

optional CodeConstraint to check the found code pattern for user-defined constraints

Returns:Iterator<InstructionHandle[]>

iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area

org.apache.bcel.util back to summary

public Interface InstructionFinder.CodeConstraint

Code patterns found may be checked using an additional user-defined constraint object whether they really match the needed criterion. I.e., check constraints that can not expressed with regular expressions.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the matched area is really useful
checkCode(InstructionHandle[]
array of instructions matching the requested pattern
match)

Method Detail

checkCodeback to summary
public boolean checkCode(InstructionHandle[] match)
Parameters
match:InstructionHandle[]

array of instructions matching the requested pattern

Returns:boolean

true if the matched area is really useful