Home

Table of Contents Cojen - Java bytecode generation and disassembly tools ClassFile object Transient classes Utilities

Cojen - Java bytecode generation and disassembly tools

 Cojen's primary goal is making raw Java classfile generation easy, without
 hiding any of the advanced features. Basic knowledge of how Java classfiles are
 structured is still required, however. The
 [http://java.sun.com/docs/books/vmspec/ Virtual Machine Specification]
 is an excellent reference.

 Method bytecode is constructed via a
 [http://cojen.github.io/Cojen/javadoc/org/cojen/classfile/CodeBuilder.html builder], in which virtual
 machine opcodes are represented as slightly higher level instructions. It takes
 care of selecting optimal opcodes, managing branch labels, computing operand
 stack depth, choosing local variable registers, and reducing register usage by
 liveness analysis. In addition, it supports long branches, pushing large string
 constants onto the stack, boxing and unboxing conversions, and
 [http://cojen.github.io/Cojen/javadoc/org/cojen/classfile/CodeAssembler.html#inline%28java.lang.Object%29 inlining]
 of Java code.

 The builder is represented by an
 {{{apidocs/org/cojen/classfile/CodeAssembler.html}interface}}, which can
 be used as a visitor into a code
 {{{apidocs/org/cojen/classfile/CodeDisassembler.html}disassembler}}. This feature
 can be used for just-in-time method mutation, and to aid in understanding how to use the
 code building facilities.

 A simple "Hello World" {{{example.html}example}} is provided which demonstrates
 the major class generation and loading features. {{{disassembly.html}Disassembly}}
 tools which can be run from the command line show how any class can be used as an example
 for class generation.

ClassFile object

 Defining a new class begins with the construction of a
 {{{apidocs/org/cojen/classfile/ClassFile.html}ClassFile}} object.
 Use the ClassFile instance to add fields, methods, constructors, inner
 classes, and to to specify implemented interfaces.

 Adding a method causes a MethodInfo object to be returned. Although raw bytecodes can
 be put into its code attribute, creating a CodeBuilder makes things much easier.
 Constructing a CodeBuilder around a MethodInfo causes it to take over this responsibility.

 ClassFile objects are also used for loading and representing existing classes. Reading
 a class into a ClassFile object is the first step in disassembling a class. Call one of
 the defined static readFrom methods to read a class from an input stream. Additional
 parameters can be supplied to enable reading inner classes and custom attributes.

Transient classes

 A "transient" class from Cojen's perspective is one that is dynamically
 created, never leaves the confines of the current virtual machine process, and
 whose bytecode is lost when it is unloaded. 
 {{{apidocs/org/cojen/classfile/RuntimeClassFile.html}RuntimeClassFile}}
 is used for creating such classes. Internally, it uses a ClassLoader which
 defines classes, but it never remembers the bytecode used to construct them.

 As long as references to the generated class or instances of it still exist, the class
 will not be unloaded. Once all such references are gone, the class may be unloaded, but
 it cannot be loaded again by name. It would need to be regenerated.

Utilities

 Cojen provides several powerful utility classes which also serve as examples of how to
 dynamically generate classes. {{{apidocs/org/cojen/util/BeanComparator.html}BeanComparator}}
 enables fast custom sorting of Java objects by properties,
 {{{apidocs/org/cojen/util/BeanPropertyAccessor.html}BeanPropertyAccessor}} allows
 object properties to be quickly accessed, and
 {{{apidocs/org/cojen/util/PatternMatcher.html}PatternMatcher}} supports rapid string
 comparison to patterns containing wildcards.