The Java language has become very popular and many research projects deal with further improvements of the language or its run-time behavior. The possibility to extend a language with new concepts is surely a desirable feature, but the implementation issues should be hidden from the user. Fortunately, the concepts of the Java Virtual Machine permit the user-transparent implementation of such extensions with relatively little effort.

Because the target language of Java is an interpreted language with a small and easy-to-understand set of instructions (the byte code), developers can implement and test their concepts in a very elegant way. One can write a plug-in replacement for the system's class loader which is responsible for dynamically loading class files at run-time and passing the byte code to the Virtual Machine (see section 2). Class loaders may thus be used to intercept the loading process and transform classes before they get actually executed by the JVM. While the original class files always remain unaltered, the behavior of the class loader may be reconfigured for every execution or instrumented dynamically.

The BCEL API (Byte Code Engineering Library), formerly known as JavaClass, is a toolkit for the static analysis and dynamic creation or transformation of Java class files. It enables developers to implement the desired features on a high level of abstraction without handling all the internal details of the Java class file format and thus re-inventing the wheel every time. BCEL is written entirely in Java and freely available under the terms of the Apache Software License.

This manual is structured as follows: We give a brief description of the Java Virtual Machine and the class file format in section 2. Section 3 introduces the BCEL API. Section 4 describes some typical application areas and example projects. The appendix contains code examples that are to long to be presented in the main part of this paper. All examples are included in the down-loadable distribution.