1 /*
   2  * Copyright (c) 2003, 2010, 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.spi;
  27 
  28 import javax.sql.*;
  29 
  30 /**
  31  * The synchronization mechanism that provides reader/writer capabilities for
  32  * disconnected <code>RowSet</code> objects.
  33  * A <code>SyncProvider</code> implementation is a class that extends the
  34  * <code>SyncProvider</code> abstract class.
  35  * <P>
  36  * A <code>SyncProvider</code> implementation is
  37  * identified by a unique ID, which is its fully qualified class name.
  38  * This name must be registered with the
  39  * <code>SyncFactory</code> SPI, thus making the implementation available to
  40  * all <code>RowSet</code> implementations.
  41  * The factory mechanism in the reference implementation uses this name to instantiate
  42  * the implementation, which can then provide a <code>RowSet</code> object with its
  43  * reader (a <code>javax.sql.RowSetReader</code> object) and its writer (a
  44  * <code>javax.sql.RowSetWriter</code> object).
  45  * <P>
  46  * The Jdbc <code>RowSet</code> Implementations specification provides two
  47  * reference implementations of the <code>SyncProvider</code> abstract class:
  48  * <code>RIOptimisticProvider</code> and <code>RIXMLProvider</code>.
  49  * The <code>RIOptimisticProvider</code> can set any <code>RowSet</code>
  50  * implementation with a <code>RowSetReader</code> object and a
  51  * <code>RowSetWriter</code> object.  However, only the <code>RIXMLProvider</code>
  52  * implementation can set an <code>XmlReader</code> object and an
  53  * <code>XmlWriter</code> object. A <code>WebRowSet</code> object uses the
  54  * <code>XmlReader</code> object to read data in XML format to populate itself with that
  55  * data.  It uses the <code>XmlWriter</code> object to write itself to a stream or
  56  * <code>java.io.Writer</code> object in XML format.
  57  * <P>
  58  * <h3>1.0 Naming Convention for Implementations</h3>
  59  * As a guide  to naming <code>SyncProvider</code>
  60  * implementations, the following should be noted:
  61  * <UL>
  62  * <li>The name for a <code>SyncProvider</code> implementation
  63  * is its fully qualified class name.
  64  * <li>It is recommended that vendors supply a
  65  * <code>SyncProvider</code> implementation in a package named <code>providers</code>.
  66  * </UL>
  67  * <p>
  68  * For instance, if a vendor named Fred, Inc. offered a
  69  * <code>SyncProvider</code> implementation, you could have the following:
  70  * <PRE>
  71  *     Vendor name:  Fred, Inc.
  72  *     Domain name of vendor:  com.fred
  73  *     Package name:  com.fred.providers
  74  *     SyncProvider implementation class name:  HighAvailabilityProvider
  75  *
  76  *     Fully qualified class name of SyncProvider implementation:
  77  *                        com.fred.providers.HighAvailabilityProvider
  78  * </PRE>
  79  * <P>
  80  * The following line of code uses the fully qualified name to register
  81  * this implementation with the <code>SyncFactory</code> static instance.
  82  * <PRE>
  83  *     SyncFactory.registerProvider(
  84  *                          "com.fred.providers.HighAvailabilityProvider");
  85  * </PRE>
  86  * <P>
  87  * The default <code>SyncProvider</code> object provided with the reference
  88  * implementation uses the following name:
  89  * <pre>
  90  *     com.sun.rowset.providers.RIOptimisticProvider
  91  * </pre>
  92  * <p>
  93  * A vendor can register a <code>SyncProvider</code> implementation class name
  94  * with Oracle Corporation by sending email to jdbc@sun.com.
  95  * Oracle will maintain a database listing the
  96  * available <code>SyncProvider</code> implementations for use with compliant
  97  * <code>RowSet</code> implementations.  This database will be similar to the
  98  * one already maintained to list available JDBC drivers.
  99  * <P>
 100  * Vendors should refer to the reference implementation synchronization
 101  * providers for additional guidance on how to implement a new
 102  * <code>SyncProvider</code> implementation.
 103  *
 104  * <h3>2.0 How a <code>RowSet</code> Object Gets Its Provider</h3>
 105  *
 106  * A disconnected <code>Rowset</code> object may get access to a
 107  * <code>SyncProvider</code> object in one of the following two ways:
 108  * <UL>
 109  *  <LI>Using a constructor<BR>
 110  *      <PRE>
 111  *       CachedRowSet crs = new CachedRowSet(
 112  *                  "com.fred.providers.HighAvailabilitySyncProvider");
 113  *      </PRE>
 114  *  <LI>Using the <code>setSyncProvider</code> method
 115  *      <PRE>
 116  *       CachedRowSet crs = new CachedRowSet();
 117  *       crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");
 118  *      </PRE>
 119 
 120  * </UL>
 121  * <p>
 122  * By default, the reference implementations of the <code>RowSet</code> synchronization
 123  * providers are always available to the Java platform.
 124  * If no other pluggable synchronization providers have been correctly
 125  * registered, the <code>SyncFactory</code> will automatically generate
 126  * an instance of the default <code>SyncProvider</code> reference implementation.
 127  * Thus, in the preceding code fragment, if no implementation named
 128  * <code>com.fred.providers.HighAvailabilitySyncProvider</code> has been
 129  * registered with the <code>SyncFactory</code> instance, <i>crs</i> will be
 130  * assigned the default provider in the reference implementation, which is
 131  * <code>com.sun.rowset.providers.RIOptimisticProvider</code>.
 132  * <p>
 133  * <h3>3.0 Violations and Synchronization Issues</h3>
 134  * If an update between a disconnected <code>RowSet</code> object
 135  * and a data source violates
 136  * the original query or the underlying data source constraints, this will
 137  * result in undefined behavior for all disconnected <code>RowSet</code> implementations
 138  * and their designated <code>SyncProvider</code> implementations.
 139  * Not defining the behavior when such violations occur offers greater flexibility
 140  * for a <code>SyncProvider</code>
 141  * implementation to determine its own best course of action.
 142  * <p>
 143  * A <code>SyncProvider</code> implementation
 144  * may choose to implement a specific handler to
 145  * handle a subset of query violations.
 146  * However if an original query violation or a more general data source constraint
 147  * violation is not handled by the <code>SyncProvider</code> implementation,
 148  * all <code>SyncProvider</code>
 149  * objects must throw a <code>SyncProviderException</code>.
 150  * <p>
 151  * <h3>4.0 Updatable SQL VIEWs</h3>
 152  * It is possible for any disconnected or connected <code>RowSet</code> object to be populated
 153  * from an SQL query that is formulated originally from an SQL <code>VIEW</code>.
 154  * While in many cases it is possible for an update to be performed to an
 155  * underlying view, such an update requires additional metadata, which may vary.
 156  * The <code>SyncProvider</code> class provides two constants to indicate whether
 157  * an implementation supports updating an SQL <code>VIEW</code>.
 158  * <ul>
 159  * <li><code><b>NONUPDATABLE_VIEW_SYNC</b></code> - Indicates that a <code>SyncProvider</code>
 160  * implementation does not support synchronization with an SQL <code>VIEW</code> as the
 161  * underlying source of data for the <code>RowSet</code> object.
 162  * <li><code><b>UPDATABLE_VIEW_SYNC</b></code> - Indicates that a
 163  * <code>SyncProvider</code> implementation
 164  * supports synchronization with an SQL <code>VIEW</code> as the underlying source
 165  * of data.
 166  * </ul>
 167  * <P>
 168  * The default is for a <code>RowSet</code> object not to be updatable if it was
 169  * populated with data from an SQL <code>VIEW</code>.
 170  * <P>
 171  * <h3>5.0 <code>SyncProvider</code> Constants</h3>
 172  * The <code>SyncProvider</code> class provides three sets of constants that
 173  * are used as return values or parameters for <code>SyncProvider</code> methods.
 174  * <code>SyncProvider</code> objects may be implemented to perform synchronization
 175  * between a <code>RowSet</code> object and its underlying data source with varying
 176  * degrees of of care. The first group of constants indicate how synchronization
 177  * is handled. For example, <code>GRADE_NONE</code> indicates that a
 178  * <code>SyncProvider</code> object will not take any care to see what data is
 179  * valid and will simply write the <code>RowSet</code> data to the data source.
 180  * <code>GRADE_MODIFIED_AT_COMMIT</code> indicates that the provider will check
 181  * only modified data for validity.  Other grades check all data for validity
 182  * or set locks when data is modified or loaded.
 183  * <OL>
 184  *  <LI>Constants to indicate the synchronization grade of a
 185  *     <code>SyncProvider</code> object
 186  *   <UL>
 187  *    <LI>SyncProvider.GRADE_NONE
 188  *    <LI>SyncProvider.GRADE_MODIFIED_AT_COMMIT
 189  *    <LI>SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
 190  *    <LI>SyncProvider.GRADE_LOCK_WHEN_MODIFIED
 191  *    <LI>SyncProvider.GRADE_LOCK_WHEN_LOADED
 192  *   </UL>
 193  *  <LI>Constants to indicate what locks are set on the data source
 194  *   <UL>
 195  *     <LI>SyncProvider.DATASOURCE_NO_LOCK
 196  *     <LI>SyncProvider.DATASOURCE_ROW_LOCK
 197  *     <LI>SyncProvider.DATASOURCE_TABLE_LOCK
 198  *     <LI>SyncProvider.DATASOURCE_DB_LOCK
 199  *   </UL>
 200  *  <LI>Constants to indicate whether a <code>SyncProvider</code> object can
 201  *       perform updates to an SQL <code>VIEW</code> <BR>
 202  *       These constants are explained in the preceding section (4.0).
 203  *   <UL>
 204  *     <LI>SyncProvider.UPDATABLE_VIEW_SYNC
 205  *     <LI>SyncProvider.NONUPDATABLE_VIEW_SYNC
 206  *   </UL>
 207  * </OL>
 208  *
 209  * @author Jonathan Bruce
 210  * @see javax.sql.rowset.spi.SyncFactory
 211  * @see javax.sql.rowset.spi.SyncFactoryException
 212  */
 213 public abstract class SyncProvider {
 214 
 215    /**
 216     * Creates a default <code>SyncProvider</code> object.
 217     */
 218     public SyncProvider() {
 219     }
 220 
 221     /**
 222      * Returns the unique identifier for this <code>SyncProvider</code> object.
 223      *
 224      * @return a <code>String</code> object with the fully qualified class name of
 225      *         this <code>SyncProvider</code> object
 226      */
 227     public abstract String getProviderID();
 228 
 229     /**
 230      * Returns a <code>javax.sql.RowSetReader</code> object, which can be used to
 231      * populate a <code>RowSet</code> object with data.
 232      *
 233      * @return a <code>javax.sql.RowSetReader</code> object
 234      */
 235     public abstract RowSetReader getRowSetReader();
 236 
 237     /**
 238      * Returns a <code>javax.sql.RowSetWriter</code> object, which can be
 239      * used to write a <code>RowSet</code> object's data back to the
 240      * underlying data source.
 241      *
 242      * @return a <code>javax.sql.RowSetWriter</code> object
 243      */
 244     public abstract RowSetWriter getRowSetWriter();
 245 
 246     /**
 247      * Returns a constant indicating the
 248      * grade of synchronization a <code>RowSet</code> object can expect from
 249      * this <code>SyncProvider</code> object.
 250      *
 251      * @return an int that is one of the following constants:
 252      *           SyncProvider.GRADE_NONE,
 253      *           SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT,
 254      *           SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,
 255      *           SyncProvider.GRADE_LOCK_WHEN_MODIFIED,
 256      *           SyncProvider.GRADE_LOCK_WHEN_LOADED
 257      */
 258     public abstract int getProviderGrade();
 259 
 260 
 261     /**
 262      * Sets a lock on the underlying data source at the level indicated by
 263      * <i>datasource_lock</i>. This should cause the
 264      * <code>SyncProvider</code> to adjust its behavior by increasing or
 265      * decreasing the level of optimism it provides for a successful
 266      * synchronization.
 267      *
 268      * @param datasource_lock one of the following constants indicating the severity
 269      *           level of data source lock required:
 270      * <pre>
 271      *           SyncProvider.DATASOURCE_NO_LOCK,
 272      *           SyncProvider.DATASOURCE_ROW_LOCK,
 273      *           SyncProvider.DATASOURCE_TABLE_LOCK,
 274      *           SyncProvider.DATASOURCE_DB_LOCK,
 275      * </pre>
 276      * @throws SyncProviderException if an unsupported data source locking level
 277      *           is set.
 278      * @see #getDataSourceLock
 279      */
 280     public abstract void setDataSourceLock(int datasource_lock)
 281         throws SyncProviderException;
 282 
 283     /**
 284      * Returns the current data source lock severity level active in this
 285      * <code>SyncProvider</code> implementation.
 286      *
 287      * @return a constant indicating the current level of data source lock
 288      *        active in this <code>SyncProvider</code> object;
 289      *         one of the following:
 290      * <pre>
 291      *           SyncProvider.DATASOURCE_NO_LOCK,
 292      *           SyncProvider.DATASOURCE_ROW_LOCK,
 293      *           SyncProvider.DATASOURCE_TABLE_LOCK,
 294      *           SyncProvider.DATASOURCE_DB_LOCK
 295      * </pre>
 296      * @throws SyncProviderException if an error occurs determining the data
 297      *        source locking level.
 298      * @see #setDataSourceLock
 299 
 300      */
 301     public abstract int getDataSourceLock()
 302         throws SyncProviderException;
 303 
 304     /**
 305      * Returns whether this <code>SyncProvider</code> implementation
 306      * can perform synchronization between a <code>RowSet</code> object
 307      * and the SQL <code>VIEW</code> in the data source from which
 308      * the <code>RowSet</code> object got its data.
 309      *
 310      * @return an <code>int</code> saying whether this <code>SyncProvider</code>
 311      *         object supports updating an SQL <code>VIEW</code>; one of the
 312      *         following:
 313      *            SyncProvider.UPDATABLE_VIEW_SYNC,
 314      *            SyncProvider.NONUPDATABLE_VIEW_SYNC
 315      */
 316     public abstract int supportsUpdatableView();
 317 
 318     /**
 319      * Returns the release version of this <code>SyncProvider</code> instance.
 320      *
 321      * @return a <code>String</code> detailing the release version of the
 322      *     <code>SyncProvider</code> implementation
 323      */
 324     public abstract String getVersion();
 325 
 326     /**
 327      * Returns the vendor name of this <code>SyncProvider</code> instance
 328      *
 329      * @return a <code>String</code> detailing the vendor name of this
 330      *     <code>SyncProvider</code> implementation
 331      */
 332     public abstract String getVendor();
 333 
 334     /*
 335      * Standard description of synchronization grades that a SyncProvider
 336      * could provide.
 337      */
 338 
 339     /**
 340      * Indicates that no synchronization with the originating data source is
 341      * provided. A <code>SyncProvider</code>
 342      * implementation returning this grade will simply attempt to write
 343      * updates in the <code>RowSet</code> object to the underlying data
 344      * source without checking the validity of any data.
 345      *
 346      */
 347     public static final int GRADE_NONE = 1;
 348 
 349     /**
 350      * Indicates a low level optimistic synchronization grade with
 351      * respect to the originating data source.
 352      *
 353      * A <code>SyncProvider</code> implementation
 354      * returning this grade will check only rows that have changed.
 355      *
 356      */
 357     public static final int GRADE_CHECK_MODIFIED_AT_COMMIT = 2;
 358 
 359     /**
 360      * Indicates a high level optimistic synchronization grade with
 361      * respect to the originating data source.
 362      *
 363      * A <code>SyncProvider</code> implementation
 364      * returning this grade will check all rows, including rows that have not
 365      * changed.
 366      */
 367     public static final int GRADE_CHECK_ALL_AT_COMMIT = 3;
 368 
 369     /**
 370      * Indicates a pessimistic synchronization grade with
 371      * respect to the originating data source.
 372      *
 373      * A <code>SyncProvider</code>
 374      * implementation returning this grade will lock the row in the originating
 375      * data source.
 376      */
 377     public static final int GRADE_LOCK_WHEN_MODIFIED = 4;
 378 
 379     /**
 380      * Indicates the most pessimistic synchronization grade with
 381      * respect to the originating
 382      * data source. A <code>SyncProvider</code>
 383      * implementation returning this grade will lock the entire view and/or
 384      * table affected by the original statement used to populate a
 385      * <code>RowSet</code> object.
 386      */
 387     public static final int GRADE_LOCK_WHEN_LOADED = 5;
 388 
 389     /**
 390      * Indicates that no locks remain on the originating data source. This is the default
 391      * lock setting for all <code>SyncProvider</code> implementations unless
 392      * otherwise directed by a <code>RowSet</code> object.
 393      */
 394     public static final int DATASOURCE_NO_LOCK = 1;
 395 
 396     /**
 397      * Indicates that a lock is placed on the rows that are touched by the original
 398      * SQL statement used to populate the <code>RowSet</code> object
 399      * that is using this <code>SyncProvider</code> object.
 400      */
 401     public static final int DATASOURCE_ROW_LOCK = 2;
 402 
 403     /**
 404      * Indicates that a lock is placed on all tables that are touched by the original
 405      * SQL statement used to populate the <code>RowSet</code> object
 406      * that is using this <code>SyncProvider</code> object.
 407      */
 408     public static final int DATASOURCE_TABLE_LOCK = 3;
 409 
 410     /**
 411      * Indicates that a lock is placed on the entire data source that is the source of
 412      * data for the <code>RowSet</code> object
 413      * that is using this <code>SyncProvider</code> object.
 414      */
 415     public static final int DATASOURCE_DB_LOCK = 4;
 416 
 417     /**
 418      * Indicates that a <code>SyncProvider</code> implementation
 419      * supports synchronization between a <code>RowSet</code> object and
 420      * the SQL <code>VIEW</code> used to populate it.
 421      */
 422     public static final int UPDATABLE_VIEW_SYNC = 5;
 423 
 424     /**
 425      * Indicates that a <code>SyncProvider</code> implementation
 426      * does <B>not</B> support synchronization between a <code>RowSet</code>
 427      * object and the SQL <code>VIEW</code> used to populate it.
 428      */
 429     public static final int NONUPDATABLE_VIEW_SYNC = 6;
 430 }