manual.tex

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

\item[Load   and   store operations]    for   local   variables   like
\texttt{iload} and  \texttt{istore}.  There are also  array operations
like \texttt{iastore} which stores an integer value into an array.

\item[Field access:] The  value of an instance field  may be retrieved
with \texttt{getfield} and written with \texttt{putfield}.  For static
fields,   there    are   \texttt{getstatic}   and   \texttt{putstatic}
counterparts.

\item[Method  invocation:] Methods  may  either be  called via  static
references with \texttt{invokesta\-tic} or be bound virtually with the
\texttt{invokevirtual}  instruction. Super  class methods  and private
methods are invoked with \texttt{invokespecial}.

\item[Object  allocation:]  Class  instances  are allocated  with  the
\texttt{new}  instruction, arrays  of basic  type  like \texttt{int[]}
with \texttt{newarray}, arrays  of references like \texttt{String[][]}
with \texttt{anewarray} or \texttt{multianewarray}.

\item[Conversion and type checking:]  For stack operands of basic type
there  exist casting  operations  like \texttt{f2i}  which converts  a
float  value into  an integer.   The validity  of a  type cast  may be
checked with  \texttt{checkcast} and the  \texttt{instanceof} operator
can be directly mapped to the equally named instruction.
\end{description}

Most  instructions  have a  fixed  length,  but  there are  also  some
variable-length instructions: In particular, the \texttt{lookupswitch}
and  \texttt{tableswitch} instructions,  which are  used  to implement
\texttt{switch()}  statements.   Since  the  number  of  \texttt{case}
clauses  may vary,  these instructions  contain a  variable  number of
statements.

We  will not list  all byte  code instructions  here, since  these are
explained in  detail in the  JVM specification.  The opcode  names are
mostly self-explaining,  so understanding the  following code examples
should be fairly intuitive.

\subsection{Method code}\label{sec:code2}

Non-abstract methods  contain an attribute  (\texttt{Code}) that holds
the following data: The maximum  size of the method's stack frame, the
number   of   local   variables    and   an   array   of   byte   code
instructions. Optionally,  it may  also contain information  about the
names of local variables and source file line numbers that can be used
by a debugger.

Whenever  an exception is thrown, the  JVM performs exception handling
by looking   into a  table  of exception  handlers.   The table  marks
handlers, i.e.  pieces  of code, to  be responsible for  exceptions of
certain types  that  are raised   within a  given  area  of  the  byte
code. When there is no appropriate handler the exception is propagated
back to the caller of the method. The handler information is itself
stored in an attribute contained within the \texttt{Code} attribute.

\subsection{Byte code offsets}\label{sec:offsets}

Targets  of  branch instructions  like  \texttt{goto}  are encoded  as
relative offsets  in the array  of byte codes. Exception  handlers and
local variables refer to absolute addresses within the byte code.  The
former  contains  references   to  the  start  and  the   end  of  the
\texttt{try} block,  and to the instruction handler  code.  The latter
marks the  range in which a  local variable is valid,  i.e. its scope.
This makes it  difficult to insert or delete code  areas on this level
of abstraction, since one has  to recompute the offsets every time and
update the referring objects. We will see in section \ref{sec:cgapi}
how \jc remedies this restriction.

\subsection{Type information}\label{sec:types}

Java is  a type-safe language and  the information about  the types of
fields,    local    variables,    and    methods    is    stored    in
\emph{signatures}. These are strings stored  in the \cp and encoded in
a special  format.  For example the  argument and return  types of the
\texttt{main} method

\begin{verbatim}
  public static void main(String[] argv)
\end{verbatim}

are represented by the signature

\begin{verbatim}
  ([java/lang/String;)V
\end{verbatim}

Classes  and  arrays  are   internally  represented  by  strings  like
\texttt{"java/lang/String"},  basic types  like  \texttt{float} by  an
integer number. Within signatures they are represented by single
characters, e.g., \texttt{"I"}, for integer.

\subsection{Code example}\label{sec:fac}

The  following example  program prompts  for a  number and  prints the
faculty  of  it.  The  \texttt{readLine()}  method  reading  from  the
standard input  may raise an \texttt{IOException} and  if a misspelled
number    is    passed   to    \texttt{parseInt()}    it   throws    a
\texttt{NumberFormatException}. Thus, the critical area of code must be
encapsulated in a \texttt{try-catch} block.

{\small \begin{verbatim}
import java.io.*;
public class Faculty {
  private static BufferedReader in = new BufferedReader(new
                                InputStreamReader(System.in));
  public static final int fac(int n) {
    return (n == 0)? 1 : n * fac(n - 1);
  }
  public static final int readInt() {
    int n = 4711;
    try {
      System.out.print("Please enter a number> ");
      n = Integer.parseInt(in.readLine());
    } catch(IOException e1) { System.err.println(e1); }
      catch(NumberFormatException e2) { System.err.println(e2); }
    return n;
  }
  public static void main(String[] argv) {
    int n = readInt();
    System.out.println("Faculty of " + n + " is " + fac(n));
  }}
\end{verbatim}}

This code example  typically compiles to the following  chunks of byte
code:

\subsubsection{Method fac}

{\small \begin{verbatim}
0:  iload_0
1:  ifne            #8
4:  iconst_1
5:  goto            #16
8:  iload_0
9:  iload_0
10: iconst_1
11: isub
12: invokestatic    Faculty.fac (I)I (12)
15: imul
16: ireturn

LocalVariable(start_pc = 0, length = 16, index = 0:int n)
\end{verbatim}}

The  method \texttt{fac}  has only  one local  variable,  the argument
\texttt{n}, stored in  slot 0.  This variable's scope  ranges from the
start of  the byte  code sequence to  the very  end.  If the  value of
\texttt{n} (stored  in local variable  0, i.e. the value  fetched with
\texttt{iload\_0}) is  not equal  to 0, the  \texttt{ifne} instruction
branches to  the byte code at offset  8, otherwise a 1  is pushed onto
the operand stack  and the control flow branches  to the final return.
For ease of reading, the offsets of the branch instructions, which are
actually   relative,  are displayed  as  absolute  addresses in  these
examples.

If  recursion has to  continue, the  arguments for  the multiplication
(\texttt{n}  and \texttt{fac(n -  1)}) are  evaluated and  the results
pushed onto the operand stack.  After the multiplication operation has
been performed the function returns the computed value from the top of
the stack.

\subsubsection{Method readInt}

{\small \begin{verbatim}
0:  sipush        4711
3:  istore_0
4:  getstatic     java.lang.System.out Ljava/io/PrintStream;
7:  ldc           "Please enter a number> "
9:  invokevirtual java.io.PrintStream.print (Ljava/lang/String;)V
12: getstatic     Faculty.in Ljava/io/BufferedReader;
15: invokevirtual java.io.BufferedReader.readLine ()Ljava/lang/String;
18: invokestatic  java.lang.Integer.parseInt (Ljava/lang/String;)I
21: istore_0
22: goto          #44
25: astore_1
26: getstatic     java.lang.System.err Ljava/io/PrintStream;
29: aload_1
30: invokevirtual java.io.PrintStream.println (Ljava/lang/Object;)V
33: goto          #44
36: astore_1
37: getstatic     java.lang.System.err Ljava/io/PrintStream;
40: aload_1
41: invokevirtual java.io.PrintStream.println (Ljava/lang/Object;)V 
44: iload_0
45: ireturn

Exception handler(s) = 
From    To      Handler Type
4       22      25      java.io.IOException(6)
4       22      36      NumberFormatException(10)
\end{verbatim}}

First the local variable \texttt{n}  (in slot 0) is initialized to the
value  4711.   The  next  instruction, \texttt{getstatic},  loads  the
static  \texttt{System.out} field onto  the stack.   Then a  string is
loaded and  printed, a number   read from the  standard input and
assigned to \texttt{n}.

If    one   of   the    called   methods    (\texttt{readLine()}   and
\texttt{parseInt()}) throws  an exception, the  \jvm calls one  of the
declared exception  handlers, depending on the type  of the exception.
The \texttt{try}-clause  itself does not  produce any code,  it merely
defines the range in which  the following handlers are active.  In the
example  the specified  source  code area  maps  to a  byte code  area
ranging from offset 4 (inclusive)  to 22 (exclusive).  If no exception
has   occurred   (``normal''   execution   flow)   the   \texttt{goto}
instructions  branch behind  the  handler code.   There  the value  of
\texttt{n} is loaded and returned.

For  example the handler   for \texttt{java.io.IOException}  starts at
offset 25. It simply prints the error  and branches back to the normal
execution flow, i.e. as if no exception had occurred.

\section{The BCEL API}\label{sec:api}

The \jc API abstracts from  the concrete circumstances of the \jvm and
how  to  read and  write  binary Java  class  files.   The API  mainly
consists of three parts:

\begin{enumerate}
  
\item A package that contains classes that describe ``static''
  constraints of class files, i.e., reflect the class file format and
  is not intended for byte code modifications.  The classes may be
  used to read and write class files from or to a file.  This is
  useful especially for analyzing Java classes without having the
  source files at hand.  The main data structure is called
  \texttt{JavaClass} which contains methods, fields, etc..

\item A  package to dynamically generate  or modify \texttt{JavaClass}
objects.  It  may be  used  e.g. to  insert  analysis  code, to  strip
unnecessary  information from class  files, or  to implement  the code
generator back-end of a Java compiler.

\item Various code examples and  utilities like a class file viewer, a
tool  to convert class  files into  HTML, and  a converter  from class
files to the Jasmin assembly language \cite{jasmin}.
\end{enumerate}

\subsection{JavaClass}\label{sec:javaclass}

The  ``static''  component of  the  \jc  API  resides in  the  package
\path{de.fub.bytecode.classfile} and represents class files.  All of the
binary   components  and   data   structures  declared   in  the   JVM
specification  \cite{jvm} and described  in section  \ref{sec:jvm} are
mapped to classes.  Figure \ref{fig:umljc} shows an UML diagram of the
hierarchy of  classes of the  \jc API.  Figure \ref{fig:umlcp}  in the
appendix also  shows a  detailed diagram of  the \texttt{ConstantPool}
components.

\begin{figure}[htbp]
  \begin{center}
    \leavevmode 
    \epsfysize0.93\textheight
    \epsfbox{eps/javaclass.eps}
    \caption{UML diagram for the \jc API}\label{fig:umljc}
  \end{center}
\end{figure}

The  top-level data  structure  is \texttt{JavaClass},  which in  most
cases is created by  a \texttt{Class\-Par\-ser} object that is capable
of parsing  binary class files. A  \texttt{JavaClass} object basically
consists of  fields, methods, symbolic  references to the  super class
and to the implemented interfaces.

The  \cp serves  as some  kind of  central repository  and is  thus of
outstanding  importance  for  all  components.   \texttt{ConstantPool}
objects contain  an array of fixed size  of \texttt{Constant} entries,
which may be retrieved via the \texttt{getConstant()} method taking an