1 /* 2 * Copyright (c) 2003, 2019, 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 * <h2>1.0 Background</h2> 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 * 61 * <h2>2.0 Usage Guidelines</h2> 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 * 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 implemented 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 * 101 * <h2>3.0 Managing Multiple Match Columns</h2> 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 * @since 1.5 133 */ 134 public interface Joinable { 135 136 /** 137 * Sets the designated column as the match column for this <code>RowSet</code> 138 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 139 * object based on the match column. 140 * <p> 141 * Sub-interfaces such as the <code>CachedRowSet</code> 142 * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows 143 * primary key semantics to be enforced on specific columns. 144 * Implementations of the <code>setMatchColumn(int columnIdx)</code> method 145 * should ensure that the constraints on the key columns are maintained when 146 * a <code>CachedRowSet</code> object sets a primary key column as a match column. 147 * 148 * @param columnIdx an <code>int</code> identifying the index of the column to be 149 * set as the match column 150 * @throws SQLException if an invalid column index is set 151 * @see #setMatchColumn(int[]) 152 * @see #unsetMatchColumn(int) 153 * 154 */ 155 public void setMatchColumn(int columnIdx) throws SQLException; 156 157 /** 158 * Sets the designated columns as the match column for this <code>RowSet</code> 159 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 160 * object based on the match column. 161 * 162 * @param columnIdxes an array of <code>int</code> identifying the indexes of the 163 * columns to be set as the match columns 164 * @throws SQLException if an invalid column index is set 165 * @see #setMatchColumn(int[]) 166 * @see #unsetMatchColumn(int[]) 167 */ 168 public void setMatchColumn(int[] columnIdxes) throws SQLException; 169 170 /** 171 * Sets the designated column as the match column for this <code>RowSet</code> 172 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 173 * object based on the match column. 174 * <p> 175 * Subinterfaces such as the <code>CachedRowSet</code> interface define 176 * the method <code>CachedRowSet.setKeyColumns</code>, which allows 177 * primary key semantics to be enforced on specific columns. 178 * Implementations of the <code>setMatchColumn(String columnIdx)</code> method 179 * should ensure that the constraints on the key columns are maintained when 180 * a <code>CachedRowSet</code> object sets a primary key column as a match column. 181 * 182 * @param columnName a <code>String</code> object giving the name of the column 183 * to be set as the match column 184 * @throws SQLException if an invalid column name is set, the column name 185 * is a null, or the column name is an empty string 186 * @see #unsetMatchColumn 187 * @see #setMatchColumn(int[]) 188 */ 189 public void setMatchColumn(String columnName) throws SQLException; 190 191 /** 192 * Sets the designated columns as the match column for this <code>RowSet</code> 193 * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 194 * object based on the match column. 195 * 196 * @param columnNames an array of <code>String</code> objects giving the names 197 * of the column to be set as the match columns 198 * @throws SQLException if an invalid column name is set, the column name 199 * is a null, or the column name is an empty string 200 * @see #unsetMatchColumn 201 * @see #setMatchColumn(int[]) 202 */ 203 public void setMatchColumn(String[] columnNames) throws SQLException; 204 205 /** 206 * Retrieves the indexes of the match columns that were set for this 207 * <code>RowSet</code> object with the method 208 * <code>setMatchColumn(int[] columnIdxes)</code>. 209 * 210 * @return an <code>int</code> array identifying the indexes of the columns 211 * that were set as the match columns for this <code>RowSet</code> object 212 * @throws SQLException if no match column has been set 213 * @see #setMatchColumn 214 * @see #unsetMatchColumn 215 */ 216 public int[] getMatchColumnIndexes() throws SQLException; 217 218 /** 219 * Retrieves the names of the match columns that were set for this 220 * <code>RowSet</code> object with the method 221 * <code>setMatchColumn(String [] columnNames)</code>. 222 * 223 * @return an array of <code>String</code> objects giving the names of the columns 224 * set as the match columns for this <code>RowSet</code> object 225 * @throws SQLException if no match column has been set 226 * @see #setMatchColumn 227 * @see #unsetMatchColumn 228 * 229 */ 230 public String[] getMatchColumnNames() throws SQLException; 231 232 /** 233 * Unsets the designated column as the match column for this <code>RowSet</code> 234 * object. 235 * <P> 236 * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 237 * must ensure that a key-like constraint continues to be enforced until the 238 * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 239 * designated column. 240 * 241 * @param columnIdx an <code>int</code> that identifies the index of the column 242 * that is to be unset as a match column 243 * @throws SQLException if an invalid column index is designated or if 244 * the designated column was not previously set as a match 245 * column 246 * @see #setMatchColumn 247 */ 248 public void unsetMatchColumn(int columnIdx) throws SQLException; 249 250 /** 251 * Unsets the designated columns as the match column for this <code>RowSet</code> 252 * object. 253 * 254 * @param columnIdxes an array of <code>int</code> that identifies the indexes 255 * of the columns that are to be unset as match columns 256 * @throws SQLException if an invalid column index is designated or if 257 * the designated column was not previously set as a match 258 * column 259 * @see #setMatchColumn 260 */ 261 public void unsetMatchColumn(int[] columnIdxes) throws SQLException; 262 263 /** 264 * Unsets the designated column as the match column for this <code>RowSet</code> 265 * object. 266 * <P> 267 * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 268 * must ensure that a key-like constraint continues to be enforced until the 269 * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 270 * designated column. 271 * 272 * @param columnName a <code>String</code> object giving the name of the column 273 * that is to be unset as a match column 274 * @throws SQLException if an invalid column name is designated or 275 * the designated column was not previously set as a match 276 * column 277 * @see #setMatchColumn 278 */ 279 public void unsetMatchColumn(String columnName) throws SQLException; 280 281 /** 282 * Unsets the designated columns as the match columns for this <code>RowSet</code> 283 * object. 284 * 285 * @param columnName an array of <code>String</code> objects giving the names of 286 * the columns that are to be unset as the match columns 287 * @throws SQLException if an invalid column name is designated or the 288 * designated column was not previously set as a match column 289 * @see #setMatchColumn 290 */ 291 public void unsetMatchColumn(String[] columnName) throws SQLException; 292 }