Program Objects

This is a framework built on top of the BCEL bytecode manipulation package. It provides a higher level API, extensive caching of information, etc.

The API is here

Insert more information here!

The package provides classes for manipulating components of a Java program. An application is represented as a hierarchy of program objects. Different objects represent:

An Application object can be exported to produce an executable jar file.

Program objects are built atop the BCEL byte code engineering library and provide wrappers for BCEL methods. Finer-level components such as instruction lists are manipulated by calling BCEL methods directly. Code that makes direct BCEL calls must also call the mark() method of the enclosing program object to inform it of the change.

Program objects support caching by associating a version counter with each object. The counter is incremented automatically by the methods in this package or manually by calling the mark() method. The caching system is used to improve performance by this package and by external packages such as sandmark.metric.

The methods in this package act locally: For example, renaming a method does not alter any references to the method. Some heavyweight methods with global effect are provided in the sandmark.program.util package.

Application Objects

Represents a complete Java program. An Application object is the root of a tree encompassing Classes and all their subcomponents, plus other jar file entries such as images or sound clips. The jar file manifest is part of the application itself and is not a node in the tree.

Here is a simple example that reads a jar file and prints the classes:

    sandmark.program.Application app =
       new sandmark.program.Application("program.jar");
    java.util.Iterator it = a.classes();
    while (it.hasNext()) {
       sandmark.program.Class cls = (sandmark.program.Class) it.next();
       System.out.println("class " + cls.getName());
    }

This example renames the main class and writes a new jar file:

    sandmark.program.Application app =
       new sandmark.program.Application("old.jar");
    sandmark.program.Class c = app.getMain();
    c.setName("Start");
    app.setMain(c);
    app.save("new.jar");
 

Method Objects

Method objects Represent a single method within a class or interface. A Method object embeds a BCEL MethodGen object in a Sandmark program object. Most methods just call the corresponding BCEL method. Modification methods automatically call the mark method to register their changes.

Here is a simple example of how to use the BCEL interfaces. This code adds a NOP instruction at the beginning of each method in a supplied class.

    static void addNOPs(sandmark.program.Class c) {
       sandmark.program.Method[] mlist = c.getMethods();
       java.util.Iterator it = c.methods();
       while (it.hasNext()) {
          sandmark.program.Method m = (sandmark.program.Method) it.next();
          System.out.println(
             "    method " + m.getName() + " " + m.getSignature());
          org.apache.bcel.generic.InstructionList ilist = m.getInstructionList();
          ilist.insert(org.apache.bcel.generic.InstructionConstants.NOP);
          m.mark();
       }
    }