## jclasslib bytecode viewer help

### ej-technologies GmbH, Ingo Kegel, 2003-08-20

## Sponsor

The development of the jclasslib bytecode viewer is sponsored by ej-technologies GmbH.

- If you are working with Java bytecode, you might also be interested in JProfiler, an all-purpose Java profiling suite.

- If you have to deploy Java GUI or server applications, you might also be interested in install4j, a multi-platform Java installer builder.

## Purpose

jclasslib is a Java class file library that can be used to read, modify and write class files. The jclasslib bytecode viewer displays class files and bytecode and lets you navigate through the class file structure in a browser-like fashion. While the bytecode manipulation part is of interest to developers with specialized development targets such as obfuscators, compilers or code completion engines, the bytecode viewer is a standalone application which is useful for anyone trying to understand the java virtual machine.

## Installing the jclasslib bytecode viewer

### Requirements

To run the jclasslib bytecode viewer you need a Java 1.4 runtime environment or higher, available at http://java.sun.com/j2se/.

### Installing from binary distribution

The jclasslib bytecode viewer is provided as a Windows installer or as a gzipped tar archive. Besides unpacking it at a suitable location, no further steps are necessary for the installation. Specifically, no external libraries and classpath settings are necessary.

### Installing as Netbeans module

To install the bytecode viewer as a Netbeans module, double click on `jclasslib.nbm` in Windows, or perform the following steps in the Netbeans IDE: Tools->Update Center and select [Install Manually Downloaded Modules (*.nbm files)]. Add the file `jclasslib.nbm` in the next step and complete the remaining steps of the installation wizard.

### Building jclasslib from source

To build jclasslib, you need the ant build tool (>= 1.5) available at http://ant.apache.org/. If you want to build this documentation, you have to install the dcobook DTD and stylesheets. This is done in three steps:

1. Create a directory `docbook` in `doc/src` under the jclasslib root. In this new directory, create the subdirectories `dtd` and `stylesheets`.

2. download the Docbook XML DTD version 4.1.2 from http://www.oasis-open.org/docbook/xml/index.shtml and unpack contents of this zip file directly to the `dtd` directory created in step 1.

3. download the Docbook XSL stylesheets from http://sourceforge.net/project/showfiles.php?group_id=21935 and unpack the zip file to the `stylesheets` directory created in step 1. Rename the first directory which contains all the other files to `docbook`.

The following ant targets are used for building jclasslib:

ant target | purpose
--- | ---
compile (default) | compile java files to the `build` directory
jar | create jar file in the `build` directory
doc | build this documentation in the `doc` directory
javadoc | build the javadoc documentation in the `doc/api` directory
dist | build a distribution of jclasslib in the `dist` directory. The distribution is created with install4j available at http://www.ej-technologies.com/products/install4j/overview.html.
clean | cleans all generated files and directories

## The bytecode viewer

### Starting the bytecode viewer

Application launchers for Microsoft Windows (`jclasslib.exe`) and UNIX (`jclasslib`) are available. The bytecode viewer can also be run by entering

`java -jar jclasslib.jar`

at the command line with the current director at the jclasslib root. If you want to use the jclasslib bytecode viewer with the default look and feel instead of the native look and feel, pass the VM parameter `jclasslib.laf.default=true` to the application. For the Windows launcher, this is done by passing `-J-Djclasslib.laf.default=true` as an argument.

As an argument, you can pass either the path of a workspace file or the path of a single class file to be opened on startup.

### Using the bytecode viewer

The bytecode viewer allows you to open class files and jar archives (not java files!) with File->Open class file. Class files will be displayed in child windows which are initially maximized. If you select a jar file, a tree will be displayed which lets you to select a class contained within the archive. As you open class files, the classpath will be automatically updated. You can edit the classpath by choosing Classpath->Setup classpath. You can also choose a class from the currently configured classpath by choosing Classpath->Browse classpath and selecting the desired class from the classpath tree. The classpath for a new workspace initially consists of the runtime library of the JRE that is used to run the bytecode viewer.

The currently configured classpath, the currently opened classes, the window positions and the currently selected detail panes for each class constitute a workspace. Workspaces can be saved and loaded with the File->Save workspace and File->Open Workspace actions. A list of the 10 last used workspaces is displayed in the File+Reopen Workspace menu.

As you navigate through constant pool entries and branch offsets in a class, the backward and forward actions will become available. In this way, you can for example examine the details of a constant pool entry and then easily return to the bytecode you were looking at. If you recompile the class while having it opened in the bytecode viewer, you can reload the class file with Browse->Reload (CTRL-R).

The information contained in a class file are accessible via the tree in the left side of the window, closely mirroring the structures as defined in the Java virtual machine specification. The panel to the right side of the tree displays details contained in the selected structure. Green underlined entries are hyperlinks, which lead to a different structure in the tree or to a different offset in a code structure. Red entries - prefixed by verbose explanations in normal font - are values contained in a particular fields of a structure.

The detail view of any attribute structure is always composed of two areas:

- The generic info pane showing fields that apply to all attribute structures.

- The specific info pane showing fields that apply only to the specified attribute structure.

The main sections of the class file structure tree are:

General Information

  All fields without sub-structure directly contained in the class file structure.

Constant pool

  The runtime constant pool of the class file. All entries are named as suggested in the Java virtual machine specification and are hyperlinked where appropriate. For class references, method references, interface method references and field references a [Show] button is displayed that displays the referenced class or class member. If the referenced class is not the currently displayed class, the bytecode viewer will try to locate the class in the currently configured class path and open it in a new window. If the class is already opened, the existing window will be activated. If the class can not be located, you get a chance to edit the classpath and try again.

Interfaces

  All interfaces which are implemented by the class described by the class file numbered from `0` to `n - 1`.

Fields

  All fields of the class described by the class file.

Fields

  All fields of the class described by the class file. Fields entries may themselves be nodes and contain a `ConstantValue` attribute.

Methods

  All methods of the class described by the class file. Method entries contain at least a `Code` attribute. The specific info part of the detail view of a code attribute contains a tabbed pane with 3 tabs showing

  - the bytecode in a somewhat modified assembly notation like the one produced by javap. The left gutter shows line numbers in small font. The red numbers at the start of each line show the byte offset of the opcode in the current method. Constant pool entries are hyperlinks denoted as `#nnn`, links to other offset such as in branching instructions are hyperlinks denoted as `nnn`.

  - the exception table pertaining to the bytecode.

  - other fields of the code attribute structure without further sub-structure.

  The `Code` attribute usually contains other attributes itself and is therefore a node in the tree.

To understand the meaning of the classfile structure, its substructures and the bytecode itself, it is useful to have the Java virtual machine specification at hand.

### The bytecode viewer as a Netbeans module

To open a class file in Netbeans, the first step is to either select a java source node or a class file node in the explorer or to activate a Java source file in the source editor. Java sources have to be compiled in order for the bytecode viewer menu entries to be available. The second step is to either right click and navigate to Tools->View class file in the popup menu or to execute Tools->View class file in the main Netbeans menu.

## The bytecode manipulation library

### UML diagrams of jclasslib

The following UML diagrams for the bytecode manipulation library packages contained in `org.gjt.jclasslib` and its subpackages give an overview of the general architecture.

- `org.gjt.jclasslib.bytecode`

- `org.gjt.jclasslib.io`

- `org.gjt.jclasslib.structures`

- `org.gjt.jclasslib.structures.attributes`

- `org.gjt.jclasslib.structures.constants`

### Debugging reading and writing of class files

To see extensive debugging on stdout while jclasslib reads or writes class files, set the JVM environment variable `org.gjt.jclasslib.structures.AbstractStructure.SYSTEM_PROPERTY_DEBUG` (= `jclasslib.io.debug`) to `true` either by passing `-Djclasslib.io.debug=true` right after the the `java` command in the invokation of the apllication of by setting the property via `System.setProperty`.

### Using jclasslib in your own application

To use jclasslib in your own application you need to look at the javadoc documentation and at the source. Here are a few hints on how to begin:

- The single most important class is the `org.gjt.jclasslib.structures.ClassFile` class. All other structures defined in the class file format are hooked up here.

- Reading and writing class files is done with the `org.gjt.jclasslib.io.ClassFileReader` and `org.gjt.jclasslib.io.ClassFileWriter` classes.

- Bytecode is not translated to java classes within a `ClassFile` structure. To manipulate bytecode as a sequence of opcodes the `org.gjt.jclasslib.io.ByteCodeReader` and `org.gjt.jclasslib.io.ByteCodeWriter` classes can be used to convert the bytecode between classes of the `org.gjt.jclasslib.bytecode` package and `byte[]` arrays as returned and expected by the `ClassFile` structure.

- Inserting your own instructions into existing bytecode is done by creating a list of instances of `org.gjt.jclasslib.io.CodeInsertion` and invoking the `org.gjt.jclasslib.io.CodeInsertion.apply` method. This way, bytecode offsets of branch instructions are shifted to take account for the inserted instructions. Dependant structures such as line number and exception table are updated as well.

- Manipulation of the constant pool is most conveniently done via the `org.gjt.jclasslib.structures.ConstantPoolUtil` class. With its static methods, you can insert higher-level constant pool entries which require other constant pool entries to be genererated with only one method call.

## Trademarks

- Sun, Sun Microsystems and Java are registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

- Microsoft and Microsoft Windows are registered trademarks of Microsoft Corporation, registered in the U.S. and other countries.