Java Persistent Objects - Persistence Manager Factory

Persistence Manager Factory

Any JDO-enabled application will require at least one PersistenceManagerFactory. Typically applications create one per datastore being utilised. A PersistenceManagerFactory provides access to PersistenceManagers which allow objects to be persisted, and retrieved. The PersistenceManagerFactory can be configured to provide particular behaviour.

The simplest way of creating a PersistenceManagerFactory is as follows

Properties properties = new Properties();
properties.setProperty("javax.jdo.PersistenceManagerFactoryClass","org.jpox.PersistenceManagerFactoryImpl");
properties.setProperty("javax.jdo.option.ConnectionDriverName","com.mysql.jdbc.Driver");
properties.setProperty("javax.jdo.option.ConnectionURL","jdbc:mysql://localhost/myDB");
properties.setProperty("javax.jdo.option.ConnectionUserName","login");
properties.setProperty("javax.jdo.option.ConnectionPassword","password");
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(properties);

A slight variation on this, for use with JPOX 1.1.0-beta-3 onwards, is to use a file to specify these properties like this

javax.jdo.PersistenceManagerFactoryClass=org.jpox.PersistenceManagerFactoryImpl
javax.jdo.option.ConnectionDriverName=com.mysql.jdbc.Driver
javax.jdo.option.ConnectionURL=jdbc:mysql://localhost/myDB
javax.jdo.option.ConnectionUserName=login
javax.jdo.option.ConnectionPassword=password

and then to create the PersistenceManagerFactory using this file

File propsFile = new File(filename);
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(propsFile);

A final alternative would be to call JDOHelper.getPersistenceManagerFactory(jndiLocation, context);, hence accessing the properties via JNDI. This is available from JPOX 1.1.0-beta-3 onwards.

Whichever way we wish to obtain the PersistenceManagerFactory we have defined a series of properties to give the behaviour of the PersistenceManagerFactory. The first property specifies to use the JPOX implementation, and the following 4 properties define the datastore that it should connect to. There are many properties available. Some of these are standard JDO properties, and some are JPOX extensions.

Standard JDO Properties

Parameter	Values	Description
javax.jdo.PersistenceManagerFactoryClass	org.jpox.PersistenceManagerFactoryImpl	The name of the PersistenceManager implementation
javax.jdo.option.ConnectionFactory		Instance of a connection factory. For RBDMS, it must be an instance of javax.sql.DataSource. See Data Sources.
javax.jdo.option.ConnectionFactory2		Instance of a connection factory. For RBDMS, it must be an instance of javax.sql.DataSource. See Data Sources.
javax.jdo.option.ConnectionFactoryName		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.
javax.jdo.option.ConnectionFactory2Name		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.
javax.jdo.option.ConnectionDriverName		The name of the (JDBC) driver to use for the DB
javax.jdo.option.ConnectionURL		URL specifying the datastore to use for persistence
javax.jdo.option.ConnectionUserName		Username to use for connecting to the DB
javax.jdo.option.ConnectionPassword		Password to use for connecting to the DB
javax.jdo.option.IgnoreCache	true \| false	Whether to ignore the cache for queries
javax.jdo.option.Multithreaded	true \| false	Whether to run the PersistenceManager multithreaded
javax.jdo.option.NontransactionalRead	true \| false	Whether to allow nontransactional reads
javax.jdo.option.NontransactionalWrite	true \| false	Whether to allow nontransactional writes. Not supported by JPOX
javax.jdo.option.Optimistic	true \| false	Whether to use Optimistic transactions
javax.jdo.option.RetainValues	true \| false	Whether to suppress automatic eviction of persistent instances on transaction completion
javax.jdo.option.RestoreValues	true \| false	Whether persistent object have transactional field values restored when transaction rollback occurs.
javax.jdo.option.Mapping		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.
javax.jdo.mapping.Catalog		Name of the catalog to use by default for all classes persisted using this PMF. This can be overridden in the MetaData where required, and is optional. JPOX will prefix all table names with this catalog name if the RDBMS supports specification of catalog names in DDL.
javax.jdo.mapping.Schema		Name of the schema to use by default for all classes persisted using this PMF. This can be overridden in the MetaData where required, and is optional. JPOX will prefix all table names with this schema name if the RDBMS supports specification of schema names in DDL.
javax.jdo.option.DetachAllOnCommit	true \| false	Allows the user to select that when a transaction is committed all objects enlisted in that transaction will be automatically detached. This is supported from version 1.1.0-beta-5 of JPOX

Extension JPOX Properties

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

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)
Identity Generation - properties controlling the generation of object identities
MetaData - metadata properties
Auto-Start - Auto-Start Mechanism properties
General - general properties
Type Mapping - properties controlling the mapping of java types to the datastore types
Query - properties controlling the behaviour of queries
Failover - properties controlling the failover

Schema Control

org.jpox.datastoreAdapterClassName
Description	This property allows you to supply the class name of the adapter to use for your datastore. The default is not to specify this property and JPOX will autodetect the datastore type and use its own internal datastore adapter classes. This allows you to override the default behaviour where there maybe is some issue with the default adapter class.
Range of Values	(valid class name on the CLASSPATH)
Since	1.1.0-beta-3

org.jpox.connectionPoolingType
Description	This property allows you to utilise a 3rd party software package for enabling connection pooling using a JPOX plugin. Currently JPOX 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 Connection Pooling guide for details.
Range of Values	None \| DBCP \| C3P0 \| Proxool
Since	1.1.0-beta-3. "Proxool" is only available from 1.1.2 of JPOX

org.jpox.connectionPoolingConfigurationFile
Description	Allows specification of configuration properties for controlling the connection pooling when you have specified the org.jpox.connectionPoolingType above.
Range of Values	Filename present in the CLASSPATH
Since	1.1.0-rc-1

org.jpox.autoCreateSchema
Description	Whether to automatically generate any tables and constraints that don't exist. Please refer to the Schema Guide for more details.
Range of Values	true \| false
Since	1.0.0-beta-4

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

org.jpox.autoCreateColumns
Description	Whether to automatically generate any columns that don't exist. Please refer to the Schema Guide for more details.
Range of Values	true \| false
Since	1.1.0-beta-1

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

org.jpox.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
Since	1.1.0

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

org.jpox.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 Schema Guide for more details.
Range of Values	true \| false
Since	1.1.0-beta-3

org.jpox.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

org.jpox.rdbms.statementBatchLimit
Description	Maximum number of statements that can be batched. Currently only applies to container elements/keys/values, and currently only support values of 0 (disabled) and -1 (no limit)
Range of Values	-1 \| 0
Since	1.1.2

org.jpox.rdbms.CheckExistTablesOrViews
Description	Whether to check if the table/view exists. If false, it disables the automatic generation of tables that don't exist.
Range of Values	true \| false

org.jpox.initializePrimaryKeyColumnInfo

Description

Load schema information of the primary key columns from database. This setting is useful when working with an existing schema where the primary key columns are auto-incremented by the database and JDO identity strategy is set to native in the metadata. Only runs if org.jpox.validateTables is disabled and org.jpox.initializePrimaryKeyColumnInfo is enabled. If org.jpox.validateTables and org.jpox.validateColumns settings are enabled, the schema information is loaded for all columns in the table.

Range of Values

true | false

org.jpox.foreignKeyCreateMode
Description	How to determine the foreign keys to be created. AUTO will automatically add foreign-keys to handle all relationships, and will utilise the specified MetaData foreign-key information. STRICT will only use the information in the MetaData file(s).
Range of Values	AUTO \| STRICT

org.jpox.readOnlyDatastore
Description	Whether the datastore is read-only or not (fixed in structure and contents). Prior to version 1.1.2 this was called "org.jpox.readOnlySchema"
Range of Values	true \| false
Since	1.1.0-alpha-3

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

org.jpox.fixedDatastore
Description	Whether the datastore is fixed in structure or not. Prior to version 1.1.2 this was called "org.jpox.fixedSchema"
Range of Values	true \| false
Since	1.1.0-alpha-3

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

org.jpox.identifier.case
Description	Which case to use in generated table and column names. See also the Identifier Guide.
Range of Values	UpperCase \| LowerCase \| PreserveCase
Since	1.1.0-beta-3

org.jpox.identifier.wordSeparator
Description	Separator character(s) to use between words in generated identifiers. Defaults to "_" (underscore)
Since	1.1.0-beta-3

org.jpox.identifier.tablePrefix
Description	Prefix to be prepended to all generated table names (if the identifier factory supports it)
Since	1.1.0-beta-3

org.jpox.identifier.tableSuffix
Description	Suffix to be appended to all generated table names (if the identifier factory supports it)
Since	1.1.0-beta-3

org.jpox.rdbms.uniqueConstraints.mapInverse
Description	Whether to add unique constraints to the element table for a map inverse field. Possible values are true or false.
Range of values	true \| false
Since	1.1.0-alpha-2

org.jpox.rdbms.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 JPOX this will be "new-table" for all classes.
Range of Values	JDO2 \| JPOX

Transactions and Locking

org.jpox.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

org.jpox.useUpdateLock
Description	Whether JPOX should use 'SELECT ... FOR UPDATE' on all fetch operations to prevent dirty writes. Only applies to read committed and read uncommitted transaction isolation level and doesn't apply to Optimistic Transactions. Please refer to the Transactions Guide
Range of Values	true \| false

Caching

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

org.jpox.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
Since	1.1.0-beta-4

org.jpox.cache.level1.type
Description	Name of the type of Level 1 cache to use. Defines the backing map.
Range of Values	Up to JPOX 1.1.2 org.jpox.cache.WeakRefCache \| org.jpox.cache.SoftRefCache \| org.jpox.cache.HardRefCache \| your class name From JPOX 1.1.3 weak \| soft \| hard \| {your-plugin-name}

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

org.jpox.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	Up to JPOX 1.1.1 org.jpox.cache.DefaultLevel2Cache \| your class name From JPOX 1.1.2 DEFAULT \| SOFT \| Tangosol \| EHCache \| EHCacheClassBased \| OSCache \| SwarmCache \| {your-plugin-name}

org.jpox.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
Range of Values	your cache name

org.jpox.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
Range of Values	your configuration file

Identity/Value Generation

org.jpox.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

org.jpox.poid.transactionIsolation
Description	Select the default JDBC transaction isolation level for transactions used by identity generation. Must have org.jpox.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

org.jpox.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}

org.jpox.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}
Since	1.1.0-alpha-3

org.jpox.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}

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

Auto-Start

org.jpox.autoStartMechanism

Description

How to initialise JPOX at startup. This allows JPOX 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 org.jpox.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.

Range of Values

XML | SchemaTable | Classes | None

org.jpox.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

org.jpox.autoStartMechanismXmlFile
Description	Filename used for the XML file for AutoStart when using "XML" Auto-Start Mechanism
Since	1.1.0-alpha-3

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

General

org.jpox.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-ket> elements, so we provide a "JPOX" 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 \| JPOX
Since	1.1.2

org.jpox.attachSameDatastore
Description	When attaching an object JPOX 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
Since	1.1.5

org.jpox.detachOnClose
Description	This allows the user to specify whether, when a PersistenceManager is closed, that all objects in the L1 cache are automatically detached.
Range of Values	false \| true
Since	1.1.0-beta-5

org.jpox.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.
Range of Values	true \| false
Since	1.1.0-beta-5

org.jpox.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 JPOX default, meaning that only the first level of related obejcts will be fetched by default.
Range of Values	-1 \| 1 \| positive integer (non-zero)
Since	1.1.1

org.jpox.classLoaderResolverName
Description	Name of a ClassLoaderResolver to use in class loading. JPOX 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}
Since	1.1.1

org.jpox.implementationCreatorName
Description	Name of a class that creates implementations of "persistent interfaces". This is part of the JDO2 functionality and really should never be changed, but is provided for completeness.
Range of Values	org.jpox.enhancer.ImplementationCreatorImpl \| {fully-qualified class name}
Since	1.1.1

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

org.jpox.store.classAdditionMaxRetries
Description	The maximum number of retries when trying to find a class to persist or when validating a class.
Range of Values	3 \| A positive integer

org.jpox.oracle.nlsSortOrder
Description	Sort order for Oracle String fields in queries (BINARY disables native language sorting)
Range of Values	LATIN \| See Oracle documentation

org.jpox.delayDatastoreOperationsUntilCommit
Description	Whether the datastore operations are delayed until commit. Possible values are true or false.
Range of values	true \| false

Type Mapping control

org.jpox.rdbms.stringDefaultLength
Description	The default (max) length to use for all strings that dont have their column length defined in MetaData.
Range of Values	256 \| A valid length

org.jpox.rdbms.dateTimezone
Description	The timezone to use when storing date timestamps. Accepts standard notation of timezone with values like "Europe/London", "UTC", "Europe/Moscow", etc as per the Java TimeZone class. The special value of "JDK_DEFAULT_TIMEZONE" will call Timezone.getDefault() to get the timezone.
Range of Values	"UTC" \| "JDK_DEFAULT_TIMEZONE" \| A valid timezone

Query control

org.jpox.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
Since	1.1.0

org.jpox.query.fetchSize
Description	The number of rows to be fetched from the datastore when more rows are required.
Range of Values	0 \| A positive value

org.jpox.query.fetchDirection
Description	The direction in which the query results will be navigated.
Range of Values	forward \| reverse \| unknown

org.jpox.query.resultSetType
Description	Type of ResultSet to create. Not all JDBC drivers accept all options. The values correspond directly to the ResultSet options.
Range of Values	forward-only \| scroll-sensitive \| scroll-insensitive

org.jpox.query.resultSetConcurrency
Description	Whether the ResultSet is readonly or can be updated. Not all JDBC drivers support all options. The values correspond directly to the ResultSet options.
Range of Values	read-only \| updateable

org.jpox.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)

org.jpox.jdoql.useInnerJoinsOnly
Description	Whether to use inner joins only on any JDOQL queries. This overrides the type of join that JPOX will select for the situation being modelled, and doing so is at the users own risk since it may result in a Query that returns inconsistent results with the JDOQL standard.
Range of Values	false \| true
Since	1.1.0-beta-6

org.jpox.query.allowAllSQLStatements
Description	javax.jdo.query.SQL queries are allowed by JDO 2 standard only to run SELECT queries. This extension permits to bypass this limitation.
Range of Values	false \| true

Failover

org.jpox.store.connectionProvider.Name
Description	name of the registered connection provider.
Since	1.2.0

org.jpox.store.connectionProvider.FailOnError
Description	Flag if an error causes the operation to thrown an exception, or false to skip to next DataSource. If an error occurs on the last DataSource on the list an Exception will be thrown no matter if failOnError is true or false. This is a hint only.
Range of Values	false \| true
Since	1.2.0