What is Byte Code Engineering?
------------------------------

The  Byte Code Engineering  Library (formerly  known as  JavaClass) is
intended to  give users a  convenient possibility to  analyze, create,
and  manipulate   (binary)  Java   class  files  (those   ending  with
.class).  Classes are  represented by  objects which  contain  all the
symbolic  information  of the  given  class:  methods  and fields,  in
particular.

Such objects can be read from  an existing file, be transformed by the
application (e.g.  a class  loader at run-time)  and dumped to  a file
again. The  Byte Code  Engineering Library may  be also useful  if you
want to learn  about the Java Virtual Machine (JVM)  and the format of
Java .class files. It was mainly designed to be used in other projects
in order to handle the creation of class files with more comfort.

For  example,  you could  manipulate  a  class  file to  implement  an
obsfuscator. (An ``obsfuscator''  mangles the information contained in
a class  file to  a human-unreadable format.  This is useful  when you
want to  keep someone from  decompiling your classes). Vice  versa, if
you  are writing  a compiler  that produces  Java byte  code,  you can
conveniently construct  class objects with this library  and then dump
them to a file.


Documentation
-------------

Technical report: "Byte Code  Engineering  with  the JavaClass  API"
available at

	ftp://bcel.sourceforge.net/pub/bcel/report.ps.gz

Conference paper: "Byte Code  Engineering" available at

	ftp://bcel.sourceforge.net/pub/bcel/paper.ps.gz

View the API documentation in the docs/ directory with your favorite
WWW browser, e.g.:

	% netscape <BCEL>/docs/packages.html


As  a   first  demonstration,  listclass.java  is   included  in  this
distribution,  which   displays  the  contents  of   the  given  class
files. You can use the  switches "-code" to show the disassembled code
and "-constants" to print the whole constant pool. (Which may be quite
long!)

Requirements
------------

BCEL  is   written  entirely in   Java,  so  it should be  fairly
straightforward to get it set up and running in your environment. Just
set your  CLASSPATH variable to  the appropiate   value, i.e. on  UNIX
system using the (t)csh

	% setenv CLASSPATH ${CLASSPATH}:<BCEL>

where <BCEL> is the path to the unpacked directory.

I have tested BCEL with the JDK 1.3 on Solaris and Linux and with
VisualAge under WindowsNT.

Trying it out
-------------

After setting the CLASSPATH try to use the list utility:

	% java listclass -code -constants java.lang.StringBuffer | more

Then take a look  at the source code in  listclass.java. You may  also
want to try patchclass.java  which  patches string constants in  class
files.  For example:

	% java listclass -constants patchclass.class
	% java patchclass string foobar patchclass.class
	% java listclass -constants _patchclass.class

You'll note the subtle difference...

Java class objects can be traversed with Visitor patterns as described
in  the notorious  "Design  Patterns" book.  The JasminVisitor  class,
e.g., makes use of it in  order to convert class files into the Jasmin
assembler format. Try

	% java JasminVisitor listclass 
	% more listclass.j

Take a look   at the Mini   language I wrote for demonstration
purposes:

	http://bcel.sourceforge.net/Mini-README

There  is an example  program named  "helloify.java" included  in this
distribution that takes class files and modifies all of their methods,
so that they will "Hello" and their name and signature before anything
else. Modifying the program itself gives us funny results:

	% java helloify helloify.class

This yields  a class file  named "helloify_hello.class", which  we can
use to modify itself again:

	% java helloify_hello helloify_hello.class
	Hello from public static void main(String[])
	Hello from private static final void helloifyClassName(de.fub.bytecode.classfile.JavaClass)
	Hello from private static final de.fub.bytecode.classfile.Method 
	helloifyMethod(de.fub.bytecode.classfile.Method)
	...

yields "helloify_hello_hello.class" and so  on. Every time the printed
message will be repeated once more.

Other examples
--------------

Other  code examples  of  the API  are "HelloWorldBuilder.java"  which
creates  a "HelloWorld"  class and  "Peephole.java" which  remove NOPs
from all methods of a class.

Class2HTML
----------

The  Class2HTML tool  converts class  files  into HTML  files. For example, try

	% java de.fub.bytecode.util.Class2HTML -d classdocs \
	  de/fub/bytecode/util/*.class and
	% java de.fub.bytecode.util.Class2HTML -d classdocs -zip \
	  $JAVA_HOME/lib/classes.zip java/lang/Object.class

Then you can view the generated documentation with

	% netscape classdocs/de.fub.bytecode.util.Class2HTML.html


Rebuilding BCEL
--------------------

The classes of this package  should be precompiled.  You can recompile
the package simply by typing

	% cd <BCEL>
	% make allclean
	% make JC=javac JFLAGS=
	% mkdir docs
	% make docs

where <BCEL> is the path to the unpacked directory. You will have
to use GNU make. Typing

	% cd <BCEL>/de/fub/bytecode
	% javac */*.java *.java

might work, too.

Further readings
----------------

You can find detailed information about the JVM at SUN's FTP server

	ftp://java.sun.com/docs/specs/

Ther are also some good books available
	
	"Java Virtual Machine", by Meyer and Downing
	"The Java Virtual Machine Specification", by Lindholm and Yellin,
	also available online at

	http://www.javasoft.com/docs/books/vmspec/index.html

New versions
------------

	http://bcel.sourceforge.net/


Author
------

The  BCEL  is copyright  (2001)  Markus  Dahm.  Send bug  reports  and
suggestions  to markus.dahm@berlin.de  (Markus Dahm),  please  tell me
also if  you find this tool helpful  and in what kind  of projects you
use it.
