1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sql.rowset; 27 28 import java.sql.SQLException; 29 30 /** 31 * <h3>1.0 Background</h3> 32 * The <code>Joinable</code> interface provides the methods for getting and 33 * setting a match column, which is the basis for forming the SQL <code>JOIN</code> 34 * formed by adding <code>RowSet</code> objects to a <code>JoinRowSet</code> 35 * object. 36 * <P> 37 * Any standard <code>RowSet</code> implementation <b>may</b> implement 38 * the <code>Joinable</code> interface in order to be 39 * added to a <code>JoinRowSet</code> object. Implementing this interface gives 40 * a <code>RowSet</code> object the ability to use <code>Joinable</code> methods, 41 * which set, retrieve, and get information about match columns. An 42 * application may add a 43 * <code>RowSet</code> object that has not implemented the <code>Joinable</code> 44 * interface to a <code>JoinRowSet</code> object, but to do so it must use one 45 * of the <code>JoinRowSet.addRowSet</code> methods that takes both a 46 * <code>RowSet</code> object and a match column or an array of <code>RowSet</code> 47 * objects and an array of match columns. 48 * <P> 49 * To get access to the methods in the <code>Joinable</code> interface, a 50 * <code>RowSet</code> object implements at least one of the 51 * five standard <code>RowSet</code> interfaces and also implements the 52 * <code>Joinable</code> interface. In addition, most <code>RowSet</code> 53 * objects extend the <code>BaseRowSet</code> class. For example: 54 * <pre> 55 * class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable { 56 * : 57 * : 58 * } 59 * </pre> 60 * <P> 61 * <h3>2.0 Usage Guidelines</h3> 62 * <P> 63 * The methods in the <code>Joinable</code> interface allow a <code>RowSet</code> object 64 * to set a match column, retrieve a match column, or unset a match column, which is 65 * the column upon which an SQL <code>JOIN</code> can be based. 66 * An instance of a class that implements these methods can be added to a 67 * <code>JoinRowSet</code> object to allow an SQL <code>JOIN</code> relationship to 68 * be established. 69 * <p> 70 * <pre> 71 * CachedRowSet crs = new MyRowSetImpl(); 72 * crs.populate((ResultSet)rs); 73 * (Joinable)crs.setMatchColumnIndex(1); 74 * 75 * JoinRowSet jrs = new JoinRowSetImpl(); 76 * jrs.addRowSet(crs); 77 * </pre> 78 * In the previous example, <i>crs</i> is a <code>CachedRowSet</code> object that 79 * has emplemented the <code>Joinable</code> interface. In the following example, 80 * <i>crs2</i> has not, so it must supply the match column as an argument to the 81 * <code>addRowSet</code> method. This example assumes that column 1 is the match 82 * column. 83 * <PRE> 84 * CachedRowSet crs2 = new MyRowSetImpl(); 85 * crs2.populate((ResultSet)rs); 86 * 87 * JoinRowSet jrs2 = new JoinRowSetImpl(); 88 * jrs2.addRowSet(crs2, 1); 89 * </PRE> 90 * <p> 91 * The <code>JoinRowSet</code> interface makes it possible to get data from one or 92 * more <code>RowSet</code> objects consolidated into one table without having to incur 93 * the expense of creating a connection to a database. It is therefore ideally suited 94 * for use by disconnected <code>RowSet</code> objects. Nevertheless, any 95 * <code>RowSet</code> object <b>may</b> implement this interface 96 * regardless of whether it is connected or disconnected. Note that a 97 * <code>JdbcRowSet</code> object, being always connected to its data source, can 98 * become part of an SQL <code>JOIN</code> directly without having to become part 99 * of a <code>JoinRowSet</code> object. 100 * <P> 101 * <h3>3.0 Managing Multiple Match Columns</h3> 102 * The index array passed into the <code>setMatchColumn</code> methods indicates 103 * how many match columns are being set (the length of the array) in addition to 104 * which columns will be used for the match. For example: 105 * <pre> 106 * int[] i = {1, 2, 4, 7}; // indicates four match columns, with column 107 * // indexes 1, 2, 4, 7 participating in the JOIN. 108 * Joinable.setMatchColumn(i); 109 * </pre> 110 * Subsequent match columns may be added as follows to a different <code>Joinable</code> 111 * object (a <code>RowSet</code> object that has implemented the <code>Joinable</code> 112 * interface). 113 * <pre> 114 * int[] w = {3, 2, 5, 3}; 115 * Joinable2.setMatchColumn(w); 116 * </pre> 117 * When an application adds two or more <code>RowSet</code> objects to a 118 * <code>JoinRowSet</code> object, the order of the indexes in the array is 119 * particularly important. Each index of 120 * the array maps directly to the corresponding index of the previously added 121 * <code>RowSet</code> object. If overlap or underlap occurs, the match column 122 * data is maintained in the event an additional <code>Joinable</code> RowSet is 123 * added and needs to relate to the match column data. Therefore, applications 124 * can set multiple match columns in any order, but 125 * this order has a direct effect on the outcome of the <code>SQL</code> JOIN. 126 * <p> 127 * This assertion applies in exactly the same manner when column names are used 128 * rather than column indexes to indicate match columns. 129 * 130 * @see JoinRowSet 131 * @author Jonathan Bruce 132 */ 133 public interface Joinable { 134 135 /** 136 * Sets the designated column as the match column for this <code>RowSet</code> 137 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 138 * object based on the match column. 139 * <p> 140 * Sub-interfaces such as the <code>CachedRowSet</code>™ 141 * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows 142 * primary key semantics to be enforced on specific columns. 143 * Implementations of the <code>setMatchColumn(int columnIdx)</code> method 144 * should ensure that the constraints on the key columns are maintained when 145 * a <code>CachedRowSet</code> object sets a primary key column as a match column. 146 * 147 * @param columnIdx an <code>int</code> identifying the index of the column to be 148 * set as the match column 149 * @throws SQLException if an invalid column index is set 150 * @see #setMatchColumn(int[]) 151 * @see #unsetMatchColumn(int) 152 * 153 */ 154 public void setMatchColumn(int columnIdx) throws SQLException; 155 156 /** 157 * Sets the designated columns as the match column for this <code>RowSet</code> 158 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 159 * object based on the match column. 160 * 161 * @param columnIdxes an array of <code>int</code> identifying the indexes of the 162 * columns to be set as the match columns 163 * @throws SQLException if an invalid column index is set 164 * @see #setMatchColumn(int[]) 165 * @see #unsetMatchColumn(int[]) 166 */ 167 public void setMatchColumn(int[] columnIdxes) throws SQLException; 168 169 /** 170 * Sets the designated column as the match column for this <code>RowSet</code> 171 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 172 * object based on the match column. 173 * <p> 174 * Subinterfaces such as the <code>CachedRowSet</code> interface define 175 * the method <code>CachedRowSet.setKeyColumns</code>, which allows 176 * primary key semantics to be enforced on specific columns. 177 * Implementations of the <code>setMatchColumn(String columnIdx)</code> method 178 * should ensure that the constraints on the key columns are maintained when 179 * a <code>CachedRowSet</code> object sets a primary key column as a match column. 180 * 181 * @param columnName a <code>String</code> object giving the name of the column 182 * to be set as the match column 183 * @throws SQLException if an invalid column name is set, the column name 184 * is a null, or the column name is an empty string 185 * @see #unsetMatchColumn 186 * @see #setMatchColumn(int[]) 187 */ 188 public void setMatchColumn(String columnName) throws SQLException; 189 190 /** 191 * Sets the designated columns as the match column for this <code>RowSet</code> 192 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 193 * object based on the match column. 194 * 195 * @param columnNames an array of <code>String</code> objects giving the names 196 * of the column to be set as the match columns 197 * @throws SQLException if an invalid column name is set, the column name 198 * is a null, or the column name is an empty string 199 * @see #unsetMatchColumn 200 * @see #setMatchColumn(int[]) 201 */ 202 public void setMatchColumn(String[] columnNames) throws SQLException; 203 204 /** 205 * Retrieves the indexes of the match columns that were set for this 206 * <code>RowSet</code> object with the method 207 * <code>setMatchColumn(int[] columnIdxes)</code>. 208 * 209 * @return an <code>int</code> array identifying the indexes of the columns 210 * that were set as the match columns for this <code>RowSet</code> object 211 * @throws SQLException if no match column has been set 212 * @see #setMatchColumn 213 * @see #unsetMatchColumn 214 */ 215 public int[] getMatchColumnIndexes() throws SQLException; 216 217 /** 218 * Retrieves the names of the match columns that were set for this 219 * <code>RowSet</code> object with the method 220 * <code>setMatchColumn(String [] columnNames)</code>. 221 * 222 * @return an array of <code>String</code> objects giving the names of the columns 223 * set as the match columns for this <code>RowSet</code> object 224 * @throws SQLException if no match column has been set 225 * @see #setMatchColumn 226 * @see #unsetMatchColumn 227 * 228 */ 229 public String[] getMatchColumnNames() throws SQLException; 230 231 /** 232 * Unsets the designated column as the match column for this <code>RowSet</code> 233 * object. 234 * <P> 235 * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 236 * must ensure that a key-like constraint continues to be enforced until the 237 * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 238 * designated column. 239 * 240 * @param columnIdx an <code>int</code> that identifies the index of the column 241 * that is to be unset as a match column 242 * @throws SQLException if an invalid column index is designated or if 243 * the designated column was not previously set as a match 244 * column 245 * @see #setMatchColumn 246 */ 247 public void unsetMatchColumn(int columnIdx) throws SQLException; 248 249 /** 250 * Unsets the designated columns as the match column for this <code>RowSet</code> 251 * object. 252 * 253 * @param columnIdxes an arrary of <code>int</code> that identifies the indexes 254 * of the columns that are to be unset as match columns 255 * @throws SQLException if an invalid column index is designated or if 256 * the designated column was not previously set as a match 257 * column 258 * @see #setMatchColumn 259 */ 260 public void unsetMatchColumn(int[] columnIdxes) throws SQLException; 261 262 /** 263 * Unsets the designated column as the match column for this <code>RowSet</code> 264 * object. 265 * <P> 266 * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 267 * must ensure that a key-like constraint continues to be enforced until the 268 * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 269 * designated column. 270 * 271 * @param columnName a <code>String</code> object giving the name of the column 272 * that is to be unset as a match column 273 * @throws SQLException if an invalid column name is designated or 274 * the designated column was not previously set as a match 275 * column 276 * @see #setMatchColumn 277 */ 278 public void unsetMatchColumn(String columnName) throws SQLException; 279 280 /** 281 * Unsets the designated columns as the match columns for this <code>RowSet</code> 282 * object. 283 * 284 * @param columnName an array of <code>String</code> objects giving the names of 285 * the columns that are to be unset as the match columns 286 * @throws SQLException if an invalid column name is designated or the 287 * designated column was not previously set as a match column 288 * @see #setMatchColumn 289 */ 290 public void unsetMatchColumn(String[] columnName) throws SQLException; 291 }