ClassEnhancer (Oracle - Berkeley DB Java API)
Date: 2010-04-12

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.8.30
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.persist.model
Class ClassEnhancer

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

All Implemented Interfaces:
  ClassFileTransformer

    public class ClassEnhancer

extends Object
implements 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 a ClassEnhancerTask ant task: the source is in the

    java/ext

directory in Berkeley DB.

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
`ClassEnhancer()` Creates a class enhancer that searches all packages.
`ClassEnhancer(Set<String> packageNames)` Creates a class enhancer that searches a given set of packages.

Method Summary
`byte[]` | `enhance(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(String[] args)` Enhances classes in the directories specified.
`static void` | `premain(String args, Instrumentation inst)` Enhances classes as specified by a JVM -javaagent argument.
`void` | `setVerbose(boolean verbose)` Sets verbose mode.
`byte[]` | `transform(ClassLoader loader, String className, Class<?> classBeingRedefined, 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(Set<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(String[] args)
                     throws 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:
    `Exception`

### premain

    public static void premain(String args,
                               Instrumentation inst)

  Enhances classes as specified by a JVM -javaagent argument.

  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.

### getVerbose

    public boolean getVerbose()

  Gets verbose mode.

  See Also:
    `setVerbose(boolean)`

### transform

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

  Specified by:
    `transform` in interface `ClassFileTransformer`

### enhance

    public byte[] enhance(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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.8.30
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 1996-2009 Oracle. All rights reserved.