Any JDO-enabled application will require at least one PersistenceManagerFactory which accepts properties to define its capabilities. Any JPA-enabled application will require at least one EntityManagerFactory which also accepts properties to define its capabilities. DataNucleus provides a large number of properties for use with either JDO or JPA APIs.

Use of the following properties gives you more control over the operations of DataNucleus, but bear in mind that these properties are only for use with DataNucleus and will not work with other JDO/JPA implementations.

• Datastore Definition - datastore properties
• General - general properties
• Schema Control - properties controlling the generation of the datastore schema.
• Transactions and Locking - properties controlling how transactions operate
• Caching - properties controlling the behaviour of the cache(s)
• Value Generation - properties controlling the generation of object identities and field values
• MetaData - metadata properties
• Auto-Start - Auto-Start Mechanism properties
• Query - properties controlling the behaviour of queries
• JPA - properties allowing extra functionality with JPA.

Please note that there are additional persistence properties for each supported datastore. See RDBMS and DB4O

Datastore Definition

datanucleus.ConnectionFactory
Description	Instance of a connection factory. For RDBMS, it must be an instance of javax.sql.DataSource. See Data Sources. This is for a transactional DataSource
Range of Values

datanucleus.ConnectionFactory2
Description	Instance of a connection factory. For RDBMS, it must be an instance of javax.sql.DataSource. See Data Sources. This is for a non-transactional DataSource
Range of Values

datanucleus.ConnectionFactoryName
Description	The JNDI name for a connection factory. For RBDMS, it must be a JNDI name that points to a javax.sql.DataSource object. See Data Sources. This is for a transactional DataSource
Range of Values

datanucleus.ConnectionFactory2Name
Description	The JNDI name for a connection factory. For RBDMS, it must be a JNDI name that points to a javax.sql.DataSource object. See Data Sources. This is for a non-transactional DataSource
Range of Values

datanucleus.ConnectionDriverName
Description	The name of the (JDBC) driver to use for the DB
Range of Values

datanucleus.ConnectionDriverURL
Description	URL specifying the datastore to use for persistence
Range of Values

datanucleus.ConnectionUserName
Description	Username to use for connecting to the DB
Range of Values

datanucleus.ConnectionPassword
Description	Password to use for connecting to the DB
Range of Values

General

datanucleus.IgnoreCache
Description	Whether to ignore the cache for queries
Range of Values	true | false

datanucleus.Multithreaded
Description	Whether to run the PersistenceManager multithreaded
Range of Values	true | false

datanucleus.NontransactionalRead
Description	Whether to allow nontransactional reads
Range of Values	true | false

datanucleus.NontransactionalWrite
Description	Whether to allow nontransactional writes
Range of Values	true | false

datanucleus.Optimistic
Description	Whether to use Optimistic transactions
Range of Values	true | false

datanucleus.RetainValues
Description	Whether to suppress the clearing of values from persistent instances on transaction completion
Range of Values	true | false

datanucleus.RestoreValues
Description	Whether persistent object have transactional field values restored when transaction rollback occurs.
Range of Values	true | false

datanucleus.Mapping
Description	Name for the ORM MetaData mapping files to use with this PMF. For example if this is set to "mysql" then the implementation looks for MetaData mapping files called "{classname}-mysql.orm" or "package-mysql.orm". If this is not specified then the JDO implementation assumes that all is specified in the JDO MetaData file. RDBMS datastores only
Range of Values

datanucleus.Catalog
Description	Name of the catalog to use by default for all classes persisted using this PMF/EMF. This can be overridden in the MetaData where required, and is optional. DataNucleus will prefix all table names with this catalog name if the RDBMS supports specification of catalog names in DDL. RDBMS datastores only
Range of Values

datanucleus.Schema
Description	Name of the schema to use by default for all classes persisted using this PMF/EMF. This can be overridden in the MetaData where required, and is optional. DataNucleus will prefix all table names with this schema name if the RDBMS supports specification of schema names in DDL. RDBMS datastores only
Range of Values

datanucleus.DetachAllOnCommit
Description	Allows the user to select that when a transaction is committed all objects enlisted in that transaction will be automatically detached.
Range of Values	true | false

datanucleus.CopyOnAttach
Description	Whether, when attaching a detached object, we create an attached copy or simply migrate the detached object to attached state
Range of Values	true | false

datanucleus.TransactionType
Description	Type of transaction to use. If running under J2SE the default is RESOURCE_LOCAL, and if running under J2EE the default is JTA.
Range of Values	RESOURCE_LOCAL | JTA

datanucleus.ServerTimeZoneID
Description	Id of the TimeZone under which the datastore server is running. If this is not specified or is set to null it is assumed that the datastore server is running in the same timezone as the JVM under which DataNucleus is running.
Range of Values

datanucleus.PersistenceUnitName
Description	Name of a persistence-unit to be found in a persistence.xml file (under META-INF) that defines the persistence properties to use and the classes to use within the persistence process.
Range of Values

datanucleus.persistenceXmlFilename
Description	URL name of the persistence.xml file that should be used instead of using "META-INF/persistence.xml".
Range of Values

datanucleus.storeManagerType
Description	Type of the StoreManager to use for this PMF/EMF. This has typical values of "rdbms", "db4o". If it isnt specified then it falls back to trying to find the StoreManager from the connection URL. The associated DataNucleus plugin has to be in the CLASSPATH when selecting this. When using data sources (as usually done in a JavaEE container), DataNucleus cannot find out the correct type automatically and this option must be set.
Range of Values	rdbms | db4o | alternate StoreManager key

datanucleus.managedRuntime
Description	Whether to allow management of the runtime of DataNucleus. Allows hooking in JMX. Please refer to the Management Guide
Range of Values	true | false

datanucleus.deletionPolicy
Description	Allows the user to decide the policy when deleting objects. The default is "JDO2" which firstly checks if the field is dependent and if so deletes dependents, and then for others will null any foreign keys out. The problem with this option is that it takes no account of whether the user has also defined <foreign-key> elements, so we provide a "DataNucleus" mode that does the dependent field part first and then if a FK element is defined will leave it to the FK in the datastore to perform any actions, and otherwise does the nulling.
Range of Values	JDO2 | DataNucleus

datanucleus.findObjectCheckInheritance
Description	When retrieving an object by identity DataNucleus can do a check on the inheritance level of the object. In many cases this check is not adding anything since the id implies the inheritance level. This allows the user to turn off the check.
Range of Values	true | false

datanucleus.attachSameDatastore
Description	When attaching an object DataNucleus by default makes no assumption about which datastore the object was detached from and so makes a check for existence before attaching each object. This option allows you to turn off that check when you know you are detaching and attaching using the same datastore.
Range of Values	false | true

datanucleus.detachOnClose
Description	This allows the user to specify whether, when a PersistenceManager is closed, that all objects in the L1 cache are automatically detached. Users are recommended to not use this option, and instead use the JDO2 standard datanucleus.DetachAllOnCommit . This option may be removed in a later release.
Range of Values	false | true

datanucleus.manageRelationships
Description	This allows the user control over whether DataNucleus will try to manage bidirectional relations, correcting the input objects so that all relations are consistent. This process runs when flush()/commit() is called. You can set it to false if you always set both sides of a relation when persisting/updating.
Range of Values	true | false

datanucleus.manageRelationshipsChecks
Description	This allows the user control over whether DataNucleus will make consistency checks on bidirectional relations. If "datanucleus.managedRelationships" is not selected then no checks are performed. If a consistency check fails at flush()/commit() then a JDOUserException is thrown. You can set it to false if you want to omit all consistency checks.
Range of Values	true | false

datanucleus.persistenceByReachabilityAtCommit
Description	Whether to run the "persistence-by-reachability" algorithm at commit() time. This means that objects that were reachable at a call to makePersistent() but that are no longer persistent will be removed from persistence. For performance improvements, consider turning this off.
Range of Values	true | false

datanucleus.maxFetchDepth
Description	Specifies the default maximum fetch depth to use for fetching operations. The JDO2 specification defines a default of 1, and this is the DataNucleus default, meaning that only the first level of related objects will be fetched by default.
Range of Values	-1 | 1 | positive integer (non-zero)

datanucleus.classLoaderResolverName
Description	Name of a ClassLoaderResolver to use in class loading. DataNucleus provides a default that implements the JDO2 specification for class loading. This property allows the user to override this with their own class better suited to their own loading requirements.
Range of Values	jdo | {name of class-loader-resolver plugin}

datanucleus.primaryClassLoader
Description	Sets a primary classloader for situations where a primary classloader is not accessible. This ClassLoader is used when the class is not found in the default ClassLoader search path. As example, when the database driver is loaded by a different ClassLoader not in the ClassLoader search path for JDO or JPA specifications.
Range of Values	instance of java.lang.ClassLoader

datanucleus.implementationCreatorName
Description	Symbolic name of an implementation creator for "persistent interfaces" (JDO2). DataNucleus provides two creators, one using BCEL and the other using ASM. Please note that you should have the DataNucleus Enhancer in the CLASSPATH together with either BCEL or ASM to use "persistent interfaces".
Range of Values	asm | bcel

datanucleus.plugin.pluginRegistryClassName
Description	Name of a class that acts as registry of plug-ins.
Range of Values	{fully-qualified class name}

datanucleus.plugin.pluginRegistryBundleCheck
Description	Defines what happens when plugin bundles are found and are duplicated
Range of Values	EXCEPTION | LOG | NONE

Schema Control

datanucleus.autoCreateSchema
Description	Whether to automatically generate any tables and constraints that don't exist. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.autoCreateTables
Description	Whether to automatically generate any tables that don't exist. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.autoCreateColumns
Description	Whether to automatically generate any columns that don't exist. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.autoCreateConstraints
Description	Whether to automatically generate any constraints that don't exist. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.autoCreateWarnOnError
Description	Whether to only log a warning when errors occur during the auto-creation/validation process. Please use with care since if the schema is incorrect errors will likely come up later and this will postpone those error checks til later, when it may be too late!!
Range of Values	true | false

datanucleus.validateTables
Description	Whether to validate tables against the persistence definition. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.validateColumns
Description	Whether to validate columns against the persistence definition. This refers to the column detail structure and NOT to whether the column exists or not. Please refer to the RDBMS Schema Guide for more details.
Range of Values	true | false

datanucleus.validateConstraints
Description	Whether to validate table constraints against the persistence definition. Please refer to the Schema Guide for more details.
Range of Values	true | false

datanucleus.readOnlyDatastore
Description	Whether the datastore is read-only or not (fixed in structure and contents).
Range of Values	true | false

datanucleus.readOnlyDatastoreAction
Description	What happens when a datastore is read-only and an object is attempted to be persisted.
Range of Values	EXCEPTION | IGNORE

datanucleus.fixedDatastore
Description	Whether the datastore is fixed in structure or not.
Range of Values	true | false

datanucleus.identifierFactory
Description	Name of the identifier factory to use when generating table/column names etc. See also the JDO RDBMS Identifier Guide.
Range of Values	jpox | jpox2 | jpa | {user-plugin-name}

datanucleus.identifier.case
Description	Which case to use in generated table and column names. See also the JDO RDBMS Identifier Guide.
Range of Values	UpperCase | LowerCase | PreserveCase

datanucleus.identifier.wordSeparator
Description	Separator character(s) to use between words in generated identifiers. Defaults to "_" (underscore)

datanucleus.identifier.tablePrefix
Description	Prefix to be prepended to all generated table names (if the identifier factory supports it)

datanucleus.identifier.tableSuffix
Description	Suffix to be appended to all generated table names (if the identifier factory supports it)

datanucleus.defaultInheritanceStrategy
Description	How to choose the inheritance strategy default for classes where no strategy has been specified. With JDO2 this will be "new-table" for base classes and "superclass-table" for subclasses. With DataNucleus this will be "new-table" for all classes.
Range of Values	JDO2 | DataNucleus

Transactions and Locking

datanucleus.transactionIsolation
Description	Select the default JDBC transaction isolation level for ALL PersistenceManager factories - case insensitive, and spaces/underscores are treated the same. Some databases do not support all isolation levels, refer to your database documentation. Please refer to the Transactions Guide
Range of Values	READ_UNCOMMITTED | READ_COMMITTED | REPEATABLE_READ | SERIALIZABLE

datanucleus.jtaLocator
Description	Selects the locator to use when using JTA transactions so that DataNucleus can find the JTA TransactionManager. If this isn't specified and using JTA transactions DataNucleus will search all available locators which could have a performance impact. See JTA Locator extension. If specifying "custom_jndi" please also specify "datanucleus.jtaJndiLocation"
Range of Values	jboss | jonas | jotm | oc4j | orion | resin | sap | sun | weblogic | websphere | custom_jndi | alias of a JTA transaction locator

datanucleus.jtaJndiLocation
Description	Name of a JNDI location to find the JTA transaction manager from (when using JTA transactions). This is for the case where you know where it is located. If not used DataNucleus will try certain well-known locations
Range of Values	JNDI location

datanucleus.datastoreTransactionDelayOperations
Description	For use when using datastore transactions and has the effect of delaying datastore operations until flush()/commit()
Range of values	true | false

datanucleus.datastoreTransactionFlushLimit
Description	For use when using datastore transactions and is the limit on number of dirty objects before a flush to the datastore will be performed.
Range of values	1 | positive integer

datanucleus.connectionPoolingType
Description	This property allows you to utilise a 3rd party software package for enabling connection pooling using a DataNucleus plugin. Currently DataNucleus supports use of DBCP, C3P0 or Proxool. You must have the plugin and the related 3rd party JARs in your CLASSPATH to use this option. Please refer to the RDBMS Connection Pooling guide for details.
Range of Values	None | DBCP | C3P0 | Proxool

datanucleus.connectionPoolingConfigurationFile
Description	Allows specification of configuration properties for controlling the connection pooling when you have specified the datanucleus.connectionPoolingType above.
Range of Values	Filename present in the CLASSPATH

datanucleus.connection.resourceType
Description	Resource Type for connection ???
Range of Values	JTA | RESOURCE_LOCAL

datanucleus.connection.resourceType2
Description	Resource Type for connection 2
Range of Values	JTA | RESOURCE_LOCAL

Caching

datanucleus.cache.collections
Description	SCO collections can be used in 2 modes in DataNucleus. You can allow DataNucleus to cache the collections contents, or you can tell DataNucleus to access the datastore for every access of the SCO collection. The default is to use the cached collection.
Range of Values	true | false

datanucleus.cache.collections.lazy
Description	When using cached collections/maps, the elements/keys/values can be loaded when the object is initialised, or can be loaded when accessed (lazy loading). The default is to use lazy loading when the field is not in the current fetch group, and to not use lazy loading when the field is in the current fetch group.
Range of Values	true | false

datanucleus.cache.level1.type
Description	Name of the type of Level 1 cache to use. Defines the backing map.
Range of Values	weak | soft | hard | {your-plugin-name}

datanucleus.cache.level2
Description	Whether to use a Level 2 Cache with this Persistence Manager Factory.
Range of Values	true | false

datanucleus.cache.level2.type
Description	Name of the type of Level 2 Cache to use. Can be used to interface with external caching products.
Range of Values	DEFAULT | SOFT | Tangosol | EHCache | EHCacheClassBased | OSCache | SwarmCache | {your-plugin-name}

datanucleus.cache.level2.cacheName
Description	Name of the cache. This is for use with plugins such as the Tangosol cache plugin for accessing the particular cache. Please refer to the Cache Guide for JDO or JPA
Range of Values	your cache name

datanucleus.cache.level2.configurationFile
Description	The path to the configuration file. e.g. /cache.xml The file must be in the classpath and will be looked up as a java resource. Please refer to the Cache Guide for JDO or JPA
Range of Values	your configuration file

Value Generation

datanucleus.datastoreIdentityClassName
Description	Which "datastore-identity" class plugin to use to represent datastore identities. Refer to Datastore Identity extensions for details.
Range of Values	jpox | {user-supplied plugin}

datanucleus.poid.transactionAttribute
Description	Whether to use the PM connection or open a new connection. Only used by POID generators that require a connection to the datastore.
Range of Values	New | UsePM

datanucleus.poid.transactionIsolation
Description	Select the default JDBC transaction isolation level for transactions used by identity generation. Must have datanucleus.poid.transactionAttribute set to New . Case insensitive, and spaces/underscores are treated the same. Some databases do not support all isolation levels, refer to your database documentation. Please refer to the Transactions Guide
Range of Values	READ_UNCOMMITTED | READ_COMMITTED | REPEATABLE_READ | SERIALIZABLE

MetaData

datanucleus.metadata.jdoFileExtension
Description	Suffix for JDO MetaData files. Provides the ability to override the default suffix and also to have one PMF with one suffix and another with a different suffix, hence allowing differing persistence of the same classes using different PMF's.
Range of values	jdo | {file suffix}

datanucleus.metadata.ormFileExtension
Description	Suffix for ORM MetaData files. Provides the ability to override the default suffix and also to have one PMF with one suffix and another with a different suffix, hence allowing differing persistence of the same classes using different PMF's.
Range of values	orm | {file suffix}

datanucleus.metadata.jdoqueryFileExtension
Description	Suffix for JDO Query MetaData files. Provides the ability to override the default suffix and also to have one PMF with one suffix and another with a different suffix, hence allowing differing persistence of the same classes using different PMF's.
Range of values	jdoquery | {file suffix}

datanucleus.metadata.validate
Description	Whether to validate the MetaData file(s) for XML correctness (against the DTD) when parsing
Range of values	true | false

datanucleus.metadata.annotationsManager
Description	Class name for the annotations manager
Range of values	org.datanucleus.metadata.annotations.AnnotationManagerImpl | {class-name}

Auto-Start

datanucleus.autoStartMechanism
Description	How to initialise DataNucleus at startup. This allows DataNucleus to read in from some source the classes that it was persisting for this data store the previous time. "XML" stores the information in an XML file for this purpose. "SchemaTable" stores a table in the RDBMS for this purpose. "Classes" looks at the property datanucleus.autoStartClassNames for a list of classes. The other option is "None" (start from scratch each time). Please refer to the Auto-Start Mechanism Guide for more details. The default for RDBMS is "SchemaTable". The default for all other datastores is "None".
Range of Values	XML | Classes | None | SchemaTable

datanucleus.autoStartMechanismMode
Description	The mode of operation of the auto start mode. Currently there are 3 values. "Quiet" means that at startup if any errors are encountered, they are fixed quietly. "Ignored" means that at startup if any errors are encountered they are just ignored. "Checked" means that at startup if any errors are encountered they are thrown as exceptions.
Range of values	Checked | Ignored | Quiet

datanucleus.autoStartMechanismXmlFile
Description	Filename used for the XML file for AutoStart when using "XML" Auto-Start Mechanism

datanucleus.autoStartClassNames
Description	This property specifies a list of classes (comma-separated) that are loaded at startup when using the "Classes" Auto-Start Mechanism.

Query control

datanucleus.query.timeout
Description	The timeout to apply to all queries (seconds). This also will apply to all fetch statements - for example when retrieving objects using PM.getObjectById().
Range of Values	0 | A positive value (seconds)

datanucleus.query.flushBeforeExecution
Description	This property can enforce a flush to the datastore of any outstanding changes just before executing all queries. If using optimistic transactions any updates are typically held back until flush/commit and so the query would otherwise not take them into account.
Range of Values	true | false

datanucleus.query.useFetchPlan
Description	Whether to use the FetchPlan when executing a JDOQL query. The default is to use it which means that the relevant fields of the object will be retrieved. This allows the option of just retrieving the identity columns.
Range of Values	true | false

JPA

datanucleus.jpa.oneToManyUniFkRelations
Description	Strict JPA1 behaviour doesnt permit a 1-N unidirectional FK relation - must have a join table. Setting this property to true means that DataNucleus will allow this relation, overriding this shortsighted JPA specification behaviour
Range of Values	false | true