configuration

This chapter describes the OpenJPA configuration framework. It concludes with descriptions of all the configuration properties recognized by OpenJPA. You may want to browse these properties now, but it is not necessary. Most of them will be referenced later in the documentation as we explain the various features they apply to.

configuration runtime The OpenJPA runtime includes a comprehensive system of configuration defaults and overrides: openjpa.xml OpenJPA first looks for an optional openjpa.xml resource. OpenJPA searches for this resource in each top-level directory of your CLASSPATH. OpenJPA will also find the resource if you place it within a META-INF directory in any top-level directory of the CLASSPATH. The openjpa.xml resource contains property settings in JPA's XML format. You can customize the name or location of the above resource by specifying the correct resource path in the openjpa.properties System property. You can override any value defined in the above resource by setting the System property of the same name to the desired value. Persistence createEntityManagerFactory In JPA, the values in the standard META-INF/persistence.xml bootstrapping file used by the Persistence class at runtime override the values in the above resource, as well as any System property settings. The Map passed to Persistence.createEntityManagerFactory at runtime also overrides previous settings, including properties defined in persistence.xml. In JPA, The Map passed to the methods defined in the Query and EntityManager interfaces at runtime also overrides previous settings, including properties defined in persistence.xml. The Map is in effect only during the method invocation. When using JCA deployment the config-property values in your ra.xml file override other settings. All OpenJPA command-line tools accept flags that allow you to specify the configuration resource to use, and to override any property. describes these flags. Internally, the OpenJPA runtime environment and development tools manipulate property settings through a general Configuration interface, and in particular its OpenJPAConfiguration and JDBCConfiguration subclasses. For advanced customization, OpenJPA's extended runtime interfaces and its development tools allow you to access these interfaces directly. See the Javadoc for details.

configuration command line OpenJPA development tools share the same set of configuration defaults and overrides as the runtime system. They also allow you to specify property values on the command line: -properties/-p <configuration file or resource>: Use the -properties flag, or its shorter -p form, to specify a configuration file to use. Note that OpenJPA always searches the default file locations described above, so this flag is only needed when you do not have a default resource in place, or when you wish to override the defaults. The given value can be the path to a file, or the resource name of a file somewhere in the CLASSPATH. OpenJPA will search the given location as well as the location prefixed by META-INF/ . Thus, to point an OpenJPA tool at META-INF/my-persistence.xml, you can use: <tool> -p my-persistence.xml If you want to run a tool against just one particular persistence unit in a configuration file, you can do so by specifying an anchor along with the resource. If you do not specify an anchor, the tools will run against all the persistence units defined within the specified resource, or the default resource if none is specified. If the persistence unit is defined within the default resource location, then you can just specify the raw anchor itself: <tool> -p my-persistence.xml#sales-persistence-unit <tool> -p #invoice-persistence-unit -<property name> <property value>: Any configuration property that you can specify in a configuration file can be overridden with a command line flag. The flag name is always the last token of the corresponding property name, with the first letter in either upper or lower case. For example, to override the openjpa.ConnectionUserName property, you could pass the -connectionUserName <value> flag to any tool. Values set this way override both the values in the configuration file and values set via System properties.

code formatting Some OpenJPA development tools generate Java code. These tools share a common set of command-line flags for formatting their output to match your coding style. All code formatting flags can begin with either the codeFormat or cf prefix. -codeFormat./-cf.tabSpaces <spaces>: The number of spaces that make up a tab, or 0 to use tab characters. Defaults to using tab characters. -codeFormat./-cf.spaceBeforeParen <true/t | false/f>: Whether or not to place a space before opening parentheses on method calls, if statements, loops, etc. Defaults to false. -codeFormat./-cf.spaceInParen <true/t | false/f>: Whether or not to place a space within parentheses; i.e. method( arg) . Defaults to false. -codeFormat./-cf.braceOnSameLine <true/t | false/f>: Whether or not to place opening braces on the same line as the declaration that begins the code block, or on the next line. Defaults to true . -codeFormat./-cf.braceAtSameTabLevel <true/t | false/f> : When the braceOnSameLine option is disabled, you can choose whether to place the brace at the same tab level of the contained code. Defaults to false. -codeFormat./-cf.scoreBeforeFieldName <true/t | false/f> : Whether to prefix an underscore to names of private member variables. Defaults to false. -codeFormat./-cf.linesBetweenSections <lines>: The number of lines to skip between sections of code. Defaults to 1. java org.apache.openjpa.enhance.ApplicationIdTool -cf.spaceBeforeParen true -cf.tabSpaces 4

configuration plugins plugins configuration Because OpenJPA is a highly customizable environment, many configuration properties relate to the creation and configuration of system plugins. Plugin properties have a syntax very similar to that of Java 5 annotations. They allow you to specify both what class to use for the plugin and how to configure the public fields or bean properties of the instantiated plugin instance. The easiest way to describe the plugin syntax is by example: OpenJPA has a pluggable L2 caching mechanism that is controlled by the openjpa.DataCache configuration property. Suppose that you have created a new class, com.xyz.MyDataCache, that you want OpenJPA to use for caching. You've made instances of MyDataCache configurable via two methods, setCacheSize(int size) and setRemoteHost(String host). The sample below shows how you would tell OpenJPA to use an instance of your custom plugin with a max size of 1000 and a remote host of cacheserver . <property name="openjpa.DataCache" value="com.xyz.MyDataCache(CacheSize=1000, RemoteHost=cacheserver)"/> As you can see, plugin properties take a class name, followed by a comma-separated list of values for the plugin's public fields or bean properties in parentheses. OpenJPA will match each named property to a field or setter method in the instantiated plugin instance, and set the field or invoke the method with the given value (after converting the value to the right type, of course). The first letter of the property names can be in either upper or lower case. The following would also have been valid: com.xyz.MyDataCache(cacheSize=1000, remoteHost=cacheserver) If you do not need to pass any property settings to a plugin, you can just name the class to use: com.xyz.MyDataCache Similarly, if the plugin has a default class that you do not want to change, you can simply specify a list of property settings, without a class name. For example, OpenJPA's query cache companion to the data cache has a default implementation suitable to most users, but you still might want to change the query cache's size. It has a CacheSize property for this purpose: CacheSize=1000 Finally, many of OpenJPA's built-in options for plugins have short alias names that you can use in place of the full class name. The data cache property, for example, has an available alias of true for the standard cache implementation. The property value simply becomes: true The standard cache implementation class also has a CacheSize property, so to use the standard implementation and configure the size, specify: true(CacheSize=1000) The remainder of this chapter reviews the set of configuration properties OpenJPA recognizes.

configuration of OpenJPA properties OpenJPA defines many configuration properties. Most of these properties are provided for advanced users who wish to customize OpenJPA's behavior; the majority of developers can omit them. The following properties apply to any OpenJPA back-end, though the given descriptions are tailored to OpenJPA's default JDBC store. Few of the properties recognized by OpenJPA have been standardized in JPA 2.0 Specification using equivalent names. These properties can be specified either by the JPA standard key or equivalent OpenJPA key. Specifying the same key once as JPA standard key and again as equivalent OpenJPA key in the same configuration, however, is not allowed. The following table lists these standard JPA properties and their OpenJPA equivalent. Standard JPA 2.0 OpenJPA Equivalent javax.persistence.jdbc.driver openjpa.ConnectionDriverName javax.persistence.jdbc.url openjpa.ConnectionURL javax.persistence.jdbc.user openjpa.ConnectionUserName javax.persistence.jdbc.password openjpa.ConnectionPassword

AutoClear transactions AutoClear AutoClear Property name: openjpa.AutoClear Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getAutoClear Resource adaptor config-property: AutoClear Default: datastore Possible values: datastore, all Description: When to automatically clear instance state: on entering a datastore transaction, or on entering any transaction.

AutoDetach detach AutoDetach AutoDetach Property name: openjpa.AutoDetach Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getAutoDetach Resource adaptor config-property: AutoDetach Default: - Possible values: close, commit, nontx-read Description: A comma-separated list of events when managed instances will be automatically detached.

BrokerFactory Property name: openjpa.BrokerFactory Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerFactory Resource adaptor config-property: BrokerFactory Default: jdbc Possible values: jdbc, abstractstore, remote Description: A plugin string (see ) describing the org.apache.openjpa.kernel.BrokerFactory type to use.

BrokerImpl Broker BrokerImpl Property name: openjpa.BrokerImpl Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerImpl Resource adaptor config-property: BrokerImpl Default: default Description: A plugin string (see ) describing the org.apache.openjpa.kernel.Broker type to use at runtime. See on for details.

Callbacks Callbacks Callbacks Property name: openjpa.Callbacks Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getCallbackOptionsInstance Resource adaptor config-property: Callbacks Default: default Description: A plugin string (see ) to fine tune some of the configurable properties related to callbacks. The plug-in supports two boolean properties: PostPersistCallbackImmediate: whether the post-persist callback is invoked as soon as a new instance is managed. The default is false, implies that the post-persist callback is invoked after the instance been committed or flushed to the datastore. AllowsMultipleMethodsForSameCallback: whether multiple methods of the same class can handle the same callback event. Defaults to false.

ClassResolver class loading ClassResolver Property name: openjpa.ClassResolver Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getClassResolver Resource adaptor config-property: ClassResolver Default: default Description: A plugin string (see ) describing the org.apache.openjpa.util.ClassResolver implementation to use for class name resolution. You may wish to plug in your own resolver if you have special classloading needs.

Compatibility backwards compatibility Property name: openjpa.Compatibility Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getCompatibility Resource adaptor config-property: Compatibility Default: - Description: Encapsulates options to mimic the behavior of previous OpenJPA releases.

ConnectionDriverName connections ConnectionDriverName Property name: openjpa.ConnectionDriverName Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionDriverName Resource adaptor config-property: ConnectionDriverName Default: - Description: The full class name of either the JDBC java.sql.Driver, or a javax.sql.DataSource implementation to use to connect to the database. See for details.

Connection2DriverName connections Connection2DriverName Property name: openjpa.Connection2DriverName Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2DriverName Resource adaptor config-property: Connection2DriverName Default: - Description: This property is equivalent to the openjpa.ConnectionDriverName property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionFactory connections ConnectionFactory Property name: openjpa.ConnectionFactory Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory Resource adaptor config-property: ConnectionFactory Default: - Description: A javax.sql.DataSource to use to connect to the database. See for details.

ConnectionFactory2 connections ConnectionFactory2 Property name: openjpa.ConnectionFactory2 Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2 Resource adaptor config-property: ConnectionFactory2 Default: - Description: An unmanaged javax.sql.DataSource to use to connect to the database. See for details.

ConnectionFactoryName connections ConnectionFactoryName Property name: openjpa.ConnectionFactoryName Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryName Resource adaptor config-property: ConnectionFactoryName Default: - Description: The JNDI location of a javax.sql.DataSource to use to connect to the database. See for details.

ConnectionFactory2Name connections ConnectionFactory2Name Property name: openjpa.ConnectionFactory2Name Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Name Resource adaptor config-property: ConnectionFactory2Name Default: - Description: The JNDI location of an unmanaged javax.sql.DataSource to use to connect to the database. See for details.

ConnectionFactoryMode connections ConnectionFactoryMode Property name: openjpa.ConnectionFactoryMode Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryMode Resource adaptor config-property: ConnectionFactoryMode Default: local Possible values: local, managed Description: The connection factory mode to use when integrating with the application server's managed transactions. See for details.

ConnectionFactoryProperties connections ConnectionFactoryProperties Property name: openjpa.ConnectionFactoryProperties Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryProperties Resource adaptor config-property: ConnectionFactoryProperties Default: - Description: A plugin string (see ) listing properties for configuration of the datasource in use. See the for details.

ConnectionFactory2Properties connections ConnectionFactory2Properties Property name: openjpa.ConnectionFactory2Properties Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Properties Resource adaptor config-property: ConnectionFactory2Properties Default: - Description: This property is equivalent to the openjpa.ConnectionFactoryProperties property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionPassword connections ConnectionPassword Property name: openjpa.ConnectionPassword Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionPassword Resource adaptor config-property: ConnectionPassword Default: - Description: The password for the user specified in the ConnectionUserName property. See for details.

Connection2Password connections Connection2Password Property name: openjpa.Connection2Password Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Password Resource adaptor config-property: Connection2Password Default: - Description: This property is equivalent to the openjpa.ConnectionPassword property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionProperties connections ConnectionProperties Property name: openjpa.ConnectionProperties Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionProperties Resource adaptor config-property: ConnectionProperties Default: - Description: A plugin string (see ) listing properties to configure the driver listed in the ConnectionDriverName property described below. See for details.

Connection2Properties connections Connection2Properties Property name: openjpa.Connection2Properties Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Properties Resource adaptor config-property: Connection2Properties Default: - Description: This property is equivalent to the openjpa.ConnectionProperties property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionURL connections ConnectionURL Property name: openjpa.ConnectionURL Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionURL Resource adaptor config-property: ConnectionURL Default: - Description: The JDBC URL for the database. See for details.

Connection2URL connections Connection2URL Property name: openjpa.Connection2URL Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2URL Resource adaptor config-property: Connection2URL Default: - Description: This property is equivalent to the openjpa.ConnectionURL property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionUserName connections ConnectionUserName Property name: openjpa.ConnectionUserName Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionUserName Resource adaptor config-property: ConnectionUserName Default: - Description: The user name to use when connecting to the database. See the for details.

Connection2UserName connections Connection2UserName Property name: openjpa.Connection2UserName Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2UserName Resource adaptor config-property: Connection2UserName Default: - Description: This property is equivalent to the openjpa.ConnectionUserName property described in , but applies to the alternate connection factory used for unmanaged connections. See for details.

ConnectionRetainMode connections ConnectionRetainMode Property name: openjpa.ConnectionRetainMode Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionRetainMode Resource adaptor config-property: ConnectionRetainMode Default: on-demand Description: Controls how OpenJPA uses datastore connections. This property can also be specified for individual sessions. See for details.

DataCache caching DataCache Property name: openjpa.DataCache Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDataCache Resource adaptor config-property: DataCache Default: false Description: A plugin list string (see ) describing the org.apache.openjpa.datacache.DataCaches to use for data caching. See for details.

DataCacheManager caching DataCacheManager Property name: openjpa.DataCacheManager Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheManager Resource adaptor config-property: DataCacheManager Default: default Description: A plugin string (see ) describing the openjpa.datacache.DataCacheManager that manages the system data caches. See for details on data caching.

DataCacheMode caching DataCacheTimeout Property name: openjpa.DataCacheMode Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheMode Resource adaptor config-property: DataCacheMode Default: DataCacheMode.UNSPECIFIED (see javadoc for details) Description:Determines which entities will be included in the DataCache. May be any of the values defined in .

DataCacheTimeout caching DataCacheTimeout Property name: openjpa.DataCacheTimeout Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheTimeout Resource adaptor config-property: DataCacheTimeout Default: -1 Description: The number of milliseconds that data in the data cache is valid. Set this to -1 to indicate that data should not expire from the cache. This property can also be specified for individual classes. See for details.

DetachState detach DetachState DetachState Property name: openjpa.DetachState Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDetachState Resource adaptor config-property: DetachState Default: loaded Possible values: loaded, fetch-groups, all Description: Determines which fields are part of the detached graph and related options. For more details, see .

DynamicDataStructs caching DynamicDataStructs remote DynamicDataStructs Property name: openjpa.DynamicDataStructs Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDynamicDataStructs Resource adaptor config-property: DynamicDataStructs Default: false Description: Whether to dynamically generate customized structs to hold persistent data. Both the OpenJPA data cache and the remote framework rely on data structs to cache and transfer persistent state. With dynamic structs, OpenJPA can customize data storage for each class, eliminating the need to generate primitive wrapper objects. This saves memory and speeds up certain runtime operations. The price is a longer warm-up time for the application - generating and loading custom classes into the JVM takes time. Therefore, only set this property to true if you have a long-running application where the initial cost of class generation is offset by memory and speed optimization over time.

FetchBatchSize large result sets FetchBatchSize Property name: openjpa.FetchBatchSize Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getFetchBatchSize Resource adaptor config-property: FetchBatchSize Default: -1 Description: The number of rows to fetch at once when scrolling through a result set. The fetch size can also be set at runtime. See for details.

DataCache encryption Property name: openjpa.EncryptionProvider Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getEncryptionProvider Resource adaptor config-property: EncryptionProvider Default: false Description: A plugin list string (see ) describing the org.apache.openjpa.lib.EncryptionProviders to use for connection password encryption. See for details.

fetch groups FetchGroups Property name: openjpa.FetchGroups Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getFetchGroups Resource adaptor config-property: FetchGroups Default: - Description: A comma-separated list of fetch group names that are to be loaded when retrieving objects from the datastore. Fetch groups can also be set at runtime. See for details.

FlushBeforeQueries Query FlushBeforeQueries flush FlushBeforeQueries Property name: openjpa.FlushBeforeQueries Property name: openjpa.FlushBeforeQueries Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getFlushBeforeQueries Resource adaptor config-property: FlushBeforeQueries Default: true Description: Whether or not to flush any changes made in the current transaction to the datastore before executing a query. See for details.

IgnoreChanges Property name: openjpa.IgnoreChanges Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getIgnoreChanges Resource adaptor config-property: IgnoreChanges Default: false Description: Whether to consider modifications to persistent objects made in the current transaction when evaluating queries. Setting this to true allows OpenJPA to ignore changes and execute the query directly against the datastore. A value of false forces OpenJPA to consider whether the changes in the current transaction affect the query, and if so to either evaluate the query in-memory or flush before running it against the datastore.

Id Property name: openjpa.Id Resource adaptor config-property: Id Default: none Description: An environment-specific identifier for this configuration. This might correspond to a JPA persistence-unit name, or to some other more-unique value available in the current environment.

InitializeEagerly

InverseManager Initialization Configuration Property name: openjpa.InitializeEagerly Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.isInitializeEagerly Resource adaptor config-property: InitializeEagerly Default: false Possible values: false, true Description: Controls whether initialization is eager or lazy. Eager initialization imply all persistent classes, their mapping information, database connectivity and all other resources specified in the configuration of a persistence unit will be initialized when a persistent unit is constructed. The default behavior is lazy i.e. persistent classes, database and other resources are initialized only when the application refers to a resource for the first time.

InverseManager bidirectional relation InverseManager Property name: openjpa.InverseManager Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getInverseManager Resource adaptor config-property: InverseManager Default: false Possible values: false, true Description: A plugin string (see ) describing a org.apache.openjpa.kernel.InverseManager to use for managing bidirectional relations upon a flush. See for usage documentation.

LockManager locking LockManager Property name: openjpa.LockManager Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getLockManager Resource adaptor config-property: LockManager Default: mixed Possible values: none, sjvm, version, pessimistic, mixed Description: A plugin string (see ) describing a org.apache.openjpa.kernel.LockManager to use for acquiring locks on persistent instances during transactions. See for more information.

LockTimeout locking LockTimeout Property name: openjpa.LockTimeout Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getLockTimeout Resource adaptor config-property: LockTimeout Default: -1 Description: The number of milliseconds to wait for an object lock before throwing an exception, or -1 for no limit. See for details.

Log logging Log Property name: openjpa.Log Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getLog Resource adaptor config-property: Log Default: true Possible values: openjpa, commons, log4j, none Description: A plugin string (see ) describing a org.apache.openjpa.lib.log.LogFactory to use for logging. For details on logging, see .

ManagedRuntime transactions managed ManagedRuntime Property name: openjpa.ManagedRuntime Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getManagedRuntime Resource adaptor config-property: ManagedRuntime Default: auto Description: A plugin string (see ) describing the org.apache.openjpa.ee.ManagedRuntime implementation to use for obtaining a reference to the TransactionManager in an enterprise environment.

Mapping Property name: openjpa.Mapping Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getMapping Resource adaptor config-property: Mapping Default: - Description: The symbolic name of the object-to-datastore mapping to use.

MaxFetchDepth eager fetching MaxFetchDepth Property name: openjpa.MaxFetchDepth Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getMaxFetchDepth Resource adaptor config-property: MaxFetchDepth Default: -1 Description: The maximum depth of relations to traverse when eager fetching. Use -1 for no limit. Defaults to no limit. See for details on eager fetching.

MetaDataFactory metadata MetaDataFactory Property name: openjpa.MetaDataFactory Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getMetaDataFactory Resource adaptor config-property: MetaDataFactory Default: jpa Description: A plugin string (see ) describing the openjpa.meta.MetaDataFactory to use to store and retrieve metadata for your persistent classes. See for details.

Multithreaded threading Multithreaded Property name: openjpa.Multithreaded Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getMultithreaded Resource adaptor config-property: Multithreaded Default: false Description: Whether persistent instances and OpenJPA components other than the EntityManagerFactory will be accessed by multiple threads at once.

Optimistic transactions optimistic Property name: openjpa.Optimistic Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getOptimistic Resource adaptor config-property: Optimistic Default: true Description: Selects between optimistic and pessimistic (datastore) transactional modes.

OrphanedKeyAction foreign keys OrphanedKeyAction Property name: openjpa.OrphanedKeyAction Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getOrphanedKeyAction Resource adaptor config-property: OrphanedKeyAction Default: log Possible values: log, exception, none Description: A plugin string (see ) describing a org.apache.openjpa.event.OrphanedKeyAction to invoke when OpenJPA discovers an orphaned datastore key. See for details.

NontransactionalRead Property name: openjpa.NontransactionalRead Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalRead Resource adaptor config-property: NontransactionalRead Default: true Description: Whether the OpenJPA runtime will allow you to read data outside of a transaction.

NontransactionalWrite Property name: openjpa.NontransactionalWrite Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalWrite Resource adaptor config-property: NontransactionalWrite Default: true Description: Whether you can modify persistent objects and perform persistence operations outside of a transaction. Changes will take effect on the next transaction.

ProxyManager proxies ProxyManager Property name: openjpa.ProxyManager Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getProxyManager Resource adaptor config-property: ProxyManager Default: default Description: A plugin string (see ) describing a org.apache.openjpa.util.ProxyManager to use for proxying mutable second class objects. See for details.

QueryCache caching QueryCache Property name: openjpa.QueryCache Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getQueryCache Resource adaptor config-property: QueryCache Default: true, when the data cache (see ) is also enabled, false otherwise. Description: A plugin string (see ) describing the org.apache.openjpa.datacache.QueryCache implementation to use for caching of queries loaded from the data store. See for details.

QueryCompilationCache caching QueryCompilationCache Property name: openjpa.QueryCompilationCache Resource adaptor config-property: QueryCompilationCache Default: true. Description: A plugin string (see ) describing the java.util.Map to use for caching of data used during query compilation. See for details.

ReadLockLevel locking ReadLockLevel Property name: openjpa.ReadLockLevel Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getReadLockLevel Resource adaptor config-property: ReadLockLevel Default: read Possible values: none, read, write, optimistic, optimistic-force-increment, pessimistic-read, pessimistic-write, pessimistic-force-increment, numeric values for lock-manager specific lock levels Description: The default level at which to lock objects retrieved during a non-optimistic transaction. Note that for the default JDBC lock manager, read and write lock levels are equivalent. Lock levels pessimistic-read, pessimistic-write and pessimistic-force-increment are in effect only when the mixed lock manager is used.

RemoteCommitProvider caching RemoteCommitProvider remote RemoteCommitProvider Property name: openjpa.RemoteCommitProvider Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getRemoteCommitProvider Resource adaptor config-property: RemoteCommitProvider Default: - Description: A plugin string (see ) describing the org.apache.openjpa.event.RemoteCommitProvider implementation to use for distributed event notification. See for more information.

RestoreState Property name: openjpa.RestoreState Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getRestoreState Resource adaptor config-property: RestoreState Default: none Possible values: none, immutable, all Description: Whether to restore managed fields to their pre-transaction values when a rollback occurs.

RetainState Property name: openjpa.RetainState Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getRetainState Resource adaptor config-property: RetainState Default: true Description: Whether persistent fields retain their values on transaction commit.

RetryClassRegistration metadata RetryClassRegistration Property name: openjpa.RetryClassRegistration Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getRetryClassRegistration Resource adaptor config-property: RetryClassRegistration Default: false Description: Controls whether to log a warning and defer registration instead of throwing an exception when a persistent class cannot be fully processed. This property should only be used in complex classloader situations where security is preventing OpenJPA from reading registered classes. Setting this to true unnecessarily may obscure more serious problems.

Property name: openjpa.RuntimeUnenhancedClasses Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getRuntimeUnenhancedClasses Resource adaptor config property: RuntimeUnenhancedClasses Default: unsupported Possible values: supported, unsupported, warn Description: The RuntimeUnenhancedClasses property controls how OpenJPA handles classes that have not been enhanced by the PCEnhancer tool or automatically by a javaagent. If RuntimeUnenhancedClasses is set to supported OpenJPA will automatically create subclasses for unenhanced entity classes. If set to unsupported OpenJPA will not create subclasses for unenhanced entity classes and will throw an exception when they are detected. If set to warn OpenJPA will not create subclasses for unenhanced entity classes but will log a warning message. This function is often useful for rapid prototyping but is not generally recommended for use in production. Please consult the reference guide before changing the default value. See the reference guide section on unenhanced types for more information

Property name: openjpa.DynamicEnhancementAgent Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getDynamicEnhancementAgent Resource adaptor config property: DynamicEnhancementAgent Default: true Description: The DynamicEnhancementAgent property controls whether or not OpenJPA will attempt to dynamically load the PCEnhancer javaagent. See the reference guide for more information

Property name: openjpa.SavepointManager Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getSavepointManager Resource adaptor config-property: SavepointManager Default: in-mem Possible values: in-mem, jdbc, oracle Description: A plugin string (see ) describing a org.apache.openjpa.kernel.SavepointManager to use for managing transaction savepoints. See for details.

Sequence Property name: openjpa.Sequence Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getSequence Resource adaptor config-property: Sequence Default: table Description: A plugin string (see ) describing the org.apache.openjpa.kernel.Seq implementation to use for the system sequence. See for more information.

Specification Property name: openjpa.Specification Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getSpecificationInstance Resource adaptor config-property: Specification Default: table Description: A formatted string describing the Specification to use for the default configuration options. The format of the Specifcation string is name [major.[minor]] where name denotes the name of the Specification such as JPA or JDO, major denotes the major integral version number of the Specification and minor denotes a minor version which can be an arbitrary string. See for more information.

TransactionMode transactions TransactionMode Property name: openjpa.TransactionMode Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getTransactionMode Resource adaptor config-property: TransactionMode Default: local Possible values: local, managed Description: The default transaction mode to use. You can override this setting per-session.

WriteLockLevel locking WriteLockLevel Property name: openjpa.WriteLockLevel Configuration API: org.apache.openjpa.conf.OpenJPAConfiguration.getWriteLockLevel Resource adaptor config-property: WriteLockLevel Default: write Possible values: none, read, write, optimistic, optimistic-force-increment, pessimistic-read, pessimistic-write, pessimistic-force-increment, numeric values for lock-manager specific lock levels. Description: The default level at which to lock objects changed during a non-optimistic transaction. Note that for the default JDBC lock manager, read and write lock levels are equivalent. Lock levels pessimistic-read, pessimistic-write and pessimistic-force-increment are in effect only when the mixed lock manager is used.

configuration of JDBC properties The following properties apply exclusively to the OpenJPA JDBC back-end.

ConnectionDecorators connections ConnectionDecorators Property name: openjpa.jdbc.ConnectionDecorators Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getConnectionDecorators Resource adaptor config-property: ConnectionDecorators Default: - Description: A comma-separated list of plugin strings (see ) describing org.apache.openjpa.lib.jdbc.ConnectionDecorator instances to install on the connection factory. These decorators can wrap connections passed from the underlying DataSource to add functionality. OpenJPA will pass all connections through the list of decorators before using them. Note that by default OpenJPA employs all of the built-in decorators in the org.apache.openjpa.lib.jdbc package already; you do not need to list them here.

DBDictionary JDBC DBDictionary Property name: openjpa.jdbc.DBDictionary Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDBDictionary Resource adaptor config-property: DBDictionary Default: Based on the openjpa.ConnectionURL openjpa.ConnectionDriverName Description: A plugin string (see ) describing the org.apache.openjpa.jdbc.sql.DBDictionary to use for database interaction. OpenJPA typically auto-configures the dictionary based on the JDBC URL, but you may have to set this property explicitly if you are using an unrecognized driver, or to plug in your own dictionary for a database OpenJPA does not support out-of-the-box. See for details.

DriverDataSource JDBC DriverDataSource Property name: openjpa.jdbc.DriverDataSource Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDriverDataSource Resource adaptor config-property: DriverDataSource Default: pooling Description: The alias or full class name of the org.apache.openjpa.jdbc.schema.DriverDataSource implementation to use to wrap JDBC Driver classes with javax.sql.DataSource instances.

EagerFetchMode eager fetching EagerFetchMode Property name: openjpa.jdbc.EagerFetchMode Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getEagerFetchMode Resource adaptor config-property: EagerFetchMode Default: parallel Possible values: parallel, join, none Description: Optimizes how OpenJPA loads persistent relations. This setting can also be varied at runtime. See for details.

FetchDirection large result sets FetchDirection Property name: openjpa.jdbc.FetchDirection Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getFetchDirection Resource adaptor config-property: FetchDirection Default: forward Possible values: forward, reverse, unknown Description: The expected order in which query result lists will be accessed. This property can also be varied at runtime. See for details.

JDBCListeners JDBC JDBCListeners Property name: openjpa.jdbc.JDBCListeners Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getJDBCListeners Resource adaptor config-property: JDBCListeners Default: - Description: A comma-separated list of plugin strings (see ) describing org.apache.openjpa.lib.jdbc.JDBCListener event listeners to install. These listeners will be notified on various JDBC-related events.

LRSSize large result sets LRSSize Property name: openjpa.jdbc.LRSSize Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getLRSSize Resource adaptor config-property: LRSSize Default: query Possible values: query, last, unknown Description: The strategy to use to calculate the size of a result list. This property can also be varied at runtime. See for details.

MappingDefaults mapping metadata MappingDefaults Property name: openjpa.jdbc.MappingDefaults Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingDefaults Resource adaptor config-property: MappingDefaults Default: jpa Description: A plugin string (see ) describing the org.apache.openjpa.jdbc.meta.MappingDefaults to use to define default column names, table names, and constraints for your persistent classes. See for details.

MappingFactory mapping metadata MappingFactory Property name: openjpa.jdbc.MappingFactory Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingFactory Resource adaptor config-property: MappingFactory Default: - Description: A plugin string (see ) describing the org.apache.openjpa.meta.MetaDataFactory to use to store and retrieve object-relational mapping information for your persistent classes. See for details.

Prepared SQL Cache caching QuerySQLCache Property name: openjpa.jdbc.QuerySQLCache Resource adaptor config-property: QuerySQLCache Default: true. Description: A plugin string (see ) describing the options to cache and reuse SQL statements generated for JPQL queries. See for details.

ResultSetType large result sets ResultSetType Property name: openjpa.jdbc.ResultSetType Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getResultSetType Resource adaptor config-property: ResultSetType Default: forward-only Possible values: forward-only , scroll-sensitive, scroll-insensitive Description: The JDBC result set type to use when fetching result lists. This property can also be varied at runtime. See for details.

schema Schema Property name: openjpa.jdbc.Schema Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchema Resource adaptor config-property: Schema Default: - Description: The default schema name to prepend to unqualified table names. Also, the schema in which OpenJPA will create new tables. See for details.

SchemaFactory schema SchemaFactory Property name: openjpa.jdbc.SchemaFactory Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemaFactory Resource adaptor config-property: SchemaFactory Default: dynamic Possible values: dynamic, native, file, table, others Description: A plugin string (see ) describing the org.apache.openjpa.jdbc.schema.SchemaFactory to use to store and retrieve information about the database schema. See for details.

schema Schemas Property name: openjpa.jdbc.Schemas Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemas Resource adaptor config-property: Schemas Default: - Description: A comma-separated list of the schemas and/or tables used for your persistent data. See for details.

SQLFactory SQL SQLFactory Property name: openjpa.jdbc.SQLFactory Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSQLFactory Resource adaptor config-property: SQLFactory Default: default Description: A plugin string (see ) describing the org.apache.openjpa.jdbc.sql.SQLFactory to use to abstract common SQL constructs.

SubclassFetchMode eager fetching SubclassFetchMode inheritance SubclassFetchMode Property name: openjpa.jdbc.SubclassFetchMode Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSubclassFetchMode Resource adaptor config-property: SubclassFetchMode Default: parallel Possible values: parallel, join, none Description: How to select subclass data when it is in other tables. This setting can also be varied at runtime. See .

SynchronizeMappings mapping metadata SynchronizeMappings Property name: openjpa.jdbc.SynchronizeMappings Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSynchronizeMappings Resource adaptor config-property: SynchronizeMappings Default: - Description: Controls whether OpenJPA will attempt to run the mapping tool on all persistent classes to synchronize their mappings and schema at runtime. Useful for rapid test/debug cycles. See for more information.

TransactionIsolation transactions TransactionIsolation JDBC TransactionIsolation Property name: openjpa.jdbc.TransactionIsolation Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getTransactionIsolation Resource adaptor config-property: TransactionIsolation Default: default Possible values: default, none, read-committed, read-uncommitted, repeatable-read, serializable Description: The JDBC transaction isolation level to use. See for details.

UpdateManager JDBC UpdateManager Property name: openjpa.jdbc.UpdateManager Configuration API: org.apache.openjpa.jdbc.conf.JDBCConfiguration.getUpdateManager Resource adaptor config-property: UpdateManager Default: batching-constraint Possible values: default, operation-order, constraint, batching-constraint, batching-operation-order Description: The full class name of the org.apache.openjpa.jdbc.kernel.UpdateManager to use to flush persistent object changes to the datastore. The provided default implementation is org.apache.openjpa.jdbc.kernel.BatchingConstraintUpdateManager .

The default behavior of certain OpenJPA API methods can evolve to align with the behaviors defined in JPA specification. To maintain backward compatibility, OpenJPA allows configuration options such that while the default behavior changes to align with current JPA Specification, the previous behaviors can always be emulated. For example, JPA 2.0 specification introduces a new API void EntityManager.detach(Object entity) that detaches the given entity from the current persistence context. OpenJPA has provided similar feature via <T> T OpenJPAEntityManager.detach(T entity) prior to JPA 2.0. OpenJPA detach(), however, has different default behavior than what JPA 2.0 specification mandates. Firstly, OpenJPA creates a copy of the given entity as a detached instance and returns it, whereas JPA 2.0 behavior requires the same given entity instance be detached. Secondly, the given instance is removed from the persistence context for JPA 2.0, whereas OpenJPA detach() method, prior to JPA 2.0, does not remove the instance from the persistence context as a copy is returned. Thirdly, OpenJPA will flush before detaching a dirty instance so that the detached instance can later be merged, whereas JPA 2.0 detach() semantics does not require a dirty instance be flushed before detach. A user application running with OpenJPA that is compliant to a specific version of JPA of specification, the older behavior can be emulated by configuring OpenJPA Compatibility options. For example, openjpa.Compatibility=FlushBeforeDetach=false,CopyOnDetach=true will emulate the older behavior of detach even when running with OpenJPA that are compliant to JPA 2.0 Specification. The configuration can also be set to a different version of the specification. For example, openjpa.Specification="JPA 1.0" configuration setting will emulate default OpenJPA behavior as it were for JPA Specification version 1.0. Setting via openjpa.Specification is a shorthand for more fine-grained control available via openjpa.Compatibility.