Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

edu.ucsb.ccs.jcontractor
Class jInstrument

java.lang.Object
  |
  +--edu.ucsb.ccs.jcontractor.jInstrument
public class jInstrument
extends java.lang.Object

Utility to read in class files and instrument class methods to enforce jContractor contracts. Instrumented class files are written to a destination directory which defaults to the current working directory. The program may be run from the command line by passing the names of files to instrument as arguments, or by invoking the instrumentClassFile(String) method. If specified, the instrumentation file controls the instrumentation level of each class in the system. The available instrumentation levels are: 

   None - No contracts checked.
   Pre  - Preconditions checked.
   Post - Preconditions and postconditions checked.
   All  - Preconditions, postconditions, and invariants checked.
The instrumentation file contains class names followed by instrumentation levels, and separated by whitespace. For example: 
   *                                      none
   edu.*                                  pre
   edu.ucsb.ccs.jcontractor.jInstrument   all
This file says the the jInstrument class should be instrumented completetly and the other classes in edu and all subpackages should have precondition checks. Wildcard matching works as in Java import statements, except that the wildcard matches any class in the package or any subpackage. More specific filters override general filters (edu.ccs.jcontractor.jInstrument overrides edu.*). jInstrument also includes a "strip mode" which removes contract methods from bytecode in order to decrease the file size. While jContractor contracts have no runtime effect when the class is run without jContractor, they do increase the size of the bytecode. The "-s" flag on the command line tells jInstrument to remove contract methods instead of adding calls to them. Once contract checks are inserted, the class becomes dependent on its contract methods to run correctly. For this reason it is not possible remove the contract methods from an instrumented class. 
   Usage: jInstrument [-options] classfile1 classfile2 classfile3 ...

   Options:
     -s               Strip contract code to decrease file size.
     -d         Specify destination directory for
                      instrumented files.
     -f         Specify the instrumentation file.
     -v, --verbose    Enable verbose logging.  Prints name of each
                      class as it is instrumented.
     -e, --version    Print version number and exit.

Version:
$Id: jInstrument.java,v 1.36 2003/02/02 11:33:19 parkera Exp $
Author:
Parker Abercrombie, Murat Karaorman
See Also:
jContractor

Field Summary
static java.lang.String JCONTRACTOR_FLAG_CONSTANT
          The prefix of a constant that will be inserted into the constant pool of classes that jInstrument instruments to mark them as instrumented.
static java.lang.String USAGE_MESSAGE
          Usage message to be printed if the command line arguments do not match the specification.
static java.lang.String VERSION
          Constant for the version number that is printed when the --version command line argument is given.
 
Constructor Summary
jInstrument()
          Create a default instance that will check all contracts on all classes, in non-verbose mode.
 
Method Summary
 java.lang.String getDestination()
          Get the destination directory of files written by instrumentClassFile(String).
 InstrumentationFilter getInstrumentationFilter()
          Get the instrumentation filter that determines which classes are instrumented and to what level.
 boolean getVerbose()
          Get the value of the verbose flag.
 byte[] instrumentClass(org.apache.bcel.classfile.JavaClass javaclass)
          Instrument a class to enforce jContractor contracts.
 void instrumentClassFile(java.lang.String classFilename)
          Instrument a class file to enforce jContractor contracts, and write the instrumented file to the directory specified by destination.
static boolean isInstrumented(org.apache.bcel.classfile.JavaClass javaclass)
          Determine if a class has been instrumented.
static void main(java.lang.String[] argv)
          Instrument all the classes specified on the command line.
static void parseInstrumentationFile(java.lang.String filename, CompositeInstrumentationFilter filter)
          Parse an instrumentation file.
static void parseInstrumentationList(java.lang.String packageNames, int instrumentationLevel, CompositeInstrumentationFilter filter)
          Parse a comma separated list of packages to instrument and create instrumentation filters.
 boolean setDestination_Precondition(java.lang.String path, java.lang.Void RESULT)
           
 void setDestination(java.lang.String path)
          Set the destination directory of files written by instrumentClassFile(String).
 void setInstrumentationFilter(InstrumentationFilter filter)
          Set the instrumentation filter that determines which classes are instrumented and to what level.
 void setVerbose(boolean flag)
          Set the value of the verbose flag.
 void stripContracts(java.lang.String classFilename)
          Remove contract methods from a class file, to decrease the file size.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JCONTRACTOR_FLAG_CONSTANT

public static final java.lang.String JCONTRACTOR_FLAG_CONSTANT
The prefix of a constant that will be inserted into the constant pool of classes that jInstrument instruments to mark them as instrumented. The complete constant is formed by appending the class name to this constant. (= "JCONTRACTOR").

See Also:
MarkInstrumentedTransformation, Constant Field Values

USAGE_MESSAGE

public static final java.lang.String USAGE_MESSAGE
Usage message to be printed if the command line arguments do not match the specification.

See Also:
Constant Field Values

VERSION

public static final java.lang.String VERSION
Constant for the version number that is printed when the --version command line argument is given.

See Also:
Constant Field Values
Constructor Detail

jInstrument

public jInstrument()
Create a default instance that will check all contracts on all classes, in non-verbose mode. Instrumented files will be written to the current working directory.

Method Detail

instrumentClassFile

public void instrumentClassFile(java.lang.String classFilename)
                         throws java.io.IOException,
                                InstrumentationException
Instrument a class file to enforce jContractor contracts, and write the instrumented file to the directory specified by destination.

Throws:
java.io.IOException - if there are problems reading from the class file.
InstrumentationException

instrumentClass

public byte[] instrumentClass(org.apache.bcel.classfile.JavaClass javaclass)
                       throws InstrumentationException
Instrument a class to enforce jContractor contracts.

Parameters:
javaclass - a class to instrument.
Throws:
InstrumentationException - if jInstrument is unable to instrument the class.

stripContracts

public void stripContracts(java.lang.String classFilename)
                    throws java.io.IOException,
                           InstrumentationException
Remove contract methods from a class file, to decrease the file size. `stripContracts' does not remove contract checks from instrumented code, it removes the actual contract methods. The goal is to decrease the size of the deployed file, not to undo the instrumentation process. Once a class has been instrumented, it is not possible to remove contract code.

java.io.IOException
InstrumentationException

setInstrumentationFilter

public void setInstrumentationFilter(InstrumentationFilter filter)
Set the instrumentation filter that determines which classes are instrumented and to what level.

Parameters:
filter - the new filter.
See Also:
getInstrumentationFilter()

getInstrumentationFilter

public InstrumentationFilter getInstrumentationFilter()
Get the instrumentation filter that determines which classes are instrumented and to what level.

Returns:
the filter that determines which classes are instrumented.
See Also:
setInstrumentationFilter(InstrumentationFilter)

parseInstrumentationFile

public static void parseInstrumentationFile(java.lang.String filename,
                                            CompositeInstrumentationFilter filter)
                                     throws java.io.IOException
Parse an instrumentation file. The instrumentation file contains class names followed by instrumentation levels, and separated by whitespace. For example: 
   *                                      none
   edu.*                                  pre
   edu.ucsb.ccs.jcontractor.jInstrument   all
This file says the the jInstrument class should be instrumented completetly and the other classes in edu and all subpackages should have precondition checks. Wildcard matching works as in Java import statements, except that the wildcard matches any class in the package or any subpackage. More specific filters override general filters (edu.ccs.jcontractor.jInstrument overrides edu.*).

This method parses the file and creates a PackageLevelInstrumentationFilter for each entry. These filters are appended to a CompositeInstrumentationFilter.

Parameters:
filename - the name of the file to parse. The file must exist and contain text in the format described above.
filter - a CompositeInstrumentationFilter to which filters will be appended. After execution, this filter will include filters to enforce the rules described in the file.
java.io.IOException

parseInstrumentationList

public static void parseInstrumentationList(java.lang.String packageNames,
                                            int instrumentationLevel,
                                            CompositeInstrumentationFilter filter)
Parse a comma separated list of packages to instrument and create instrumentation filters. A PackageLevelInstrumentationFilter will be created for each package, and appended to the composite filter passed into this method.

Parameters:
packageNames - a comma separated list of package names, including class names and possibly wildcards. See the PackageLevelInstrumentationFilter.setPackageAndClass() for details on the accepted format.
instrumentationLevel - the instrumentation level to assign to classes in these packages.
filter - a composite filter to which the new filters will be added.
See Also:
PackageLevelInstrumentationFilter#setClassName(), PackageLevelInstrumentationFilter#setPackageClassName()

setVerbose

public void setVerbose(boolean flag)
Set the value of the verbose flag. jInstrument prints out the names of class files as they are instrumented when this flag is set.

Parameters:
flag - the new value of the verbose flag.
See Also:
getVerbose()

getVerbose

public boolean getVerbose()
Get the value of the verbose flag.

Returns:
the value of the verbose flag.
See Also:
setVerbose(boolean)

setDestination

public void setDestination(java.lang.String path)
Set the destination directory of files written by instrumentClassFile(String).

Parameters:
path - the new destination. If the directory does not exist, it will be created.
See Also:
instrumentClassFile(String), getDestination()

setDestination_Precondition

public boolean setDestination_Precondition(java.lang.String path,
                                           java.lang.Void RESULT)

getDestination

public java.lang.String getDestination()
Get the destination directory of files written by instrumentClassFile(String).

Returns:
the destination for instrumented files written to disk.
See Also:
instrumentClassFile(String), setDestination(String)

isInstrumented

public static boolean isInstrumented(org.apache.bcel.classfile.JavaClass javaclass)
Determine if a class has been instrumented. Classes are marked as instrumented by adding a special constant to the constant pool.

Parameters:
javaclass - a class to test.
Returns:
true if javaclass has already been instrumented.

main

public static void main(java.lang.String[] argv)
Instrument all the classes specified on the command line. The instrumented version of each class is written to the directory given after the "-d" command line argument, or to the current directory if there is no such argument.

Parameters:
argv - command line arguments. These are the names of the class files to instrument.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD