| Current Path : /proc/2/cwd/usr/share/doc/db4-devel-4.7.25/gsg/JAVA/ |
| Current File : //proc/2/cwd/usr/share/doc/db4-devel-4.7.25/gsg/JAVA/getmultiple.html |
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Retrieving Multiple Objects</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
<link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
<link rel="up" href="persist_access.html" title="Chapter 5. Saving and Retrieving Objects" />
<link rel="previous" href="simpleget.html" title="Retrieving Objects from an Entity Store" />
<link rel="next" href="dpl_entityjoin.html" title="Join Cursors" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Retrieving Multiple Objects</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="simpleget.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. Saving and Retrieving Objects</th>
<td width="20%" align="right"> <a accesskey="n" href="dpl_entityjoin.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="getmultiple"></a>Retrieving Multiple Objects</h2>
</div>
</div>
<div></div>
</div>
<p>
It is possible to iterate over every object referenced
by a specific index. You may want to do this if, for
example, you want to examine or modify every object
accessible by a specific primary index.
</p>
<p>
In addition, some indexes result in the retrieval of multiple
objects. For example, <tt class="literal">MANY_TO_ONE</tt>
secondary indexes can result in more than one object for any given
key (also known as <span class="emphasis"><em>duplicate keys</em></span>).
When this is the case, you must iterate
over the resulting set of objects in order to examine
each object in turn.
</p>
<p>
There are two ways to iterate over a collection of
objects as returned by an index. One is to use a
standard Java <tt class="classname">Iterator</tt>, which you
obtain using an <tt class="classname">EntityCursor</tt>,
which in turn you can obtain from a <tt class="classname">PrimaryIndex</tt>:
</p>
<pre class="programlisting">PrimaryIndex<String,SimpleEntityClass> pi =
store.getPrimaryIndex(String.class, SimpleEntityClass.class);
EntityCursor<SimpleEntityClass> pi_cursor = pi.entities();
try {
Iterator<SimpleEntityClass> i = pi_cursor.iterator();
while (i.hasNext()) {
// Do something here
}
} finally {
// Always close the cursor
pi_cursor.close();
} </pre>
<p>
Alternatively, you can use a Java "foreach" statement
to iterate over object set:
</p>
<pre class="programlisting">PrimaryIndex<String,SimpleEntityClass> pi =
store.getPrimaryIndex(String.class, SimpleEntityClass.class);
EntityCursor<SimpleEntityClass> pi_cursor = pi.entities();
try {
for (SimpleEntityClass seci : pi_cursor) {
// do something with each object "seci"
}
// Always make sure the cursor is closed when we are done with it.
} finally {
sec_cursor.close();
} </pre>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dpl_cursor_initialize"></a>Cursor Initialization</h3>
</div>
</div>
<div></div>
</div>
<p>
When a cursor is first opened, it is not
positioned to any value; that is,
it is not <span class="emphasis"><em>initialized</em></span>.
Most of the <tt class="classname">EntityCursor</tt>
methods that move a cursor will initialize it
to either the first or last object, depending
on whether the operation is moving the cursor
forward (all <tt class="literal">next...</tt>
methods) or backwards (all
<tt class="literal">prev...</tt>) methods.
</p>
<p>
You can also force a cursor, whether it is
initialized or not, to return the first object
by calling
<tt class="methodname">EntityCursor.first()</tt>.
Similarly, you can force a return of the last
object using
<tt class="methodname">EntityCursor.last()</tt>.
</p>
<p>
Operations that do not move the cursor (such as
<tt class="methodname">EntityCursor.current()</tt>
or <tt class="methodname">EntityCursor.delete()</tt>
will throw an
<tt class="classname">IllegalStateException</tt>
when used on an uninitialized cursor.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dpl_dups"></a>Working with Duplicate Keys</h3>
</div>
</div>
<div></div>
</div>
<p>
If you have duplicate secondary keys, you can return an
<tt class="classname">EntityIndex</tt> class object for them
using <tt class="methodname">SecondaryIndex.subIndex()</tt>
Then, use that object's
<tt class="methodname">entities()</tt>
method to obtain an <tt class="classname">EntityCursor</tt>
instance.
</p>
<p>
For example:
</p>
<pre class="programlisting">PrimaryIndex<String,SimpleEntityClass> pi =
store.getPrimaryIndex(String.class, SimpleEntityClass.class);
SecondaryIndex<String,String,SimpleEntityClass> si =
store.getSecondaryIndex(pi, String.class, "sKey");
EntityCursor<SimpleEntityClass> sec_cursor =
si.subIndex("skeyone").entities();
try {
for (SimpleEntityClass seci : sec_cursor) {
// do something with each object "seci"
}
// Always make sure the cursor is closed when we are done with it.
} finally {
sec_cursor.close(); } </pre>
<p>
Note that if you are working with duplicate keys, you can
control how cursor iteration works by using the following
<tt class="classname">EntityCursor</tt> methods:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<tt class="methodname">nextDup()</tt>
</p>
<p>
Moves the cursor to the next object with the
same key as the cursor is currently
referencing. That is, this method returns the
next duplicate object. If no such object
exists, this method returns
<tt class="literal">null</tt>.
</p>
</li>
<li>
<p>
<tt class="methodname">prevDup()</tt>
</p>
<p>
Moves the cursor to the previous object with the
same key as the cursor is currently
referencing. That is, this method returns the
previous duplicate object in the cursor's set
of objects. If no such object exists, this method returns
<tt class="literal">null</tt>.
</p>
</li>
<li>
<p>
<tt class="methodname">nextNoDup()</tt>
</p>
<p>
Moves the cursor to the next object in the
cursor's set that has a key which is different
than the key that the cursor is currently
referencing. That is, this method skips all
duplicate objects and returns the
next non-duplicate object in the cursor's set
of objects. If no such object exists, this method returns
<tt class="literal">null</tt>.
</p>
</li>
<li>
<p>
<tt class="methodname">prevNoDup()</tt>
</p>
<p>
Moves the cursor to the previous object in the
cursor's set that has a key which is different
than the key that the cursor is currently
referencing. That is, this method skips all
duplicate objects and returns the
previous non-duplicate object in the cursor's set
of objects. If no such object exists, this method returns
<tt class="literal">null</tt>.
</p>
</li>
</ul>
</div>
<p>
For example:
</p>
<pre class="programlisting">PrimaryIndex<String,SimpleEntityClass> pi =
store.getPrimaryIndex(String.class, SimpleEntityClass.class);
SecondaryIndex<String,String,SimpleEntityClass> si =
store.getSecondaryIndex(pi, String.class, "sKey");
EntityCursor<SimpleEntityClass> sec_cursor =
si.subIndex("skeyone").entities();
try {
Iterator<SimpleEntityClass> i = sec_cursor.iterator();
while (i.nextNoDup()) {
// Do something here
}
// Always make sure the cursor is closed when we are done with it.
} finally {
sec_cursor.close(); } </pre>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dpl_cursor_range"></a>Key Ranges</h3>
</div>
</div>
<div></div>
</div>
<p>
You can restrict the scope of a cursor's movement
by specifying a <span class="emphasis"><em>range</em></span> when you
create the cursor. The cursor can then never be
positioned outside of the specified range.
</p>
<p>
When specifying a range, you indicate whether a
range bound is <span class="emphasis"><em>inclusive</em></span> or
<span class="emphasis"><em>exclusive</em></span> by providing a
boolean value for each range.
<tt class="literal">true</tt> indicates that the provided
bound is inclusive, while <tt class="literal">false</tt>
indicates that it is exclusive.
</p>
<p>
You provide this information when you call
<tt class="classname">PrimaryIndex.entities()</tt>
or
<tt class="classname">SecondaryIndex.entities()</tt>.
For example, suppose you had a class indexed by
numerical information. Suppose further that you
wanted to examine only those objects with indexed
values of 100 - 199. Then (assuming the numerical
information is the primary index), you can bound
your cursor as follows:
</p>
<pre class="programlisting">
EntityCursor<SomeEntityClass> cursor =
primaryIndex.entities(100, true, 200, false);
try {
for (SomeEntityClass sec : cursor {
// Do something here to objects ranged from 100 to 199
}
// Always make sure the cursor is closed when we are done with it.
} finally {
cursor.close(); } </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="simpleget.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="persist_access.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="dpl_entityjoin.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Retrieving Objects from an Entity Store </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Join Cursors</td>
</tr>
</table>
</div>
</body>
</html>
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)