Class dec.trek.TrekThe Trek class allows you to set the properties of a trek, navigate the objects of a program, and manage a trek. Coding a simple Trek application often involves no more than subclassing the Trek class and writing a single page of code. At the other extreme, you can code a GUI Trek application that can process multiple programs, do different kind of treks, and store persistent state between usages. Method Summary
MethodsConstructs an uninitialized Trek object. See setXxx, getCmdLine, initTrek, and doTrek for how to initialize a trek. Does nothing. If you call doTrek, it is called at the end of the trek. You should define this method in a subclass of Trek if you wish to perform an action at the end of the trek. protected void atEndOf(ClassFile cf) Does nothing. If you call doTrek, it is called for each classfile after all its fields and methods have been scanned. You should define this method in a subclass of Trek if you wish to perform an action after each classfile is scanned. Parameters: cf identifies the classfile that was just scanned protected void atEndOf(Method method) Does nothing. If you call doTrek, it is called for each method after all its locals and statements have been scanned. You should define this method in a subclass of Trek if you wish to perform an action after each method is scanned. Parameters: method identifies the method that was just scanned protected void atEndOf(Statement stmt) Does nothing. If you call doTrek, it is called for each statement after all its instructions have been scanned. You should define this method in a subclass of Trek if you wish to perform an action after each statement is scanned. Parameters: stmt identifies the statement that was just scanned Does nothing. If you call doTrek, it is called at the start of the trek. You should define this method in a subclass of Trek if you wish to perform an action at the start of the trek. protected void atStartOf(ClassFile cf) Does nothing. If you call doTrek, it is called for each classfile before its fields and methods are scanned. You should define this method in a subclass of Trek if you wish to perform an action before each classfile is scanned. Parameters: cf identifies the classfile that is about to be scanned protected void atStartOf(Method method) Does nothing. If you call doTrek, it is called for each method before its locals and statements are scanned. You should define this method in a subclass of Trek if you wish to perform an action before each method is scanned. Parameters: method identifies the method that is about to be scanned protected void atStartOf(Statement stmt) Does nothing. If you call doTrek, it is called for each statement before its instructions are scanned. You should define this method in a subclass of Trek if you wish to perform an action before each statement is scanned. Parameters: stmt identifies the statement that is about to be scanned protected void at(Field field) Does nothing. If you call doTrek, it is called for each field as it is scanned. You should define this method in a subclass of Trek if you wish to perform an action as each field is scanned. Parameters: field identifies the field that is being scanned protected void at(Instruction inst) Does nothing. If you call doTrek, it is called for each instruction as it is scanned. You should define this method in a subclass of Trek if you wish to perform an action as each instruction is scanned. Parameters: inst identifies the instruction that is being scanned protected void at(Local loc) Does nothing. If you call doTrek, it is called for each local variable as it is scanned. You should define this method in a subclass of Trek if you wish to perform an action as each local variable is scanned. Parameters: loc identifies the local variable that is being scanned protected void atReference(ClassFile cf, Member mem) Does nothing. If you call doReferences, it calls atReference for each classfile that references the specified member. If mem identifies a method, this means that the method is defined or invoked by cfs class. If mem identifies a field, this means that the field is fetched or modified by cfs class. You should define this method in a subclass of Trek if you wish to perform an action for each classfile that references mem. Parameters: cf identifies a classfile that references mem mem a Field object or a Method object Example: Calling doReferences(fld) would cause the following atReference method to display each statement where fld is used. protected atReference(ClassFile cf, Member mem) { . for (Method meth=cf.firstMethod(); cf!=null; cf=cf.next()) { . . for (Statement st=meth.firstStatement; st!=null; st=st.next()) { . . . if (st.references(mem)) System.out.println(st.toString()); } } } public void atVerbose(String msg) Outputs the specified message to System.out. This method is called periodically during a trek when verbose mode is enabled - unless you provide your own implementation of atVerbose. For example, to maintain a status line in a GUI trek application, you would need to provide your own implementation of atVerbose. To use your own implementation of atVerbose: (1) subclass the Trek class or (2) define a class that implements dec.trek.VerboseSink (atVerbose is the only method in this interface) and call setVerboseSink. Parameters: msg the verbose message to process Removes all changes made to the in-memory representations of the trek's classfiles, and marks each classfile as unmodified. If you have an application in which you can delete changes as well as insert them, you can use cleanTrek to support this. That is, rather than removing changes from your instrumented program, you can: (1) maintain a change-description list, and insert and remove change-descriptions from it, (2) apply the changes currently in the change-description list whenever you need to write out your modified classes, and (3) call saveTrek and cleanTrek after you apply these changes. public void doReferences(Member mem) Calls atReference for each classfile that references the specified member. Parameters: mem a Field object or a Method object Scans all the classfiles, fields, methods, locals, statements, and instructions in the scope of the trek. If initTrek has not been called, it calls initTrek before starting the scan and endTrek after completing the scan. If the trek has an empty class list, an exception is thrown. To perform actions during the trek, you need to override the appropriate atXxx methods in the Trek class. Thus doTrek should only be invoked on an object whose class subclasses the Trek class. public void doTrek(int level) Scans from level 1 thru the specified level. Classfiles are at level 1; fields and methods are at level 2; locals and statements at level 3, and instructions at level 4. Thus calling doTrek(4) is equivalent to calling doTrek(). Parameters: level highest level to scan thru If the trek is active, this method does a saveTrek and frees the resources used in the trek. Calling endTrek for an inactive trek simply does nothing. If called during an automatic scan (ie. from an atXxx method called by doTrek), the rest of the objects in the trek are skipped. public void endTrek(int level) If called during an automatic scan , ends processing of the current object at level. If the specified level >= the level of the innermost current object, processing of the innermost object is ended. For example, if you call endTrek(1) from atStartOf(ClassFile cf), cf's methods and fields will not be scanned and atEndOf(cf) will not be called. If the specified level is < the level of the innermost current object, processing of the encompassing object is ended. For example, if you call endTrek(2) from atEndOf(Statement stmt), the rest of the statements and local variables in stmt's method will not be scanned and atEndOf(its method) will not be called.
public ClassFile findClassFile(String name) If the specified class identifies a classfile that is in the trek's class list or has been cached in the trek, its ClassFile object is returned. Otherwise null is returned. A classfile gets cached in a trek when you do a getClassFile. A classfile will also be cached if data within it is needed. For example, if you do ances.isAncestor(descen), superclasses of descen are accesed to determine if ances is an ancestor of descen. If any of these classfiles are not already in memory, isAncestor will read them. Parameters: name the fully qualified class name of the classfile to access public ClassFile firstClassFile() Returns the ClassFile object for the classfile in the trek whose class is alphabetically first. If the trek has not been initialized yet, null is returned instead. public ClassFile getClassFile(String name) Returns the ClassFile object of name, or throws an exception. This method calls findClassFile to see if the classfile is already in memory. If that returns null, it tries to read name's classfile by looking in the directories of the trek's input path. If that fails, it throws an exception. If the classfile has to be read, it is cached in the trek but not inserted into the trek's list of classfiles. Thus a doTrek or classfile.next scan will not process this classfile until you do an insertClassFile. Secondly, repeatedly doing getClassFile(name1) will read name1 at most once. Parameters: name the fully qualified class name of the classfile to access public void getCmdLine(String argv[]) Parses the specified Trek application command line. Processes base-classes, and the debug, -ip, -op, -sc, and -verbose switches, and calls getCmdLineArg for any other word on the command line. So if your application has any arguments and switches unique to it, you should override getCmdLineArg. If the user's command line does not contain base-classes or if a common switch is incorrectly specified or if an application-specific argument is incorrectly specified (see getCmdLineArg), a TrekException is thrown. If your application is not a console application, you can use setDebugMode, setClassList, SetOutPath, and setVerboseMode to set the Trek properties that getCmdLine sets for you automatically. Parameters: argv each string in the array contains a word of the command line. A word consists of non-blank characters. protected int getCmdLineArg(String argv[], int curr) Returns 0, which causes getCmdLine to throw a TrekException. If your application has any arguments unique to it, you should override this method. If your getCmdLineArg accepts the argument passed to it, it should return curr + number of words parsed. Otherwise it should return 0. Parameters: argv each string in the array contains a word of the command line. A word consists of non-blank characters. curr the index of the word in argv to start processing with Returns the Method object for the main classs main method if any. Else returns null. A trek's main class is the first class in its base classes property. public static int getModifiers(String flaglist) Returns the acc flags corresponding to the access modifiers in flaglist. Parameters: flaglist one or more of the Java access modifiers, like private and final, separated by semi-colons public Object getObject(String objid) Returns the classfile, method, field, local, or statement corresponding to the specified object Id. If the Id does not correspond to any accessible program object, null is returned instead. An object Id is acquired by calling object.toObjectId(). Parameters: objid the object Id of the program object being sought public Object getObject(String variable, Instruction wrt) Returns the Local, Field or Method object identified by the specified variable reference, or throws an exception if variable identifies no code object. The leftmost name in the variable reference may be: (1) a local variable active at this instruction, (2) a static member of this instructions class, (3) a non-static member of its class if its method is not static, or (4) /each/package/piece/class/name, which means a member of the specified class.
Parameters: variable the variable reference to look up wrt the variable reference is evaluated with respect to this instruction public Object getObject(String variable, Statement wrt) Returns the Local, Field or Method object identified by the specified variable reference, or throws an exception if variable identifies no code object. For this method, the leftmost name in the variable reference may be: (1) a local variable active at this statement, (2) a static member of this statements class, (3) a non-static member of its class if its method is not static, or (4) /each/package/piece/class/name, which means a member of the specified class. Parameters: variable the variable reference to look up wrt the variable reference is evaluated with respect to this statement public static int getVersion() Returns the version number of the Trek class library. This number increases for each new version. Thus it can be used to check if the library being invoked has some minimum version, for example. Reads all the classfiles within the scope of the trek, as defined by the Trek objects base classes, input path, and scope properties. However if the trek has already been initialized, an exception is thrown. The initial value of the base classes property is "none". The initial value of the input path property is the JVMs current classpath. The initial value of the scope property says to scan only the base classes (ie. no recursion). These properties can be set by calling setClassList (possibly via getCmdLine). initTrek reads at least the classes specified in base classes.
When initTrek tries to open a classfile, it looks in the directories in input path, left to right. If the classfile is not found in any of these directories, an error is reported: public void synchronized insertClassFile(ClassFile cf) Inserts the specified classfile into the trek. The classfile is inserted in the trek's classfiles according to the alphabetical position of its name. Thus if you call this method in the middle of a scan of a trek's classfiles, cf will be processed by the in-progress scan only if you are not past cf's name in your scan. Parameters: cf identifies the classfile that should be inserted in the trek public void joinTrek(Trek trek) Makes the current trek have the same program objects as trek. This allows you to combine multiple doTrek-based classes into one application. In other words, trek has its own atXxx methods and each of its sub-treks has its own atXxx methods, but they all share the same classfiles. Parameters: trek the main trek to join, or null to unjoin public ClassFile lastClassFile()Returns the ClassFile object for the classfile whose class is alphabetically last. If the trek has not been initialized yet, null is returned instead. public static String nextItem(String list, int currpos[]) Returns the next item of the list. If list is 0-length or there are no more items in it, null is returned instead. Parameters: list a String containing items separated by semi-colons (eg. "abc" or "1st;2nd"). However a semi-colon preceding by a backslash, or between double quotes or single quotes, will not be treated as the end of an item. currpos a 2-item array that should contain (0, 0) on the 1st call. Thus int cp[] = new int[2] can be used to initialize this argument. Writes out any classfiles that are marked as modified, and marks them as unmodified. Modified classfiles are written to the directory identified by the Trek objects output path property. The initial value of the output path property is the current directory. This property can be set via setOutPath or via getCmdLine. To write modified classfiles and then restore their in-memory representations to their original state, call cleanTrek after calling saveTrek. public void synchronized setClassList(String basecl, String inpath, String sco) Sets the Trek objects base classes, input path, and scope properties from the specified strings. As initTrek describes, these properties tell initTrek which classfiles to read in and where to look for them. Parameters: basecl base classes is set to the specified value. It should be null, 0-length, or a list of properly-cased fully qualified class names, separated by semi-colons. If it is empty, you must use getClassFile and insertClassFile (or repeat setClassList with a non-empty value) before using doTrek. If it is non-empty, the leftmost classfile is used to set the Trek objects main class property which getMainMethod uses to find the program's main method. inpath if null or 0-length, input path is set to the Java virtual machines classpath. Otherwise it should be a list of locations, separated by semi-colons. A location can be "." (which means the current directory), a directory spec, or the filespec of a .jar or .zip file. Also the last location can be "+", which means append the JVMs classpath. sco if null or 0-length, scope is set to self. Otherwise it must contain pkg, p1, user, u1, or all, and scope is set to the specified value. Example: Setting the input path property to .;\xxx\classes;\java\lib\classes.zip would cause initTrek to first look in the users current directory, then in \xxx\classes, and finally in \java\lib\classes.zip when it tries to read in a classfile. public void synchronized setClassList(String trekid) Sets the Trek objects base classes, input path, and scope properties from the specified trek ID. Parameters: trekid the ID (previously acquired using Trek.toObjectId()) to use in restoring a trek's class list public void synchronized setClassOrder(int order) Sets the order in which classes are stored and processed in a trek. Note that class order must be set before the trek is initialized. If this method is not called for a trek, classes are ordered by class. Ordering by package means that classes are sorted by their fully qualified class names. Ordering by class means that classes are sorted by their unqualified class names, and package is only a minor sort key. Parameters: order Trek.CLORD_BYCLASS or Trek.CLORD_BYPACKAGE. public void setDebugMode(boolean onoff) Sets debug mode on or off. When debug mode is on, a stack trace is output to the error stream when you call toErrorMessage. Similarly, a stack trace is output to the log stream when the Trek package logs an error. Parameters: onoff turns debug mode on if true, and turns debug mode off if false. public void
setLogStream(PrintStream stream) Sets where logging messages are output to. The log is closed and the log stream property is cleared by endTrek, so the setting only applies to the current trek. If not called for a trek, messages are logged to current-directory/trek.log. Parameters: stream where to send log messages to public void setOutPath(String outpath) Sets the Trek objects output path property to the specified directory. This property controls where modified classfiles and classfile dumps are written out to. Parameters: outpath the string to set the output path property to. If null or 0-length, the property is set to the current directory. public void setVerboseMode(boolean onoff) Sets verbose mode on or off. When verbose mode is on, trek progress report messages are output via atVerbose. Parameters: onoff turns verbose mode on if true, and turns verbose mode off if false. public void setVerboseSink(VerboseSink sink) Sets the supplier of the VerboseSink interface (ie. the atVerbose method) to the specified object. If null, it makes the current Trek object the supplier object. Parameters: sink an object of a class that implements VerboseSink, or null public String toErrorMessage(Throwable e) Returns a string about the specified error. If the error has been logged in trek.log, the string contains the processing context that existed when the error occurred. Otherwise it contains the error message for the error. Parameters: e the error to process Returns a formatted string containing the Treks base classes, input path, and scope. Returns a string that can be used to restore a trek class list, or null if the trek's class list is unknown. Use setClassList(trekid) to restore the class list. public static String toVersion() Returns the version of the Trek class library, in the form: T or V major.minor.fixkit. T is for preliminary kits, and V is for released kits.
|