4+1 = CAFEBABE: Java Bytecode in Eclipse

What might itemis staff do on their project-free 4 + 1 day? They continue their education, often by working on their own ideas; I would like to introduce just such a project today. The goal was to build familiarity with Xtext and Xtend. The result is a Java Byte Code (JBC) Editor based on these technologies.
 

HelloWorldInJBC-1

 
Xtext is above all an Eclipse-based framework for creating textual DSLs and generating tools for them, while Java bytecode stored in .class files is binary. What appears out-of-scope at first is easy to manage with one or two tricks.

Without going into too much detail here, the most important part is replacing the IDocumentProvider of the editor. This converts binary data both when reading text and writing back to binary format. In a future article I'll go into more detail about the technique, but today will just stick to the use and functionality of the Java bytecode editor.

Motivation

Why might you be interested in the contents of .class files and using an editor on them? In most projects the Java code itself is interesting, but not what the compiler makes of it. But there are cases in which a viewer and possibly an editor for the binary data could be helpful.

For example, anyone who writes their own compiler and designs a language for the Java Virtual Machine that compiles to bytecode will probably benefit if they can see the output of their tool. The same use case might arise with tool manufacturers who instrument bytecodes to allow, for example, tracing or profiling.

For anyone working on frameworks that dynamically create bytecode it might also be helpful to look at the code of existing classes, or to manually modify their code to observe the effects in real time before casting them into code.

Last but not least, an eager student who might want to look a little deeper into the technique could find it interesting and educational to see how the JVM gets its code. 

Installation

You can get an idea of the possibilities most easily by installing and trying out our Java bytecode editor. Just go to the following update site in Eclipse under Help -> Install New Software…

http://download.itemis.com/jbc/updates/

Install the JBC feature, confirm the license (EPL) and restart.

InstallJBC-1 


Open the editor

To open the .class file associated with a .java file, an Open JBC entry is provided in the Package and Project Explorer context menu. Executing this opens a new editor that displays the bytecode as a DSL.

OpenJBCFromJava-1

 
You can of course open .class file directly with an editor. This is done as usual in Eclipse via the context menu using the command Open With -> JBC Editor.
 

OpenJBCFromClass-1

 

Editing the bytecode

The editor displays each byte as a hexadecimal number. The only exception is UTF8 strings, which are represented as they are in Java; this is to provide enhanced editability. Changing a string value is as easy as it is in Java code. The data is enriched with keywords and grouping brackets to highlight its meaning. The presentation corresponds directly to what you can get from the Java Spec via the ClassFile format.

You can generally navigate within the code using F3 / Ctrl + Click. This allows you to follow references easily, which are represented by two bytes in most cases. If occurrence marking is activated the target under the cursor will be highlighted.
 

OccurenceMarking

In the bytecode the length of a table is display before each table. This length must be adjusted if entries are deleted or added using the editor. The editor therefore offers validation that compares the actual lengths of tables with their specified lengths. If they do not match they are highlighted as errors and can be adjusted via Quick Fix (Ctrl + 1).
 

Validation-1

 
Information displayed by hovering, together with the outline, can provide further understanding of the bytecode. The elements from the editor are also shown here, but with resolved references and interpreted values. For example, any access modifiers of a class are displayed textually rather than as a hexadecimal number, as in the editor.
 

Outline

 

To get an initial feel for the editor, try the following:

  1. Create a ‘Hello World’ program
  2. Run it and observe its output
  3. Open the JBC editor
  4. Change the string constant that contains the output text
  5. Save to the JBC editor
  6. Run the program again and observe the output

The source code

This project was implemented quickly thanks to Xtext. It could be extended with many more features that you might find useful: extended validations, better auto-completion, templates, refactorings, a formatter and more. All these could be added with minimal effort, or at least significantly less effort than would be involved in writing an Eclipse plug-in with plain Java. If your appetite is whetted you can also look at the source code on GitHub.

About Arne Deutsch

Arne Deutsch works as an IT consultant at itemis AG in Bonn. His focus is on Language Engineering, Xtext and the development of tools for Eclipse.