manual.tex

一个用于对.class文件进行插桩的开源工具

\documentclass[12pt,twoside]{article}

\usepackage{epsf,a4wide,moreverb,url}
\usepackage{palatino}

\newcommand\jc{{\sffamily BCEL }}
\newcommand\cp{{constant pool }}
\newcommand\cpe{constant pool}
\newcommand\jvm{{Java Virtual Machine }}
\newcommand\jvme{{Java Virtual Machine}}
\newcommand\vm{{Virtual Machine }}
\newcommand\href[2]{#2}

\begin{document}

\title{Byte Code Engineering Library (BCEL)\\
       Description and usage manual\\
       {\small \textbf{Version 1.0}}}

\author{{\Large Markus Dahm}\\\\
        \href{mailto:[e-mail]}{\texttt{[e-mail]}}}

\maketitle

%\tableofcontents

\begin{abstract}
Extensions  and improvements of the  programming language Java and its
related  execution environment (Java   Virtual Machine,  JVM)  are the
subject  of a large number  of research  projects and proposals. There
are  projects, for  instance, to add   parameterized types to Java, to
implement ``Aspect-Oriented Programming'', to perform sophisticated
static analysis, and to improve the run-time performance.

Since  Java classes  are  compiled into  portable  binary class  files
(called   \emph{byte   code}),  it   is   the   most  convenient   and
platform-independent  way  to  implement  these  improvements  not  by
writing a  new compiler or changing  the JVM, but  by transforming the
byte  code.   These  transformations  can either  be  performed  after
compile-time,  or at load-time.   Many programmers  are doing  this by
implementing their own specialized byte code manipulation tools, which
are, however, restricted in the range of their re-usability.

To deal with the necessary class file transformations, we introduce an
API   that   helps   developers   to  conveniently   implement   their
transformations.
\end{abstract}

\section{Introduction}\label{sec:intro}

The  Java language  \cite{gosling} 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 implementation  issues
should be hidden from the user.  Fortunately, the concepts of the \jvm
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  \emph{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 \vm  (see  section
\ref{sec:classloaders}).  Class loaders may  thus be used to intercept
the  loading process and  transform classes  before they  get actually
executed  by the  JVM  \cite{classloader}.  While  the original  class
files always remain unaltered, the behavior of the class loader may be
reconfigured for every execution or instrumented dynamically.

The \jc 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.  \jc is written entirely in
Java and freely available under the terms of the Apache Software
License.  \footnote{The distribution is available at
  \url{http://jakarta.apache.org/bcel/}, including several code
  examples and javadoc manuals.  }

This paper is structured as follows:  We give a  brief description of
the \jvm and the class  file format in section \ref{sec:jvm}.  Section
\ref{sec:api} introduces  the \jc API.   Section \ref{sec:application}
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.

\subsection{Related work}

There are  a number  of proposals and  class libraries that  have some
similarities with \textsc{BCEL}: The JOIE \cite{joie} toolkit can
be used to instrument class loaders with dynamic behavior.  Similarly,
``Binary  Component Adaptation''  \cite{bca} allows  components  to be
adapted and  evolved on-the-fly.  Han  Lee's ``Byte-code Instrumenting
Tool'' \cite{bit} allows the user  to insert calls to analysis methods
anywhere in the  byte code.  The Jasmin language  \cite{jasmin} can be
used  to   hand-write  or  generate   pseudo-assembler  code.   D-Java
\cite{classfile} and JCF \cite{inside} are class viewing tools.

In contrast to these projects, \jc is intended to be a general purpose
tool  for ``byte  code engineering''.   It gives  full control  to the
developer on a high level of  abstraction and is not restricted to any
particular application area.

\section{The Java Virtual Machine}\label{sec:jvm}

Readers already familiar with the \jvm and the Java class file format
may want to skip this section and proceed with section \ref{sec:api}.

Programs written  in the  Java language are  compiled into  a portable
binary format called \emph{byte  code}.  Every class is represented by
a  single class  file  containing  class related  data  and byte  code
instructions. These  files are loaded dynamically  into an interpreter
(\jvme, JVM) and executed.

Figure  \ref{fig:jvm}  illustrates  the  procedure  of  compiling  and
executing a Java class:  The source file (\texttt{HelloWorld.java}) is
compiled into a Java class file (\texttt{HelloWorld.class}), loaded by
the  byte  code  interpreter  and  executed.  In  order  to  implement
additional  features, researchers  may want  to transform  class files
(drawn  with  bold lines)  before  they  get  actually executed.  This
application area is one of the main issues of this article.

\begin{figure}[htbp]
  \begin{center}
    \leavevmode
    \epsfxsize\textwidth
    \epsfbox{eps/jvm.eps}
    \caption{Compilation and execution of Java classes}
    \label{fig:jvm}
  \end{center}
\end{figure}

Note that the  use of the general term  ``Java'' implies two meanings:
on the one hand, Java as a programming language is meant, on the other
hand, the Java  Virtual Machine, which is not  necessarily targeted by
the Java language  exclusively, but may be used  by other languages as
well (e.g.   Eiffel \cite{eiffel}, or Ada \cite{ada}).   We assume the
reader to  be familiar with  the Java language  and to have  a general
understanding of the Virtual Machine.

\subsection{Java class file format}\label{sec:format}

Giving a  full overview of  the design issues  of the Java  class file
format and the  associated byte code instructions is  beyond the scope
of this paper.   We will just give a  brief introduction covering the
details  that  are  necessary  for  understanding  the  rest  of  this
paper. The format of class files and the byte code instruction set are
described  in more  detail  in the  ``\jvm Specification''  \cite{jvm}
\footnote{Also             available             online             at
\url{http://www.javasoft.com/docs/books/vmspec/index.html}},   and  in
\cite{jasmin}.   Especially,  we  will  not  deal  with  the  security
constraints that the \jvm has to check at run-time, i.e. the byte code
verifier.

Figure \ref{fig:classfile} shows a  simplified example of the contents
of a  Java class file:  It starts with  a header containing  a ``magic
number'' (\texttt{0xCAFEBABE}) and the version number, followed by the
\emph{\cpe}, which can be roughly thought of as the text segment of an
executable, the  \emph{access rights}  of the class  encoded by  a bit
mask, a list of interfaces  implemented by the class, lists containing
the  fields and  methods of  the  class, and  finally the  \emph{class
attributes}, e.g.  the  \texttt{SourceFile} attribute telling the name
of  the source  file.  Attributes  are  a way  of putting  additional,
e.g. user-defined,  information into class file  data structures.  For
example, a  custom class  loader may evaluate  such attribute  data in
order to perform its  transformations.  The JVM specification declares
that unknown, i.e.  user-defined attributes must be ignored by any \vm
implementation.

\begin{figure}[htbp]
  \begin{center}
    \leavevmode
    \epsfxsize\textwidth
    \epsfbox{eps/classfile.eps}
    \caption{Java class file format}
    \label{fig:classfile}
  \end{center}
\end{figure}

Because  all of  the  information needed  to  dynamically resolve  the
symbolic  references to  classes, fields  and methods  at  run-time is
coded  with string  constants, the  \cp contains  in fact  the largest
portion of an average class file, approximately 60\% \cite{statistic}.
The byte code instructions themselves just make up 12\%.

The right upper box shows a  ``zoomed'' excerpt of the \cpe, while the
rounded box below depicts  some instructions that are contained within
a  method  of the  example  class.  These  instructions represent  the
straightforward translation of the well-known statement:

\begin{verbatim}
   System.out.println("Hello, world");
\end{verbatim}

The first instruction loads the  contents of the field \texttt{out} of
class  \texttt{java.lang.System} onto  the operand  stack. This  is an
instance of  the class \texttt{java.io.PrintStream}.  The \texttt{ldc}
(``Load constant'') pushes a reference  to the string "Hello world" on
the  stack.    The  next  instruction  invokes   the  instance  method
\texttt{println}  which  takes  both  values as  parameters  (Instance
methods always  implicitly take an  instance reference as  their first
argument).

Instructions,  other  data  structures   within  the  class  file  and
constants  themselves  may  refer  to  constants  in  the  \cpe.  Such
references are implemented via fixed indexes encoded directly into the
instructions.   This  is illustrated  for  some  items  of the  figure
emphasized    with   a    surrounding   box.

For  example,  the  \texttt{invokevirtual}  instruction  refers  to  a
\texttt{MethodRef} constant  that contains information  about the name
of the  called method, the  signature (i.e.  the encoded  argument and
return types),  and to  which class the  method belongs.  In  fact, as
emphasized by the boxed  value, the \texttt{MethodRef} constant itself
just refers to other entries holding the real data, e.g.  it refers to
a \texttt{ConstantClass} entry containing  a symbolic reference to the
class \texttt{java.io.PrintStream}.   To keep the  class file compact,
such  constants  are   typically  shared  by  different  instructions.
Similarly, a field is represented by a \texttt{Fieldref} constant that
includes information about the name, the type and the containing class
of the field.

The \cp  basically holds the following types  of constants: References
to methods, fields and  classes, strings, integers, floats, longs, and
doubles.

\subsection{Byte code instruction set}\label{sec:code}

The JVM  is a  stack-oriented interpreter that  creates a  local stack
frame of fixed size for every method invocation. The size of the local
stack has to  be computed by the compiler.  Values  may also be stored
intermediately in a frame area containing \emph{local variables} which
can  be used  like  a set  of  registers.  These  local variables  are
numbered from 0  to 65535, i.e.  you have a maximum  of 65536 of local
variables.   The  stack  frames   of  caller  and  callee  method  are
overlapping, i.e.  the caller  pushes arguments onto the operand stack
and the called method receives them in local variables.

The byte code instruction  set currently consists of 212 instructions,
44  opcodes  are  marked  as  reserved  and may  be  used  for  future
extensions   or   intermediate   optimizations  within   the   Virtual
Machine. The instruction set can be roughly grouped as follows:

\begin{description}
\item[Stack operations:] Constants can be pushed onto the stack either
by loading them from the \cp with the \texttt{ldc} instruction or with
special ``short-cut''  instructions where the operand  is encoded into
the  instructions, e.g.   \texttt{iconst\_0} or  \texttt{bipush} (push
byte value).

\item[Arithmetic  operations:]   The  instruction  set   of  the  \jvm
distinguishes  its  operand  types  using  different  instructions  to
operate on  values of  specific type.  Arithmetic  operations starting
with  \texttt{i}, for  example,  denote  an  integer  operation.  E.g.,
\texttt{iadd} that adds two integers and pushes the result back on the
stack.     The    Java    types    \texttt{boolean},    \texttt{byte},
\texttt{short}, and \texttt{char} are handled as integers by the JVM.

\item[Control flow:] There  are branch instructions like \texttt{goto}
and   \texttt{if\_icmpeq},    which   compares   two    integers   for
equality.  There  is  also   a  \texttt{jsr}  (jump  sub-routine)  and
\texttt{ret} pair of instructions that  is  used to implement the
\texttt{finally} clause of  \texttt{try-catch} blocks.  Exceptions may
be thrown with the \texttt{athrow} instruction.

Branch  targets  are coded  as  offsets  from  the current  byte  code
position, i.e. with an integer number.