blob: 37d2443202c7d3425cbc77dac8e2bbecb6551c26 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.6.0_18) on Fri May 21 07:02:03 BST 2010 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
javax.jdo (JDO API 3.0)
</TITLE>
<META NAME="date" CONTENT="2010-05-21">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="javax.jdo (JDO API 3.0)";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV PACKAGE&nbsp;
&nbsp;<A HREF="../../javax/jdo/annotations/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../index.html?javax/jdo/package-summary.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<H2>
Package javax.jdo
</H2>
This package contains the JDO specification interfaces and classes.
<P>
<B>See:</B>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Interface Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/Constants.html" title="interface in javax.jdo">Constants</A></B></TD>
<TD>Constant values used in JDO.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/Extent.html" title="interface in javax.jdo">Extent&lt;E&gt;</A></B></TD>
<TD>Instances of the <code>Extent</code> class represent the entire collection
of instances in the data store of the candidate class or interface
possibly including its subclasses or subinterfaces.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/FetchGroup.html" title="interface in javax.jdo">FetchGroup</A></B></TD>
<TD>FetchGroup represents a named fetch group for a specific class or
interface.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/FetchPlan.html" title="interface in javax.jdo">FetchPlan</A></B></TD>
<TD>Fetch groups are activated using methods on this interface.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/InstanceCallbacks.html" title="interface in javax.jdo">InstanceCallbacks</A></B></TD>
<TD>A <code>PersistenceCapable</code> class that provides callback methods for life
cycle events implements this interface.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOEnhancer.html" title="interface in javax.jdo">JDOEnhancer</A></B></TD>
<TD>Interface for a JDO Enhancer.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOEntityManager.html" title="interface in javax.jdo">JDOEntityManager</A></B></TD>
<TD>&nbsp;</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOEntityManagerFactory.html" title="interface in javax.jdo">JDOEntityManagerFactory</A></B></TD>
<TD>&nbsp;</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/PersistenceManager.html" title="interface in javax.jdo">PersistenceManager</A></B></TD>
<TD><code>PersistenceManager</code> is the primary interface for JDO-aware
application components.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/PersistenceManagerFactory.html" title="interface in javax.jdo">PersistenceManagerFactory</A></B></TD>
<TD>The <code>PersistenceManagerFactory</code> is the interface to use to obtain
<code>PersistenceManager</code> instances.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/Query.html" title="interface in javax.jdo">Query</A></B></TD>
<TD>The <code>Query</code> interface allows applications to obtain persistent
instances, values, and aggregate data
from the data store.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/Transaction.html" title="interface in javax.jdo">Transaction</A></B></TD>
<TD>The JDO <code>Transaction</code> interface provides for initiation and
completion of transactions under user control.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/Enhancer.html" title="class in javax.jdo">Enhancer</A></B></TD>
<TD>Main class to invoke a JDO Enhancer.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOHelper.html" title="class in javax.jdo">JDOHelper</A></B></TD>
<TD>This class can be used by a JDO-aware application to call the JDO behavior
of <code>PersistenceCapable</code> instances without declaring them to be
<code>PersistenceCapable</code>.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Enum Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/ObjectState.html" title="enum in javax.jdo">ObjectState</A></B></TD>
<TD>This class defines the object states for JDO instances.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Exception Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOCanRetryException.html" title="class in javax.jdo">JDOCanRetryException</A></B></TD>
<TD>This is the base class for exceptions that can be retried.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDODataStoreException.html" title="class in javax.jdo">JDODataStoreException</A></B></TD>
<TD>This class represents data store exceptions that can be retried.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDODetachedFieldAccessException.html" title="class in javax.jdo">JDODetachedFieldAccessException</A></B></TD>
<TD>This class represents exceptions caused by access of an unloaded field while
the instance is detached.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOEnhanceException.html" title="class in javax.jdo">JDOEnhanceException</A></B></TD>
<TD>Exception thrown when an error occurs during enhancement.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOException.html" title="class in javax.jdo">JDOException</A></B></TD>
<TD>This is the root of all JDO Exceptions.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOFatalDataStoreException.html" title="class in javax.jdo">JDOFatalDataStoreException</A></B></TD>
<TD>This class represents data store exceptions that cannot be retried.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOFatalException.html" title="class in javax.jdo">JDOFatalException</A></B></TD>
<TD>This class represents exceptions that are fatal; that is, the condition
that caused it cannot be bypassed even if the operation is retried.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOFatalInternalException.html" title="class in javax.jdo">JDOFatalInternalException</A></B></TD>
<TD>This class represents errors in the implementation for which no user
error handling is possible.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOFatalUserException.html" title="class in javax.jdo">JDOFatalUserException</A></B></TD>
<TD>This class represents user errors that cannot be retried.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDONullIdentityException.html" title="class in javax.jdo">JDONullIdentityException</A></B></TD>
<TD>An instance of this class is thrown when attempting to create an object id
when the object id constructor parameter is null.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOObjectNotFoundException.html" title="class in javax.jdo">JDOObjectNotFoundException</A></B></TD>
<TD>This class represents exceptions caused by the user accessing
an object that does not exist in the datastore.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOOptimisticVerificationException.html" title="class in javax.jdo">JDOOptimisticVerificationException</A></B></TD>
<TD>This class represents optimistic verification failures.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOQueryInterruptedException.html" title="class in javax.jdo">JDOQueryInterruptedException</A></B></TD>
<TD>This class represents exceptions caused when a query is cancelled by a user calling
Query.cancel().</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOReadOnlyException.html" title="class in javax.jdo">JDOReadOnlyException</A></B></TD>
<TD>This class represents exceptions caused by an attempt to update a datastore
when the PMF was created as "read-only".</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOUnsupportedOptionException.html" title="class in javax.jdo">JDOUnsupportedOptionException</A></B></TD>
<TD>This class represents exceptions caused by the use of optional features
not supported by the JDO implementation.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOUserCallbackException.html" title="class in javax.jdo">JDOUserCallbackException</A></B></TD>
<TD>This class represents exceptions caused by exceptions thrown
during execution of callbacks or listeners.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../javax/jdo/JDOUserException.html" title="class in javax.jdo">JDOUserException</A></B></TD>
<TD>This class represents user errors that can possibly be retried.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<A NAME="package_description"><!-- --></A><H2>
Package javax.jdo Description
</H2>
<P>
This package contains the JDO specification interfaces and classes.
<P>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.
<P>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).
<P>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.
<P>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.
<P>The application acquires an instance of the JDO PersistenceManager by
calling the getPersistenceManager method on an instance of JDO
PersistenceManagerFactory.
<P>The JDO PersistenceManager is the primary interface for JDO-aware
application components:
<ul>
<li>it gives access to the current Transaction interface;
<li>it is the factory for the Query interface;
<li>it contains methods for managing the life cycle of persistent instances.
</ul>
<P>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.
<P>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.
<P>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.
<P>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.
<P>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.
<P>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.
<P>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.
<P>
<P>
<DL>
</DL>
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV PACKAGE&nbsp;
&nbsp;<A HREF="../../javax/jdo/annotations/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../index.html?javax/jdo/package-summary.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
Copyright &copy; 2005-2010 Apache Software Foundation. All Rights Reserved.
</BODY>
</HTML>