/*
 * @(#)JoinRowSet.java	1.8 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.*;
import javax.sql.*;
import javax.naming.*;
import java.io.*;
import java.math.*;
import java.util.*;

import javax.sql.rowset.*;

/**
 * The <code>JoinRowSet</code> interface provides a mechanism for combining related
 * data from different <code>RowSet</code> objects into one <code>JoinRowSet</code>
 * object, which represents an SQL <code>JOIN</code>.
 * In other words, a <code>JoinRowSet</code> object acts as a
 * container for the data from <code>RowSet</code> objects that form an SQL
 * <code>JOIN</code> relationship.
 * <P>
 * The <code>Joinable</code> interface provides the methods for setting,
 * retrieving, and unsetting a match column, the basis for 
 * establishing an SQL <code>JOIN</code> relationship. The match column may
 * alternatively be set by supplying it to the appropriate version of the
 * <code>JointRowSet</code> method <code>addRowSet</code>.
 * <P>
 * <p>
 * <h3>1.0 Overview</h3>
 * Disconnected <code>RowSet</code> objects (<code>CachedRowSet</code> objects
 * and implementations extending the <code>CachedRowSet</code> interface)
 * do not have a standard way to establish an SQL <code>JOIN</code> between 
 * <code>RowSet</code> objects without the expensive operation of 
 * reconnecting to the data source. The <code>JoinRowSet</code> 
 * interface is specifically designed to address this need. 
 * <P>
 * Any <code>RowSet</code> object 
 * can be added to a <code>JoinRowSet</code> object to become
 * part of an SQL <code>JOIN</code> relationship. This means that both connected
 * and disconnected <code>RowSet</code> objects can be part of a <code>JOIN</code>.
 * <code>RowSet</code> objects operating in a connected environment 
 * (<code>JdbcRowSet</code> objects) are
 * encouraged to use the database to which they are already 
 * connected to establish SQL <code>JOIN</code> relationships between
 * tables directly. However, it is possible for a
 * <code>JdbcRowSet</code> object to be added to a <code>JoinRowSet</code> object 
 * if necessary.  
 * <P>
 * Any number of <code>RowSet</code> objects can be added to an
 * instance of <code>JoinRowSet</code> provided that they
 * can be related in an SQL <code>JOIN</code>.
 * By definition, the SQL <code>JOIN</code> statement is used to
 * combine the data contained in two or more relational database tables based
 * upon a common attribute. The <code>Joinable</code> interface provides the methods
 * for establishing a common attribute, which is done by setting a
 * <i>match column</i>. The match column commonly coincides with
 * the primary key, but there is
 * no requirement that the match column be the same as the primary key.
 * By establishing and then enforcing column matches,
 * a <code>JoinRowSet</code> object establishes <code>JOIN</code> relationships 
 * between <code>RowSet</code> objects without the assistance of an available
 * relational database.
 * <P>
 * The type of <code>JOIN</code> to be established is determined by setting
 * one of the <code>JoinRowSet</code> constants using the method
 * <code>setJoinType</code>. The following SQL <code>JOIN</code> types can be set:
 * <UL>
 *  <LI><code>CROSS_JOIN</code>
 *  <LI><code>FULL_JOIN</code>
 *  <LI><code>INNER_JOIN</code> - the default if no <code>JOIN</code> type has been set
 *  <LI><code>LEFT_OUTER_JOIN</code>
 *  <LI><code>RIGHT_OUTER_JOIN</code>
 * </UL>
 * Note that if no type is set, the <code>JOIN</code> will automatically be an
 * inner join. The comments for the fields in the
 * <code>JoinRowSet</code> interface explain these <code>JOIN</code> types, which are
 * standard SQL <code>JOIN</code> types. 
 * <P>
 * <h3>2.0 Using a <code>JoinRowSet</code> Object for Creating a <code>JOIN</code></h3>
 * When a <code>JoinRowSet</code> object is created, it is empty.
 * The first <code>RowSet</code> object to be added becomes the basis for the
 * <code>JOIN</code> relationship.
 * Applications must determine which column in each of the
 * <code>RowSet</code> objects to be added to the <code>JoinRowSet</code> object 
 * should be the match column. All of the 
 * <code>RowSet</code> objects must contain a match column, and the values in
 * each match column must be ones that can be compared to values in the other match
 * columns. The columns do not have to have the same name, though they often do, 
 * and they do not have to store the exact same data type as long as the data types
 * can be compared.  
 * <P>
 * A match column can be be set in two ways: 
 * <ul>
 *  <li>By calling the <code>Joinable</code> method <code>setMatchColumn</code><br>
 *  This is the only method that can set the match column before a <code>RowSet</code>