I looked again at the description of the resource name, and I just cannot justify why it's needed for this API. In a build environment, you know where the .class files are and for the enhancer to access them directly, you would need to name the file system directory where they are compiled. If the enhancer instead accessed them via a class loader, you would need to give the class loader the file name. So I don't see the benefit for a build time enhancement.
For runtimes, where you don't have access to the file system, someone must have put the class path entry into the constructor for a URLClassLoader, or used the system classpath. Whoever put the class path entry there is probably the same entity that is calling for the enhancement.
For a dynamic class loader that creates a class and then asks for it to be enhanced, there doesn't seem to be a need for loading anything except possibly metadata files.
In a container, the Java Persistence infrastructure to dynamically enhance classes should be sufficient to integrate the JDO enhancer without resort to resource loading.
Feedback regarding the need to include resources is needed. <proposed> Add to 23.1 Overview:A command line tool to invoke a build-time 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. 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 EnhancementThe 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 anticipated 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 these sources:
a byte array such as might be created by a dynamic class generator;a .class file that contains the byte codes as generated by the javac compiler;
a jar file containing multiple classes;Metadata follows the overriding rules in Chapter 18. Metadata for the input classes is provided by three possible sources:
JDOMetadata instances provided by API, which overrides.jdo files provided by files or contained within jar files, which overrides
annotations on the classes.If .jdo files are needed, they are loaded by the enhancer via getResourceAsStream from the provided class loader.
The output byte code representations can be written to one of three destinations:
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 class file or jar file is used as input, the file must be able to be opened in read/write mode. 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 MainThe 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 or file 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 directory
-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.
Parameters are processed as follows:-ecp <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 and passed to the enhancer 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, recursing through parent directories in the file system.
For a .jar file, the file must contain .class files and the corresponding .jdo and .orm metadata files.
</proposed> Craig L Russell Architect, Sun Java Enterprise System http://db.apache.org/jdo 408 276-5638 mailto:craig.russ...@sun.com P.S. A good JDO? O, Gasp!
smime.p7s
Description: S/MIME cryptographic signature
