1 /*

     2  * Copyright 2003-2004 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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><sup><font size=-2>TM</font></sup>

   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 }