Java example source code file (WebRowSet.java)

This example Java source code file (WebRowSet.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

cachedrowset, corporation\/\/xsd, ioexception, jdbc, math, naming, oracle, public_xml_schema, sax, schema\/\/en, schema_system_id, sql, sqlexception, string, webrowset

The WebRowSet.java Java example source code

/*
 * Copyright (c) 2003, 2013, 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;

import java.sql.*;
import javax.sql.*;
import javax.naming.*;
import java.io.*;
import java.math.*;
import org.xml.sax.*;

/**
 * The standard interface that all implementations of a {@code WebRowSet}
 * must implement.
 *
 * <h3>1.0 Overview
 * The {@code WebRowSetImpl} provides the standard
 * reference implementation, which may be extended if required.
 * <P>
 * The standard WebRowSet XML Schema definition is available at the following
 * URI:
 * <ul>
 * <li>
 * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd
 * </li>
 * </ul>
 * It describes the standard XML document format required when describing a
 * {@code RowSet} object in XML and must be used be all standard implementations
 * of the {@code WebRowSet} interface to ensure interoperability. In addition,
 * the {@code WebRowSet} schema uses specific SQL/XML Schema annotations,
 * thus ensuring greater cross
 * platform inter-operability. This is an effort currently under way at the ISO
 * organization. The SQL/XML definition is available at the following URI:
 * <ul>
 * <li>
 * <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml">http://standards.iso.org/iso/9075/2002/12/sqlxml
 * </li>
 * </ul>
 * The schema definition describes the internal data of a {@code RowSet} object
 * in three distinct areas:
 * <UL>
 * <li>properties - These properties describe the standard synchronization
 * provider properties in addition to the more general {@code RowSet} properties.
 * </li>
 * <li>metadata - This describes the metadata associated with the tabular structure governed by a
 * {@code WebRowSet} object. The metadata described is closely aligned with the
 * metadata accessible in the underlying {@code java.sql.ResultSet} interface.
 * </li>
 * <li>data - This describes the original data (the state of data since the
 * last population
 * or last synchronization of the {@code WebRowSet} object) and the current
 * data. By keeping track of the delta between the original data and the current data,
 * a {@code WebRowSet} maintains the ability to synchronize changes
 * in its data back to the originating data source.
 * </li>
 * </ul>
 *
 * <h3>2.0 WebRowSet States
 * The following sections demonstrates how a {@code WebRowSet} implementation
 * should use the XML Schema to describe update, insert, and delete operations
 * and to describe the state of a {@code WebRowSet} object in XML.
 *
 * <h4>2.1 State 1 - Outputting a {@code WebRowSet} Object to XML
 * In this example, a {@code WebRowSet} object is created and populated with a simple 2 column,
 * 5 row table from a data source. Having the 5 rows in a {@code WebRowSet} object
 * makes it possible to describe them in XML. The
 * metadata describing the various standard JavaBeans properties as defined
 * in the RowSet interface plus the standard properties defined in
 * the {@code CachedRowSet}™ interface
 * provide key details that describe WebRowSet
 * properties. Outputting the WebRowSet object to XML using the standard
 * {@code writeXml} methods describes the internal properties as follows:
 * <PRE>
 * {@code
 * <properties>
 *       <command>select co1, col2 from test_table
 *      <concurrency>1
 *      <datasource/>
 *      <escape-processing>true
 *      <fetch-direction>0
 *      <fetch-size>0
 *      <isolation-level>1
 *      <key-columns/>
 *      <map/>
 *      <max-field-size>0
 *      <max-rows>0
 *      <query-timeout>0
 *      <read-only>false
 *      <rowset-type>TRANSACTION_READ_UNCOMMITED
 *      <show-deleted>false
 *      <table-name/>
 *      <url>jdbc:thin:oracle
 *      <sync-provider>
 *              <sync-provider-name>.com.rowset.provider.RIOptimisticProvider
 *              <sync-provider-vendor>Oracle Corporation
 *              <sync-provider-version>1.0
 *              <sync-provider-grade>LOW
 *              <data-source-lock>NONE
 *      </sync-provider>
 * </properties>
 * } </PRE>
 * The meta-data describing the make up of the WebRowSet is described
 * in XML as detailed below. Note both columns are described between the
 * {@code column-definition} tags.
 * <PRE>
 * {@code
 * <metadata>
 *      <column-count>2
 *      <column-definition>
 *              <column-index>1
 *              <auto-increment>false
 *              <case-sensitive>true
 *              <currency>false
 *              <nullable>1
 *              <signed>false
 *              <searchable>true
 *              <column-display-size>10
 *              <column-label>COL1
 *              <column-name>COL1
 *              <schema-name/>
 *              <column-precision>10
 *              <column-scale>0
 *              <table-name/>
 *              <catalog-name/>
 *              <column-type>1
 *              <column-type-name>CHAR
 *      </column-definition>
 *      <column-definition>
 *              <column-index>2
 *              <auto-increment>false
 *              <case-sensitive>false
 *              <currency>false
 *              <nullable>1
 *              <signed>true
 *              <searchable>true
 *              <column-display-size>39
 *              <column-label>COL2
 *              <column-name>COL2
 *              <schema-name/>
 *              <column-precision>38
 *              <column-scale>0
 *              <table-name/>
 *              <catalog-name/>
 *              <column-type>3
 *              <column-type-name>NUMBER
 *      </column-definition>
 * </metadata>
 * }</PRE>
 * Having detailed how the properties and metadata are described, the following details
 * how the contents of a {@code WebRowSet} object is described in XML. Note, that
 * this describes a {@code WebRowSet} object that has not undergone any
 * modifications since its instantiation.
 * A {@code currentRow} tag is mapped to each row of the table structure that the
 * {@code WebRowSet} object provides. A {@code columnValue} tag may contain
 * either the {@code stringData} or {@code binaryData} tag, according to
 * the SQL type that
 * the XML value is mapping back to. The {@code binaryData} tag contains data in the
 * Base64 encoding and is typically used for {@code BLOB} and {@code CLOB} type data.
 * <PRE>
 * {@code
 * <data>
 *      <currentRow>
 *              <columnValue>
 *                      firstrow
 *              </columnValue>
 *              <columnValue>
 *                      1
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      secondrow
 *              </columnValue>
 *              <columnValue>
 *                      2
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      thirdrow
 *              </columnValue>
 *              <columnValue>
 *                      3
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      fourthrow
 *              </columnValue>
 *              <columnValue>
 *                      4
 *              </columnValue>
 *      </currentRow>
 * </data>
 * }</PRE>
 * <h4>2.2 State 2 - Deleting a Row
 * Deleting a row in a {@code WebRowSet} object involves simply moving to the row
 * to be deleted and then calling the method {@code deleteRow}, as in any other
 * {@code RowSet} object.  The following
 * two lines of code, in which <i>wrs is a {@code WebRowSet} object, delete
 * the third row.
 * <PRE>
 *     wrs.absolute(3);
 *     wrs.deleteRow();
 * </PRE>
 * The XML description shows the third row is marked as a {@code deleteRow},
 *  which eliminates the third row in the {@code WebRowSet} object.
 * <PRE>
 * {@code
 * <data>
 *      <currentRow>
 *              <columnValue>
 *                      firstrow
 *              </columnValue>
 *              <columnValue>
 *                      1
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      secondrow
 *              </columnValue>
 *              <columnValue>
 *                      2
 *              </columnValue>
 *      </currentRow>
 *      <deleteRow>
 *              <columnValue>
 *                      thirdrow
 *              </columnValue>
 *              <columnValue>
 *                      3
 *              </columnValue>
 *      </deleteRow>
 *      <currentRow>
 *              <columnValue>
 *                      fourthrow
 *              </columnValue>
 *              <columnValue>
 *                      4
 *              </columnValue>
 *      </currentRow>
 * </data>
 *} </PRE>
 * <h4>2.3 State 3 - Inserting a Row
 * A {@code WebRowSet} object can insert a new row by moving to the insert row,
 * calling the appropriate updater methods for each column in the row, and then
 * calling the method {@code insertRow}.
 * <PRE>
 * {@code
 * wrs.moveToInsertRow();
 * wrs.updateString(1, "fifththrow");
 * wrs.updateString(2, "5");
 * wrs.insertRow();
 * }</PRE>
 * The following code fragment changes the second column value in the row just inserted.
 * Note that this code applies when new rows are inserted right after the current row,
 * which is why the method {@code next} moves the cursor to the correct row.
 * Calling the method {@code acceptChanges} writes the change to the data source.
 *
 * <PRE>
 * {@code wrs.moveToCurrentRow();
 * wrs.next();
 * wrs.updateString(2, "V");
 * wrs.acceptChanges();
 * }</PRE>
 * Describing this in XML demonstrates where the Java code inserts a new row and then
 * performs an update on the newly inserted row on an individual field.
 * <PRE>
 * {@code
 * <data>
 *      <currentRow>
 *              <columnValue>
 *                      firstrow
 *              </columnValue>
 *              <columnValue>
 *                      1
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      secondrow
 *              </columnValue>
 *              <columnValue>
 *                      2
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      newthirdrow
 *              </columnValue>
 *              <columnValue>
 *                      III
 *              </columnValue>
 *      </currentRow>
 *      <insertRow>
 *              <columnValue>
 *                      fifthrow
 *              </columnValue>
 *              <columnValue>
 *                      5
 *              </columnValue>
 *              <updateValue>
 *                      V
 *              </updateValue>
 *      </insertRow>
 *      <currentRow>
 *              <columnValue>
 *                      fourthrow
 *              </columnValue>
 *              <columnValue>
 *                      4
 *              </columnValue>
 *      </currentRow>
 * </date>
 *} </PRE>
 * <h4>2.4 State 4 - Modifying a Row
 * Modifying a row produces specific XML that records both the new value and the
 * value that was replaced.  The value that was replaced becomes the original value,
 * and the new value becomes the current value. The following
 * code moves the cursor to a specific row, performs some modifications, and updates
 * the row when complete.
 * <PRE>
 *{@code
 * wrs.absolute(5);
 * wrs.updateString(1, "new4thRow");
 * wrs.updateString(2, "IV");
 * wrs.updateRow();
 * }</PRE>
 * In XML, this is described by the {@code modifyRow} tag. Both the original and new
 * values are contained within the tag for original row tracking purposes.
 * <PRE>
 * {@code
 * <data>
 *      <currentRow>
 *              <columnValue>
 *                      firstrow
 *              </columnValue>
 *              <columnValue>
 *                      1
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      secondrow
 *              </columnValue>
 *              <columnValue>
 *                      2
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      newthirdrow
 *              </columnValue>
 *              <columnValue>
 *                      III
 *              </columnValue>
 *      </currentRow>
 *      <currentRow>
 *              <columnValue>
 *                      fifthrow
 *              </columnValue>
 *              <columnValue>
 *                      5
 *              </columnValue>
 *      </currentRow>
 *      <modifyRow>
 *              <columnValue>
 *                      fourthrow
 *              </columnValue>
 *              <updateValue>
 *                      new4thRow
 *              </updateValue>
 *              <columnValue>
 *                      4
 *              </columnValue>
 *              <updateValue>
 *                      IV
 *              </updateValue>
 *      </modifyRow>
 * </data>
 * }</PRE>
 *
 * @see javax.sql.rowset.JdbcRowSet
 * @see javax.sql.rowset.CachedRowSet
 * @see javax.sql.rowset.FilteredRowSet
 * @see javax.sql.rowset.JoinRowSet
 */

public interface WebRowSet extends CachedRowSet {

   /**
    * Reads a {@code WebRowSet} object in its XML format from the given
    * {@code Reader} object.
    *
    * @param reader the {@code java.io.Reader} stream from which this
    *        {@code WebRowSet} object will be populated

    * @throws SQLException if a database access error occurs
    */
    public void readXml(java.io.Reader reader) throws SQLException;

    /**
     * Reads a stream based XML input to populate this {@code WebRowSet}
     * object.
     *
     * @param iStream the {@code java.io.InputStream} from which this
     *        {@code WebRowSet} object will be populated
     * @throws SQLException if a data source access error occurs
     * @throws IOException if an IO exception occurs
     */
    public void readXml(java.io.InputStream iStream) throws SQLException, IOException;

   /**
    * Populates this {@code WebRowSet} object with
    * the contents of the given {@code ResultSet} object and writes its
    * data, properties, and metadata
    * to the given {@code Writer} object in XML format.
    * <p>
    * NOTE: The {@code WebRowSet} cursor may be moved to write out the
    * contents to the XML data source. If implemented in this way, the cursor <b>must
    * be returned to its position just prior to the {@code writeXml()} call.
    *
    * @param rs the {@code ResultSet} object with which to populate this
    *        {@code WebRowSet} object
    * @param writer the {@code java.io.Writer} object to write to.
    * @throws SQLException if an error occurs writing out the rowset
    *          contents in XML format
    */
    public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException;

   /**
    * Populates this {@code WebRowSet} object with
    * the contents of the given {@code ResultSet} object and writes its
    * data, properties, and metadata
    * to the given {@code OutputStream} object in XML format.
    * <p>
    * NOTE: The {@code WebRowSet} cursor may be moved to write out the
    * contents to the XML data source. If implemented in this way, the cursor <b>must
    * be returned to its position just prior to the {@code writeXml()} call.
    *
    * @param rs the {@code ResultSet} object with which to populate this
    *        {@code WebRowSet} object
    * @param oStream the {@code java.io.OutputStream} to write to
    * @throws SQLException if a data source access error occurs
    * @throws IOException if a IO exception occurs
    */
    public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException;

   /**
    * Writes the data, properties, and metadata for this {@code WebRowSet} object
    * to the given {@code Writer} object in XML format.
    *
    * @param writer the {@code java.io.Writer} stream to write to
    * @throws SQLException if an error occurs writing out the rowset
    *          contents to XML
    */
    public void writeXml(java.io.Writer writer) throws SQLException;

    /**
     * Writes the data, properties, and metadata for this {@code WebRowSet} object
     * to the given {@code OutputStream} object in XML format.
     *
     * @param oStream the {@code java.io.OutputStream} stream to write to
     * @throws SQLException if a data source access error occurs
     * @throws IOException if a IO exception occurs
     */
    public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException;

    /**
     * The public identifier for the XML Schema definition that defines the XML
     * tags and their valid values for a {@code WebRowSet} implementation.
     */
    public static String PUBLIC_XML_SCHEMA =
        "--//Oracle Corporation//XSD Schema//EN";

    /**
     * The URL for the XML Schema definition file that defines the XML tags and
     * their valid values for a {@code WebRowSet} implementation.
     */
    public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd";
}