Cayenne User Documentation
JPA Agent

## Cayenne Agent

Cayenne JPA provider requires enhancement of the Entity classes. In J2EE environment container takes care of registering the enhancer classes. In J2SE environment (such as command-line applications, or web containers like Jetty or Tomcat) runtime class enhancement is more tricky.

A common portable approach to integrate enhancer in J2SE environment is via Java instrumentation API (see `java.lang.instrument` package documentation for details). This requires Cayenne "agent" to be specified in the JVM startup options. Cayenne Agent is a special jar file that comes with Cayenne distribution called `"cayenne-agent-x.x.x.jar"`. It has no external dependencies (not even on Cayenne itself).

## Agent Arguments

The following arguments can be optionally passed to Cayenne Agent on startup:

`jpa-eager-load` | Loads all JPA units available on CLASSPATH. This option ensures correct enhancement of all persistent classes, regardless of the provider loading order. Without this option, classes loaded before their persistence unit was instantiated will not be properly enhanced. However use with caution as this option can slow down the application significantly (i.e. use only if you are having problems with class enhancement).

## Examples

- Command-line example:

    java -javaagent:/path/to/cayenne-agent-xxxx.jar org.example.Main

    java -javaagent:/path/to/cayenne-agent-xxxx.jar=jpa-eager-load org.example.Main

- Jetty Example
  TODO

- Tomcat Example
  TODO

.
Copyright ©2001-2008 Apache Software Foundation