JoinRowSet


1   /*
2    * @(#)JoinRowSet.java  1.7 04/05/29
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sql.rowset;
9   
10  import java.sql.*;
11  import javax.sql.*;
12  import javax.naming.*;
13  import java.io.*;
14  import java.math.*;
15  import java.util.*;
16  
17  import javax.sql.rowset.*;
18  
19  /**
20   * The <code>JoinRowSet</code> interface provides a mechanism for combining related
21   * data from different <code>RowSet</code> objects into one <code>JoinRowSet</code>
22   * object, which represents an SQL <code>JOIN</code>.
23   * In other words, a <code>JoinRowSet</code> object acts as a
24   * container for the data from <code>RowSet</code> objects that form an SQL
25   * <code>JOIN</code> relationship.
26   * <P>
27   * The <code>Joinable</code> interface provides the methods for setting,
28   * retrieving, and unsetting a match column, the basis for 
29   * establishing an SQL <code>JOIN</code> relationship. The match column may
30   * alternatively be set by supplying it to the appropriate version of the
31   * <code>JointRowSet</code> method <code>addRowSet</code>.
32   * <P>
33   * <p>
34   * <h3>1.0 Overview</h3>
35   * Disconnected <code>RowSet</code> objects (<code>CachedRowSet</code> objects
36   * and implementations extending the <code>CachedRowSet</code> interface)
37   * do not have a standard way to establish an SQL <code>JOIN</code> between 
38   * <code>RowSet</code> objects without the expensive operation of 
39   * reconnecting to the data source. The <code>JoinRowSet</code> 
40   * interface is specifically designed to address this need. 
41   * <P>
42   * Any <code>RowSet</code> object 
43   * can be added to a <code>JoinRowSet</code> object to become
44   * part of an SQL <code>JOIN</code> relationship. This means that both connected
45   * and disconnected <code>RowSet</code> objects can be part of a <code>JOIN</code>.
46   * <code>RowSet</code> objects operating in a connected environment 
47   * (<code>JdbcRowSet</code> objects) are
48   * encouraged to use the database to which they are already 
49   * connected to establish SQL <code>JOIN</code> relationships between
50   * tables directly. However, it is possible for a
51   * <code>JdbcRowSet</code> object to be added to a <code>JoinRowSet</code> object 
52   * if necessary.  
53   * <P>
54   * Any number of <code>RowSet</code> objects can be added to an
55   * instance of <code>JoinRowSet</code> provided that they
56   * can be related in an SQL <code>JOIN</code>.
57   * By definition, the SQL <code>JOIN</code> statement is used to
58   * combine the data contained in two or more relational database tables based
59   * upon a common attribute. The <code>Joinable</code> interface provides the methods
60   * for establishing a common attribute, which is done by setting a
61   * <i>match column</i>. The match column commonly coincides with
62   * the primary key, but there is
63   * no requirement that the match column be the same as the primary key.
64   * By establishing and then enforcing column matches,
65   * a <code>JoinRowSet</code> object establishes <code>JOIN</code> relationships 
66   * between <code>RowSet</code> objects without the assistance of an available
67   * relational database.
68   * <P>
69   * The type of <code>JOIN</code> to be established is determined by setting
70   * one of the <code>JoinRowSet</code> constants using the method
71   * <code>setJoinType</code>. The following SQL <code>JOIN</code> types can be set:
72   * <UL>
73   *  <LI><code>CROSS_JOIN</code>
74   *  <LI><code>FULL_JOIN</code>
75   *  <LI><code>INNER_JOIN</code> - the default if no <code>JOIN</code> type has been set
76   *  <LI><code>LEFT_OUTER_JOIN</code>
77   *  <LI><code>RIGHT_OUTER_JOIN</code>
78   * </UL>
79   * Note that if no type is set, the <code>JOIN</code> will automatically be an
80   * inner join. The comments for the fields in the
81   * <code>JoinRowSet</code> interface explain these <code>JOIN</code> types, which are
82   * standard SQL <code>JOIN</code> types. 
83   * <P>
84   * <h3>2.0 Using a <code>JoinRowSet</code> Object for Creating a <code>JOIN</code></h3>
85   * When a <code>JoinRowSet</code> object is created, it is empty.
86   * The first <code>RowSet</code> object to be added becomes the basis for the
87   * <code>JOIN</code> relationship.
88   * Applications must determine which column in each of the
89   * <code>RowSet</code> objects to be added to the <code>JoinRowSet</code> object 
90   * should be the match column. All of the 
91   * <code>RowSet</code> objects must contain a match column, and the values in
92   * each match column must be ones that can be compared to values in the other match
93   * columns. The columns do not have to have the same name, though they often do, 
94   * and they do not have to store the exact same data type as long as the data types
95   * can be compared.  
96   * <P>
97   * A match column can be be set in two ways: 
98   * <ul>
99   *  <li>By calling the <code>Joinable</code> method <code>setMatchColumn</code><br>
100  *  This is the only method that can set the match column before a <code>RowSet</code> 
101  *  object is added to a <code>JoinRowSet</code> object. The <code>RowSet</code> object
102  *  must have implemented the <code>Joinable</code> interface in order to use the method
103  *  <code>setMatchColumn</code>. Once the match column value
104  *  has been set, this method can be used to reset the match column at any time.
105  *  <li>By calling one of the versions of the <code>JoinRowSet</code> method 
106  *  <code>addRowSet</code> that takes a column name or number (or an array of
107  *  column names or numbers)<BR>
108  *  Four of the five <code>addRowSet</code> methods take a match column as a parameter.
109  *  These four methods set or reset the match column at the time a <code>RowSet</code> 
110  *  object is being added to a <code>JoinRowSet</code> object.
111  * </ul>
112  * <h3>3.0 Sample Usage</h3>
113  * <p>
114  * The following code fragment adds two <code>CachedRowSet</code> 
115  * objects to a <code>JoinRowSet</code> object. Note that in this example,
116  * no SQL <code>JOIN</code> type is set, so the default <code>JOIN</code> type,
117  * which is <i>INNER_JOIN</i>, is established. 
118  * <p>
119  * In the following code fragment, the table <code>EMPLOYEES</code>, whose match 
120  * column is set to the first column (<code>EMP_ID</code>), is added to the
121  * <code>JoinRowSet</code> object <i>jrs</i>. Then
122  * the table <code>ESSP_BONUS_PLAN</code>, whose match column is likewise 
123  * the <code>EMP_ID</code> column, is added. When this second
124  * table is added to <i>jrs</i>, only the rows in 
125  * <code>ESSP_BONUS_PLAN</code> whose <code>EMP_ID</code> value matches an
126  * <code>EMP_ID</code> value in the <code>EMPLOYEES</code> table are added.
127  * In this case, everyone in the bonus plan is an employee, so all of the rows
128  * in the table <code>ESSP_BONUS_PLAN</code> are added to the <code>JoinRowSet</code>
129  * object.  In this example, both <code>CachedRowSet</code> objects being added
130  * have implemented the <code>Joinable</code> interface and can therefore call 
131  * the <code>Joinable</code> method <code>setMatchColumn</code>.
132  * <PRE>
133  *     JoinRowSet jrs = new JoinRowSetImpl();
134  * 
135  *     ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES");
136  *     CachedRowSet empl = new CachedRowSetImpl();
137  *     empl.populate(rs1);
138  *     empl.setMatchColumn(1); 
139  *     jrs.addRowSet(empl);
140  * 
141  *     ResultSet rs2 = stmt.executeQuery("SELECT * FROM ESSP_BONUS_PLAN");
142  *     CachedRowSet bonus = new CachedRowSetImpl();
143  *     bonus.populate(rs2);
144  *     bonus.setMatchColumn(1); // EMP_ID is the first column
145  *     jrs.addRowSet(bonus);
146  * </PRE>
147  * <P>
148  * At this point, <i>jrs</i> is an inside JOIN of the two <code>RowSet</code> objects
149  * based on their <code>EMP_ID</code> columns. The application can now browse the
150  * combined data as if it were browsing one single <code>RowSet</code> object.
151  * Because <i>jrs</i> is itself a <code>RowSet</code> object, an application can
152  * navigate or modify it using <code>RowSet</code> methods.
153  * <PRE>
154  *     jrs.first();
155  *     int employeeID = jrs.getInt(1);
156  *     String employeeName = jrs.getString(2);
157  * </PRE>
158  * <P>
159  * Note that because the SQL <code>JOIN</code> must be enforced when an application
160  * adds a second or subsequent <code>RowSet</code> object, there
161  * may be an initial degradation in performance while the <code>JOIN</code> is
162  * being performed.
163  * <P>
164  * The following code fragment adds an additional <code>CachedRowSet</code> object.
165  * In this case, the match column (<code>EMP_ID</code>) is set when the 
166  * <code>CachedRowSet</code> object is added to the <code>JoinRowSet</code> object. 
167  * <PRE>
168  *     ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB");
169  *     CachedRowSet fourO1k = new CachedRowSetImpl();
170  *     four01k.populate(rs3);
171  *     jrs.addRowSet(four01k, 1);
172  * </PRE>
173  * <P>
174  * The <code>JoinRowSet</code> object <i>jrs</i> now contains values from all three
175  * tables. The data in each row in <i>four01k</i> in which the value for the 
176  * <code>EMP_ID</code> column matches a value for the <code>EMP_ID</code> column 
177  * in <i>jrs</i> has been added to <i>jrs</i>.
178  * <P>
179  * <h3>4.0 <code>JoinRowSet</code> Methods</h3>
180  * The <code>JoinRowSet</code> interface supplies several methods for adding 
181  * <code>RowSet</code> objects and for getting information about the 
182  * <code>JoinRowSet</code> object.
183  * <UL>
184  *   <LI>Methods for adding one or more <code>RowSet</code> objects<BR>
185  *       These methods allow an application to add one <code>RowSet</code> object
186  *       at a time or to add multiple <code>RowSet</code> objects at one time. In
187  *       either case, the methods may specify the match column for each 
188  *       <code>RowSet</code> object being added.
189  *   <LI>Methods for getting information<BR>
190  *       One method retrieves the <code>RowSet</code> objects in the 
191  *       <code>JoinRowSet</code> object, and another method retrieves the 
192  *       <code>RowSet</code> names.  A third method retrieves either the SQL 
193  *       <code>WHERE</code> clause used behind the scenes to form the 
194  *       <code>JOIN</code> or a text description of what the <code>WHERE</code>
195  *       clause does.
196  *   <LI>Methods related to the type of <code>JOIN</code><BR>
197  *       One method sets the <code>JOIN</code> type, and five methods find out whether
198  *       the <code>JoinRowSet</code> object supports a given type.
199  *   <LI>A method to make a separate copy of the <code>JoinRowSet</code> object<BR>
200  *       This method creates a copy that can be persisted to the data source.
201  * </UL>
202  * <P>
203  */
204 
205 public interface JoinRowSet extends WebRowSet   {
206 
207     /**
208      * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code>
209      * object. If the <code>RowSet</code> object
210      * is the first to be added to this <code>JoinRowSet</code>
211      * object, it forms the basis of the <code>JOIN</code> relationship to be 
212      * established.
213      * <P>
214      * This method should be used only when the given <code>RowSet</code>
215      * object already has a match column that was set with the <code>Joinable</code>
216      * method <code>setMatchColumn</code>.
217      * <p>
218      * Note: A <code>Joinable</code> object is any <code>RowSet</code> object
219      * that has implemented the <code>Joinable</code> interface. 
220      *
221      * @param rowset the <code>RowSet</code> object that is to be added to this
222      *        <code>JoinRowSet</code> object; it must implement the 
223      *        <code>Joinable</code> interface and have a match column set
224      * @throws SQLException if (1) an empty rowset is added to the to this
225      *         <code>JoinRowSet</code> object, (2) a match column has not been
226      *         set for <i>rowset</i>, or (3) <i>rowset</i>
227      *         violates the active <code>JOIN</code>
228      * @see Joinable#setMatchColumn
229      */
230     public void addRowSet(Joinable   rowset) throws SQLException;
231 
232     /**
233      * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code>
234      * object and sets the designated column as the match column for
235      * the <code>RowSet</code> object. If the <code>RowSet</code> object
236      * is the first to be added to this <code>JoinRowSet</code>
237      * object, it forms the basis of the <code>JOIN</code> relationship to be 
238      * established.
239      * <P>
240      * This method should be used when <i>RowSet</i> does not already have a match
241      * column set.
242      *
243      * @param rowset the <code>RowSet</code> object that is to be added to this
244      *        <code>JoinRowSet</code> object; it may implement the 
245      *        <code>Joinable</code> interface 
246      * @param columnIdx an <code>int</code> that identifies the column to become the
247      *         match column
248      * @throws SQLException if (1) <i>rowset</i> is an empty rowset or
249      *         (2) <i>rowset</i> violates the active <code>JOIN</code>
250      * @see Joinable#unsetMatchColumn
251      */
252     public void addRowSet(RowSet rowset, int columnIdx) throws SQLException;
253 
254     /**
255      * Adds <i>rowset</i> to this <code>JoinRowSet</code> object and
256      * sets the designated column as the match column. If <i>rowset</i>
257      * is the first to be added to this <code>JoinRowSet</code>
258      * object, it forms the basis for the <code>JOIN</code> relationship to be 
259      * established. 
260      * <P>
261      * This method should be used when the given <code>RowSet</code> object
262      * does not already have a match column.     
263      * 
264      * @param rowset the <code>RowSet</code> object that is to be added to this
265      *        <code>JoinRowSet</code> object; it may implement the 
266      *        <code>Joinable</code> interface 
267      * @param columnName the <code>String</code> object giving the name of the 
268      *        column to be set as the match column
269      * @throws SQLException if (1) <i>rowset</i> is an empty rowset or
270      *         (2) the match column for <i>rowset</i> does not satisfy the
271      *         conditions of the <code>JOIN</code>
272      */
273      public void addRowSet(RowSet rowset, 
274                            String   columnName) throws SQLException;
275 
276     /**
277      * Adds one or more <code>RowSet</code> objects contained in the given 
278      * array of <code>RowSet</code> objects to this <code>JoinRowSet</code> 
279      * object and sets the match column for
280      * each of the <code>RowSet</code> objects to the match columns 
281      * in the given array of column indexes. The first element in 
282      * <i>columnIdx</i> is set as the match column for the first
283      * <code>RowSet</code> object in <i>rowset</i>, the second element of
284      * <i>columnIdx</i> is set as the match column for the second element
285      * in <i>rowset</i>, and so on.
286      * <P>
287      * The first <code>RowSet</code> object added to this <code>JoinRowSet</code>
288      * object forms the basis for the <code>JOIN</code> relationship.
289      * <P>
290      * This method should be used when the given <code>RowSet</code> object
291      * does not already have a match column.
292      *
293      * @param rowset an array of one or more <code>RowSet</code> objects 
294      *        to be added to the <code>JOIN</code>; it may implement the 
295      *        <code>Joinable</code> interface  
296      * @param columnIdx an array of <code>int</code> values indicating the index(es)
297      *        of the columns to be set as the match columns for the <code>RowSet</code>
298      *        objects in <i>rowset</i>
299      * @throws SQLException if (1) an empty rowset is added to this 
300      *         <code>JoinRowSet</code> object, (2) a match column is not set
301      *         for a <code>RowSet</code> object in <i>rowset</i>, or (3) 
302      *         a <code>RowSet</code> object being added violates the active
303      *         <code>JOIN</code>
304      */
305     public void addRowSet(RowSet[] rowset, 
306                           int[] columnIdx) throws SQLException;
307 
308     /**
309      * Adds one or more <code>RowSet</code> objects contained in the given 
310      * array of <code>RowSet</code> objects to this <code>JoinRowSet</code> 
311      * object and sets the match column for
312      * each of the <code>RowSet</code> objects to the match columns 
313      * in the given array of column names. The first element in 
314      * <i>columnName</i> is set as the match column for the first
315      * <code>RowSet</code> object in <i>rowset</i>, the second element of
316      * <i>columnName</i> is set as the match column for the second element
317      * in <i>rowset</i>, and so on.
318      * <P>
319      * The first <code>RowSet</code> object added to this <code>JoinRowSet</code>
320      * object forms the basis for the <code>JOIN</code> relationship.
321      * <P>
322      * This method should be used when the given <code>RowSet</code> object(s)
323      * does not already have a match column.
324      *
325      * @param rowset an array of one or more <code>RowSet</code> objects 
326      *        to be added to the <code>JOIN</code>; it may implement the 
327      *        <code>Joinable</code> interface 
328      * @param columnName an array of <code>String</code> values indicating the 
329      *        names of the columns to be set as the match columns for the 
330      *        <code>RowSet</code> objects in <i>rowset</i>
331      * @throws SQLException if (1) an empty rowset is added to this 
332      *         <code>JoinRowSet</code> object, (2) a match column is not set
333      *         for a <code>RowSet</code> object in <i>rowset</i>, or (3) 
334      *         a <code>RowSet</code> object being added violates the active
335      *         <code>JOIN</code>
336      */
337     public void addRowSet(RowSet[] rowset, 
338                           String  [] columnName) throws SQLException;
339     
340     /**
341      * Returns a <code>Collection</code> object containing the 
342      * <code>RowSet</code> objects that have been added to this
343      * <code>JoinRowSet</code> object.
344      * This should return the 'n' number of RowSet contained
345      * within the <code>JOIN</code> and maintain any updates that have occured while in
346      * this union.
347      * 
348      * @return a <code>Collection</code> object consisting of the 
349      *        <code>RowSet</code> objects added to this <code>JoinRowSet</code>
350      *        object
351      * @throws SQLException if an error occurs generating the 
352      *         <code>Collection</code> object to be returned
353      */
354     public Collection<?> getRowSets() throws java.sql.SQLException  ; 
355 
356     /**
357      * Returns a <code>String</code> array containing the names of the
358      *         <code>RowSet</code> objects added to this <code>JoinRowSet</code>
359      *         object.
360      *
361      * @return a <code>String</code> array of the names of the
362      *         <code>RowSet</code> objects in this <code>JoinRowSet</code>
363      *         object
364      * @throws SQLException if an error occurs retrieving the names of
365      *         the <code>RowSet</code> objects
366      * @see CachedRowSet#setTableName
367      */
368     public String  [] getRowSetNames() throws java.sql.SQLException  ;   
369 
370     /**
371      * Creates a new <code>CachedRowSet</code> object containing the 
372      * data in this <code>JoinRowSet</code> object, which can be saved
373      * to a data source using the <code>SyncProvider</code> object for
374      * the <code>CachedRowSet</code> object.
375      * <P>
376      * If any updates or modifications have been applied to the JoinRowSet
377      * the CachedRowSet returned by the method will not be able to persist
378      * it's changes back to the originating rows and tables in the 
379      * in the datasource. The CachedRowSet instance returned should not
380      * contain modification data and it should clear all properties of
381      * it's originating SQL statement. An application should reset the
382      * SQL statement using the <code>RowSet.setCommand</code> method.
383      * <p>
384      * In order to allow changes to be persisted back to the datasource
385      * to the originating tables, the <code>acceptChanges</code> method
386      * should be used and called on a JoinRowSet object instance. Implementations
387      * can leverage the internal data and update tracking in their 
388      * implementations to interact with the SyncProvider to persist any
389      * changes. 
390      *
391      * @return a CachedRowSet containing the contents of the JoinRowSet
392      * @throws SQLException if an error occurs assembling the CachedRowSet
393      * object 
394      * @see javax.sql.RowSet
395      * @see javax.sql.rowset.CachedRowSet
396      * @see javax.sql.rowset.spi.SyncProvider
397      */
398     public CachedRowSet   toCachedRowSet() throws java.sql.SQLException  ;
399 
400     /**
401      * Indicates if CROSS_JOIN is supported by a JoinRowSet 
402      * implementation
403      *
404      * @return true if the CROSS_JOIN is supported; false otherwise
405      */
406     public boolean supportsCrossJoin();
407 
408     /**
409      * Indicates if INNER_JOIN is supported by a JoinRowSet 
410      * implementation
411      *
412      * @return true is the INNER_JOIN is supported; false otherwise
413      */
414     public boolean supportsInnerJoin();
415 
416     /**
417      * Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet 
418      * implementation
419      *
420      * @return true is the LEFT_OUTER_JOIN is supported; false otherwise
421      */
422     public boolean supportsLeftOuterJoin();
423 
424     /**
425      * Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet 
426      * implementation
427      *
428      * @return true is the RIGHT_OUTER_JOIN is supported; false otherwise
429      */
430     public boolean supportsRightOuterJoin();
431 
432     /**
433      * Indicates if FULL_JOIN is supported by a JoinRowSet 
434      * implementation
435      *
436      * @return true is the FULL_JOIN is supported; false otherwise
437      */
438     public boolean supportsFullJoin();
439 
440     /**
441      * Allow the application to adjust the type of <code>JOIN</code> imposed
442      * on tables contained within the JoinRowSet object instance.
443      * Implementations should throw a SQLException if they do 
444      * not support a given <code>JOIN</code> type.
445      *
446      * @param joinType the standard JoinRowSet.XXX static field definition
447      * of a SQL <code>JOIN</code> to re-configure a JoinRowSet instance on
448      * the fly.
449      * @throws SQLException if an unsupported <code>JOIN</code> type is set
450      * @see #getJoinType
451      */
452     public void setJoinType(int joinType) throws SQLException;   
453 
454     /**
455      * Return a SQL-like description of the WHERE clause being used
456      * in a JoinRowSet object. An implementation can describe
457      * the WHERE clause of the SQL <code>JOIN</code> by supplying a SQL
458      * strings description of <code>JOIN</code> or provide a textual
459      * description to assist applications using a <code>JoinRowSet</code>
460      *
461      * @return whereClause a textual or SQL description of the logical
462      * WHERE clause used in the JoinRowSet instance
463      * @throws SQLException if an error occurs in generating a representation
464      * of the WHERE clause.
465      */
466     public String   getWhereClause() throws SQLException;
467     
468     /**
469      * Returns a <code>int</code> describing the set SQL <code>JOIN</code> type 
470      * governing this JoinRowSet instance. The returned type will be one of
471      * standard JoinRowSet types: <code>CROSS_JOIN</code>, <code>INNER_JOIN</code>, 
472      * <code>LEFT_OUTER_JOIN</code>, <code>RIGHT_OUTER_JOIN</code> or 
473      * <code>FULL_JOIN</code>.
474      *
475      * @return joinType one of the standard JoinRowSet static field 
476      *     definitions of a SQL <code>JOIN</code>. <code>JoinRowSet.INNER_JOIN</code>
477      *     is returned as the default <code>JOIN</code> type is no type has been
478      *     explicitly set.
479      * @throws SQLException if an error occurs determining the SQL <code>JOIN</code>
480      *     type supported by the JoinRowSet instance.
481      * @see #setJoinType
482      */
483     public int getJoinType() throws SQLException;
484 
485     /**
486      * An ANSI-style <code>JOIN</code> providing a cross product of two tables
487      */
488     public static int CROSS_JOIN = 0;
489 
490     /**
491      * An ANSI-style <code>JOIN</code> providing a inner join between two tables. Any
492      * unmatched rows in either table of the join should be discarded.
493      */
494     public static int INNER_JOIN = 1;
495 
496     /**
497      * An ANSI-style <code>JOIN</code> providing a left outer join between two
498      * tables. In SQL, this is described where all records should be 
499      * returned from the left side of the JOIN statement.
500      */
501     public static int LEFT_OUTER_JOIN = 2;
502     
503     /**
504      * An ANSI-style <code>JOIN</code> providing a right outer join between
505      * two tables. In SQL, this is described where all records from the
506      * table on the right side of the JOIN statement even if the table 
507      * on the left has no matching record.
508      */
509     public static int RIGHT_OUTER_JOIN = 3;
510 
511     /**
512      * An ANSI-style <code>JOIN</code> providing a a full JOIN. Specifies that all 
513      * rows from either table be returned regardless of matching
514      * records on the other table.
515      */
516     public static int FULL_JOIN = 4;
517 
518         
519 }
520 
521
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags