Class dec.trek.ClassFile

A .class file – or classfile – is the executable form of a class. The ClassFile object allows you to manipulate classfiles.

This class does not have a public constructor. To reach a trek’s classfiles, you must use firstClassFile() or lastClassFile() in the Trek class, or override its atStartOf(ClassFile) or atEndOf(ClassFile) methods. You can also add classfiles to a trek using getClassFile and insertClassFile.

Method Summary

  • addInterface – add an interface to this classfile
  • dump – outputs a text representation of this classfile to a file
  • firstField – returns the Field object of the first field of this classfile
  • firstFieldRef – returns the first FieldRef in this classfile's constant pool
  • firstMethod – returns the Method object of the first method of this classfile
  • firstMethodRef – returns the first MethodRef in this classfile's constant pool
  • firstTypeRef – returns the first TypeRef in this classfile's constant pool
  • firstValueRef – returns the first ValueRef in this classfile's constant pool
  • getSize – returns the number of bytes in this classfile
  • getTrek – returns the Trek object this classfile is within
  • hasModifier – returns true if this class has any of the specified access modifiers
  • isAncestor – returns true if this class is an ancestor class of the specified class
  • lastField – returns the Field object for the last field of this classfile
  • lastMethod – returns the Method object for the first method of this classfile
  • next – returns the ClassFile object of the next classfile of this trek
  • prev – returns the ClassFile object of the previous classfile of this trek
  • read – reads a classfile from the specified stream
  • references – returns true if code in this class references the specified member
  • refresh – rereads the classfile into memory if it has changed
  • write – writes the classfile to the specified stream
  • toInterfaces – returns the interfaces that this class implements
  • toName – returns the unqualified name of this classfile
  • toObjectId – returns the object Id of this classfile
  • toPackage – returns the package name of this classfile
  • toQualifiedName – returns the fully qualified name of this classfile
  • toString – returns the source code for the declaration of this classfile
  • toSuperClass – returns the fully qualified name of this classfile’s superclass
  • write – writes the classfile to the specified stream

Fields

public Object userDefined

Field that can be used by an application developer to store arbitrary data about this object during the trek.

Example:

Suppose your trek could reach a classfile more than once. The following code fragment would insure that the classfile’s methods are scanned only once.

if (cf.userDefined!=null) return;
cf.userDefined = new Object();
scanMethodsOf(cf);

Methods

public void addInterface(String interface)

Adds the specified interface to this classfile. This is mainly useful for adding empty interfaces like Serializable.

Parameters:

interface – fully qualified class name to add. Its classfile need not exist yet.

public void dump(int flags)

Outputs the class and member declarations of this classfile to <classname>.dmp in the current directory. Additionally outputs the types of classfile content specified by flags.

Parameters:

flags – 0, or one or more of the DMP constants defined in the Trek class.

public Field firstField()

Returns the Field of the alphabetically first field name defined within this classfile, or null if it has no fields.

public FieldRef firstFieldRef()

Returns the FieldRef of the first field reference in this classfile's constant pool, or null if there are none.

public Method firstMethod()

Returns the Method of the alphabetically first method name defined within this classfile, or null if it has no methods. (Because a classfile’s static initializer method is actually named <clinit> and its constructors are actually named <init>, they are always at the front of the list).

public MethodRef firstMethodRef()

Returns the MethodRef of the first method reference in this classfile's constant pool, or null if there are none.

public TypeRef firstTypeRef()

Returns the TypeRef of the first class or array reference in this classfile's constant pool, or null if there are none.

public ValueRef firstValueRef()

Returns the ValueRef of the first value constant in this classfile's constant pool, or null if there are none.

public long getSize()

Returns the number of bytes in this classfile

public Trek getTrek()

Returns the Trek object that this classfile is within

public boolean hasModifier(int flags)

Returns true if the classfile’s class was declared with any of the specified by flags.

Parameters:

flags – one or more of the ACC constants defined in the Trek class.

Example:

For a program containing:

private static myclass extends Object {…}

The following code in a Trek application would set acc to true.

ClassFile cf = myclass’s ClassFile object;
boolean acc = cf.hasModifier(ACC_STATIC|ACC_PUBLIC)

public boolean isAncestor(ClassFile cf)

Returns true if this is one of the superclasses of the specified class, and false if it is not. However if isAncestor cannot access a classfile that is needed to help make this determination, an exception is thrown.

Parameters:

cf – the ClassFile to check

public Field lastField()

Returns the Field of the alphabetically last field name defined within this classfile.

public Method lastMethod()

Returns the Method of the alphabetically last method name defined within this classfile.

public ClassFile next()

Returns the ClassFile of the alphabetically next classfile in the trek.

public ClassFile prev()

Returns the ClassFile of the alphabetically previous classfile in the trek.

public static ClassFile read(DataInputStream stream, Trek trek)

Reads a classfile from the specified stream and returns a ClassFile object for it. But if there is an error reading or interpreting data in the stream, an exception is thrown instead.

The returned ClassFile is freestanding; it is neither cached in the trek nor inserted into the trek's list of classes. So if and when you clear all your references to it, it will be garbage collected. However you can insert the returned ClassFile into a trek's class list by calling insertClassFile.

Parameters:

stream – the stream to read from

trek – this trek is made the parent of the created ClassFile object

public boolean references(Member mem)

Returns true if this classfile has code that uses the specified field or method.

Parameters:

mem – the Method or Field object to check. (Member is the superclass of these two classes).

public boolean refresh()

Checks the time of last modification of the classfile, and rereads it if it has changed since the last time it was read in. This includes the case of a new file being in an earlier directory of the classpath.

Any unsaved instrumentations are lost when a classfile is reread. Conversely the classfile is marked as unmodified.

References to the ClassFile object itself remain valid. However if you have cached a reference to any code object within the classfile, the cached reference is now invalid and must be updated or discarded.

public String[] toInterfaces()

Returns an array containing the fully qualified name of each interface that this class implements. If this class implements no interfaces, the returned array's size is 0.

public String toName()

Returns the unqualified name of this classfile’s class (eg. Trek).

public String toObjectId()

Returns a persistent value that identifies this classfile. A reference to this classfile can be acquired by calling getObject on a trek that this classfile is within.

public String toPackage()

Returns the package of this classfile’s class. If the class is not in a package, it returns the null string.

public String toQualifiedName()

Returns the fully qualified name of this classfile’s class (eg. dec.trek.Trek).

public String toString()

Returns the source statement that defined this classfile’s class.

public String toSuperClass()

Returns the fully qualified name of this classfile’s superclass. If this classfile has no superclass, it returns null.

public void write(DataOutputStream stream, boolean clean)

Writes the classfile to the specified stream, and marks its in-memory representation as unmodified.

Parameters:

stream – the output stream to write to

clean – true says to remove all changes made to the classfile's in-memory representation

Example:

This method can be used in conjunction with a class loader:

ByteArrayOutputStream bst = new ByteArrayOutputStream();
DataOutputStream dst = new DataOutputStream(bst);
classfile.write(dst, false);
String name = classfile.toQualifiedName();
byte data[] = bst.toByteArray();
classloader.defineClass(name, data, 0, data.length);