2362N/A * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * <h3>1.0 Background</h3> 0N/A * The <code>Joinable</code> interface provides the methods for getting and 0N/A * setting a match column, which is the basis for forming the SQL <code>JOIN</code> 0N/A * formed by adding <code>RowSet</code> objects to a <code>JoinRowSet</code> 0N/A * Any standard <code>RowSet</code> implementation <b>may</b> implement 0N/A * the <code>Joinable</code> interface in order to be 0N/A * added to a <code>JoinRowSet</code> object. Implementing this interface gives 0N/A * a <code>RowSet</code> object the ability to use <code>Joinable</code> methods, 0N/A * which set, retrieve, and get information about match columns. An 0N/A * application may add a 0N/A * <code>RowSet</code> object that has not implemented the <code>Joinable</code> 0N/A * interface to a <code>JoinRowSet</code> object, but to do so it must use one 0N/A * of the <code>JoinRowSet.addRowSet</code> methods that takes both a 0N/A * <code>RowSet</code> object and a match column or an array of <code>RowSet</code> 0N/A * objects and an array of match columns. 0N/A * To get access to the methods in the <code>Joinable</code> interface, a 0N/A * <code>RowSet</code> object implements at least one of the 0N/A * five standard <code>RowSet</code> interfaces and also implements the 0N/A * <code>Joinable</code> interface. In addition, most <code>RowSet</code> 0N/A * objects extend the <code>BaseRowSet</code> class. For example: 0N/A * class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable { 0N/A * <h3>2.0 Usage Guidelines</h3> 0N/A * The methods in the <code>Joinable</code> interface allow a <code>RowSet</code> object 0N/A * to set a match column, retrieve a match column, or unset a match column, which is 0N/A * the column upon which an SQL <code>JOIN</code> can be based. 0N/A * An instance of a class that implements these methods can be added to a 0N/A * <code>JoinRowSet</code> object to allow an SQL <code>JOIN</code> relationship to 0N/A * CachedRowSet crs = new MyRowSetImpl(); 0N/A * crs.populate((ResultSet)rs); 0N/A * (Joinable)crs.setMatchColumnIndex(1); 0N/A * JoinRowSet jrs = new JoinRowSetImpl(); 0N/A * jrs.addRowSet(crs); 0N/A * In the previous example, <i>crs</i> is a <code>CachedRowSet</code> object that 0N/A * has emplemented the <code>Joinable</code> interface. In the following example, 0N/A * <i>crs2</i> has not, so it must supply the match column as an argument to the 0N/A * <code>addRowSet</code> method. This example assumes that column 1 is the match 0N/A * CachedRowSet crs2 = new MyRowSetImpl(); 0N/A * crs2.populate((ResultSet)rs); 0N/A * JoinRowSet jrs2 = new JoinRowSetImpl(); 0N/A * jrs2.addRowSet(crs2, 1); 0N/A * The <code>JoinRowSet</code> interface makes it possible to get data from one or 0N/A * more <code>RowSet</code> objects consolidated into one table without having to incur 0N/A * the expense of creating a connection to a database. It is therefore ideally suited 0N/A * for use by disconnected <code>RowSet</code> objects. Nevertheless, any 0N/A * <code>RowSet</code> object <b>may</b> implement this interface 0N/A * regardless of whether it is connected or disconnected. Note that a 0N/A * <code>JdbcRowSet</code> object, being always connected to its data source, can 0N/A * become part of an SQL <code>JOIN</code> directly without having to become part 0N/A * of a <code>JoinRowSet</code> object. 0N/A * <h3>3.0 Managing Multiple Match Columns</h3> 0N/A * The index array passed into the <code>setMatchColumn</code> methods indicates 0N/A * how many match columns are being set (the length of the array) in addition to 0N/A * which columns will be used for the match. For example: 0N/A * int[] i = {1, 2, 4, 7}; // indicates four match columns, with column 0N/A * // indexes 1, 2, 4, 7 participating in the JOIN. 0N/A * Joinable.setMatchColumn(i); 0N/A * Subsequent match columns may be added as follows to a different <code>Joinable</code> 0N/A * object (a <code>RowSet</code> object that has implemented the <code>Joinable</code> 0N/A * int[] w = {3, 2, 5, 3}; 0N/A * Joinable2.setMatchColumn(w); 0N/A * When an application adds two or more <code>RowSet</code> objects to a 0N/A * <code>JoinRowSet</code> object, the order of the indexes in the array is 0N/A * particularly important. Each index of 0N/A * the array maps directly to the corresponding index of the previously added 0N/A * <code>RowSet</code> object. If overlap or underlap occurs, the match column 0N/A * data is maintained in the event an additional <code>Joinable</code> RowSet is 0N/A * added and needs to relate to the match column data. Therefore, applications 0N/A * can set multiple match columns in any order, but 0N/A * this order has a direct effect on the outcome of the <code>SQL</code> JOIN. 0N/A * This assertion applies in exactly the same manner when column names are used 0N/A * rather than column indexes to indicate match columns. 0N/A * @author Jonathan Bruce 0N/A * Sets the designated column as the match column for this <code>RowSet</code> 0N/A * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 0N/A * object based on the match column. 0N/A * Sub-interfaces such as the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> 0N/A * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows 0N/A * primary key semantics to be enforced on specific columns. 0N/A * Implementations of the <code>setMatchColumn(int columnIdx)</code> method 0N/A * should ensure that the constraints on the key columns are maintained when 0N/A * a <code>CachedRowSet</code> object sets a primary key column as a match column. 0N/A * @param columnIdx an <code>int</code> identifying the index of the column to be 0N/A * set as the match column 0N/A * @throws SQLException if an invalid column index is set 0N/A * @see #setMatchColumn(int[]) 0N/A * @see #unsetMatchColumn(int) 0N/A * Sets the designated columns as the match column for this <code>RowSet</code> 0N/A * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 0N/A * object based on the match column. 0N/A * @param columnIdxes an array of <code>int</code> identifying the indexes of the 0N/A * columns to be set as the match columns 0N/A * @throws SQLException if an invalid column index is set 0N/A * @see #setMatchColumn(int[]) 0N/A * @see #unsetMatchColumn(int[]) 0N/A * Sets the designated column as the match column for this <code>RowSet</code> 0N/A * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 0N/A * object based on the match column. 0N/A * Subinterfaces such as the <code>CachedRowSet</code> interface define 0N/A * the method <code>CachedRowSet.setKeyColumns</code>, which allows 0N/A * primary key semantics to be enforced on specific columns. 0N/A * Implementations of the <code>setMatchColumn(String columnIdx)</code> method 0N/A * should ensure that the constraints on the key columns are maintained when 0N/A * a <code>CachedRowSet</code> object sets a primary key column as a match column. 0N/A * @param columnName a <code>String</code> object giving the name of the column 0N/A * to be set as the match column 0N/A * @throws SQLException if an invalid column name is set, the column name 0N/A * is a null, or the column name is an empty string 0N/A * @see #unsetMatchColumn 0N/A * @see #setMatchColumn(int[]) 0N/A * Sets the designated columns as the match column for this <code>RowSet</code> 0N/A * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code> 0N/A * object based on the match column. 0N/A * @param columnNames an array of <code>String</code> objects giving the names 0N/A * of the column to be set as the match columns 0N/A * @throws SQLException if an invalid column name is set, the column name 0N/A * is a null, or the column name is an empty string 0N/A * @see #unsetMatchColumn 0N/A * @see #setMatchColumn(int[]) 0N/A * Retrieves the indexes of the match columns that were set for this 0N/A * <code>RowSet</code> object with the method 0N/A * <code>setMatchColumn(int[] columnIdxes)</code>. 0N/A * @return an <code>int</code> array identifying the indexes of the columns 0N/A * that were set as the match columns for this <code>RowSet</code> object 0N/A * @throws SQLException if no match column has been set 0N/A * @see #setMatchColumn 0N/A * @see #unsetMatchColumn 0N/A * Retrieves the names of the match columns that were set for this 0N/A * <code>RowSet</code> object with the method 0N/A * <code>setMatchColumn(String [] columnNames)</code>. 0N/A * @return an array of <code>String</code> objects giving the names of the columns 0N/A * set as the match columns for this <code>RowSet</code> object 0N/A * @throws SQLException if no match column has been set 0N/A * @see #setMatchColumn 0N/A * @see #unsetMatchColumn 0N/A * Unsets the designated column as the match column for this <code>RowSet</code> 0N/A * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 0N/A * must ensure that a key-like constraint continues to be enforced until the 0N/A * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 0N/A * designated column. 0N/A * @param columnIdx an <code>int</code> that identifies the index of the column 0N/A * that is to be unset as a match column 0N/A * @throws SQLException if an invalid column index is designated or if 0N/A * the designated column was not previously set as a match 0N/A * @see #setMatchColumn 0N/A * Unsets the designated columns as the match column for this <code>RowSet</code> 0N/A * @param columnIdxes an arrary of <code>int</code> that identifies the indexes 0N/A * of the columns that are to be unset as match columns 0N/A * @throws SQLException if an invalid column index is designated or if 0N/A * the designated column was not previously set as a match 0N/A * @see #setMatchColumn 0N/A * Unsets the designated column as the match column for this <code>RowSet</code> 0N/A * <code>RowSet</code> objects that implement the <code>Joinable</code> interface 0N/A * must ensure that a key-like constraint continues to be enforced until the 0N/A * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the 0N/A * designated column. 0N/A * @param columnName a <code>String</code> object giving the name of the column 0N/A * that is to be unset as a match column 0N/A * @throws SQLException if an invalid column name is designated or 0N/A * the designated column was not previously set as a match 0N/A * @see #setMatchColumn 0N/A * Unsets the designated columns as the match columns for this <code>RowSet</code> 0N/A * @param columnName an array of <code>String</code> objects giving the names of 0N/A * the columns that are to be unset as the match columns 0N/A * @throws SQLException if an invalid column name is designated or the 0N/A * designated column was not previously set as a match column 0N/A * @see #setMatchColumn