org.datanucleus.enhancer
Class DataNucleusEnhancer

java.lang.Object
  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 :-

• Via the command line, entering via the main method. This creates a DataNucleusEnhancer object, sets the options necessary and calls the execute method.
• Programmatically, creating the DataNucleusEnhancer object settings options and running etc.

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.