API Overview API Index Package Overview Direct link to this page
JDK 1.6
  javax.sql.rowset. Joinable View Javadoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

/*
 * @(#)Joinable.java	1.6 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.sql.rowset;

import java.sql.SQLException;

/**
 * <h3>1.0 Background</h3>
 * The <code>Joinable</code> interface provides the methods for getting and
 * setting a match column, which is the basis for forming the SQL <code>JOIN</code>
 * formed by adding <code>RowSet</code> objects to a <code>JoinRowSet</code>
 * object.
 * <P>
 * Any standard <code>RowSet</code> implementation <b>may</b> implement 
 * the <code>Joinable</code> interface in order to be
 * added to a <code>JoinRowSet</code> object. Implementing this interface gives
 * a <code>RowSet</code> object the ability to use <code>Joinable</code> methods,
 * which set, retrieve, and get information about match columns.  An
 * application may add a
 * <code>RowSet</code> object that has not implemented the <code>Joinable</code>
 * interface to a <code>JoinRowSet</code> object, but to do so it must use one
 * of the <code>JoinRowSet.addRowSet</code> methods that takes both a
 * <code>RowSet</code> object and a match column or an array of <code>RowSet</code>
 * objects and an array of match columns. 
 * <P>
 * To get access to the methods in the <code>Joinable</code> interface, a
 * <code>RowSet</code> object implements at least one of the
 * five standard <code>RowSet</code> interfaces and also implements the 
 * <code>Joinable</code> interface.  In addition, most <code>RowSet</code>
 * objects extend the <code>BaseRowSet</code> class.  For example:
 * <pre>
 *     class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable {
 *         :
 *         :
 *     }
 * </pre>
 * <P>
 * <h3>2.0 Usage Guidelines</h3>
 * <P>
 * The methods in the <code>Joinable</code> interface allow a <code>RowSet</code> object 
 * to set a match column, retrieve a match column, or unset a match column, which is
 * the column upon which an SQL <code>JOIN</code> can be based.
 * An instance of a class that implements these methods can be added to a 
 * <code>JoinRowSet</code> object to allow an SQL <code>JOIN</code> relationship to
 *  be established.
 * <p>
 * <pre>
 *     CachedRowSet crs = new MyRowSetImpl();
 *     crs.populate((ResultSet)rs);
 *     (Joinable)crs.setMatchColumnIndex(1);
 *
 *     JoinRowSet jrs = new JoinRowSetImpl();
 *     jrs.addRowSet(crs);
 * </pre>
 * In the previous example, <i>crs</i> is a <code>CachedRowSet</code> object that
 * has emplemented the <code>Joinable</code> interface.  In the following example,
 * <i>crs2</i> has not, so it must supply the match column as an argument to the
 * <code>addRowSet</code> method. This example assumes that column 1 is the match
 * column.
 * <PRE>
 *     CachedRowSet crs2 = new MyRowSetImpl();
 *     crs2.populate((ResultSet)rs);
 *     
 *     JoinRowSet jrs2 = new JoinRowSetImpl();
 *     jrs2.addRowSet(crs2, 1);
 * </PRE>
 * <p>
 * The <code>JoinRowSet</code> interface makes it possible to get data from one or
 * more <code>RowSet</code> objects consolidated into one table without having to incur 
 * the expense of creating a connection to a database. It is therefore ideally suited
 * for use by disconnected <code>RowSet</code> objects. Nevertheless, any
 * <code>RowSet</code> object <b>may</b> implement this interface
 * regardless of whether it is connected or disconnected. Note that a
 * <code>JdbcRowSet</code> object, being always connected to its data source, can
 * become part of an SQL <code>JOIN</code> directly without having to become part
 * of a <code>JoinRowSet</code> object. 
 * <P>
 * <h3>3.0 Managing Multiple Match Columns</h3>
 * The index array passed into the <code>setMatchColumn</code> methods indicates 
 * how many match columns are being set (the length of the array) in addition to
 * which columns will be used for the match. For example:
 * <pre>
 *     int[] i = {1, 2, 4, 7}; // indicates four match columns, with column
 *                             // indexes 1, 2, 4, 7 participating in the JOIN.
 *     Joinable.setMatchColumn(i);
 * </pre>
 * Subsequent match columns may be added as follows to a different <code>Joinable</code>
 * object (a <code>RowSet</code> object that has implemented the <code>Joinable</code>
 * interface).
 * <pre>
 *     int[] w = {3, 2, 5, 3};
 *     Joinable2.setMatchColumn(w);
 * </pre>
 * When an application adds two or more <code>RowSet</code> objects to a
 * <code>JoinRowSet</code> object, the order of the indexes in the array is 
 * particularly important. Each index of 
 * the array maps directly to the corresponding index of the previously added 
 * <code>RowSet</code> object. If overlap or underlap occurs, the match column 
 * data is maintained in the event an additional <code>Joinable</code> RowSet is
 * added and needs to relate to the match column data. Therefore, applications 
 * can set multiple match columns in any order, but
 * this order has a direct effect on the outcome of the <code>SQL</code> JOIN.
 * <p>
 * This assertion applies in exactly the same manner when column names are used 
 * rather than column indexes to indicate match columns.
 *
 * @see JoinRowSet
 * @author  Jonathan Bruce
 */
public interface Joinable {
    
    /** 
     * Sets the designated column as the match column for this <code>RowSet</code>
     * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
     * object based on the match column.
     * <p>
     * Sub-interfaces such as the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
     * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows
     * primary key semantics to be enforced on specific columns.
     * Implementations of the <code>setMatchColumn(int columnIdx)</code> method
     * should ensure that the constraints on the key columns are maintained when 
     * a <code>CachedRowSet</code> object sets a primary key column as a match column.
     *
     * @param columnIdx an <code>int</code> identifying the index of the column to be
     *        set as the match column
     * @throws SQLException if an invalid column index is set
     * @see #setMatchColumn(int[])
     * @see #unsetMatchColumn(int)
     *
     */
    public void setMatchColumn(int columnIdx) throws SQLException;
    
    /**
     * Sets the designated columns as the match column for this <code>RowSet</code>
     * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
     * object based on the match column.
     *
     * @param columnIdxes an array of <code>int</code> identifying the indexes of the 
     *      columns to be set as the match columns
     * @throws SQLException if an invalid column index is set
     * @see #setMatchColumn(int[])
     * @see #unsetMatchColumn(int[])     
     */
    public void setMatchColumn(int[] columnIdxes) throws SQLException;
    
    /** 
     * Sets the designated column as the match column for this <code>RowSet</code>
     * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
     * object based on the match column.
     * <p>
     * Subinterfaces such as the <code>CachedRowSet</code> interface define
     * the method <code>CachedRowSet.setKeyColumns</code>, which allows
     * primary key semantics to be enforced on specific columns.
     * Implementations of the <code>setMatchColumn(String columnIdx)</code> method
     * should ensure that the constraints on the key columns are maintained when 
     * a <code>CachedRowSet</code> object sets a primary key column as a match column.
     *
     * @param columnName a <code>String</code> object giving the name of the column
     *      to be set as the match column
     * @throws SQLException if an invalid column name is set, the column name
     *      is a null, or the column name is an empty string
     * @see #unsetMatchColumn
     * @see #setMatchColumn(int[])
     */
    public void setMatchColumn(String columnName) throws SQLException;
    
    /**
     * Sets the designated columns as the match column for this <code>RowSet</code>
     * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
     * object based on the match column.
     *
     * @param columnNames an array of <code>String</code> objects giving the names 
     *     of the column to be set as the match columns
     * @throws SQLException if an invalid column name is set, the column name
     *      is a null, or the column name is an empty string
     * @see #unsetMatchColumn
     * @see #setMatchColumn(int[])
     */
    public void setMatchColumn(String[] columnNames) throws SQLException;
    
    /** 
     * Retrieves the indexes of the match columns that were set for this
     * <code>RowSet</code> object with the method
     * <code>setMatchColumn(int[] columnIdxes)</code>.
     *
     * @return an <code>int</code> array identifying the indexes of the columns
     *         that were set as the match columns for this <code>RowSet</code> object
     * @throws SQLException if no match column has been set
     * @see #setMatchColumn
     * @see #unsetMatchColumn     
     */
    public int[] getMatchColumnIndexes() throws SQLException;
    
    /** 
     * Retrieves the names of the match columns that were set for this
     * <code>RowSet</code> object with the method
     * <code>setMatchColumn(String [] columnNames)</code>.
     *
     * @return an array of <code>String</code> objects giving the names of the columns
     *         set as the match columns for this <code>RowSet</code> object
     * @throws SQLException if no match column has been set
     * @see #setMatchColumn
     * @see #unsetMatchColumn
     *
     */
    public String[] getMatchColumnNames() throws SQLException;
    
    /** 
     * Unsets the designated column as the match column for this <code>RowSet</code>
     * object.
     * <P>
     * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
     * must ensure that a key-like constraint continues to be enforced until the
     * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
     * designated column.
     *
     * @param columnIdx an <code>int</code> that identifies the index of the column
     *          that is to be unset as a match column
     * @throws SQLException if an invalid column index is designated or if
     *          the designated column was not previously set as a match
     *          column
     * @see #setMatchColumn     
     */
    public void unsetMatchColumn(int columnIdx) throws SQLException;
    
    /**
     * Unsets the designated columns as the match column for this <code>RowSet</code>
     * object.
     *
     * @param columnIdxes an arrary of <code>int</code> that identifies the indexes
     *     of the columns that are to be unset as match columns
     * @throws SQLException if an invalid column index is designated or if
     *          the designated column was not previously set as a match
     *          column
     * @see #setMatchColumn       
     */
    public void unsetMatchColumn(int[] columnIdxes) throws SQLException;
    
    /** 
     * Unsets the designated column as the match column for this <code>RowSet</code>
     * object.
     * <P>
     * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
     * must ensure that a key-like constraint continues to be enforced until the
     * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
     * designated column.
     *
     * @param columnName a <code>String</code> object giving the name of the column
     *          that is to be unset as a match column
     * @throws SQLException if an invalid column name is designated or
     *          the designated column was not previously set as a match
     *          column
     * @see #setMatchColumn          
     */
    public void unsetMatchColumn(String columnName) throws SQLException;
    
    /**
     * Unsets the designated columns as the match columns for this <code>RowSet</code>
     * object.
     *      
     * @param columnName an array of <code>String</code> objects giving the names of 
     *     the columns that are to be unset as the match columns
     * @throws SQLException if an invalid column name is designated or the 
     *     designated column was not previously set as a match column
     * @see #setMatchColumn  
     */
    public void unsetMatchColumn(String[] columnName) throws SQLException;     
}

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar