Module org.datanucleus
Package org.datanucleus.enhancer

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

    • Field Detail

      • 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

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

      • getEnhancerVersion

        public String getEnhancerVersion()

      • 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