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. It may also be used via an ant task.

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.

Author:

Mark Hayes

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

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.