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