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.73.2" />
9    <link rel="start" 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="prev" 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>
36      <p>
37                        If you have two or more secondary indexes set for
38                        an entity object, then you can retrieve sets of
39                        objects based on the intersection of multiple
40                        secondary index values. You do this using an
41                        <code class="classname">EntityJoin</code>
42                        class.
43                </p>
44      <p>
45                        For example, suppose you had an entity class that
46                        represented automobiles. In that case, you might
47                        be storing information about automobiles such as
48                        color, number of doors, fuel mileage,
49                        automobile type, number of passengers, make, model, and year,
50                        to name just a few.
51                </p>
52      <p>
53                        If you created a secondary index based this
54                        information, then you could use an
55                        <code class="classname">EntityJoin</code> to return
56                        all those objects representing cars with, say, two
57                        doors, that were built in 2002, and which are green
58                        in color.
59                </p>
60      <p>
61                        To create a join cursor, you:
62                </p>
63      <div class="orderedlist">
64        <ol type="1">
65          <li>
66            <p>
67                                        Open the primary index for the
68                                        entity class on which you want to
69                                        perform the join.
70                                </p>
71          </li>
72          <li>
73            <p>
74                                        Open the secondary indexes that you
75                                        want to use for the join.
76                                </p>
77          </li>
78          <li>
79            <p>
80                                        Instantiate an
81                                        <code class="classname">EntityJoin</code>
82                                        object (you use the primary index
83                                        to do this).
84                                </p>
85          </li>
86          <li>
87            <p>
88                                        Use two or more calls to 
89                                        <code class="methodname">EntityJoin.addCondition()</code>
90                                        to identify the secondary indexes
91                                        and their values that you want to use
92                                        for the equality match.
93                                </p>
94          </li>
95          <li>
96            <p>
97                                        Call
98                                        <code class="methodname">EntityJoin.entities()</code>
99                                        to obtain a cursor that you can use
100                                        to iterate over the join results.
101                                </p>
102          </li>
103        </ol>
104      </div>
105      <p>
106                        For example, suppose we had an entity class
107                        that included the following features:
108                </p>
109      <pre class="programlisting">package persist.gettingStarted;
110
111import com.sleepycat.persist.model.Entity;
112import com.sleepycat.persist.model.PrimaryKey;
113import static com.sleepycat.persist.model.Relationship.*;
114import com.sleepycat.persist.model.SecondaryKey;
115
116@Entity
117public class Automobiles {
118
119    // Primary key is the vehicle identification number
120    @PrimaryKey
121    private String vin;
122
123    // Secondary key is the vehicle's make
124    @SecondaryKey(relate=MANY_TO_ONE)
125    private String make;
126
127    // Secondary key is the vehicle's color
128    @SecondaryKey(relate=MANY_TO_ONE)
129    private String color;
130
131    ...
132
133    public String getVIN() {
134        return vin;
135    }
136
137    public String getMake() {
138        return make;
139    }
140
141    public String getColor() {
142        return color;
143    }
144    
145    ... </pre>
146      <p>
147            Then we could perform an entity join that searches for all the
148            red automobiles made by Toyota as follows:
149    </p>
150      <pre class="programlisting">
151PrimaryIndex&lt;String,Automobiles&gt; vin_pidx;
152SecondaryIndex&lt;String,String,Automobiles&gt; make_sidx;
153SecondaryIndex&lt;String,String,Automobiles&gt; color_sidx;
154
155EntityJoin&lt;String,Automobiles&gt; join = new EntityJoin(vin_pidx);
156join.addCondition(make_sidx,"Toyota");
157join.addCondition(color_sidx,"Red");
158
159// Now iterate over the results of the join operation
160ForwardCursor&lt;Automobiles&gt; join_cursor = join.entities();
161try {
162    for (Automobiles autoi : join_cursor) {
163        // do something with each object "autoi"
164    }
165// Always make sure the cursor is closed when we are done with it.
166} finally {
167    join_cursor.close();
168} </pre>
169    </div>
170    <div class="navfooter">
171      <hr />
172      <table width="100%" summary="Navigation footer">
173        <tr>
174          <td width="40%" align="left"><a accesskey="p" href="getmultiple.html">Prev</a>��</td>
175          <td width="20%" align="center">
176            <a accesskey="u" href="persist_access.html">Up</a>
177          </td>
178          <td width="40%" align="right">��<a accesskey="n" href="dpl_delete.html">Next</a></td>
179        </tr>
180        <tr>
181          <td width="40%" align="left" valign="top">Retrieving Multiple Objects��</td>
182          <td width="20%" align="center">
183            <a accesskey="h" href="index.html">Home</a>
184          </td>
185          <td width="40%" align="right" valign="top">��Deleting Entity Objects</td>
186        </tr>
187      </table>
188    </div>
189  </body>
190</html>
191