1 /*
   2  * Copyright (c) 2003, 2019, 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  *
  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  * <h2>2.0 How a <code>RowSet</code> Object Gets Its Provider</h2>
 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  *
 133  * <h2>3.0 Violations and Synchronization Issues</h2>
 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  *
 151  * <h2>4.0 Updatable SQL VIEWs</h2>
 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  *
 171  * <h2>5.0 <code>SyncProvider</code> Constants</h2>
 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 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  * @since 1.5
 213  */
 214 public abstract class SyncProvider {
 215 
 216    /**
 217     * Creates a default <code>SyncProvider</code> object.
 218     */
 219     public SyncProvider() {
 220     }
 221 
 222     /**
 223      * Returns the unique identifier for this <code>SyncProvider</code> object.
 224      *
 225      * @return a <code>String</code> object with the fully qualified class name of
 226      *         this <code>SyncProvider</code> object
 227      */
 228     public abstract String getProviderID();
 229 
 230     /**
 231      * Returns a <code>javax.sql.RowSetReader</code> object, which can be used to
 232      * populate a <code>RowSet</code> object with data.
 233      *
 234      * @return a <code>javax.sql.RowSetReader</code> object
 235      */
 236     public abstract RowSetReader getRowSetReader();
 237 
 238     /**
 239      * Returns a <code>javax.sql.RowSetWriter</code> object, which can be
 240      * used to write a <code>RowSet</code> object's data back to the
 241      * underlying data source.
 242      *
 243      * @return a <code>javax.sql.RowSetWriter</code> object
 244      */
 245     public abstract RowSetWriter getRowSetWriter();
 246 
 247     /**
 248      * Returns a constant indicating the
 249      * grade of synchronization a <code>RowSet</code> object can expect from
 250      * this <code>SyncProvider</code> object.
 251      *
 252      * @return an int that is one of the following constants:
 253      *           SyncProvider.GRADE_NONE,
 254      *           SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT,
 255      *           SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,
 256      *           SyncProvider.GRADE_LOCK_WHEN_MODIFIED,
 257      *           SyncProvider.GRADE_LOCK_WHEN_LOADED
 258      */
 259     public abstract int getProviderGrade();
 260 
 261 
 262     /**
 263      * Sets a lock on the underlying data source at the level indicated by
 264      * <i>datasource_lock</i>. This should cause the
 265      * <code>SyncProvider</code> to adjust its behavior by increasing or
 266      * decreasing the level of optimism it provides for a successful
 267      * synchronization.
 268      *
 269      * @param datasource_lock one of the following constants indicating the severity
 270      *           level of data source lock required:
 271      * <pre>
 272      *           SyncProvider.DATASOURCE_NO_LOCK,
 273      *           SyncProvider.DATASOURCE_ROW_LOCK,
 274      *           SyncProvider.DATASOURCE_TABLE_LOCK,
 275      *           SyncProvider.DATASOURCE_DB_LOCK,
 276      * </pre>
 277      * @throws SyncProviderException if an unsupported data source locking level
 278      *           is set.
 279      * @see #getDataSourceLock
 280      */
 281     public abstract void setDataSourceLock(int datasource_lock)
 282         throws SyncProviderException;
 283 
 284     /**
 285      * Returns the current data source lock severity level active in this
 286      * <code>SyncProvider</code> implementation.
 287      *
 288      * @return a constant indicating the current level of data source lock
 289      *        active in this <code>SyncProvider</code> object;
 290      *         one of the following:
 291      * <pre>
 292      *           SyncProvider.DATASOURCE_NO_LOCK,
 293      *           SyncProvider.DATASOURCE_ROW_LOCK,
 294      *           SyncProvider.DATASOURCE_TABLE_LOCK,
 295      *           SyncProvider.DATASOURCE_DB_LOCK
 296      * </pre>
 297      * @throws SyncProviderException if an error occurs determining the data
 298      *        source locking level.
 299      * @see #setDataSourceLock
 300 
 301      */
 302     public abstract int getDataSourceLock()
 303         throws SyncProviderException;
 304 
 305     /**
 306      * Returns whether this <code>SyncProvider</code> implementation
 307      * can perform synchronization between a <code>RowSet</code> object
 308      * and the SQL <code>VIEW</code> in the data source from which
 309      * the <code>RowSet</code> object got its data.
 310      *
 311      * @return an <code>int</code> saying whether this <code>SyncProvider</code>
 312      *         object supports updating an SQL <code>VIEW</code>; one of the
 313      *         following:
 314      *            SyncProvider.UPDATABLE_VIEW_SYNC,
 315      *            SyncProvider.NONUPDATABLE_VIEW_SYNC
 316      */
 317     public abstract int supportsUpdatableView();
 318 
 319     /**
 320      * Returns the release version of this <code>SyncProvider</code> instance.
 321      *
 322      * @return a <code>String</code> detailing the release version of the
 323      *     <code>SyncProvider</code> implementation
 324      */
 325     public abstract String getVersion();
 326 
 327     /**
 328      * Returns the vendor name of this <code>SyncProvider</code> instance
 329      *
 330      * @return a <code>String</code> detailing the vendor name of this
 331      *     <code>SyncProvider</code> implementation
 332      */
 333     public abstract String getVendor();
 334 
 335     /*
 336      * Standard description of synchronization grades that a SyncProvider
 337      * could provide.
 338      */
 339 
 340     /**
 341      * Indicates that no synchronization with the originating data source is
 342      * provided. A <code>SyncProvider</code>
 343      * implementation returning this grade will simply attempt to write
 344      * updates in the <code>RowSet</code> object to the underlying data
 345      * source without checking the validity of any data.
 346      *
 347      */
 348     public static final int GRADE_NONE = 1;
 349 
 350     /**
 351      * Indicates a low level optimistic synchronization grade with
 352      * respect to the originating data source.
 353      *
 354      * A <code>SyncProvider</code> implementation
 355      * returning this grade will check only rows that have changed.
 356      *
 357      */
 358     public static final int GRADE_CHECK_MODIFIED_AT_COMMIT = 2;
 359 
 360     /**
 361      * Indicates a high level optimistic synchronization grade with
 362      * respect to the originating data source.
 363      *
 364      * A <code>SyncProvider</code> implementation
 365      * returning this grade will check all rows, including rows that have not
 366      * changed.
 367      */
 368     public static final int GRADE_CHECK_ALL_AT_COMMIT = 3;
 369 
 370     /**
 371      * Indicates a pessimistic synchronization grade with
 372      * respect to the originating data source.
 373      *
 374      * A <code>SyncProvider</code>
 375      * implementation returning this grade will lock the row in the originating
 376      * data source.
 377      */
 378     public static final int GRADE_LOCK_WHEN_MODIFIED = 4;
 379 
 380     /**
 381      * Indicates the most pessimistic synchronization grade with
 382      * respect to the originating
 383      * data source. A <code>SyncProvider</code>
 384      * implementation returning this grade will lock the entire view and/or
 385      * table affected by the original statement used to populate a
 386      * <code>RowSet</code> object.
 387      */
 388     public static final int GRADE_LOCK_WHEN_LOADED = 5;
 389 
 390     /**
 391      * Indicates that no locks remain on the originating data source. This is the default
 392      * lock setting for all <code>SyncProvider</code> implementations unless
 393      * otherwise directed by a <code>RowSet</code> object.
 394      */
 395     public static final int DATASOURCE_NO_LOCK = 1;
 396 
 397     /**
 398      * Indicates that a lock is placed on the rows that are touched by the original
 399      * SQL statement used to populate the <code>RowSet</code> object
 400      * that is using this <code>SyncProvider</code> object.
 401      */
 402     public static final int DATASOURCE_ROW_LOCK = 2;
 403 
 404     /**
 405      * Indicates that a lock is placed on all tables that are touched by the original
 406      * SQL statement used to populate the <code>RowSet</code> object
 407      * that is using this <code>SyncProvider</code> object.
 408      */
 409     public static final int DATASOURCE_TABLE_LOCK = 3;
 410 
 411     /**
 412      * Indicates that a lock is placed on the entire data source that is the source of
 413      * data for the <code>RowSet</code> object
 414      * that is using this <code>SyncProvider</code> object.
 415      */
 416     public static final int DATASOURCE_DB_LOCK = 4;
 417 
 418     /**
 419      * Indicates that a <code>SyncProvider</code> implementation
 420      * supports synchronization between a <code>RowSet</code> object and
 421      * the SQL <code>VIEW</code> used to populate it.
 422      */
 423     public static final int UPDATABLE_VIEW_SYNC = 5;
 424 
 425     /**
 426      * Indicates that a <code>SyncProvider</code> implementation
 427      * does <B>not</B> support synchronization between a <code>RowSet</code>
 428      * object and the SQL <code>VIEW</code> used to populate it.
 429      */
 430     public static final int NONUPDATABLE_VIEW_SYNC = 6;
 431 }