org.datanucleus.enhancer
Class DataNucleusEnhancer

java.lang.Object
  extended by org.datanucleus.enhancer.DataNucleusEnhancer

public class DataNucleusEnhancer
extends java.lang.Object

DataNucleus Byte-Code Enhancer. This provides the entry point for enhancement. Enhancement is performed using a ClassEnhancer. Currently provides a ClassEnhancer using ASM, and a deprecated one using Apache BCEL.

You can use the DataNucleusEnhancer in two ways :-

The programmatic way would be something like this :-

 DataNucleusEnhancer enhancer = new DataNucleusEnhancer();
 enhancer.setVerbose();
 enhancer.enhancePersistenceUnit("myPersistenceUnit");
 
enhancing all classes specified by the persistence unit.


Field Summary
protected static org.datanucleus.util.Localiser LOCALISER
           
static org.datanucleus.util.NucleusLogger LOGGER
          Logger for enhancing.
protected  java.lang.ClassLoader userClassLoader
          User-provided class loader.
 
Constructor Summary
DataNucleusEnhancer()
          Constructor for an enhancer for JDO using the ASM class enhancer.
DataNucleusEnhancer(java.lang.String api, java.lang.String enhancerName)
          Constructor for an enhancer specifying the API and class enhancer.
 
Method Summary
 DataNucleusEnhancer addClass(java.lang.String className, byte[] bytes)
          Method to add the specified class (and its input bytes) to the list of classes to enhance.
 DataNucleusEnhancer addClasses(java.lang.String[] classNames)
          Method to add the specified classes to the list of classes to enhance.
 DataNucleusEnhancer addFiles(java.lang.String[] metadataFiles)
          Method to add the classes defined in specified metadata files to the list of classes to enhance.
 DataNucleusEnhancer addJar(java.lang.String jarFileName)
          Method to add the classes defined by the specified jar to the list of classes to enhance.
protected  void addMessage(java.lang.String msg, boolean error)
          Method to add a message at the required output level.
 DataNucleusEnhancer addPersistenceUnit(java.lang.String persistenceUnitName)
          Method to add the classes defined by the persistence-unit to the list of classes to enhance.
 void enhance()
          Method to enhance all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.
protected  boolean enhanceClass(org.datanucleus.metadata.ClassMetaData cmd, ClassEnhancer enhancer, boolean store)
          Method to enhance the class defined by the MetaData.
 byte[] enhanceClass(java.lang.String className, byte[] bytes)
          Method to enhance the supplied (in-memory) class from its bytes.
 int enhanceFiles(java.lang.String[] filenames)
          Method to enhance the classes defined by the input files.
 int enhancePersistenceUnit(java.lang.String persistentUnitName)
          Method to enhance the classes defined by the specified persistence-unit.
protected  ClassEnhancer getClassEnhancer(org.datanucleus.metadata.ClassMetaData cmd, byte[] bytes)
          Method to return an instance of the ClassEnhancer for use with this class.
 java.lang.ClassLoader getClassLoader()
          Accessor for the user-defined class loader for enhancement (if any).
 org.datanucleus.ClassLoaderResolver getClassLoaderResolver()
           
 java.lang.String getDestination()
          Deprecated. Use getOutputDirectory() instead
 byte[] getEnhancedBytes(java.lang.String className)
          Accessor for the enhanced bytes of any classes just enhanced.
 org.datanucleus.metadata.MetaDataManager getMetaDataManager()
          Accessor for the MetaDataManager.
 java.lang.String getOutputDirectory()
          Acessor for the output directory.
 java.util.Properties getProperties()
          Accessor for global properties defining this enhancer.
protected static java.lang.String getVendorName()
          Utility to get the vendor of Enhancer.
protected static java.lang.String getVersionNumber()
          Utility to get the version of Enhancer.
 boolean isCheckonly()
          Accessor for whether we are just checking for enhancement state.
 boolean isVerbose()
          Acessor for the verbose
static void main(java.lang.String[] args)
          Entry point for command line enhancer.
protected  void resetEnhancement()
          Method to throw away any previously stored enhancement results.
 DataNucleusEnhancer setCheckonly(boolean checkonly)
          Method to set whether we should just check for enhancement state.
 DataNucleusEnhancer setClassLoader(java.lang.ClassLoader loader)
          Method to set the class loader to use for loading the class(es) to be enhanced.
 DataNucleusEnhancer setDestination(java.lang.String dir)
          Deprecated. Use setOutputDirectory() instead
 DataNucleusEnhancer setOutputDirectory(java.lang.String dir)
          Mutator for the output directory where any classes will be written.
 DataNucleusEnhancer setSystemOut(boolean sysout)
          Mutator for whether to output to system out.
 DataNucleusEnhancer setVerbose(boolean verbose)
          Mutator for the verbose flag
 void validate()
          Method to validate all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.
protected  boolean validateClass(org.datanucleus.metadata.ClassMetaData cmd, ClassEnhancer enhancer)
          Method to validate the enhancement state of the class defined by the MetaData.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOCALISER

protected static org.datanucleus.util.Localiser LOCALISER

LOGGER

public static final org.datanucleus.util.NucleusLogger LOGGER
Logger for enhancing.


userClassLoader

protected java.lang.ClassLoader userClassLoader
User-provided class loader.

Constructor Detail

DataNucleusEnhancer

public DataNucleusEnhancer()
Constructor for an enhancer for JDO using the ASM class enhancer.


DataNucleusEnhancer

public DataNucleusEnhancer(java.lang.String api,
                           java.lang.String enhancerName)
Constructor for an enhancer specifying the API and class enhancer.

Parameters:
api - The API to use.
enhancerName - Name of the class enhancer.
Method Detail

getMetaDataManager

public org.datanucleus.metadata.MetaDataManager getMetaDataManager()
Accessor for the MetaDataManager. Allows users to register their own MetaData if defined dynamically.

Returns:
MetaData Manager

getClassLoaderResolver

public org.datanucleus.ClassLoaderResolver getClassLoaderResolver()

isCheckonly

public boolean isCheckonly()
Accessor for whether we are just checking for enhancement state.

Returns:
Whether to just check

setCheckonly

public DataNucleusEnhancer setCheckonly(boolean checkonly)
Method to set whether we should just check for enhancement state.

Parameters:
checkonly - Whether to check
Returns:
The enhancer

getOutputDirectory

public java.lang.String getOutputDirectory()
Acessor for the output directory.

Returns:
the output directory

setOutputDirectory

public DataNucleusEnhancer setOutputDirectory(java.lang.String dir)
Mutator for the output directory where any classes will be written. The default is to use any current class file location and overwrite it

Parameters:
dir - the output directory
Returns:
The enhancer

getDestination

public java.lang.String getDestination()
Deprecated. Use getOutputDirectory() instead

Accessor for the destination

Returns:
the destination

setDestination

public DataNucleusEnhancer setDestination(java.lang.String dir)
Deprecated. Use setOutputDirectory() instead

Mutator for the output directory where any classes will be written. The default is to use any current class file location and overwrite it

Parameters:
dir - the output directory
Returns:
The enhancer

getClassLoader

public java.lang.ClassLoader getClassLoader()
Accessor for the user-defined class loader for enhancement (if any).

Returns:
The class loader

setClassLoader

public DataNucleusEnhancer setClassLoader(java.lang.ClassLoader loader)
Method to set the class loader to use for loading the class(es) to be enhanced.

Parameters:
loader - The loader
Returns:
The enhancer

isVerbose

public boolean isVerbose()
Acessor for the verbose

Returns:
the verbose

setVerbose

public DataNucleusEnhancer setVerbose(boolean verbose)
Mutator for the verbose flag

Parameters:
verbose - the verbose to set
Returns:
The enhancer

setSystemOut

public DataNucleusEnhancer setSystemOut(boolean sysout)
Mutator for whether to output to system out.

Parameters:
sysout - Whether to use sysout
Returns:
The enhancer

addClass

public DataNucleusEnhancer addClass(java.lang.String className,
                                    byte[] bytes)
Method to add the specified class (and its input bytes) to the list of classes to enhance. TODO Not yet implemented - use enhanceClass instead

Parameters:
className - Name of the class
bytes - Bytes of the class
Returns:
The enhancer

addClasses

public DataNucleusEnhancer addClasses(java.lang.String[] classNames)
Method to add the specified classes to the list of classes to enhance. TODO Not yet implemented - use enhanceFiles instead

Parameters:
classNames - Names of the classes
Returns:
The enhancer

addFiles

public DataNucleusEnhancer addFiles(java.lang.String[] metadataFiles)
Method to add the classes defined in specified metadata files to the list of classes to enhance. TODO Not yet implemented - use enhanceFiles instead

Parameters:
metadataFiles - Names of the metadata files
Returns:
The enhancer

addJar

public DataNucleusEnhancer addJar(java.lang.String jarFileName)
Method to add the classes defined by the specified jar to the list of classes to enhance. TODO Not yet implemented - use enhanceFiles instead

Parameters:
jarFileName - Name of the jar file
Returns:
The enhancer

addPersistenceUnit

public DataNucleusEnhancer addPersistenceUnit(java.lang.String persistenceUnitName)
Method to add the classes defined by the persistence-unit to the list of classes to enhance. TODO Not yet implemented - use enhancePersistenceUnit instead

Parameters:
persistenceUnitName - Name of the persistence-unit
Returns:
The enhancer

enhance

public void enhance()
Method to enhance all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles. TODO This is not yet implemented - use enhanceClass, enhancePersistenceUnit etc instead


validate

public void validate()
Method to validate all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles. TODO This is not yet implemented - use enhanceClass, enhancePersistenceUnit etc with checkOnly flag.


getEnhancedBytes

public byte[] getEnhancedBytes(java.lang.String className)
Accessor for the enhanced bytes of any classes just enhanced.

Parameters:
className - Name of the class
Returns:
The bytes

resetEnhancement

protected void resetEnhancement()
Method to throw away any previously stored enhancement results.


enhanceClass

public byte[] enhanceClass(java.lang.String className,
                           byte[] bytes)
Method to enhance the supplied (in-memory) class from its bytes.

Parameters:
className - Name of the class
bytes - The bytes
Returns:
The enhanced bytes

enhanceFiles

public int enhanceFiles(java.lang.String[] filenames)
Method to enhance the classes defined by the input files. The input files can be metadata files or class files.

Parameters:
filenames - Names of files to enhance
Returns:
Number of classes successfully enhanced. -1 implies failure to enhance
Throws:
NucleusEnhanceException - If an error occurs

enhancePersistenceUnit

public int enhancePersistenceUnit(java.lang.String persistentUnitName)
Method to enhance the classes defined by the specified persistence-unit.

Parameters:
persistentUnitName - Name of persistence-unit to enhance
Returns:
Number of classes successfully enhanced. -1 implies failure to enhance
Throws:
NucleusEnhanceException - If an error occurs

getClassEnhancer

protected ClassEnhancer getClassEnhancer(org.datanucleus.metadata.ClassMetaData cmd,
                                         byte[] bytes)
Method to return an instance of the ClassEnhancer for use with this class.

Parameters:
cmd - MetaData for the class
bytes - Bytes (if provided)
Returns:
ClassEnhancer instance to use

addMessage

protected void addMessage(java.lang.String msg,
                          boolean error)
Method to add a message at the required output level.

Parameters:
msg - The message
error - Whether the message is an error, so log at error level (otherwise info)

enhanceClass

protected boolean enhanceClass(org.datanucleus.metadata.ClassMetaData cmd,
                               ClassEnhancer enhancer,
                               boolean store)
Method to enhance the class defined by the MetaData.

Parameters:
cmd - MetaData for the class
enhancer - ClassEnhancer to use
store - Whether to store the class after enhancing
Returns:
Whether the operation performed without error

validateClass

protected boolean validateClass(org.datanucleus.metadata.ClassMetaData cmd,
                                ClassEnhancer enhancer)
Method to validate the enhancement state of the class defined by the MetaData.

Parameters:
cmd - MetaData for the class
enhancer - ClassEnhancer to use
Returns:
Always returns true since there is nothing that can go wrong

getProperties

public java.util.Properties getProperties()
Accessor for global properties defining this enhancer. Provides "VersionNumber", "VendorName" as the minimum, but typically also returns "API", and "EnhancerName"

Returns:
The properties.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception
Entry point for command line enhancer. The process here is in 3 parts
  1. Process the input for obvious errors and print out summary as required
  2. Convert the input into a set of FileMetaData
  3. Enhance all classes specified in the FileMetaData

Parameters:
args - Command line arguments
Throws:
java.lang.Exception - Thrown if an error occurs

getVersionNumber

protected static java.lang.String getVersionNumber()
Utility to get the version of Enhancer.

Returns:
Version number for Enhancer.

getVendorName

protected static java.lang.String getVendorName()
Utility to get the vendor of Enhancer.

Returns:
Vendor name for Enhancer.


Copyright © 2009. All Rights Reserved.