com.sleepycat.persist.model

## Class ClassEnhancer

- java.lang.Object
- - com.sleepycat.persist.model.ClassEnhancer

- All Implemented Interfaces:
    java.lang.instrument.ClassFileTransformer

      public class ClassEnhancer
      extends java.lang.Object
      implements java.lang.instrument.ClassFileTransformer

  Enhances the bytecode of persistent classes to provide efficient access to fields and constructors, and to avoid special security policy settings for accessing non-public members. Classes are enhanced if they are annotated with `Entity` or `Persistent`.

  `ClassEnhancer` objects are thread-safe. Multiple threads may safely call the methods of a shared `ClassEnhancer` object.

  As described in the package summary, bytecode enhancement may be used either at runtime or offline (at build time).

  To use enhancement offline, this class may be used as a `main program`.

  For enhancement at runtime, this class provides the low level support needed to transform class bytes during class loading. To configure runtime enhancement you may use one of the following approaches:

  1. The BDB `je-<version>.jar` or `db.jar` file may be used as an instrumentation agent as follows:

         java -javaagent:<BDB-JAR-FILE>=enhance:packageNames ...

     `packageNames` is a comma separated list of packages containing persistent classes. Sub-packages of these packages are also searched. If `packageNames` is omitted then all packages known to the current classloader are searched.

     The "-v" option may be included in the comma separated list to print the name of each class that is enhanced.

  2. The `enhance(java.lang.String, byte[])` method may be called to implement a class loader that performs enhancement. Using this approach, it is the developer's responsibility to implement and configure the class loader.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ClassEnhancer()` Creates a class enhancer that searches all packages.
    `ClassEnhancer(java.util.Set<java.lang.String> packageNames)` Creates a class enhancer that searches a given set of packages.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `enhance(java.lang.String className, byte[] classBytes)` Enhances the given class bytes if the class is annotated with `Entity` or `Persistent`.
    `boolean` | `getVerbose()` Gets verbose mode.
    `static void` | `main(java.lang.String[] args)` Enhances classes in the directories specified.
    `static void` | `premain(java.lang.String args, java.lang.instrument.Instrumentation inst)` Enhances classes as specified by a JVM -javaagent argument.
    `void` | `setVerbose(boolean verbose)` Sets verbose mode.
    `byte[]` | `transform(java.lang.ClassLoader loader, java.lang.String className, java.lang.Class<?> classBeingRedefined, java.security.ProtectionDomain protectionDomain, byte[] classfileBuffer)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ClassEnhancer

          public ClassEnhancer()

      Creates a class enhancer that searches all packages.

    - #### ClassEnhancer

          public ClassEnhancer(java.util.Set<java.lang.String> packageNames)

      Creates a class enhancer that searches a given set of packages.
      Parameters:
        `packageNames` - a set of packages to search for persistent classes. Sub-packages of these packages are also searched. If empty or null, all packages known to the current classloader are searched.

  - ### Method Detail

    - #### main

          public static void main(java.lang.String[] args)
                           throws java.lang.Exception

      Enhances classes in the directories specified. The class files are replaced when they are enhanced, without changing the file modification date. For example:

          java -cp je-<version>.jar com.sleepycat.persist.model.ClassEnhancer ./classes

      The "-v" argument may be specified to print the name of each class file that is enhanced. The total number of class files enhanced will always be printed.

      Parameters:
        `args` - one or more directories containing classes to be enhanced. Subdirectories of these directories will also be searched. Optionally, -v may be included to print the name of every class file enhanced.
      Throws:
        `java.lang.Exception` - if a problem occurs.

    - #### premain

          public static void premain(java.lang.String args,
                                     java.lang.instrument.Instrumentation inst)

      Enhances classes as specified by a JVM -javaagent argument.
      Parameters:
        `args` - see java.lang.instrument.Instrumentation.
        `inst` - see java.lang.instrument.Instrumentation.
      See Also:
        `Instrumentation`

    - #### setVerbose

          public void setVerbose(boolean verbose)

      Sets verbose mode.

      True may be specified to print the name of each class file that is enhanced. This property is false by default.

      Parameters:
        `verbose` - whether to use verbose mode.

    - #### getVerbose

          public boolean getVerbose()

      Gets verbose mode.
      Returns:
        whether to use verbose mode.
      See Also:
        `setVerbose(boolean)`

    - #### transform

          public byte[] transform(java.lang.ClassLoader loader,
                                  java.lang.String className,
                                  java.lang.Class<?> classBeingRedefined,
                                  java.security.ProtectionDomain protectionDomain,
                                  byte[] classfileBuffer)

      Specified by:
        `transform` in interface `java.lang.instrument.ClassFileTransformer`

    - #### enhance

          public byte[] enhance(java.lang.String className,
                                byte[] classBytes)

      Enhances the given class bytes if the class is annotated with `Entity` or `Persistent`.
      Parameters:
        `className` - the class name in binary format; for example, "my.package.MyClass$Name", or null if no filtering by class name should be performed.
        `classBytes` - are the class file bytes to be enhanced.
      Returns:
        the enhanced bytes, or null if no enhancement was performed.

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.