Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

edu.ucsb.ccs.jcontractor
Class jInstrument  view jInstrument download jInstrument.java

java.lang.Object
  extended byedu.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.37 2003/02/11 08:06:09 parkera Exp $

Field Summary
protected  java.lang.String destination
          A directory to which instrumented files will be written by the instrumentClassFile(String) method.
protected  InstrumentationFilter instrumentationFilter
          An instrumentation filter that determines which classes are instrumented, and to what level.
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.
protected  edu.ucsb.ccs.jcontractor.transformation.ClassTransformer transformer
          A ClassTransformer used to instrument class files.
static java.lang.String USAGE_MESSAGE
          Usage message to be printed if the command line arguments do not match the specification.
protected  boolean verbose
          Flag to specify that output should be verbose.
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).
protected  boolean getInstrumentationFilter_Postcondition(InstrumentationFilter RESULT)
           
 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.
protected  boolean instrumentClass_Precondition(org.apache.bcel.classfile.JavaClass javaclass)
           
 byte[] instrumentClass(org.apache.bcel.classfile.JavaClass javaclass)
          Instrument a class to enforce jContractor contracts.
protected  boolean instrumentClassFile_Precondition(java.lang.String classFilename)
           
 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.
protected static boolean isInstrumented_Precondition(org.apache.bcel.classfile.JavaClass javaclass)
           
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.
protected static boolean parseInstrumentationFile_Postcondition(java.lang.String filename, CompositeInstrumentationFilter filter)
           
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).
protected  boolean setInstrumentationFilter_Postcondition(InstrumentationFilter filter)
           
 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.
protected  boolean stripContracts_Precondition(java.lang.String classFilename)
           
 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
clone, equals, finalize, 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:
edu.ucsb.ccs.jcontractor.transformation.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

verbose

protected boolean verbose
Flag to specify that output should be verbose. Set when the -v command line argument is present.


instrumentationFilter

protected InstrumentationFilter instrumentationFilter
An instrumentation filter that determines which classes are instrumented, and to what level. Defaults to instrumenting all classes to the fullest (level InstrumentationFilter.ALL).


destination

protected java.lang.String destination
A directory to which instrumented files will be written by the instrumentClassFile(String) method. Defaults to the current working directory.

See Also:
instrumentClassFile(String) 55

transformer

protected edu.ucsb.ccs.jcontractor.transformation.ClassTransformer transformer
A ClassTransformer used to instrument class files.

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.


instrumentClassFile_Precondition

protected boolean instrumentClassFile_Precondition(java.lang.String classFilename)

instrumentClass

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


instrumentClass_Precondition

protected boolean instrumentClass_Precondition(org.apache.bcel.classfile.JavaClass javaclass)

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.


stripContracts_Precondition

protected boolean stripContracts_Precondition(java.lang.String classFilename)

setInstrumentationFilter

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


setInstrumentationFilter_Postcondition

protected boolean setInstrumentationFilter_Postcondition(InstrumentationFilter filter)

getInstrumentationFilter

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


getInstrumentationFilter_Postcondition

protected boolean getInstrumentationFilter_Postcondition(InstrumentationFilter RESULT)

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.


parseInstrumentationFile_Postcondition

protected static boolean parseInstrumentationFile_Postcondition(java.lang.String filename,
                                                                CompositeInstrumentationFilter filter)

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.


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.


getVerbose

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


setDestination

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


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


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.


isInstrumented_Precondition

protected static boolean isInstrumented_Precondition(org.apache.bcel.classfile.JavaClass javaclass)

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.