Overview
Serp is an open source suite of Java 1.2+ development utilities. It includes everything from generic object pooling to localization helpers to a complete framework for manipulating Java bytecode that is easier to use than any other bytecode package out there (though I am certainly more than a little biased). These are tools that I have developed during various projects that have proven useful time and time again. If you have a suggestion for an additional utility or code that you would like to see incorporated into serp, please feel free to send it to me. Bug reports are also greatly appreciated. And if you choose to incorporate any serp tools into any of your projects, I would love to hear about it!
Abe White
abewhite@mac.com
The
serp.util package contains generic utility classes,
acting as an add-on to the java.util package.
The package serves several purposes:
serp.util.Options class.
The
serp.xml package contains utility classes for handling
XML. It uses the Java API for XML Processing (JAXP), which is standard
in Java 1.4 but is a separate download for earlier versions. The
package contains classes for efficiently accessing JAXP entities
like DocumentHandlers, types for streaming XML, etc. One
highlight of the package is a java.util.Properties
implementation that can efficiently load XML documents, provide access
to their data through XPath properties keys, and stream them out again
as XML, complete with any changes made to the XPath values.
The
serp.bytecode package contains a framework for Java
bytecode manipulation. This framework was formerly the
TechTrader Bytecode Toolkit.
Bytecode manipulation is a powerful tool in the arsenal of the Java developer. It can be used for tasks from compiling alternative programming languages to run in a JVM, to creating new classes on the fly at runtime, to instrumenting classes for performance analysis, to debugging, to altering or enhancing the capabilities of existing compiled classes. Traditionally, however, this power has come at a price: modifying bytecode has required an in-depth knowledge of the class file structure and has necessitated very low-level programming techniques. These costs have proven too much for most developers, and bytecode manipulation has been largely ignored by the mainstream.
The goal of the serp bytecode framework is to tap the full power of bytecode modification while lowering its associated costs. The framework provides a set of high-level APIs for manipulating all aspects of bytecode, from large-scale structures like class member fields to the individual instructions that comprise the code of methods. While in order to perform any advanced manipulation, some understanding of the class file format and especially of the JVM instruction set is necessary, the framework makes it as easy as possible to enter the world of bytecode development.
There are several other excellent bytecode frameworks available. Serp excels, however, in the following areas:
iconst0, while accessing the string
constant "foo" requires a different opcode, ldc,
followed by the constant pool index of "foo". In serp, however,
there is only one instruction, constant. This
instruction has setValue methods which use the
given value to automatically determine the correct opcodes and
arguments -- iconst0 for a value of 0 and
ldc plus the proper constant pool index for the
value of "foo".
Serp is not ideally suited to all applications. Here are a few disadvantages of serp:
The first step to using bytecode modification is to get familiar with
the inner workings of class files. The class file format is covered
here. Advanced manipulation involving changing or creating methods
requires knowledge of the JVM instruction set, outlined
here. Finally, learn to use the javap standard Java
tool. Running javap -c on any class name will show you
the opcodes of the class' methods -- this gives you an unlimited supply
of examples to work from when writing your own opcodes.
The first class you should study in the serp bytecode toolkit is
the serp.bytecode.Project type. From there, move onto
the serp.bytecode.BCClass, and trace its APIs into
serp.bytecode.BCFields,
serp.bytecode.BCMethods, and finally into actual
serp.bytecode.Code.
Serp uses the BSD license. This is the most open license I could find; the goal is that regardless of your application -- commercial or non-commercial, open source or closed -- you can take advantage of the utilities serp provides, or even modify them to suit your needs... without any legal issues. Also, as in all open source, access to the source code means that you have the opportunity to fix blocking bugs without waiting for the next release. The following is the text of the license:
Copyright (c) 2002, A. Abram White All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of 'serp' nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.