db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ilan Kirsh <ki...@objectdb.com>
Subject Re: Enhancer specification text for discussion
Date Mon, 22 Dec 2008 09:56:51 GMT
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!
> 


Mime
View raw message