db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig L Russell <Craig.Russ...@Sun.COM>
Subject Enhancer specification text for discussion
Date Sun, 21 Dec 2008 23:41:50 GMT
I thought at this point it would be useful to discuss the  
specification, which should resolve the remaining API issues. I still  
need to add the enhancer API itself but want to wait until we all  
agree on the description of the utility.

Add to 23.1 Overview:

A command line tool to invoke a byte code enhancer is standard with  
JDO 2.3. The tool is distributed as part of the specification jar. The  
tool analyzes command line arguments and passes control to an  
implementation-provided class to perform the enhancement of classes.  
The tool locates the implementation-provided class using the services  
locator architecture.

Add to 23.2 Goals:

Support for static enhancement of classes by a tool run after  
compilation but before execution

Support for dynamic enhancement of static (compiled with javac) and  
dynamic (created at runtime) classes by user- or implementation- 
written class loader

Support for build tools such as maven plugins, eclipse plugins, and  
ant plugins

Insert before 23.3 Enhancement: Architecture:

23.3 Standard Enhancement

The enhancement process consists of two distinct functions: analyzing  
user input as to how and what to enhance; and performing the  
enhancement of the persistent classes. A Java main program is  
distributed as part of the java specification jar. Plugins for  
Interactive Development Environments are expected by the architecture  
but not provided by the JDO specification jar itself. Enhancing the  
persistent classes is the function of a JDO implementation, and in  
particular, the Reference Implementation. The Enhancer main program  
calls a standard enhancer by using the services locator architecture.  
Thus, the Enhancer main program can call any enhancer provided by a  
JDO implementation and made available on the class path.

The enhancer operates on the byte code representation of persistent  
classes, and creates new byte code representations of the classes. The  
input byte code representations can come from four sources:

a byte array such as might be created by a dynamic class generator;
a file that contains the byte codes as generated by the javac compiler;
a jar file containing multiple classes and metadata files;
a resource loaded from a class loader that contains the byte codes as  
generated by the javac compiler

The output byte code representations can be written to one of three  
the same file as was provided as input;
the same jar file as was provided as input, in which case all contents  
of the jar file that are not enhanced are preserved intact;
a directory that contains package names as directory names with  
identical semantics to the javac compiler's output directive.

Restrictions: if a resource is used as input, then the only output  
possible is a directory. If a class file or jar file is used as input,  
the file must be read/write. If a byte array is used as input, then  
the enhanced byte array is available via a separate method call and is  
not written to output.

23.3.1 Enhancer Main

The Enhancer main class is intended to be run from an interactive  
shell (command line). It analyzes arguments and delegates to an  
implementation. The implementation must be identified via an entry in  
the class loader's resource file META-INF/services/ 
javax.jdo.JDOEnhancer. If multiple such files exist, the Enhancer main  
uses the first file containing the name of a class that can be loaded  
by the Class.forName method, containing a public no-args constructor,  
that returns an instance that implements javax.jdo.JDOEnhancer.

The enhancer is invoked with the following command line:

java -cp <classpath> javax.jdo.Enhancer <options> <directory, file, or  
resource names>

<classpath> must contain the jdo specification jar, the implementation  
jar and any implementation dependencies, the statically-compiled  
classes, and the jdo metadata files loadable as resources

<options> include:
-pu <persistence-unit-name> : the name of a persistence unit
-d <target directory> : write the enhanced classes to the specified  
-checkonly : just check the classes for enhancement status
-v : verbose output
-r : recurse through directories to find all classes and metadata  
files to enhance
-cp <enhancer class loader path> : if not already included in the java  
class loader, this parameter must contain the statically-compiled  
classes, and the jdo metadata files loadable as resources

<directory, file, or resource names>
each entry following the options must be a directory, a file, or a  
resource name.

The enhancer main program processes the command line and passes the  
parameters to the enhancer found via services lookup.

Parameters are processed until the first non-option parameter is  
found. All subsequent parameters are treated as directory, file, or  
resource names. Parameters beginning with "-" are considered to be  
options. If an option is not a standard option, it is added to the non- 
standard options list. If a non-standard option is not recognized, it  
is [[[expert group choice here: ignore it or throw an exception]]].

Parameters are processed as follows:

-cp <enhancer class loader path>: If this option is present, a new  
class loader is constructed, parented with the context class loader,  
to which the urls in the <enhancer class loader path> are added. The  
format of <enhancer class loader path> is the same as the -cp option  
of the java command. The class loader is passed to the enhancer via  
the setClassLoader method.

-pu <persistence-unit-name>: If this option is present, each  
persistence-unit-name is passed to the enhancer via the  
addPersistenceUnit method.

-d <target directory>: If this option is present, the target directory  
is passed to the enhancer via the setOutputDirectory method.

-v: If this option is present, the verbose flag is set via the  
setVerbose method.

-r: If this option is present, the recurse flag is set via the  
setRecurse method.

-checkonly: If this option is present, the files are not enhanced, but  
verified via the validate method. If this option is absent, the files  
are enhanced via the enhance method.

-<option>: If a parameter begins with a "-" is found, it is added to  
the other options list via the addOptions method.

Parameters that follow the last option are passed to the enhancer via  
the setFiles method. The enhancer handles the files as follows:

For a directory, the contents of the directory are analyzed  
for .class, .jdo, and .orm files which are then treated as if they  
were passed directly, as directory/*.class directory/*.jdo directory/ 
*.orm. If the -r option is specified, each subdirectory of the  
directory is treated as if it were itself the directory parameter.  
Thus, every .class file, .jdo file, and .orm file in the directory are  
included as files for enhancement.

For a .class file, the file must contain the byte codes of a  
persistent class consistent with the file name. Metadata is found  
using the algorithm detailed in Chapter 18, using the path specified  
for the .class file and recursing through parent directories in the  
file system.

For a .jdo or .orm file, the file must be a valid metadata file and  
the classes described in the file are treated as described  
(persistence-capable, persistence-aware, or not persistent).  Metadata  
is found using the algorithm detailed in Chapter 18.

For a .jar file, the file must contain .class files and the  
corresponding .jdo and .orm metadata files.

If the parameter is not able to be resolved as a directory or file, it  
is assumed to be a resource name that is loadable via the class loader  
constructed using the enhancer -cp parameter. If there is no -cp  
parameter then the context class loader is used. The resource name  
names a .class file, a .jdo file, or .orm file, and the treatment of  
these resources is the same as if they were files found in the file  

Craig L Russell
Architect, Sun Java Enterprise System http://db.apache.org/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!

View raw message