Author: andyj
Date: Sat Oct 13 10:55:28 2007
New Revision: 584436
URL: http://svn.apache.org/viewvc?rev=584436&view=rev
Log:
JDO-537 Add doc for object retrieval
Added:
db/jdo/site/docs/object_retrieval.html
db/jdo/site/xdocs/object_retrieval.xml
Added: db/jdo/site/docs/object_retrieval.html
URL: http://svn.apache.org/viewvc/db/jdo/site/docs/object_retrieval.html?rev=584436&view=auto
==============================================================================
--- db/jdo/site/docs/object_retrieval.html (added)
+++ db/jdo/site/docs/object_retrieval.html Sat Oct 13 10:55:28 2007
@@ -0,0 +1,54 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Java
Data Objects (JDO) - JDO Object Retrieval</title><style type="text/css" media="all">
+ @import url("./style/maven-base.css");
+
+ @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css"
type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a
href="http://db.apache.org/jdo" id="projectLogo"><img alt="Java Data Objects (JDO)"
src="./images/JDOx120.gif"></img></a><div class="clear"><hr></hr></div></div><div
id="breadcrumbs"><div class="xright"></div><div class="clear"><hr></hr></div></div><div
id="leftColumn"><div id="navcolumn"><div id="menuGeneral"><h5>General</h5><ul><li
class="none"><a href="index.html">Home</a></li><li class="none"><a
href="why_jdo.html">Why JDO?</a></li><li class="none"><a href="jdo_v_jpa.html">JDO
v JPA</a></li><li class="none"><a href="jdo_v_jpa_orm.html">JDO v
JPA : ORM</a></li><li class="none"><a href="downloads.html">Downloads</a></li><li
class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0" class="externalLink"
title="External Link">License</a></li></ul></div><br></br><div
id="menuJDO_Implementation"><h5>JDO Implementation</h5><ul><li class="none"><a
href="specifications.html">Specifications</a></li><li class="none"><a
href="tck.html">TCK</a></li></ul></div><br></br><div
id="menuJDO_Usage"><h5>JDO Usage</h5><ul><li class="none"><a
href="impls.html">Implementations</a></li><li class="none"><a href="javadoc.html">API
Javadoc</a></li><li class="none"><a href="class_types.html">Types
of Classes</a></li><li class="collapsed"><a href="metadata.html">MetaData</a></li><li
class="none"><a href="enhancement.html">Bytecode Enhancement</a></li><li
class="none"><a href="jdohelper.html">JDOHelper</a></li><li class="none"><a
href="pmf.html">PersistenceManagerFactory</a></li><li class="none"><a
href="pm.html">PersistenceManager</a></li><li class="none"><a href="transactions.html">Transactions</a></li><li
class="none"><a href="state_transition.html">Object States</a></li><li
class="none"><strong><
a href="object_retrieval.html">Object Retrieval</a></strong></li><li
class="none"><a href="extents.html">Extents</a></li><li class="collapsed"><a
href="guides.html">Guides</a></li><li class="none"><a href="references.html">References</a></li><li
class="none"><a href="exceptions.html">Exceptions</a></li><li class="none"><a
href="glossary.html">Glossary</a></li></ul></div><br></br><div
id="menuCommunity"><h5>Community</h5><ul><li class="none"><a
href="get-involved.html">Get Involved</a></li><li class="none"><a
href="team-list.html">Project Team</a></li><li class="none"><a href="mail-lists.html">Mailing
Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li><li
class="none"><a href="http://wiki.apache.org/jdo" class="externalLink" title="External
Link">Wiki</a></li></ul></div><br></br><div id="menuDevelopment"><h5>Development</h5><ul><li
class="none"><a href="roadmap.html">RoadMap / TODO</a></li><li class="none"><a
href="svn.html">Source Code</a></li><li class="none"><a
href="http://cwiki.apache.org/GMOxDEV/coding-standards.html" class="externalLink" title="External
Link">Coding Standards</a></li><li class="none"><a href="issuetracking.html">Issue
Tracking</a></li><li class="none"><a href="dependencies.html">Dependencies</a></li></ul></div><br></br></div></div><div
id="bodyColumn"><div class="contentBox"><div class="section"><a name="Object_Retrieval"></a><h2>Object
Retrieval</h2><p>
+ JDO provides persistence of objects. The logical next step after persisting
objects is to retrieve them
+ for use in your application. There are several ways to do this
+ </p><div class="subsection"><a name="Retrieve_an_object_from_its_identity"></a><h3>Retrieve
an object from its identity</h3><p>
+ The simplest form of object retrieval is where we have the identity.
This is simply
+ </p>
+ <div class="source"><pre>
+Object obj = pm.getObjectById(identity);
+ </pre></div>
+ <p>
+ If the object is in the JDO cache then it is retrieved from there, otherwise
the JDO implementation
+ goes to the datastore. When the object is retrieved its fields are populated
according to its
+ <a href="../1_1/fetchgroup.html">Fetch Group</a>.
+ </p></div><div class="subsection"><a name="Retrieve_an_object_based_on_its_Extent"></a><h3>Retrieve
an object based on its Extent</h3><p>
+ A persistable class can be persisted with an <b>Extent</b>
of all instances of that type.
+ You can use this to retrieve objects of the required type, like this
+ </p>
+ <div class="source"><pre>
+Extent ex = pm.getExtent(MyClass.class, true);
+Iterator iter = ex.iterator();
+while (iter.hasNext())
+{
+ MyClass obj = (MyClass)iter.next();
+ ...
+}</pre></div>
+ <p>
+ The second argument in the <i>getExtent</i> call is whether
to include instances of subclasses.
+ </p><br></br></div><div class="subsection"><a
name="Retrieve_an_object_based_on_a_criteria"></a><h3>Retrieve an object based
on a criteria</h3><p>
+ Where we want to retrieve all objects based on some criteria (e.g all
objects of class A where
+ field 'x' of A is a certain value) we need to use a query language. JDO2
provides 2 options here.
+ JDOQL is object-based and allows you to express your query in terms of
the classes and fields
+ you are using. SQL is datastore-based and allows you to express your
query in terms of the
+ datastore tables and columns.
+ </p><p>
+ To give an exmaple of a JDOQL query
+ </p>
+ <div class="source"><pre>
+Query q = pm.newQuery(MyClass.class, "field1 < value");
+q.declareParameters("int value");
+List results = q.execute(205);
+Iterator iter = results.iterator();
+while (iter.hasNext())
+{
+ MyClass obj = (MyClass)iter.next();
+}</pre></div>
+ <p>
+ If the objects found by the query are in the JDO cache then they are
retrieved from there, otherwise the
+ JDO implementation goes to the datastore. When the objects are retrieved
their fields are populated according to the Fetch Group.
+ </p></div></div></div></div><div class="clear"><hr></hr></div><table
border="0" width="100%" cellpadding="0" cellspacing="0"><tr><td width="100%"><img
height="1" border="0" width="100%" src="./images/header_line.gif"></img></td></tr></table><div
id="footer"><div class="xleft">
+ Documentation published: 13 October 2007<br></br>
+ © 2005-2007 <a href="http://www.apache.org/">Apache Software Foundation</a></div></div></body></html>
\ No newline at end of file
Added: db/jdo/site/xdocs/object_retrieval.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/object_retrieval.xml?rev=584436&view=auto
==============================================================================
--- db/jdo/site/xdocs/object_retrieval.xml (added)
+++ db/jdo/site/xdocs/object_retrieval.xml Sat Oct 13 10:55:28 2007
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document>
+ <properties>
+ <title>JDO Object Retrieval</title>
+ </properties>
+
+ <body>
+ <section name="Object Retrieval">
+ <p>
+ JDO provides persistence of objects. The logical next step after persisting
objects is to retrieve them
+ for use in your application. There are several ways to do this
+ </p>
+
+ <subsection name="Retrieve an object from its identity">
+ <p>
+ The simplest form of object retrieval is where we have the identity.
This is simply
+ </p>
+ <source>
+Object obj = pm.getObjectById(identity);
+ </source>
+ <p>
+ If the object is in the JDO cache then it is retrieved from there, otherwise
the JDO implementation
+ goes to the datastore. When the object is retrieved its fields are populated
according to its
+ <a href="../1_1/fetchgroup.html">Fetch Group</a>.
+ </p>
+ </subsection>
+
+ <subsection name="Retrieve an object based on its Extent">
+ <p>
+ A persistable class can be persisted with an <b>Extent</b>
of all instances of that type.
+ You can use this to retrieve objects of the required type, like this
+ </p>
+ <source>
+Extent ex = pm.getExtent(MyClass.class, true);
+Iterator iter = ex.iterator();
+while (iter.hasNext())
+{
+ MyClass obj = (MyClass)iter.next();
+ ...
+}</source>
+ <p>
+ The second argument in the <i>getExtent</i> call is whether
to include instances of subclasses.
+ </p>
+ <br/>
+ </subsection>
+
+ <subsection name="Retrieve an object based on a criteria">
+ <p>
+ Where we want to retrieve all objects based on some criteria (e.g all
objects of class A where
+ field 'x' of A is a certain value) we need to use a query language. JDO2
provides 2 options here.
+ JDOQL is object-based and allows you to express your query in terms of
the classes and fields
+ you are using. SQL is datastore-based and allows you to express your
query in terms of the
+ datastore tables and columns.
+ </p>
+ <p>
+ To give an exmaple of a JDOQL query
+ </p>
+ <source><![CDATA[
+Query q = pm.newQuery(MyClass.class, "field1 < value");
+q.declareParameters("int value");
+List results = q.execute(205);
+Iterator iter = results.iterator();
+while (iter.hasNext())
+{
+ MyClass obj = (MyClass)iter.next();
+}]]></source>
+ <p>
+ If the objects found by the query are in the JDO cache then they are
retrieved from there, otherwise the
+ JDO implementation goes to the datastore. When the objects are retrieved
their fields are populated according to the Fetch Group.
+ </p>
+ </subsection>
+ </section>
+
+ </body>
+</document>
|