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 Re: Enhancer specification text for discussion
Date Mon, 22 Dec 2008 16:08:34 GMT

On Dec 22, 2008, at 1:56 AM, Ilan Kirsh wrote:

> Resource names and class names are not the same.

Right. What the enhancer operates on is the byte code representation  
of files, not the classes as loaded by a class loader. With that  
distinction in mind, what the enhancer needs access to is either the  
file name from which it can open a file, or the resource name which it  
can ask the class loader to open as a stream.
>
> Is class name supported?

That's an open question in my mind. How would you propose that the  
enhancer find the file corresponding to the class?

1. The class loader might not want to give you access to the file,  
especially for example if it was loaded from a jar. In that case, what  
you need is the path to the jar or the resource name of the jar.

2. As far as I know, there's no reverse translation of class loader +  
class name to file name.

> (myPackage.* might also be supported).

Right; keeping in mind that the shell might resolve the "*" wild card,  
you may have to quote it.

Craig

>
>
> ----- 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!
>

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