Resource names and class names are not the same.
Is class name supported? (myPackage.* might also be supported).
----- Original Message -----
From: "Craig L Russell" <Craig.Russell@Sun.COM>
To: "JDO Expert Group" <jdo-experts-ext@Sun.COM>; "Apache JDO project"
<jdo-dev@db.apache.org>
Sent: Monday, December 22, 2008 1:41 AM
Subject: Enhancer specification text for discussion
>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.
>
> <proposed>
> 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
> 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 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
> 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. 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 system.
>
>
> </proposed>
> 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!
>
|