/* * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.sql.rowset.spi; import javax.sql.*; /** * The synchronization mechanism that provides reader/writer capabilities for * disconnected RowSet objects. * A SyncProvider implementation is a class that extends the * SyncProvider abstract class. *

* A SyncProvider implementation is * identified by a unique ID, which is its fully qualified class name. * This name must be registered with the * SyncFactory SPI, thus making the implementation available to * all RowSet implementations. * The factory mechanism in the reference implementation uses this name to instantiate * the implementation, which can then provide a RowSet object with its * reader (a javax.sql.RowSetReader object) and its writer (a * javax.sql.RowSetWriter object). *

* The Jdbc RowSet Implementations specification provides two * reference implementations of the SyncProvider abstract class: * RIOptimisticProvider and RIXMLProvider. * The RIOptimisticProvider can set any RowSet * implementation with a RowSetReader object and a * RowSetWriter object. However, only the RIXMLProvider * implementation can set an XmlReader object and an * XmlWriter object. A WebRowSet object uses the * XmlReader object to read data in XML format to populate itself with that * data. It uses the XmlWriter object to write itself to a stream or * java.io.Writer object in XML format. *

*

1.0 Naming Convention for Implementations

* As a guide to naming SyncProvider * implementations, the following should be noted: * *

* For instance, if a vendor named Fred, Inc. offered a * SyncProvider implementation, you could have the following: * 

 *     Vendor name:  Fred, Inc.
 *     Domain name of vendor:  com.fred
 *     Package name:  com.fred.providers
 *     SyncProvider implementation class name:  HighAvailabilityProvider
 *
 *     Fully qualified class name of SyncProvider implementation:
 *                        com.fred.providers.HighAvailabilityProvider
 *
*

* The following line of code uses the fully qualified name to register * this implementation with the SyncFactory static instance. * 

 *     SyncFactory.registerProvider(
 *                          "com.fred.providers.HighAvailabilityProvider");
 *
*

* The default SyncProvider object provided with the reference * implementation uses the following name: * 

 *     com.sun.rowset.providers.RIOptimisticProvider
 *
*

* A vendor can register a SyncProvider implementation class name * with Oracle Corporation by sending email to jdbc@sun.com. * Oracle will maintain a database listing the * available SyncProvider implementations for use with compliant * RowSet implementations. This database will be similar to the * one already maintained to list available JDBC drivers. *

* Vendors should refer to the reference implementation synchronization * providers for additional guidance on how to implement a new * SyncProvider implementation. * *

2.0 How a RowSet Object Gets Its Provider

* * A disconnected Rowset object may get access to a * SyncProvider object in one of the following two ways: * *

* By default, the reference implementations of the RowSet synchronization * providers are always available to the Java platform. * If no other pluggable synchronization providers have been correctly * registered, the SyncFactory will automatically generate * an instance of the default SyncProvider reference implementation. * Thus, in the preceding code fragment, if no implementation named * com.fred.providers.HighAvailabilitySyncProvider has been * registered with the SyncFactory instance, crs will be * assigned the default provider in the reference implementation, which is * com.sun.rowset.providers.RIOptimisticProvider. *

*

3.0 Violations and Synchronization Issues

* If an update between a disconnected RowSet object * and a data source violates * the original query or the underlying data source constraints, this will * result in undefined behavior for all disconnected RowSet implementations * and their designated SyncProvider implementations. * Not defining the behavior when such violations occur offers greater flexibility * for a SyncProvider * implementation to determine its own best course of action. *

* A SyncProvider implementation * may choose to implement a specific handler to * handle a subset of query violations. * However if an original query violation or a more general data source constraint * violation is not handled by the SyncProvider implementation, * all SyncProvider * objects must throw a SyncProviderException. *

*

4.0 Updatable SQL VIEWs

* It is possible for any disconnected or connected RowSet object to be populated * from an SQL query that is formulated originally from an SQL VIEW. * While in many cases it is possible for an update to be performed to an * underlying view, such an update requires additional metadata, which may vary. * The SyncProvider class provides two constants to indicate whether * an implementation supports updating an SQL VIEW. * *

* The default is for a RowSet object not to be updatable if it was * populated with data from an SQL VIEW. *

*

5.0 SyncProvider Constants

* The SyncProvider class provides three sets of constants that * are used as return values or parameters for SyncProvider methods. * SyncProvider objects may be implemented to perform synchronization * between a RowSet object and its underlying data source with varying * degrees of of care. The first group of constants indicate how synchronization * is handled. For example, GRADE_NONE indicates that a * SyncProvider object will not take any care to see what data is * valid and will simply write the RowSet data to the data source. * GRADE_MODIFIED_AT_COMMIT indicates that the provider will check * only modified data for validity. Other grades check all data for validity * or set locks when data is modified or loaded. *
    *
  1. Constants to indicate the synchronization grade of a * SyncProvider object * *
  2. Constants to indicate what locks are set on the data source * *
  3. Constants to indicate whether a SyncProvider object can * perform updates to an SQL VIEW
    * These constants are explained in the preceding section (4.0). * *
* * @author Jonathan Bruce * @see javax.sql.rowset.spi.SyncFactory * @see javax.sql.rowset.spi.SyncFactoryException */ public abstract class SyncProvider { /** * Creates a default SyncProvider object. */ public SyncProvider() { } /** * Returns the unique identifier for this SyncProvider object. * * @return a String object with the fully qualified class name of * this SyncProvider object */ public abstract String getProviderID(); /** * Returns a javax.sql.RowSetReader object, which can be used to * populate a RowSet object with data. * * @return a javax.sql.RowSetReader object */ public abstract RowSetReader getRowSetReader(); /** * Returns a javax.sql.RowSetWriter object, which can be * used to write a RowSet object's data back to the * underlying data source. * * @return a javax.sql.RowSetWriter object */ public abstract RowSetWriter getRowSetWriter(); /** * Returns a constant indicating the * grade of synchronization a RowSet object can expect from * this SyncProvider object. * * @return an int that is one of the following constants: * SyncProvider.GRADE_NONE, * SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT, * SyncProvider.GRADE_CHECK_ALL_AT_COMMIT, * SyncProvider.GRADE_LOCK_WHEN_MODIFIED, * SyncProvider.GRADE_LOCK_WHEN_LOADED */ public abstract int getProviderGrade(); /** * Sets a lock on the underlying data source at the level indicated by * datasource_lock. This should cause the * SyncProvider to adjust its behavior by increasing or * decreasing the level of optimism it provides for a successful * synchronization. * * @param datasource_lock one of the following constants indicating the severity * level of data source lock required: * 
     *           SyncProvider.DATASOURCE_NO_LOCK,
     *           SyncProvider.DATASOURCE_ROW_LOCK,
     *           SyncProvider.DATASOURCE_TABLE_LOCK,
     *           SyncProvider.DATASOURCE_DB_LOCK,
     *
* @throws SyncProviderException if an unsupported data source locking level * is set. * @see #getDataSourceLock */ public abstract void setDataSourceLock(int datasource_lock) throws SyncProviderException; /** * Returns the current data source lock severity level active in this * SyncProvider implementation. * * @return a constant indicating the current level of data source lock * active in this SyncProvider object; * one of the following: * 
     *           SyncProvider.DATASOURCE_NO_LOCK,
     *           SyncProvider.DATASOURCE_ROW_LOCK,
     *           SyncProvider.DATASOURCE_TABLE_LOCK,
     *           SyncProvider.DATASOURCE_DB_LOCK
     *
* @throws SyncProviderException if an error occurs determining the data * source locking level. * @see #setDataSourceLock */ public abstract int getDataSourceLock() throws SyncProviderException; /** * Returns whether this SyncProvider implementation * can perform synchronization between a RowSet object * and the SQL VIEW in the data source from which * the RowSet object got its data. * * @return an int saying whether this SyncProvider * object supports updating an SQL VIEW; one of the * following: * SyncProvider.UPDATABLE_VIEW_SYNC, * SyncProvider.NONUPDATABLE_VIEW_SYNC */ public abstract int supportsUpdatableView(); /** * Returns the release version of this SyncProvider instance. * * @return a String detailing the release version of the * SyncProvider implementation */ public abstract String getVersion(); /** * Returns the vendor name of this SyncProvider instance * * @return a String detailing the vendor name of this * SyncProvider implementation */ public abstract String getVendor(); /* * Standard description of synchronization grades that a SyncProvider * could provide. */ /** * Indicates that no synchronization with the originating data source is * provided. A SyncProvider * implementation returning this grade will simply attempt to write * updates in the RowSet object to the underlying data * source without checking the validity of any data. * */ public static final int GRADE_NONE = 1; /** * Indicates a low level optimistic synchronization grade with * respect to the originating data source. * * A SyncProvider implementation * returning this grade will check only rows that have changed. * */ public static final int GRADE_CHECK_MODIFIED_AT_COMMIT = 2; /** * Indicates a high level optimistic synchronization grade with * respect to the originating data source. * * A SyncProvider implementation * returning this grade will check all rows, including rows that have not * changed. */ public static final int GRADE_CHECK_ALL_AT_COMMIT = 3; /** * Indicates a pessimistic synchronization grade with * respect to the originating data source. * * A SyncProvider * implementation returning this grade will lock the row in the originating * data source. */ public static final int GRADE_LOCK_WHEN_MODIFIED = 4; /** * Indicates the most pessimistic synchronization grade with * respect to the originating * data source. A SyncProvider * implementation returning this grade will lock the entire view and/or * table affected by the original statement used to populate a * RowSet object. */ public static final int GRADE_LOCK_WHEN_LOADED = 5; /** * Indicates that no locks remain on the originating data source. This is the default * lock setting for all SyncProvider implementations unless * otherwise directed by a RowSet object. */ public static final int DATASOURCE_NO_LOCK = 1; /** * Indicates that a lock is placed on the rows that are touched by the original * SQL statement used to populate the RowSet object * that is using this SyncProvider object. */ public static final int DATASOURCE_ROW_LOCK = 2; /** * Indicates that a lock is placed on all tables that are touched by the original * SQL statement used to populate the RowSet object * that is using this SyncProvider object. */ public static final int DATASOURCE_TABLE_LOCK = 3; /** * Indicates that a lock is placed on the entire data source that is the source of * data for the RowSet object * that is using this SyncProvider object. */ public static final int DATASOURCE_DB_LOCK = 4; /** * Indicates that a SyncProvider implementation * supports synchronization between a RowSet object and * the SQL VIEW used to populate it. */ public static final int UPDATABLE_VIEW_SYNC = 5; /** * Indicates that a SyncProvider implementation * does not support synchronization between a RowSet * object and the SQL VIEW used to populate it. */ public static final int NONUPDATABLE_VIEW_SYNC = 6; }