org.datanucleus.enhancer

Class DataNucleusEnhancer

java.lang.Object

org.datanucleus.enhancer.DataNucleusEnhancer

public class DataNucleusEnhancer
extends Object

DataNucleus Byte-Code Enhancer. This provides the entry point for enhancement. Enhancement is performed using a ClassEnhancer. Currently provides a ClassEnhancer using ASM.

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

Fields

Modifier and Type	Field and Description
protected static Localiser	LOCALISER
static NucleusLogger	LOGGER Logger for enhancing.
protected ClassLoader	userClassLoader User-provided class loader.

Constructor Summary

Constructors

Constructor and Description
DataNucleusEnhancer(String apiName, Properties props) Constructor for an enhancer specifying the API and class enhancer and optional properties.

Method Summary

Modifier and Type	Method and Description
DataNucleusEnhancer	addClass(String className, byte[] bytes) Method to add the specified class (and its input bytes) to the list of classes to enhance.
DataNucleusEnhancer	addClasses(String... classNames) Method to add the specified classes to the list of classes to enhance.
DataNucleusEnhancer	addFiles(String... filenames) Method to add the specified files to the list of components to enhance.
DataNucleusEnhancer	addJar(String jarFileName) Method to add the classes defined by the specified jar to the list of components to enhance.
protected void	addMessage(String msg, boolean error) Method to add a message at the required output level.
DataNucleusEnhancer	addPersistenceUnit(String persistenceUnitName) Method to add the classes defined by the persistence-unit to the list of classes to enhance.
int	enhance() Method to enhance all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.
protected boolean	enhanceClass(ClassMetaData cmd, ClassEnhancer enhancer, boolean store) Method to enhance the class defined by the MetaData.
protected ClassEnhancer	getClassEnhancer(ClassMetaData cmd, byte[] bytes) Method to return an instance of the ClassEnhancer for use with this class.
ClassLoader	getClassLoader() Accessor for the user-defined class loader for enhancement (if any).
byte[]	getEnhancedBytes(String className) Accessor for the enhanced bytes of any classes just enhanced.
protected Collection<FileMetaData>	getFileMetadataForInput() Method that processes the registered components to enhance, and loads the metadata for them into the MetaDataManager, returning the associated FileMetaData.
MetaDataManager	getMetaDataManager() Accessor for the MetaDataManager.
String	getOutputDirectory() Acessor for the output directory.
byte[]	getPkClassBytes(String className) Accessor for the bytes of any pk classes just created.
Properties	getProperties() Accessor for global properties defining this enhancer.
boolean	isVerbose() Accessor for the verbose setting
static void	main(String[] args) Entry point for command line enhancer.
protected void	resetEnhancement() Method to throw away any previously stored enhancement results.
DataNucleusEnhancer	setClassLoader(ClassLoader loader) Method to set the class loader to use for loading the class(es) to be enhanced.
DataNucleusEnhancer	setDetachListener(boolean flag) Mutator for whether to allow generation of default constructor where needed.
DataNucleusEnhancer	setGenerateConstructor(boolean flag) Mutator for whether to allow generation of default constructor where needed.
DataNucleusEnhancer	setGeneratePK(boolean flag) Mutator for whether to allow generation of PKs where needed.
DataNucleusEnhancer	setOutputDirectory(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
int	validate() Method to validate all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.
protected boolean	validateClass(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 final Localiser LOCALISER

LOGGER

public static final NucleusLogger LOGGER

Logger for enhancing.

userClassLoader

protected ClassLoader userClassLoader

User-provided class loader.

Constructor Detail

DataNucleusEnhancer

public DataNucleusEnhancer(String apiName,
                           Properties props)

Constructor for an enhancer specifying the API and class enhancer and optional properties.

Parameters:

apiName - Name of the API to use; defines which MetaDataManager to utilise.

props - properties controlling enhancement

Method Detail

getMetaDataManager

public MetaDataManager getMetaDataManager()

Accessor for the MetaDataManager. Allows users to register their own MetaData if defined dynamically.

Returns:

MetaData Manager

getOutputDirectory

public String getOutputDirectory()

Acessor for the output directory.

Returns:

the output directory

setOutputDirectory

public DataNucleusEnhancer setOutputDirectory(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

getClassLoader

public ClassLoader getClassLoader()

Accessor for the user-defined class loader for enhancement (if any).

Returns:

The class loader

setClassLoader

public DataNucleusEnhancer setClassLoader(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()

Accessor for the verbose setting

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

setGeneratePK

public DataNucleusEnhancer setGeneratePK(boolean flag)

Mutator for whether to allow generation of PKs where needed.

Parameters:

flag - Whether to enable this

Returns:

The enhancer

setGenerateConstructor

public DataNucleusEnhancer setGenerateConstructor(boolean flag)

Mutator for whether to allow generation of default constructor where needed.

Parameters:

flag - Whether to enable this

Returns:

The enhancer

setDetachListener

public DataNucleusEnhancer setDetachListener(boolean flag)

Mutator for whether to allow generation of default constructor where needed.

Parameters:

flag - Whether to enable this

Returns:

The enhancer

addClass

public DataNucleusEnhancer addClass(String className,
                                    byte[] bytes)

Method to add the specified class (and its input bytes) to the list of classes to enhance.

Parameters:

className - Name of the class (in the format "mydomain.MyClass")

bytes - Bytes of the class

Returns:

The enhancer

addClasses

public DataNucleusEnhancer addClasses(String... classNames)

Method to add the specified classes to the list of classes to enhance.

Parameters:

classNames - Names of the classes

Returns:

The enhancer

addFiles

public DataNucleusEnhancer addFiles(String... filenames)

Method to add the specified files to the list of components to enhance.

Parameters:

filenames - Names of the files

Returns:

The enhancer

addJar

public DataNucleusEnhancer addJar(String jarFileName)

Method to add the classes defined by the specified jar to the list of components to enhance.

Parameters:

jarFileName - Name of the jar file

Returns:

The enhancer

addPersistenceUnit

public DataNucleusEnhancer addPersistenceUnit(String persistenceUnitName)

Method to add the classes defined by the persistence-unit to the list of classes to enhance.

Parameters:

persistenceUnitName - Name of the persistence-unit

Returns:

The enhancer

enhance

public int enhance()

Method to enhance all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.

Returns:

Number of classes enhanced

validate

public int validate()

Method to validate all classes defined by addClass, addClasses, addJar, addPersistenceUnit, addFiles.

Returns:

Number of classes validated

getFileMetadataForInput

protected Collection<FileMetaData> getFileMetadataForInput()

Method that processes the registered components to enhance, and loads the metadata for them into the MetaDataManager, returning the associated FileMetaData.

Returns:

The FileMetaData for the registered components.

getEnhancedBytes

public byte[] getEnhancedBytes(String className)

Accessor for the enhanced bytes of any classes just enhanced.

Parameters:

className - Name of the class

Returns:

The bytes

Throws:

NucleusException - if no bytes are available for the specified class

getPkClassBytes

public byte[] getPkClassBytes(String className)

Accessor for the bytes of any pk classes just created.

Parameters:

className - Name of the class

Returns:

The bytes

Throws:

NucleusException - if no bytes are available for the specified class

resetEnhancement

protected void resetEnhancement()

Method to throw away any previously stored enhancement results.

getClassEnhancer

protected ClassEnhancer getClassEnhancer(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(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(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(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 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(String[] args)
                 throws Exception

Entry point for command line enhancer.

Parameters:

args - Command line arguments

Throws:

Exception - Thrown if an error occurs