Joinable


1   /*
2    * @(#)Joinable.java    1.5 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.SQLException  ;
11  
12  /**
13   * <h3>1.0 Background</h3>
14   * The <code>Joinable</code> interface provides the methods for getting and
15   * setting a match column, which is the basis for forming the SQL <code>JOIN</code>
16   * formed by adding <code>RowSet</code> objects to a <code>JoinRowSet</code>
17   * object.
18   * <P>
19   * Any standard <code>RowSet</code> implementation <b>may</b> implement 
20   * the <code>Joinable</code> interface in order to be
21   * added to a <code>JoinRowSet</code> object. Implementing this interface gives
22   * a <code>RowSet</code> object the ability to use <code>Joinable</code> methods,
23   * which set, retrieve, and get information about match columns.  An
24   * application may add a
25   * <code>RowSet</code> object that has not implemented the <code>Joinable</code>
26   * interface to a <code>JoinRowSet</code> object, but to do so it must use one
27   * of the <code>JoinRowSet.addRowSet</code> methods that takes both a
28   * <code>RowSet</code> object and a match column or an array of <code>RowSet</code>
29   * objects and an array of match columns. 
30   * <P>
31   * To get access to the methods in the <code>Joinable</code> interface, a
32   * <code>RowSet</code> object implements at least one of the
33   * five standard <code>RowSet</code> interfaces and also implements the 
34   * <code>Joinable</code> interface.  In addition, most <code>RowSet</code>
35   * objects extend the <code>BaseRowSet</code> class.  For example:
36   * <pre>
37   *     class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable {
38   *         :
39   *         :
40   *     }
41   * </pre>
42   * <P>
43   * <h3>2.0 Usage Guidelines</h3>
44   * <P>
45   * The methods in the <code>Joinable</code> interface allow a <code>RowSet</code> object 
46   * to set a match column, retrieve a match column, or unset a match column, which is
47   * the column upon which an SQL <code>JOIN</code> can be based.
48   * An instance of a class that implements these methods can be added to a 
49   * <code>JoinRowSet</code> object to allow an SQL <code>JOIN</code> relationship to
50   *  be established.
51   * <p>
52   * <pre>
53   *     CachedRowSet crs = new MyRowSetImpl();
54   *     crs.populate((ResultSet)rs);
55   *     (Joinable)crs.setMatchColumnIndex(1);
56   *
57   *     JoinRowSet jrs = new JoinRowSetImpl();
58   *     jrs.addRowSet(crs);
59   * </pre>
60   * In the previous example, <i>crs</i> is a <code>CachedRowSet</code> object that
61   * has emplemented the <code>Joinable</code> interface.  In the following example,
62   * <i>crs2</i> has not, so it must supply the match column as an argument to the
63   * <code>addRowSet</code> method. This example assumes that column 1 is the match
64   * column.
65   * <PRE>
66   *     CachedRowSet crs2 = new MyRowSetImpl();
67   *     crs2.populate((ResultSet)rs);
68   *     
69   *     JoinRowSet jrs2 = new JoinRowSetImpl();
70   *     jrs2.addRowSet(crs2, 1);
71   * </PRE>
72   * <p>
73   * The <code>JoinRowSet</code> interface makes it possible to get data from one or
74   * more <code>RowSet</code> objects consolidated into one table without having to incur 
75   * the expense of creating a connection to a database. It is therefore ideally suited
76   * for use by disconnected <code>RowSet</code> objects. Nevertheless, any
77   * <code>RowSet</code> object <b>may</b> implement this interface
78   * regardless of whether it is connected or disconnected. Note that a
79   * <code>JdbcRowSet</code> object, being always connected to its data source, can
80   * become part of an SQL <code>JOIN</code> directly without having to become part
81   * of a <code>JoinRowSet</code> object. 
82   * <P>
83   * <h3>3.0 Managing Multiple Match Columns</h3>
84   * The index array passed into the <code>setMatchColumn</code> methods indicates 
85   * how many match columns are being set (the length of the array) in addition to
86   * which columns will be used for the match. For example:
87   * <pre>
88   *     int[] i = {1, 2, 4, 7}; // indicates four match columns, with column
89   *                             // indexes 1, 2, 4, 7 participating in the JOIN.
90   *     Joinable.setMatchColumn(i);
91   * </pre>
92   * Subsequent match columns may be added as follows to a different <code>Joinable</code>
93   * object (a <code>RowSet</code> object that has implemented the <code>Joinable</code>
94   * interface).
95   * <pre>
96   *     int[] w = {3, 2, 5, 3};
97   *     Joinable2.setMatchColumn(w);
98   * </pre>
99   * When an application adds two or more <code>RowSet</code> objects to a
100  * <code>JoinRowSet</code> object, the order of the indexes in the array is 
101  * particularly important. Each index of 
102  * the array maps directly to the corresponding index of the previously added 
103  * <code>RowSet</code> object. If overlap or underlap occurs, the match column 
104  * data is maintained in the event an additional <code>Joinable</code> RowSet is
105  * added and needs to relate to the match column data. Therefore, applications 
106  * can set multiple match columns in any order, but
107  * this order has a direct effect on the outcome of the <code>SQL</code> JOIN.
108  * <p>
109  * This assertion applies in exactly the same manner when column names are used 
110  * rather than column indexes to indicate match columns.
111  *
112  * @see JoinRowSet
113  * @author  Jonathan Bruce
114  */
115 public interface Joinable {
116     
117     /** 
118      * Sets the designated column as the match column for this <code>RowSet</code>
119      * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
120      * object based on the match column.
121      * <p>
122      * Sub-interfaces such as the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
123      * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows
124      * primary key semantics to be enforced on specific columns.
125      * Implementations of the <code>setMatchColumn(int columnIdx)</code> method
126      * should ensure that the constraints on the key columns are maintained when 
127      * a <code>CachedRowSet</code> object sets a primary key column as a match column.
128      *
129      * @param columnIdx an <code>int</code> identifying the index of the column to be
130      *        set as the match column
131      * @throws SQLException if an invalid column index is set
132      * @see #setMatchColumn(int[])
133      * @see #unsetMatchColumn(int)
134      *
135      */
136     public void setMatchColumn(int columnIdx) throws SQLException  ;
137     
138     /**
139      * Sets the designated columns as the match column for this <code>RowSet</code>
140      * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
141      * object based on the match column.
142      *
143      * @param columnIdxes an array of <code>int</code> identifying the indexes of the 
144      *      columns to be set as the match columns
145      * @throws SQLException if an invalid column index is set
146      * @see #setMatchColumn(int[])
147      * @see #unsetMatchColumn(int[])     
148      */
149     public void setMatchColumn(int[] columnIdxes) throws SQLException  ;
150     
151     /** 
152      * Sets the designated column as the match column for this <code>RowSet</code>
153      * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
154      * object based on the match column.
155      * <p>
156      * Subinterfaces such as the <code>CachedRowSet</code> interface define
157      * the method <code>CachedRowSet.setKeyColumns</code>, which allows
158      * primary key semantics to be enforced on specific columns.
159      * Implementations of the <code>setMatchColumn(String columnIdx)</code> method
160      * should ensure that the constraints on the key columns are maintained when 
161      * a <code>CachedRowSet</code> object sets a primary key column as a match column.
162      *
163      * @param columnName a <code>String</code> object giving the name of the column
164      *      to be set as the match column
165      * @throws SQLException if an invalid column name is set, the column name
166      *      is a null, or the column name is an empty string
167      * @see #unsetMatchColumn
168      * @see #setMatchColumn(int[])
169      */
170     public void setMatchColumn(String   columnName) throws SQLException  ;
171     
172     /**
173      * Sets the designated columns as the match column for this <code>RowSet</code>
174      * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
175      * object based on the match column.
176      *
177      * @param columnNames an array of <code>String</code> objects giving the names 
178      *     of the column to be set as the match columns
179      * @throws SQLException if an invalid column name is set, the column name
180      *      is a null, or the column name is an empty string
181      * @see #unsetMatchColumn
182      * @see #setMatchColumn(int[])
183      */
184     public void setMatchColumn(String  [] columnNames) throws SQLException  ;
185     
186     /** 
187      * Retrieves the indexes of the match columns that were set for this
188      * <code>RowSet</code> object with the method
189      * <code>setMatchColumn(int[] columnIdxes)</code>.
190      *
191      * @return an <code>int</code> array identifying the indexes of the columns
192      *         that were set as the match columns for this <code>RowSet</code> object
193      * @throws SQLException if no match column has been set
194      * @see #setMatchColumn
195      * @see #unsetMatchColumn     
196      */
197     public int[] getMatchColumnIndexes() throws SQLException  ;
198     
199     /** 
200      * Retrieves the names of the match columns that were set for this
201      * <code>RowSet</code> object with the method
202      * <code>setMatchColumn(String [] columnNames)</code>.
203      *
204      * @return an array of <code>String</code> objects giving the names of the columns
205      *         set as the match columns for this <code>RowSet</code> object
206      * @throws SQLException if no match column has been set
207      * @see #setMatchColumn
208      * @see #unsetMatchColumn
209      *
210      */
211     public String  [] getMatchColumnNames() throws SQLException  ;
212     
213     /** 
214      * Unsets the designated column as the match column for this <code>RowSet</code>
215      * object.
216      * <P>
217      * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
218      * must ensure that a key-like constraint continues to be enforced until the
219      * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
220      * designated column.
221      *
222      * @param columnIdx an <code>int</code> that identifies the index of the column
223      *          that is to be unset as a match column
224      * @throws SQLException if an invalid column index is designated or if
225      *          the designated column was not previously set as a match
226      *          column
227      * @see #setMatchColumn     
228      */
229     public void unsetMatchColumn(int columnIdx) throws SQLException  ;
230     
231     /**
232      * Unsets the designated columns as the match column for this <code>RowSet</code>
233      * object.
234      *
235      * @param columnIdxes an arrary of <code>int</code> that identifies the indexes
236      *     of the columns that are to be unset as match columns
237      * @throws SQLException if an invalid column index is designated or if
238      *          the designated column was not previously set as a match
239      *          column
240      * @see #setMatchColumn       
241      */
242     public void unsetMatchColumn(int[] columnIdxes) throws SQLException  ;
243     
244     /** 
245      * Unsets the designated column as the match column for this <code>RowSet</code>
246      * object.
247      * <P>
248      * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
249      * must ensure that a key-like constraint continues to be enforced until the
250      * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
251      * designated column.
252      *
253      * @param columnName a <code>String</code> object giving the name of the column
254      *          that is to be unset as a match column
255      * @throws SQLException if an invalid column name is designated or
256      *          the designated column was not previously set as a match
257      *          column
258      * @see #setMatchColumn          
259      */
260     public void unsetMatchColumn(String   columnName) throws SQLException  ;
261     
262     /**
263      * Unsets the designated columns as the match columns for this <code>RowSet</code>
264      * object.
265      *      
266      * @param columnName an array of <code>String</code> objects giving the names of 
267      *     the columns that are to be unset as the match columns
268      * @throws SQLException if an invalid column name is designated or the 
269      *     designated column was not previously set as a match column
270      * @see #setMatchColumn  
271      */
272     public void unsetMatchColumn(String  [] columnName) throws SQLException  ;     
273 }
274
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags