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

    • LOGGER

      public static final NucleusLogger LOGGER
      Logger for enhancing.
    • metadataMgr

      private MetaDataManager metadataMgr
    • clr

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

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

      private String enhancerVersion
    • outputDirectory

      private 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 ClassLoader userClassLoader
      User-provided class loader.
    • componentsToEnhance

      private Collection<DataNucleusEnhancer.EnhanceComponent> componentsToEnhance
      Set of components registered for enhancing.
    • bytesForClassesToEnhanceByClassName

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

      private Map<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 Map<String,byte[]> pkClassBytesByClassName
      Map of the bytes of the PK classes created, keyed by the class name. Only populated after call of enhance().
  • Constructor Details

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

    • 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