org.apache.openjpa.enhance
Class PCEnhancer

java.lang.Object
  org.apache.openjpa.enhance.PCEnhancer

public class PCEnhancer
extends Object

Bytecode enhancer used to enhance persistent classes from metadata. The enhancer must be invoked on all persistence-capable and persistence aware classes.

Author:

Abe White

Nested Class Summary

static interface	PCEnhancer.AuxiliaryEnhancer Plugin interface for additional enhancement.
static class	PCEnhancer.Flags Run flags.

Field Summary

static int	ENHANCE_AWARE
static int	ENHANCE_INTERFACE
static int	ENHANCE_NONE
static int	ENHANCE_PC
static int	ENHANCER_VERSION
static String	ISDETACHEDSTATEDEFINITIVE
static String	PRE

Constructor Summary

PCEnhancer(OpenJPAConfiguration conf, serp.bytecode.BCClass type, ClassMetaData meta)
Constructor.

PCEnhancer(OpenJPAConfiguration conf, serp.bytecode.BCClass type, MetaDataRepository repos)
Deprecated. use PCEnhancer(OpenJPAConfiguration, BCClass, MetaDataRepository, ClassLoader) instead.

PCEnhancer(OpenJPAConfiguration conf, serp.bytecode.BCClass type, MetaDataRepository repos, ClassLoader loader)
Constructor.

PCEnhancer(OpenJPAConfiguration conf, Class type)
Constructor.

PCEnhancer(OpenJPAConfiguration conf, ClassMetaData type)
Constructor.

Method Summary

boolean	getAddDefaultConstructor() A boolean indicating whether the enhancer should add a no-args constructor if one is not already present in the class.
PCEnhancer.AuxiliaryEnhancer[]	getAuxiliaryEnhancers() Gets the auxiliary enhancers registered as services.
BytecodeWriter	getBytecodeWriter() Return the current BytecodeWriter to write to or null if none.
boolean	getCreateSubclass() Whether the enhancer should make its arguments persistence-capable, or generate a persistence-capable subclass.
File	getDirectory() The base build directory to generate code to.
boolean	getEnforcePropertyRestrictions() Whether to fail if the persistent type uses property access and bytecode analysis shows that it may be violating OpenJPA's property access restrictions.
serp.bytecode.BCClass	getManagedTypeBytecode() Return the bytecode representation of the managed class being manipulated.
ClassMetaData	getMetaData() Return the metadata for the class being manipulated, or null if not a persistent type.
serp.bytecode.BCClass	getPCBytecode() Return the bytecode representation of the persistence-capable class being manipulated.
boolean	getRedefine() Whether the enhancer should mutate its arguments, or just run validation and optional subclassing logic on them.
Class	getType(ClassMetaData meta) Return the concrete type for the given class, i.e.
boolean	isAlreadyRedefined() Whether the type that this instance is enhancing has already been redefined.
boolean	isAlreadySubclassed() Whether the type that this instance is enhancing has already been subclassed in this instance's environment classloader.
static void	main(String[] args) Usage: java org.apache.openjpa.enhance.PCEnhancer [option]* <class name | .java file | .class file | .jdo file>+ Where the following options are recognized.
void	record() Write the generated bytecode.
int	run() Perform bytecode enhancements.
static boolean	run(OpenJPAConfiguration conf, String[] args, Options opts) Run the tool.
static boolean	run(OpenJPAConfiguration conf, String[] args, PCEnhancer.Flags flags, MetaDataRepository repos, BytecodeWriter writer, ClassLoader loader) Enhance the given classes.
void	setAddDefaultConstructor(boolean addDefaultConstructor) A boolean indicating whether the enhancer should add a no-args constructor if one is not already present in the class.
void	setBytecodeWriter(BytecodeWriter writer) Set the BytecodeWriter to write the bytecode to or null if none.
void	setCreateSubclass(boolean subclass) Whether the enhancer should make its arguments persistence-capable, or generate a persistence-capable subclass.
void	setDirectory(File dir) The base build directory to generate code to.
void	setEnforcePropertyRestrictions(boolean fail) Whether to fail if the persistent type uses property access and bytecode analysis shows that it may be violating OpenJPA's property access restrictions.
void	setRedefine(boolean redefine) Whether the enhancer should mutate its arguments, or just run validation and optional subclassing logic on them.

Methods inherited from class java.lang.Object

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

Field Detail

ENHANCER_VERSION

public static final int ENHANCER_VERSION

See Also:

Constant Field Values

ENHANCE_NONE

public static final int ENHANCE_NONE

See Also:

Constant Field Values

ENHANCE_AWARE

public static final int ENHANCE_AWARE

See Also:

Constant Field Values

ENHANCE_INTERFACE

public static final int ENHANCE_INTERFACE

See Also:

Constant Field Values

ENHANCE_PC

public static final int ENHANCE_PC

See Also:

Constant Field Values

PRE

public static final String PRE

See Also:

Constant Field Values

ISDETACHEDSTATEDEFINITIVE

public static final String ISDETACHEDSTATEDEFINITIVE

See Also:

Constant Field Values

Constructor Detail

PCEnhancer

public PCEnhancer(OpenJPAConfiguration conf,
                  Class type)

Constructor. Supply configuration and type to enhance.

PCEnhancer

public PCEnhancer(OpenJPAConfiguration conf,
                  ClassMetaData type)

Constructor. Supply configuration and type to enhance.

PCEnhancer

public PCEnhancer(OpenJPAConfiguration conf,
                  serp.bytecode.BCClass type,
                  MetaDataRepository repos)

Deprecated. use PCEnhancer(OpenJPAConfiguration, BCClass, MetaDataRepository, ClassLoader) instead.

Constructor. Supply configuration.

Parameters:

type - the bytecode representation fo the type to enhance; this can be created from any stream or file

repos - a metadata repository to use for metadata access, or null to create a new reporitory; the repository from the given configuration isn't used by default because the configuration might be an implementation-specific subclass whose metadata required more than just base metadata files

PCEnhancer

public PCEnhancer(OpenJPAConfiguration conf,
                  serp.bytecode.BCClass type,
                  MetaDataRepository repos,
                  ClassLoader loader)

Constructor. Supply configuration.

Parameters:

type - the bytecode representation fo the type to enhance; this can be created from any stream or file

repos - a metadata repository to use for metadata access, or null to create a new reporitory; the repository from the given configuration isn't used by default because the configuration might be an implementation-specific subclass whose metadata required more than just base metadata files

loader - the environment classloader to use for loading classes and resources.

PCEnhancer

public PCEnhancer(OpenJPAConfiguration conf,
                  serp.bytecode.BCClass type,
                  ClassMetaData meta)

Constructor. Supply configuration, type, and metadata.

Method Detail

getPCBytecode

public serp.bytecode.BCClass getPCBytecode()

Return the bytecode representation of the persistence-capable class being manipulated.

getManagedTypeBytecode

public serp.bytecode.BCClass getManagedTypeBytecode()

Return the bytecode representation of the managed class being manipulated. This is usually the same as getPCBytecode(), except when running the enhancer to redefine and subclass existing persistent types.

getMetaData

public ClassMetaData getMetaData()

Return the metadata for the class being manipulated, or null if not a persistent type.

getAddDefaultConstructor

public boolean getAddDefaultConstructor()

A boolean indicating whether the enhancer should add a no-args constructor if one is not already present in the class. OpenJPA requires that a no-arg constructor (whether created by the compiler or by the user) be present in a PC.

setAddDefaultConstructor

public void setAddDefaultConstructor(boolean addDefaultConstructor)

A boolean indicating whether the enhancer should add a no-args constructor if one is not already present in the class. OpenJPA requires that a no-arg constructor (whether created by the compiler or by the user) be present in a PC.

getRedefine

public boolean getRedefine()

Whether the enhancer should mutate its arguments, or just run validation and optional subclassing logic on them. Usually used in conjunction with setCreateSubclass(true).

Since:

1.0.0

setRedefine

public void setRedefine(boolean redefine)

Whether the enhancer should mutate its arguments, or just run validation and optional subclassing logic on them. Usually used in conjunction with setCreateSubclass(true).

Since:

1.0.0

isAlreadyRedefined

public boolean isAlreadyRedefined()

Whether the type that this instance is enhancing has already been redefined.

Since:

1.0.0

isAlreadySubclassed

public boolean isAlreadySubclassed()

Whether the type that this instance is enhancing has already been subclassed in this instance's environment classloader.

Since:

1.0.0

getCreateSubclass

public boolean getCreateSubclass()

Whether the enhancer should make its arguments persistence-capable, or generate a persistence-capable subclass.

Since:

1.0.0

setCreateSubclass

public void setCreateSubclass(boolean subclass)

Whether the enhancer should make its arguments persistence-capable, or generate a persistence-capable subclass.

Since:

1.0.0

getEnforcePropertyRestrictions

public boolean getEnforcePropertyRestrictions()

Whether to fail if the persistent type uses property access and bytecode analysis shows that it may be violating OpenJPA's property access restrictions.

setEnforcePropertyRestrictions

public void setEnforcePropertyRestrictions(boolean fail)

Whether to fail if the persistent type uses property access and bytecode analysis shows that it may be violating OpenJPA's property access restrictions.

getDirectory

public File getDirectory()

The base build directory to generate code to. The proper package structure will be created beneath this directory. Defaults to overwriting the existing class file if null.

setDirectory

public void setDirectory(File dir)

The base build directory to generate code to. The proper package structure will be creaed beneath this directory. Defaults to overwriting the existing class file if null.

getBytecodeWriter

public BytecodeWriter getBytecodeWriter()

Return the current BytecodeWriter to write to or null if none.

setBytecodeWriter

public void setBytecodeWriter(BytecodeWriter writer)

Set the BytecodeWriter to write the bytecode to or null if none.

run

public int run()

Perform bytecode enhancements.

Returns:

ENHANCE_* constant

record

public void record()
            throws IOException

Write the generated bytecode.

Throws:

IOException

getAuxiliaryEnhancers

public PCEnhancer.AuxiliaryEnhancer[] getAuxiliaryEnhancers()

Gets the auxiliary enhancers registered as services.

getType

public Class getType(ClassMetaData meta)

Return the concrete type for the given class, i.e. impl for managed interfaces

main

public static void main(String[] args)
                 throws IOException

Usage: java org.apache.openjpa.enhance.PCEnhancer [option]* <class name | .java file | .class file | .jdo file>+ Where the following options are recognized.

• -properties/-p <properties file>: The path to a OpenJPA properties file containing information as outlined in Configuration; optional.
• -<property name> <property value>: All bean properties of the standard OpenJPA OpenJPAConfiguration can be set by using their names and supplying a value; for example:
• -directory/-d <build directory>: The path to the base directory where enhanced classes are stored. By default, the enhancer overwrites the original .class file with the enhanced version. Use this option to store the generated .class file in another directory. The package structure will be created beneath the given directory.
• -addDefaultConstructor/-adc [true/t | false/f]: Whether to add a default constructor to persistent classes missing one, as opposed to throwing an exception. Defaults to true.
• -tmpClassLoader/-tcl [true/t | false/f]: Whether to load the pre-enhanced classes using a temporary class loader. Defaults to true. Set this to false when attempting to debug class loading errors.
• -enforcePropertyRestrictions/-epr [true/t | false/f]: Whether to throw an exception if a PROPERTY access entity appears to be violating standard property restrictions. Defaults to false.

Each additional argument can be either the full class name of the type to enhance, the path to the .java file for the type, the path to the .class file for the type, or the path to a .jdo file listing one or more types to enhance. If the type being enhanced has metadata, it will be enhanced as a persistence capable class. If not, it will be considered a persistence aware class, and all access to fields of persistence capable classes will be replaced by the appropriate get/set method. If the type explicitly declares the persistence-capable interface, it will not be enhanced. Thus, it is safe to invoke the enhancer on classes that are already enhanced.

Throws:

IOException

run

public static boolean run(OpenJPAConfiguration conf,
                          String[] args,
                          Options opts)
                   throws IOException

Run the tool. Returns false if invalid options given.

Throws:

IOException

run

public static boolean run(OpenJPAConfiguration conf,
                          String[] args,
                          PCEnhancer.Flags flags,
                          MetaDataRepository repos,
                          BytecodeWriter writer,
                          ClassLoader loader)
                   throws IOException

Enhance the given classes.

Throws:

IOException