# Package javax.jdo

This package contains the JDO specification interfaces and classes.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AttributeConverter<A,D> | Converts persistent attribute values (fields or properties) to different values stored in the underlying datastore and vice versa.
  Constants | Constant values used in JDO.
  Extent<E> | Instances of the `Extent` class represent the entire collection of instances in the data store of the candidate class or interface possibly including its subclasses or subinterfaces.
  FetchGroup | FetchGroup represents a named fetch group for a specific class or interface.
  FetchPlan | Fetch groups are activated using methods on this interface.
  InstanceCallbacks | A `PersistenceCapable` class that provides callback methods for life cycle events implements this interface.
  JDOEnhancer | Interface for a JDO Enhancer.
  JDOQLTypedQuery<T> | Interface for a type-safe refactorable JDOQL query, using a fluent API, based around expressions.
  JDOQLTypedSubquery<T> | Interface for a type-safe subquery, using a fluent API.
  PersistenceManager | `PersistenceManager` is the primary interface for JDO-aware application components.
  PersistenceManagerFactory | The `PersistenceManagerFactory` is the interface to use to obtain `PersistenceManager` instances.
  Query<T> | The `Query` interface allows applications to obtain persistent instances, values, and aggregate data from the data store.
  Transaction | The JDO `Transaction` interface provides for initiation and completion of transactions under user control.

- Class Summary
  Class | Description
  --- | ---
  AttributeConverter.UseDefault | Dummy converter to represent "use the implementation default for this type" when using annotations.
  Enhancer | Main class to invoke a JDO Enhancer.
  JDOHelper | This class can be used by a JDO-aware application to call the JDO behavior of `PersistenceCapable` instances without declaring them to be `PersistenceCapable`.
  LegacyJava | This class provides wrapper implementations for the Java SecurityManager and AccessController classes that were deprecated in Java 17/18.
  LegacyJava.SecurityManager | The SecurityManager is only instantiated if it is not deprecated/removed in the Java API.

- Enum Summary
  Enum | Description
  --- | ---
  ObjectState | This class defines the object states for JDO instances.

- Exception Summary
  Exception | Description
  --- | ---
  JDOCanRetryException | This is the base class for exceptions that can be retried.
  JDODataStoreException | This class represents data store exceptions that can be retried.
  JDODetachedFieldAccessException | This class represents exceptions caused by access of an unloaded field while the instance is detached.
  JDOEnhanceException | Exception thrown when an error occurs during enhancement.
  JDOException | This is the root of all JDO Exceptions.
  JDOFatalDataStoreException | This class represents data store exceptions that cannot be retried.
  JDOFatalException | This class represents exceptions that are fatal; that is, the condition that caused it cannot be bypassed even if the operation is retried.
  JDOFatalInternalException | This class represents errors in the implementation for which no user error handling is possible.
  JDOFatalUserException | This class represents user errors that cannot be retried.
  JDONullIdentityException | An instance of this class is thrown when attempting to create an object id when the object id constructor parameter is null.
  JDOObjectNotFoundException | This class represents exceptions caused by the user accessing an object that does not exist in the datastore.
  JDOOptimisticVerificationException | This class represents optimistic verification failures.
  JDOQueryInterruptedException | This class represents exceptions caused when a query is cancelled by a user calling Query.cancel().
  JDOReadOnlyException | This class represents exceptions caused by an attempt to update a datastore when the PMF was created as "read-only".
  JDOUnsupportedOptionException | This class represents exceptions caused by the use of optional features not supported by the JDO implementation.
  JDOUserCallbackException | This class represents exceptions caused by exceptions thrown during execution of callbacks or listeners.
  JDOUserException | This class represents user errors that can possibly be retried.

## Package javax.jdo Description

This package contains the JDO specification interfaces and classes.

There are two major objectives of the JDO architecture: first, to provide application programmers a transparent, Java-centric view of persistent information, including enterprise data and locally stored data; and second, to enable pluggable implementations of data stores into application servers. Data stored in data stores is presented as instances of persistence-capable classes.

JDO defines interfaces and classes to be used by application programmers when using classes whose instances are to be stored in persistent storage (persistence-capable classes), and specifies the contracts between suppliers of persistence-capable classes and the runtime environment (which is part of the JDO implementation).

The JDO architecture defines a standard set of contracts between an application programmer and an JDO vendor. These contracts focus on the view of the Java instances of persistence capable classes.

The JDO PersistenceManagerFactory is the boostrap class for a JDO application. The application gets an instance of the PersistenceManagerFactory by construction or via JDNI lookup.

The application acquires an instance of the JDO PersistenceManager by calling the getPersistenceManager method on an instance of JDO PersistenceManagerFactory.

The JDO PersistenceManager is the primary interface for JDO-aware application components:

- it gives access to the current Transaction interface;
- it is the factory for the Query interface;
- it contains methods for managing the life cycle of persistent instances.

A JDO PersistenceManager instance supports any number of JDO instances at a time. It is responsible for managing the identity of its associated JDO instances. A JDO instance is associated with either zero or one JDO PersistenceManager. It will be zero if and only if the JDO instance is transient nontransactional. As soon as the instance is made persistent or transactional, it will be associated with exactly one JDO PersistenceManager.

A JDO PersistenceManager instance supports one transaction at a time, and uses one connection to the underlying data source at a time. The JDO PersistenceManager instance might use multiple transactions serially, and might use multiple connections serially.

Normally, cache management is automatic and transparent. When instances are queried, navigated to, or modified, instantiation of instances and their fields and garbage collection of unreferenced instances occurs without any explicit control. When the transaction in which persistent instances are created, deleted, or modified commits, eviction is automatically done by the transaction completion mechanisms.

Operations on persistent JDO instances at the user's choice might be performed in the context of a transaction. That is, the view of data in the data store is transactionally consistent, according to the standard definition of ACID transactions.

The Transaction interface is used to mark the beginning and end of a application-defined unit of work. The PersistenceManager allows the application to get the instance that manages these transactional boundaries via the currentTransaction method.

The persistent manager instance is a factory for query instances, and queries are executed in the context of the persistent manager instance. The actual query execution might be performed by the JDO PersistenceManager or might be delegated by the JDO PersistenceManager to its data store. The actual query executed thus might be implemented in a very different language from Java, and might be optimized to take advantage of particular query language implementations.

Extents are collections of data store objects managed by the data store, not by explicit user operations on collections. Extent capability is a boolean property of classes that are persistence capable. If an instance of a class that has a managed extent is made persistent via reachability, the instance is put into the extent implicitly.

Copyright © 2005–2022 The Apache Software Foundation. All rights reserved.