2.3 Optional Features

JDO defines some features that are optional; JDO-compliant implementations are not required to implement them. Each optional feature is identified by a unique name, which includes a javax.jdo.option prefix. You can call the supportedOptions( ) method, defined in PersistenceManagerFactory, to determine which options an implementation supports; it returns a Collection of Strings that contain an option string. Chapter 7 presents an example using this method. Here we enumerate all the optional features and their names.

The optional features can be grouped into the following categories:

• Identity options

• Optional collections

• Transaction-related optional features

2.3.1 Identity Options

Each instance managed in a JDO environment must have a unique identifier. The following options are associated with identity:

• javax.jdo.option.ApplicationIdentity

• javax.jdo.option.DatastoreIdentity

• javax.jdo.option.NonDurableIdentity

• javax.jdo.option.ChangeApplicationIdentity

The first three options represent different kinds of identity. The fourth option indicates whether you can change the value of the fields that represent the application identity of an instance.

Support for each form of identity is optional. However, an implementation must support either datastore or application identity, and may support both. In Chapter 1 we used datastore identity, which is supported by all of the current JDO implementations. Until we cover identity in depth in Chapter 10, all of our examples will use datastore identity.

2.3.2 Optional Collections

All JDO implementations support the Collection and Set collection interfaces and the HashSet collection class defined in the java.util package. Other collections are optional in JDO, though current implementations support most of them. The following collection options are associated with a corresponding collection interface or class in the java.util package:

• javax.jdo.option.ArrayList

• javax.jdo.option.HashMap

• javax.jdo.option.Hashtable

• javax.jdo.option.LinkedList

• javax.jdo.option.TreeMap

• javax.jdo.option.TreeSet

• javax.jdo.option.Vector

• javax.jdo.option.Map

• javax.jdo.option.List

• javax.jdo.option.Array

• javax.jdo.option.NullCollection

Chapter 4 discusses optional collections in more detail. The Array option indicates whether Java's built-in arrays are supported. The NullCollection option indicates whether you can have a null value for a reference to a collection.

2.3.3 Transaction-Related Optional Features

The following options deal with transactions and special handling of instances relative to transactions:

• javax.jdo.option.NontransactionalRead

• javax.jdo.option.NontransactionalWrite

• javax.jdo.option.RetainValues

• javax.jdo.option.TransientTransactional

• javax.jdo.option.Optimistic

Some implementations allow you to read or modify an instance in memory outside of a transaction; this capability is indicated by the NontransactionalRead and NontransactionalWrite options. Some allow the instances you access during a transaction to be retained and made available after the transaction commits; this capability is determined by the RetainValues option. Chapter 14 covers nontransactional access and retaining of instances after commit. Some implementations let you have instances that are transient yet also support transactional semantics; these are called transient transactional instances, and they are covered in Chapter 13. The Optimistic option indicates whether optimistic transactions are supported; these transactions are covered in Chapter 15.