1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml">
4  <head>
5    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6    <title>Join Cursors</title>
7    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
9    <link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
10    <link rel="up" href="persist_access.html" title="Chapter��5.��Saving and Retrieving Objects" />
11    <link rel="previous" href="getmultiple.html" title="Retrieving Multiple Objects" />
12    <link rel="next" href="dpl_delete.html" title="Deleting Entity Objects" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Join Cursors</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="getmultiple.html">Prev</a>��</td>
22          <th width="60%" align="center">Chapter��5.��Saving and Retrieving Objects</th>
23          <td width="20%" align="right">��<a accesskey="n" href="dpl_delete.html">Next</a></td>
24        </tr>
25      </table>
26      <hr />
27    </div>
28    <div class="sect1" lang="en" xml:lang="en">
29      <div class="titlepage">
30        <div>
31          <div>
32            <h2 class="title" style="clear: both"><a id="dpl_entityjoin"></a>Join Cursors</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <p>
38                        If you have two or more secondary indexes set for
39                        an entity object, then you can retrieve sets of
40                        objects based on the intersection of multiple
41                        secondary index values. You do this using an
42                        <tt class="classname">EntityJoin</tt>
43                        class.
44                </p>
45      <p>
46                        For example, suppose you had an entity class that
47                        represented automobiles. In that case, you might
48                        be storing information about automobiles such as
49                        color, number of doors, fuel mileage,
50                        automobile type, number of passengers, make, model, and year,
51                        to name just a few.
52                </p>
53      <p>
54                        If you created a secondary index based this
55                        information, then you could use an
56                        <tt class="classname">EntityJoin</tt> to return
57                        all those objects representing cars with, say, two
58                        doors, that were built in 2002, and which are green
59                        in color.
60                </p>
61      <p>
62                        To create a join cursor, you:
63                </p>
64      <div class="orderedlist">
65        <ol type="1">
66          <li>
67            <p>
68                                        Open the primary index for the
69                                        entity class on which you want to
70                                        perform the join.
71                                </p>
72          </li>
73          <li>
74            <p>
75                                        Open the secondary indexes that you
76                                        want to use for the join.
77                                </p>
78          </li>
79          <li>
80            <p>
81                                        Instantiate an
82                                        <tt class="classname">EntityJoin</tt>
83                                        object (you use the primary index
84                                        to do this).
85                                </p>
86          </li>
87          <li>
88            <p>
89                                        Use two or more calls to 
90                                        <tt class="methodname">EntityJoin.addCondition()</tt>
91                                        to identify the secondary indexes
92                                        and their values that you want to use
93                                        for the equality match.
94                                </p>
95          </li>
96          <li>
97            <p>
98                                        Call
99                                        <tt class="methodname">EntityJoin.entities()</tt>
100                                        to obtain a cursor that you can use
101                                        to iterate over the join results.
102                                </p>
103          </li>
104        </ol>
105      </div>
106      <p>
107                        For example, suppose we had an entity class
108                        that included the following features:
109                </p>
110      <pre class="programlisting">package persist.gettingStarted;
111
112import com.sleepycat.persist.model.Entity;
113import com.sleepycat.persist.model.PrimaryKey;
114import static com.sleepycat.persist.model.Relationship.*;
115import com.sleepycat.persist.model.SecondaryKey;
116
117@Entity
118public class Automobiles {
119
120    // Primary key is the vehicle identification number
121    @PrimaryKey
122    private String vin;
123
124    // Secondary key is the vehicle's make
125    @SecondaryKey(relate=MANY_TO_ONE)
126    private String make;
127
128    // Secondary key is the vehicle's color
129    @SecondaryKey(relate=MANY_TO_ONE)
130    private String color;
131
132    ...
133
134    public String getVIN() {
135        return vin;
136    }
137
138    public String getMake() {
139        return make;
140    }
141
142    public String getColor() {
143        return color;
144    }
145    
146    ... </pre>
147      <p>
148            Then we could perform an entity join that searches for all the
149            red automobiles made by Toyota as follows:
150    </p>
151      <pre class="programlisting">
152PrimaryIndex&lt;String,Automobiles&gt; vin_pidx;
153SecondaryIndex&lt;String,String,Automobiles&gt; make_sidx;
154SecondaryIndex&lt;String,String,Automobiles&gt; color_sidx;
155
156EntityJoin&lt;String,Automobiles&gt; join = new EntityJoin(vin_pidx);
157join.addCondition(make_sidx,"Toyota");
158join.addCondition(color_sidx,"Red");
159
160// Now iterate over the results of the join operation
161EntityCursor&lt;Automobiles&gt; join_cursor = join.entities();
162try {
163    for (Automobiles autoi : join_cursor) {
164        // do something with each object "autoi"
165    }
166// Always make sure the cursor is closed when we are done with it.
167} finally {
168    join_cursor.close();
169} </pre>
170    </div>
171    <div class="navfooter">
172      <hr />
173      <table width="100%" summary="Navigation footer">
174        <tr>
175          <td width="40%" align="left"><a accesskey="p" href="getmultiple.html">Prev</a>��</td>
176          <td width="20%" align="center">
177            <a accesskey="u" href="persist_access.html">Up</a>
178          </td>
179          <td width="40%" align="right">��<a accesskey="n" href="dpl_delete.html">Next</a></td>
180        </tr>
181        <tr>
182          <td width="40%" align="left" valign="top">Retrieving Multiple Objects��</td>
183          <td width="20%" align="center">
184            <a accesskey="h" href="index.html">Home</a>
185          </td>
186          <td width="40%" align="right" valign="top">��Deleting Entity Objects</td>
187        </tr>
188      </table>
189    </div>
190  </body>
191</html>
192