Package org.datanucleus.enhancer

Class 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.

    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().addPersistenceUnit("myPersistenceUnit").enhance();
    enhancing all classes specified by the persistence unit.

    • Field Detail

      • LOGGER

        public static final NucleusLogger LOGGER
        Logger for enhancing.

      • clr

        private ClassLoaderResolver clr
        ClassLoader resolver for use during the enhancement process.

      • apiName

        private java.lang.String apiName
        Name of the API to use for enhancement (default is JDO).

      • enhancerVersion

        private java.lang.String enhancerVersion

      • outputDirectory

        private java.lang.String outputDirectory
        Optional output directory where any writing of enhanced classes goes.

      • verbose

        private boolean verbose
        Whether we should provide verbose output.

      • systemOut

        private boolean systemOut
        Whether to output to System.out (as well as logging).

      • generatePK

        private boolean generatePK
        Whether to allow generation of the PK when needed.

      • generateConstructor

        private boolean generateConstructor
        Whether to allow generation of the default constructor when needed.

      • detachListener

        private boolean detachListener
        Whether to use Detach Listener

      • userClassLoader

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

      • bytesForClassesToEnhanceByClassName

        private java.util.Map<java.lang.String,​byte[]> bytesForClassesToEnhanceByClassName
        Map storing input bytes of any classes to enhance, keyed by the class name (if specified using bytes).

      • enhancedBytesByClassName

        private java.util.Map<java.lang.String,​byte[]> enhancedBytesByClassName
        Map of the enhanced bytes of all classes just enhanced, keyed by the class name. Only populated after call of enhance().

      • pkClassBytesByClassName

        private java.util.Map<java.lang.String,​byte[]> pkClassBytesByClassName
        Map of the bytes of the PK classes created, keyed by the class name. Only populated after call of enhance().

    • Constructor Detail

      • DataNucleusEnhancer

        public DataNucleusEnhancer​(java.lang.String apiName,
                           java.util.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 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

      • 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()
        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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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

      • addPersistenceUnit

        public DataNucleusEnhancer addPersistenceUnit​(PersistenceUnitMetaData pumd)
        Method to add the classes defined by the persistence-unit to the list of classes to enhance.
        Parameters:
        pumd - The persistence-unit metadata (dynamically created)
        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 java.util.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​(java.lang.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​(java.lang.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​(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​(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 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.

      • getEnhancerVersion

        public java.lang.String getEnhancerVersion()

      • main

        public static void main​(java.lang.String[] args)
                 throws java.lang.Exception
        Entry point for command line enhancer.
        Parameters:
        args - Command line arguments
        Throws:
        java.lang.Exception - Thrown if an error occurs