JIG Browser Documentation, continued

Special Topics

File Maintenance

Loading files with mismatched braces can cause problems when the Browser attempts to parse class and method definitions. If loading class files into the Browser for the first time, make sure braces match and the file is in good syntactic order. The Browser checks for mismatched braces when saving so class definitions or methods cannot be saved with mismatched braces.

Transcript

The output screen for the Java operation or Transcript displays all standard output from the Java process asynchronously mixed with error output from the process. Standard input is not accepted by this read-only process screen.

Reference Browser Decay

Reference Browsers including References, Callers, Methods and Stack Trace rely on "snap-shot" information about the state of class files. As development continues this snap shot slowly becomes out of date. For this reason, reference Browsers should be used briefly and carefully, and updated periodically or discarded when they are no longer needed. To remind the user about the temporal nature of the reference Browsers, an optional ",…update?" suggestion can be applied to the Browser window title when the Browser detects that the information it contains is not necessarily current. See View Options Suggest update for more information.

Inner Classes

The display of inner classes is handled in the class list of the Browser by displaying the inner class name slightly indented and listed just below the name of the class containing it, referred to as the "outer" class. The inner class is not shown on the class list of the Browser until the outer class is selected. This is because the Browser class list is initially a list of class files found in the package-directory. The inner class is revealed once the outer class is selected and parsed by the Browser. Another kind of class in the class file but outside the definition of the outer class is referred to as an "extra" class. These extra classes, when revealed, are listed with a plus sign (+) before the extra class name, and are shown in proximity to the outer class on the Browser class list.

From within a class or hierarchy browser, an outer class when selected will not reveal its inner (or extra) classes. System, references, callers, etc., browsers (with packages) will reveal inner (or extra) classes. If in a class or hierarchy browser and you need to see inner (or extra) classes, from the class definition highlight the two words "class [class name]," where [class name] is the name of the class selected, and choose Browse References. A references browser will open allowing selection of outer, inner and extra classes, or go to a System Browser to see a complete rendering of classes and methods.

Applet Viewer

Applet Viewer will take a highlighted string for the name of the URL. The name must contain the protocol, e.g., file:c:\src\test.html, http://server/test.html. If the highlighted string is a "file:" protocol and contains no file delimiters (per the Java system property), the current user directory and currently selected package will be used to create a path to the html file. E.g., if within the package "Work.Test", package root directory "c:\java\src", and the string "file:App2.html" is highlighted, the URL is constructed: file:c:\java\src\Work\Test\App2.html.

File Applet View and Debug will start up the debugger and load an HTML file invoking an applet. With a class selected, when the debugger is invoked, the debugger will attempt to load the class, set a break point at the init() method and run.

Compiling Java

It is possible to compile multiple files across multiple directories if relative or absolute directory paths are included with the java file names. E.g.,

User's current working directory:

c:\jdk1.1.6\src\Work

File specs to compile:

..\Project\QueueManager.java ..\Project\Generated\*.java

or,

c:\jdk1.1.6\src\Project\QueueManager.java c:\jdk1.1.6\src\Project\Generated\*.java

To compile multiple files in one or more directories, use the Workspace, create the relative or absolute path specification for the files to compile, highlight, the file specs and select File Compile from the menu.

To place the compiled .class files in a different directory than the current one, use the View Options Destination directory parameter to specify the relative (to the package root directory) or absolute path for the destination. A second -d parameter in the View Options Compile options is not accepted by some compilers.

When compiling classes having explicit package names, the class file output will by default be written to a directory below the source directory named for the package, even though the source may currently be in a directory named for the package. So, for a package named Samples, you might see a directory:

c:\jdk1.1.6\src\Work\Samples\Samples

containing the class files. This is because JIG provides a default target directory for compiled classes of the current directory of the source file. An alternative to this default behavior would be to provide an explicit View Options Destination directory parameter to the compiler to place the class files elsewhere. For example, to store the class files in c:\jdk1.1.6\lib use the View Options Destination directory of:

c:\jdk1.1.6\lib

For the package "Samples," this would create the directory:

c:\jdk1.1.6\lib\Samples

and place the class file there.

To work in multiple JDK environments, like JDK1.1.6 most of the time and JDK1.2beta4 some of the time. Put the most used JDK bin, say for example JDK1.1.6/bin, on your path, then provide an Options, Optional CLASSPATH and explicit (absolute path) names for the java, javac, jdb binaries for the JDK1.2beta4 environment. These can even be put in a special jig.properties file used to start JIG when working with the "sometimes" environment. A different "jig.properties" file can be specified as a command line parameter (-i param) to JIG. It can contain a different name or a relative path (relative to JIG Home) and different name.

To use jdk1.2 tools (java, jdb, javac) in this case, set absolute paths for each tool in View Options Other options, e.g.,

compiler="c:\jdk1.2beta4\bin\javac"
debugger="c:\jdk1.2beta4\bin\jdb"
interpreter="c:\jdk1.2beta4\bin\java"

Implicit Compile

The implicit compile capability of JIG is used when invoking the Run or Debug commands in the File menu. A check is made to see whether the java file has been changed and is later than the class binary file, or if a class binary file exists. An automatic compile/recompile will occur if necessary. The implicit compile will occur only if a single class is selected in the class list of the Browser when the Run or Debug operation is selected.

Debugger

In Debugger, if trying to set a "stop in" the constructor for the class, try usining <init> if it doesn't accept the constructor method name.

Judicious use of accessors for all class variables provides a means to set breakpoints on access of those variables from within the Debugger.

The Debugger makes an educated guess about what class it has stopped in by taking the first word token returned from a "toString()" method for the value of "this." This name can then be suggested by the Debugger when clicking on the "stop in" and "stop at" buttons. The default Object.toString() returns "classname@address." When coding a toString() method for your class, including the class name as described here can make your debugging session more efficient.

Runtime Environment

The Java runtime jre 1.1.6 is delivered with JIG.

JIG Startup

JIG accepts two command line parameters on startup.

The -j parameter will set the JIG Home directory, the place where JIG looks for property files and documentation to be the user specified directory. E.g.,

C:\JIG\Jre\1.1\bin\jrew.exe -cp .;lib\jig.jar BrowserView -j c:\jdk1.1.6\src\Work

The -i parameter specifies a file or location and file to use other than the jig.properties file found in the JIG Home directory. E.g., to specify a jig.properties file in a subdirectory of the JIG Home directory,

C:\JIG\Jre\1.1\bin\jrew.exe -cp .;lib\jig.jar BrowserView -i jdk1.2\jig.properties

License File

A license file, jig.lic, is included for registered users. This file contains the registered user identification number (ID) , name and address information, as well as, the number of users for which the license is granted.

Regular Expressions

Many of the Browse operations, References, Callers, etc., use the operating system grep utility. The grep regular expressions for each of the operations are in the re.properties file.

Internationalization

A locale file of string properties, making JIG I18n compliant, is provided with your JIG installation. The file is locale_en_US.properties. As other locale files become available they can be selected in View Options Other options, the countryCode (e.g., US) and languageCode (e.g., en) properties are stored in the jig.properties file.

Sample Development Utilities

Sample utilities are provided both as a means of demonstrating JIG and for their potential use in development. These utilities include:

For more information on these utilities see the documentation provided in the Samples directory.

Miscellaneous

Be careful when selecting text in a Browser. For instance, select a class from the class list, then highlight some text in the Browser editor, perhaps to Browse References, then select Run from the File menu. You will probably see a java error message in the Transcript that the class file for your highlighted text could not be found. The Run operation works by first checking highlighted text, failing that it uses the currently selected class.

When a period occurs in a directory name as part of a package appearing in the Browser, special handling is required to distinquish the period within the directory name from the period separating package names. To display packages with embedded periods, a colon is substituted for the period in the package name for display purposes only.

The compile/run process looks for the word "error" in the compile process output dialog. If your class name has the word "error" (case sensitive) in it, the run step may not automatically follow the compile step.

The incorrect use of keywords can throw JIG off, especially the incorrect use of the keyword "class." Your Java source will not compile with incorrectly used keywords, and JIG is expecting them to be used in the correct context.

If after a long session in JIG, JIG function seems to be slowing down select Help About, and click OK. This will run a garbage collect within JIG.

Please post the complete error results and full problem description for any problems encountered with Jig to the Jig website, http://www.scubed.cc.

Note: Before you use JIG, please read the Copyright and License Information.


JIG is a product of S Cubed.

The JDK is a product of Sun Microsystems, Inc. JavaSoft is the operating company of Sun that develops the JDK.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Visual J++ is a product of Microsoft, Inc.

Copyright © 1998 S Cubed