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 * The <code>JoinRowSet</code> interface provides a mechanism for combining related 0N/A * data from different <code>RowSet</code> objects into one <code>JoinRowSet</code> 0N/A * object, which represents an SQL <code>JOIN</code>. 0N/A * In other words, a <code>JoinRowSet</code> object acts as a 0N/A * container for the data from <code>RowSet</code> objects that form an SQL 0N/A * <code>JOIN</code> relationship. 0N/A * The <code>Joinable</code> interface provides the methods for setting, 0N/A * retrieving, and unsetting a match column, the basis for 0N/A * establishing an SQL <code>JOIN</code> relationship. The match column may 0N/A * alternatively be set by supplying it to the appropriate version of the 0N/A * <code>JointRowSet</code> method <code>addRowSet</code>. 0N/A * <h3>1.0 Overview</h3> 0N/A * Disconnected <code>RowSet</code> objects (<code>CachedRowSet</code> objects 0N/A * and implementations extending the <code>CachedRowSet</code> interface) 0N/A * do not have a standard way to establish an SQL <code>JOIN</code> between 0N/A * <code>RowSet</code> objects without the expensive operation of 0N/A * reconnecting to the data source. The <code>JoinRowSet</code> 0N/A * interface is specifically designed to address this need. 0N/A * Any <code>RowSet</code> object 0N/A * can be added to a <code>JoinRowSet</code> object to become 0N/A * part of an SQL <code>JOIN</code> relationship. This means that both connected 0N/A * and disconnected <code>RowSet</code> objects can be part of a <code>JOIN</code>. 0N/A * <code>RowSet</code> objects operating in a connected environment 0N/A * (<code>JdbcRowSet</code> objects) are 0N/A * encouraged to use the database to which they are already 0N/A * connected to establish SQL <code>JOIN</code> relationships between 0N/A * tables directly. However, it is possible for a 0N/A * <code>JdbcRowSet</code> object to be added to a <code>JoinRowSet</code> object 0N/A * Any number of <code>RowSet</code> objects can be added to an 0N/A * instance of <code>JoinRowSet</code> provided that they 0N/A * can be related in an SQL <code>JOIN</code>. 0N/A * By definition, the SQL <code>JOIN</code> statement is used to 0N/A * combine the data contained in two or more relational database tables based 0N/A * upon a common attribute. The <code>Joinable</code> interface provides the methods 0N/A * for establishing a common attribute, which is done by setting a 0N/A * <i>match column</i>. The match column commonly coincides with 0N/A * the primary key, but there is 0N/A * no requirement that the match column be the same as the primary key. 0N/A * By establishing and then enforcing column matches, 0N/A * a <code>JoinRowSet</code> object establishes <code>JOIN</code> relationships 0N/A * between <code>RowSet</code> objects without the assistance of an available 0N/A * relational database. 0N/A * The type of <code>JOIN</code> to be established is determined by setting 0N/A * one of the <code>JoinRowSet</code> constants using the method 0N/A * <code>setJoinType</code>. The following SQL <code>JOIN</code> types can be set: 0N/A * <LI><code>CROSS_JOIN</code> 0N/A * <LI><code>FULL_JOIN</code> 0N/A * <LI><code>INNER_JOIN</code> - the default if no <code>JOIN</code> type has been set 0N/A * <LI><code>LEFT_OUTER_JOIN</code> 0N/A * <LI><code>RIGHT_OUTER_JOIN</code> 0N/A * Note that if no type is set, the <code>JOIN</code> will automatically be an 0N/A * inner join. The comments for the fields in the 0N/A * <code>JoinRowSet</code> interface explain these <code>JOIN</code> types, which are 0N/A * standard SQL <code>JOIN</code> types. 0N/A * <h3>2.0 Using a <code>JoinRowSet</code> Object for Creating a <code>JOIN</code></h3> 0N/A * When a <code>JoinRowSet</code> object is created, it is empty. 0N/A * The first <code>RowSet</code> object to be added becomes the basis for the 0N/A * <code>JOIN</code> relationship. 0N/A * Applications must determine which column in each of the 0N/A * <code>RowSet</code> objects to be added to the <code>JoinRowSet</code> object 0N/A * should be the match column. All of the 0N/A * <code>RowSet</code> objects must contain a match column, and the values in 0N/A * each match column must be ones that can be compared to values in the other match 0N/A * columns. The columns do not have to have the same name, though they often do, 0N/A * and they do not have to store the exact same data type as long as the data types 0N/A * A match column can be be set in two ways: 0N/A * <li>By calling the <code>Joinable</code> method <code>setMatchColumn</code><br> 0N/A * This is the only method that can set the match column before a <code>RowSet</code> 0N/A * object is added to a <code>JoinRowSet</code> object. The <code>RowSet</code> object 0N/A * must have implemented the <code>Joinable</code> interface in order to use the method 0N/A * <code>setMatchColumn</code>. Once the match column value 0N/A * has been set, this method can be used to reset the match column at any time. 0N/A * <li>By calling one of the versions of the <code>JoinRowSet</code> method 0N/A * <code>addRowSet</code> that takes a column name or number (or an array of 0N/A * column names or numbers)<BR> 0N/A * Four of the five <code>addRowSet</code> methods take a match column as a parameter. 0N/A * These four methods set or reset the match column at the time a <code>RowSet</code> 0N/A * object is being added to a <code>JoinRowSet</code> object. 0N/A * <h3>3.0 Sample Usage</h3> 0N/A * The following code fragment adds two <code>CachedRowSet</code> 0N/A * objects to a <code>JoinRowSet</code> object. Note that in this example, 0N/A * no SQL <code>JOIN</code> type is set, so the default <code>JOIN</code> type, 0N/A * which is <i>INNER_JOIN</i>, is established. 0N/A * In the following code fragment, the table <code>EMPLOYEES</code>, whose match 0N/A * column is set to the first column (<code>EMP_ID</code>), is added to the 0N/A * <code>JoinRowSet</code> object <i>jrs</i>. Then 0N/A * the table <code>ESSP_BONUS_PLAN</code>, whose match column is likewise 0N/A * the <code>EMP_ID</code> column, is added. When this second 0N/A * table is added to <i>jrs</i>, only the rows in 0N/A * <code>ESSP_BONUS_PLAN</code> whose <code>EMP_ID</code> value matches an 0N/A * <code>EMP_ID</code> value in the <code>EMPLOYEES</code> table are added. 0N/A * In this case, everyone in the bonus plan is an employee, so all of the rows 0N/A * in the table <code>ESSP_BONUS_PLAN</code> are added to the <code>JoinRowSet</code> 0N/A * object. In this example, both <code>CachedRowSet</code> objects being added 0N/A * have implemented the <code>Joinable</code> interface and can therefore call 0N/A * the <code>Joinable</code> method <code>setMatchColumn</code>. 0N/A * JoinRowSet jrs = new JoinRowSetImpl(); 0N/A * ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES"); 0N/A * CachedRowSet empl = new CachedRowSetImpl(); 0N/A * empl.populate(rs1); 0N/A * empl.setMatchColumn(1); 0N/A * jrs.addRowSet(empl); 0N/A * ResultSet rs2 = stmt.executeQuery("SELECT * FROM ESSP_BONUS_PLAN"); 0N/A * CachedRowSet bonus = new CachedRowSetImpl(); 0N/A * bonus.populate(rs2); 0N/A * bonus.setMatchColumn(1); // EMP_ID is the first column 0N/A * jrs.addRowSet(bonus); 0N/A * At this point, <i>jrs</i> is an inside JOIN of the two <code>RowSet</code> objects 0N/A * based on their <code>EMP_ID</code> columns. The application can now browse the 0N/A * combined data as if it were browsing one single <code>RowSet</code> object. 0N/A * Because <i>jrs</i> is itself a <code>RowSet</code> object, an application can 0N/A * navigate or modify it using <code>RowSet</code> methods. 0N/A * int employeeID = jrs.getInt(1); 0N/A * String employeeName = jrs.getString(2); 0N/A * Note that because the SQL <code>JOIN</code> must be enforced when an application 0N/A * adds a second or subsequent <code>RowSet</code> object, there 0N/A * may be an initial degradation in performance while the <code>JOIN</code> is 0N/A * The following code fragment adds an additional <code>CachedRowSet</code> object. 0N/A * In this case, the match column (<code>EMP_ID</code>) is set when the 0N/A * <code>CachedRowSet</code> object is added to the <code>JoinRowSet</code> object. 0N/A * ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB"); 0N/A * CachedRowSet fourO1k = new CachedRowSetImpl(); 0N/A * four01k.populate(rs3); 0N/A * jrs.addRowSet(four01k, 1); 0N/A * The <code>JoinRowSet</code> object <i>jrs</i> now contains values from all three 0N/A * tables. The data in each row in <i>four01k</i> in which the value for the 0N/A * <code>EMP_ID</code> column matches a value for the <code>EMP_ID</code> column 0N/A * in <i>jrs</i> has been added to <i>jrs</i>. 0N/A * <h3>4.0 <code>JoinRowSet</code> Methods</h3> 0N/A * The <code>JoinRowSet</code> interface supplies several methods for adding 0N/A * <code>RowSet</code> objects and for getting information about the 0N/A * <code>JoinRowSet</code> object. 0N/A * <LI>Methods for adding one or more <code>RowSet</code> objects<BR> 0N/A * These methods allow an application to add one <code>RowSet</code> object 0N/A * at a time or to add multiple <code>RowSet</code> objects at one time. In 0N/A * either case, the methods may specify the match column for each 0N/A * <code>RowSet</code> object being added. 0N/A * <LI>Methods for getting information<BR> 0N/A * One method retrieves the <code>RowSet</code> objects in the 0N/A * <code>JoinRowSet</code> object, and another method retrieves the 0N/A * <code>RowSet</code> names. A third method retrieves either the SQL 0N/A * <code>WHERE</code> clause used behind the scenes to form the 0N/A * <code>JOIN</code> or a text description of what the <code>WHERE</code> 0N/A * <LI>Methods related to the type of <code>JOIN</code><BR> 0N/A * One method sets the <code>JOIN</code> type, and five methods find out whether 0N/A * the <code>JoinRowSet</code> object supports a given type. 0N/A * <LI>A method to make a separate copy of the <code>JoinRowSet</code> object<BR> 0N/A * This method creates a copy that can be persisted to the data source. 0N/A * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code> 0N/A * object. If the <code>RowSet</code> object 0N/A * is the first to be added to this <code>JoinRowSet</code> 0N/A * object, it forms the basis of the <code>JOIN</code> relationship to be 0N/A * This method should be used only when the given <code>RowSet</code> 0N/A * object already has a match column that was set with the <code>Joinable</code> 0N/A * method <code>setMatchColumn</code>. 0N/A * Note: A <code>Joinable</code> object is any <code>RowSet</code> object 0N/A * that has implemented the <code>Joinable</code> interface. 0N/A * @param rowset the <code>RowSet</code> object that is to be added to this 0N/A * <code>JoinRowSet</code> object; it must implement the 0N/A * <code>Joinable</code> interface and have a match column set 0N/A * @throws SQLException if (1) an empty rowset is added to the to this 0N/A * <code>JoinRowSet</code> object, (2) a match column has not been 0N/A * set for <i>rowset</i>, or (3) <i>rowset</i> 0N/A * violates the active <code>JOIN</code> 0N/A * @see Joinable#setMatchColumn 0N/A * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code> 0N/A * object and sets the designated column as the match column for 0N/A * the <code>RowSet</code> object. If the <code>RowSet</code> object 0N/A * is the first to be added to this <code>JoinRowSet</code> 0N/A * object, it forms the basis of the <code>JOIN</code> relationship to be 0N/A * This method should be used when <i>RowSet</i> does not already have a match 0N/A * @param rowset the <code>RowSet</code> object that is to be added to this 0N/A * <code>JoinRowSet</code> object; it may implement the 0N/A * <code>Joinable</code> interface 0N/A * @param columnIdx an <code>int</code> that identifies the column to become the 0N/A * @throws SQLException if (1) <i>rowset</i> is an empty rowset or 0N/A * (2) <i>rowset</i> violates the active <code>JOIN</code> 0N/A * @see Joinable#unsetMatchColumn 0N/A * Adds <i>rowset</i> to this <code>JoinRowSet</code> object and 0N/A * sets the designated column as the match column. If <i>rowset</i> 0N/A * is the first to be added to this <code>JoinRowSet</code> 0N/A * object, it forms the basis for the <code>JOIN</code> relationship to be 0N/A * This method should be used when the given <code>RowSet</code> object 0N/A * does not already have a match column. 0N/A * @param rowset the <code>RowSet</code> object that is to be added to this 0N/A * <code>JoinRowSet</code> object; it may implement the 0N/A * <code>Joinable</code> interface 0N/A * @param columnName the <code>String</code> object giving the name of the 0N/A * column to be set as the match column 0N/A * @throws SQLException if (1) <i>rowset</i> is an empty rowset or 0N/A * (2) the match column for <i>rowset</i> does not satisfy the 0N/A * conditions of the <code>JOIN</code> 0N/A * Adds one or more <code>RowSet</code> objects contained in the given 0N/A * array of <code>RowSet</code> objects to this <code>JoinRowSet</code> 0N/A * object and sets the match column for 0N/A * each of the <code>RowSet</code> objects to the match columns 0N/A * in the given array of column indexes. The first element in 0N/A * <i>columnIdx</i> is set as the match column for the first 0N/A * <code>RowSet</code> object in <i>rowset</i>, the second element of 0N/A * <i>columnIdx</i> is set as the match column for the second element 0N/A * in <i>rowset</i>, and so on. 0N/A * The first <code>RowSet</code> object added to this <code>JoinRowSet</code> 0N/A * object forms the basis for the <code>JOIN</code> relationship. 0N/A * This method should be used when the given <code>RowSet</code> object 0N/A * does not already have a match column. 0N/A * @param rowset an array of one or more <code>RowSet</code> objects 0N/A * to be added to the <code>JOIN</code>; it may implement the 0N/A * <code>Joinable</code> interface 0N/A * @param columnIdx an array of <code>int</code> values indicating the index(es) 0N/A * of the columns to be set as the match columns for the <code>RowSet</code> 0N/A * objects in <i>rowset</i> 0N/A * @throws SQLException if (1) an empty rowset is added to this 0N/A * <code>JoinRowSet</code> object, (2) a match column is not set 0N/A * for a <code>RowSet</code> object in <i>rowset</i>, or (3) 0N/A * a <code>RowSet</code> object being added violates the active 0N/A * Adds one or more <code>RowSet</code> objects contained in the given 0N/A * array of <code>RowSet</code> objects to this <code>JoinRowSet</code> 0N/A * object and sets the match column for 0N/A * each of the <code>RowSet</code> objects to the match columns 0N/A * in the given array of column names. The first element in 0N/A * <i>columnName</i> is set as the match column for the first 0N/A * <code>RowSet</code> object in <i>rowset</i>, the second element of 0N/A * <i>columnName</i> is set as the match column for the second element 0N/A * in <i>rowset</i>, and so on. 0N/A * The first <code>RowSet</code> object added to this <code>JoinRowSet</code> 0N/A * object forms the basis for the <code>JOIN</code> relationship. 0N/A * This method should be used when the given <code>RowSet</code> object(s) 0N/A * does not already have a match column. 0N/A * @param rowset an array of one or more <code>RowSet</code> objects 0N/A * to be added to the <code>JOIN</code>; it may implement the 0N/A * <code>Joinable</code> interface 0N/A * @param columnName an array of <code>String</code> values indicating the 0N/A * names of the columns to be set as the match columns for the 0N/A * <code>RowSet</code> objects in <i>rowset</i> 0N/A * @throws SQLException if (1) an empty rowset is added to this 0N/A * <code>JoinRowSet</code> object, (2) a match column is not set 0N/A * for a <code>RowSet</code> object in <i>rowset</i>, or (3) 0N/A * a <code>RowSet</code> object being added violates the active 0N/A * Returns a <code>Collection</code> object containing the 0N/A * <code>RowSet</code> objects that have been added to this 0N/A * <code>JoinRowSet</code> object. 0N/A * This should return the 'n' number of RowSet contained 0N/A * within the <code>JOIN</code> and maintain any updates that have occured while in 0N/A * @return a <code>Collection</code> object consisting of the 0N/A * <code>RowSet</code> objects added to this <code>JoinRowSet</code> 0N/A * @throws SQLException if an error occurs generating the 0N/A * <code>Collection</code> object to be returned 0N/A * Returns a <code>String</code> array containing the names of the 0N/A * <code>RowSet</code> objects added to this <code>JoinRowSet</code> 0N/A * @return a <code>String</code> array of the names of the 0N/A * <code>RowSet</code> objects in this <code>JoinRowSet</code> 0N/A * @throws SQLException if an error occurs retrieving the names of 0N/A * the <code>RowSet</code> objects 0N/A * @see CachedRowSet#setTableName 0N/A * Creates a new <code>CachedRowSet</code> object containing the 0N/A * data in this <code>JoinRowSet</code> object, which can be saved 0N/A * to a data source using the <code>SyncProvider</code> object for 0N/A * the <code>CachedRowSet</code> object. 0N/A * If any updates or modifications have been applied to the JoinRowSet 0N/A * the CachedRowSet returned by the method will not be able to persist 0N/A * it's changes back to the originating rows and tables in the 0N/A * in the datasource. The CachedRowSet instance returned should not 0N/A * contain modification data and it should clear all properties of 0N/A * it's originating SQL statement. An application should reset the 0N/A * SQL statement using the <code>RowSet.setCommand</code> method. 0N/A * In order to allow changes to be persisted back to the datasource 0N/A * to the originating tables, the <code>acceptChanges</code> method 0N/A * should be used and called on a JoinRowSet object instance. Implementations 0N/A * can leverage the internal data and update tracking in their 0N/A * implementations to interact with the SyncProvider to persist any 0N/A * @return a CachedRowSet containing the contents of the JoinRowSet 0N/A * @throws SQLException if an error occurs assembling the CachedRowSet 0N/A * @see javax.sql.RowSet 0N/A * @see javax.sql.rowset.CachedRowSet 0N/A * @see javax.sql.rowset.spi.SyncProvider 0N/A * Indicates if CROSS_JOIN is supported by a JoinRowSet 0N/A * @return true if the CROSS_JOIN is supported; false otherwise 0N/A * Indicates if INNER_JOIN is supported by a JoinRowSet 0N/A * @return true is the INNER_JOIN is supported; false otherwise 0N/A * Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet 0N/A * @return true is the LEFT_OUTER_JOIN is supported; false otherwise 0N/A * Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet 0N/A * @return true is the RIGHT_OUTER_JOIN is supported; false otherwise 0N/A * Indicates if FULL_JOIN is supported by a JoinRowSet 0N/A * @return true is the FULL_JOIN is supported; false otherwise 0N/A * Allow the application to adjust the type of <code>JOIN</code> imposed 0N/A * on tables contained within the JoinRowSet object instance. 0N/A * Implementations should throw a SQLException if they do 0N/A * not support a given <code>JOIN</code> type. 0N/A * @param joinType the standard JoinRowSet.XXX static field definition 0N/A * of a SQL <code>JOIN</code> to re-configure a JoinRowSet instance on 0N/A * @throws SQLException if an unsupported <code>JOIN</code> type is set 0N/A * Return a SQL-like description of the WHERE clause being used 0N/A * in a JoinRowSet object. An implementation can describe 0N/A * the WHERE clause of the SQL <code>JOIN</code> by supplying a SQL 0N/A * strings description of <code>JOIN</code> or provide a textual 0N/A * description to assist applications using a <code>JoinRowSet</code> 0N/A * @return whereClause a textual or SQL description of the logical 0N/A * WHERE clause used in the JoinRowSet instance 0N/A * @throws SQLException if an error occurs in generating a representation 0N/A * of the WHERE clause. 0N/A * Returns a <code>int</code> describing the set SQL <code>JOIN</code> type 0N/A * governing this JoinRowSet instance. The returned type will be one of 0N/A * standard JoinRowSet types: <code>CROSS_JOIN</code>, <code>INNER_JOIN</code>, 0N/A * <code>LEFT_OUTER_JOIN</code>, <code>RIGHT_OUTER_JOIN</code> or 0N/A * <code>FULL_JOIN</code>. 0N/A * @return joinType one of the standard JoinRowSet static field 0N/A * definitions of a SQL <code>JOIN</code>. <code>JoinRowSet.INNER_JOIN</code> 0N/A * is returned as the default <code>JOIN</code> type is no type has been 0N/A * @throws SQLException if an error occurs determining the SQL <code>JOIN</code> 0N/A * type supported by the JoinRowSet instance. 0N/A * An ANSI-style <code>JOIN</code> providing a cross product of two tables 0N/A * An ANSI-style <code>JOIN</code> providing a inner join between two tables. Any 0N/A * unmatched rows in either table of the join should be discarded. 0N/A * An ANSI-style <code>JOIN</code> providing a left outer join between two 0N/A * tables. In SQL, this is described where all records should be 0N/A * returned from the left side of the JOIN statement. 0N/A * An ANSI-style <code>JOIN</code> providing a right outer join between 0N/A * two tables. In SQL, this is described where all records from the 0N/A * table on the right side of the JOIN statement even if the table 0N/A * on the left has no matching record. 0N/A * An ANSI-style <code>JOIN</code> providing a a full JOIN. Specifies that all 0N/A * rows from either table be returned regardless of matching 0N/A * records on the other table.