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 com.sun.rowset.providers;

    27 

    28 import com.sun.rowset.JdbcRowSetResourceBundle;

    29 import java.io.IOException;

    30 import java.sql.*;

    31 import javax.sql.*;

    32 

    33 import javax.sql.rowset.spi.*;

    34 

    35 /**

    36  * A reference implementation of a JDBC RowSet synchronization provider

    37  * with the ability to read and write rowsets in well formed XML using the

    38  * standard WebRowSet schema.

    39  *

    40  * <h3>1.0 Background</h3>

    41  * This synchronization provider is registered with the

    42  * <code>SyncFactory</code> by default as the

    43  * <code>com.sun.rowset.providers.RIXMLProvider</code>.

    44  * <P>

    45  * A <code>WebRowSet</code> object uses an <code>RIXMLProvider</code> implementation

    46  * to read an XML data source or to write itself in XML format using the

    47  * <code>WebRowSet</code> XML schema definition available at

    48  * <pre>

    49  *     <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd</a>

    50  * </pre>

    51  * The <code>RIXMLProvider</code> implementation has a synchronization level of

    52  * GRADE_NONE, which means that it does no checking at all for conflicts.  It

    53  * simply writes a <code>WebRowSet</code> object to a file.

    54  * <h3>2.0 Usage</h3>

    55  * A <code>WebRowSet</code> implementation is created with an <code>RIXMLProvider</code>

    56  * by default.

    57  * <pre>

    58  *     WebRowSet wrs = new FooWebRowSetImpl();

    59  * </pre>

    60  * The <code>SyncFactory</code> always provides an instance of

    61  * <code>RIOptimisticProvider</code> when no provider is specified,

    62  * but the implementation of the default constructor for <code>WebRowSet</code> sets the

    63  * provider to be the <code>RIXMLProvider</code> implementation.  Therefore,

    64  * the following line of code is executed behind the scenes as part of the

    65  * implementation of the default constructor.

    66  * <pre>

    67  *     wrs.setSyncProvider("com.sun.rowset.providers.RIXMLProvider");

    68  * </pre>

    69  * See the standard <code>RowSet</code> reference implementations in the

    70  * <code>com.sun.rowset</code> package for more details.

    71  *

    72  * @author  Jonathan Bruce

    73  * @see javax.sql.rowset.spi.SyncProvider

    74  * @see javax.sql.rowset.spi.SyncProviderException

    75  * @see javax.sql.rowset.spi.SyncFactory

    76  * @see javax.sql.rowset.spi.SyncFactoryException

    77  */

    78 public final class RIXMLProvider extends SyncProvider {

    79 

    80     /**

    81      * The unique provider identifier.

    82      */

    83     private String providerID = "com.sun.rowset.providers.RIXMLProvider";

    84 

    85     /**

    86      * The vendor name of this SyncProvider implementation.

    87      */

    88     private String vendorName = "Oracle Corporation";

    89 

    90     /**

    91      * The version number of this SyncProvider implementation.

    92      */

    93     private String versionNumber = "1.0";

    94 

    95     private JdbcRowSetResourceBundle resBundle;

    96 

    97     private XmlReader xmlReader;

    98     private XmlWriter xmlWriter;

    99 

   100     /**

   101      * This provider is available to all JDBC <code>RowSet</code> implementations as the

   102      * default persistence provider.

   103      */

   104     public RIXMLProvider() {

   105         providerID = this.getClass().getName();

   106         try {

   107            resBundle = JdbcRowSetResourceBundle.getJdbcRowSetResourceBundle();

   108         } catch(IOException ioe) {

   109             throw new RuntimeException(ioe);

   110         }

   111     }

   112 

   113     /**

   114      * Returns <code>"javax.sql.rowset.providers.RIXMLProvider"</code>, which is

   115      * the fully qualified class name of this provider implementation.

   116      *

   117      * @return a <code>String</code> object with the fully specified class name of

   118      *           this <code>RIOptimisticProvider</code> implementation

   119      */

   120     public String getProviderID() {

   121         return providerID;

   122     }

   123 

   124     // additional methods that sit on top of reader/writer methods back to

   125     // original datasource. Allow XML state to be written out and in

   126 

   127     /**

   128      * Sets this <code>WebRowSet</code> object's reader to the given

   129      * <code>XmlReader</code> object.

   130      *

   131      * @throws SQLException if a database access error occurs

   132      */

   133     public void setXmlReader(XmlReader reader) throws SQLException {

   134         xmlReader = reader;

   135     }

   136 

   137     /**

   138      * Sets this <code>WebRowSet</code> object's writer to the given

   139      * <code>XmlWriter</code> object.

   140      *

   141      * @throws SQLException if a database access error occurs

   142      */

   143     public void setXmlWriter(XmlWriter writer) throws SQLException {

   144         xmlWriter = writer;

   145     }

   146 

   147     /**

   148      * Retrieves the reader that this <code>WebRowSet</code> object

   149      * will call when its <code>readXml</code> method is called.

   150      *

   151      * @return the <code>XmlReader</code> object for this SyncProvider

   152      * @throws SQLException if a database access error occurs

   153      */

   154     public XmlReader getXmlReader() throws SQLException {

   155         return xmlReader;

   156     }

   157 

   158     /**

   159      * Retrieves the writer that this <code>WebRowSet</code> object

   160      * will call when its <code>writeXml</code> method is called.

   161      *

   162      * @return the <code>XmlWriter</code> for this SyncProvider

   163      * @throws SQLException if a database access error occurs

   164      */

   165     public XmlWriter getXmlWriter() throws SQLException {

   166         return xmlWriter;

   167     }

   168 

   169     /**

   170      * Returns the <code>SyncProvider</code> grade of syncrhonization that

   171      * <code>RowSet</code> object instances can expect when using this

   172      * implementation. As this implementation provides no synchonization

   173      * facilities to the XML data source, the lowest grade is returned.

   174      *

   175      * @return the <code>SyncProvider</code> syncronization grade of this

   176      *     provider; must be one of the following constants:

   177      *       <PRE>

   178      *          SyncProvider.GRADE_NONE,

   179      *          SyncProvider.GRADE_MODIFIED_AT_COMMIT,

   180      *          SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,

   181      *          SyncProvider.GRADE_LOCK_WHEN_MODIFIED,

   182      *          SyncProvider.GRADE_LOCK_WHEN_LOADED

   183      *       </PRE>

   184      *

   185      */

   186     public int getProviderGrade() {

   187         return SyncProvider.GRADE_NONE;

   188     }

   189 

   190     /**

   191      * Returns the default UPDATABLE_VIEW behavior of this reader

   192      *

   193      */

   194     public int supportsUpdatableView() {

   195         return SyncProvider.NONUPDATABLE_VIEW_SYNC;

   196     }

   197 

   198     /**

   199      * Returns the default DATASOURCE_LOCK behavior of this reader

   200      */

   201     public int getDataSourceLock() throws SyncProviderException {

   202         return SyncProvider.DATASOURCE_NO_LOCK;

   203     }

   204 

   205     /**

   206      * Throws an unsupported operation exception as this method does

   207      * function with non-locking XML data sources.

   208      */

   209     public void setDataSourceLock(int lock) throws SyncProviderException {

   210         throw new UnsupportedOperationException(resBundle.handleGetObject("rixml.unsupp").toString());

   211     }

   212 

   213     /**

   214      * Returns a null object as RowSetWriters are not returned by this SyncProvider

   215      */

   216     public RowSetWriter getRowSetWriter() {

   217         return null;

   218     }

   219 

   220     /**

   221      * Returns a null object as RowSetWriter objects are not returned by this

   222      * SyncProvider

   223      */

   224     public RowSetReader getRowSetReader() {

   225         return null;

   226     }

   227 

   228   /**

   229      * Returns the release version ID of the Reference Implementation Optimistic

   230      * Synchronization Provider.

   231      *

   232      * @return the <code>String</code> detailing the version number of this SyncProvider

   233      */

   234     public String getVersion() {

   235         return this.versionNumber;

   236     }

   237 

   238     /**

   239      * Returns the vendor name of the Reference Implemntation Optimistic

   240      * Syncchronication Provider

   241      *

   242      * @return the <code>String</code> detailing the vendor name of this

   243      *      SyncProvider

   244      */

   245     public String getVendor() {

   246         return this.vendorName;

   247     }

   248 }