stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge

Browse Source
This commit is contained in:
Jesper Wilhelmsson 2020-01-28 07:25:31 +01:00
commit efa4d2f9e1
15 changed files with 597 additions and 597 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/java.base/share/classes/java/io/ObjectInputFilter.java
View File

@ -206,11 +206,10 @@ public interface ObjectInputFilter {
* <p>
* The filter is configured during the initialization of the {@code ObjectInputFilter.Config}
* class. For example, by calling {@link #getSerialFilter() Config.getSerialFilter}.
* If the system property {@systemProperty jdk.serialFilter} is defined on the command line,
* it is used to configure the filter.
* If the system property is not defined on the command line, and the
* {@link java.security.Security} property {@code jdk.serialFilter} is defined
* then it is used to configure the filter.
* If the Java virtual machine is started with the system property
* {@systemProperty jdk.serialFilter}, its value is used to configure the filter.
* If the system property is not defined, and the {@link java.security.Security} property
* {@code jdk.serialFilter} is defined then it is used to configure the filter.
* Otherwise, the filter is not configured during initialization and
* can be set with {@link #setSerialFilter(ObjectInputFilter) Config.setSerialFilter}.
* Setting the {@code jdk.serialFilter} with {@link System#setProperty(String, String)

4
src/java.base/share/classes/java/util/stream/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2020, 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
@ -176,7 +176,7 @@
* do:
*
* <pre>{@code
* int sumOfWeights = widgets.}<code><b>parallelStream()</b></code>{@code
* int sumOfWeights = widgets.<b>parallelStream()</b>
* .filter(b -> b.getColor() == RED)
* .mapToInt(b -> b.getWeight())
* .sum();

4
src/java.smartcardio/share/classes/javax/smartcardio/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -36,7 +36,7 @@
*
* <p>
* The API is defined by classes in the package
* <code>javax.smartcardio</code>. They can be classified as follows:
* {@code javax.smartcardio}. They can be classified as follows:
*
* <dl>
* <dt>Classes describing the corresponding Smart Card structures

30
src/java.sql.rowset/share/classes/com/sun/rowset/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@ -24,48 +24,48 @@
*/
/**
* Provides five standard implementations of the standard JDBC <code>RowSet</code> implementation
* Provides five standard implementations of the standard JDBC {@code RowSet} implementation
* interface definitions. These reference implementations are included with the J2SE version
* 1.5 platform and represent the benchmark standard <code>RowSet</code> implementations as verified
* 1.5 platform and represent the benchmark standard {@code RowSet} implementations as verified
* by the Test Compatibility Kit (TCK) as mandated by the Java Community Process.
* <br>
*
* <h2>1.0 Available JDBC RowSet Reference Implementations </h2>
* The following implementations are provided:<br>
*
* <blockquote><code><b>JdbcRowSetImpl</b></code> - The <code>javax.sql.rowset.JdbcRowSet</code>
* <blockquote><b>{@code JdbcRowSetImpl}</b> - The {@code javax.sql.rowset.JdbcRowSet}
* interface reference implementation. <br>
* <br>
* <code><b>CachedRowSetImpl</b></code> - The <code>javax.sql.rowset.CachedRowSet</code> interface
* <b>{@code CachedRowSetImpl}</b> - The {@code javax.sql.rowset.CachedRowSet} interface
* reference implementation.<br>
* <br>
* <code><b>WebRowSetImpl</b></code> - The <code>javax.sql.rowset.WebRowSet</code> interface
* <b>{@code WebRowSetImpl}</b> - The {@code javax.sql.rowset.WebRowSet} interface
* reference implementation.<br>
* <br>
* <code><b>FilteredRowSetImpl</b></code> - The <code>javax.sql.rowset.FilteredRowSet</code>
* <b>{@code FilteredRowSetImpl}</b> - The {@code javax.sql.rowset.FilteredRowSet}
* interface reference implementation.<br>
* <br>
* <code><b>JoinRowSetImpl</b></code> - The <code>javax.sql.rowset.JoinRowSet</code> interface
* <b>{@code JoinRowSetImpl}</b> - The {@code javax.sql.rowset.JoinRowSet} interface
* reference implementation.<br>
* </blockquote>
*
* All details on their expected behavior, including their interactions with the <code>SyncProvider</code>
* SPI and helper classes are provided in the interface definitions in the <code>javax.sql.rowset</code>
* All details on their expected behavior, including their interactions with the {@code SyncProvider}
* SPI and helper classes are provided in the interface definitions in the {@code javax.sql.rowset}
* package specification.<br>
*
* <h2>2.0 Usage</h2>
* The reference implementations represent robust implementations of the standard
* <code>RowSet</code> interfaces defined in the <code>javax.sql.rowset</code> package.
* All disconnected <code>RowSet</code> implementations, such as the <code>CachedRowSetImpl</code>
* and <code>WebRowSetImpl</code>, are flexible enough to use the <code>SyncFactory</code> SPIs to
* leverage non-reference implementation <code>SyncProvider</code> implementations to obtain
* {@code RowSet} interfaces defined in the {@code javax.sql.rowset} package.
* All disconnected {@code RowSet} implementations, such as the {@code CachedRowSetImpl}
* and {@code WebRowSetImpl}, are flexible enough to use the {@code SyncFactory} SPIs to
* leverage non-reference implementation {@code SyncProvider} implementations to obtain
* differing synchronization semantics. Furthermore, developers and vendors alike are free
* to use these implementations and integrate them into their products just as they
* can with to other components of the Java platform.<br>
*
* <h2>3.0 Extending the JDBC RowSet Implementations</h2>
*
* The JDBC <code>RowSet</code> reference implementations are provided as non-final
* The JDBC {@code RowSet} reference implementations are provided as non-final
* classes so that any developer can extend them to provide additional features
* while maintaining the core required standard functionality and compatibility. It
* is anticipated that many vendors and developers will extend the standard feature

94
src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@ -25,39 +25,39 @@
/**
*
* Repository for the <code>RowSet</code> reference implementations of the
* <code>SyncProvider</code> abstract class. These implementations provide a
* disconnected <code>RowSet</code>
* Repository for the {@code RowSet} reference implementations of the
* {@code SyncProvider} abstract class. These implementations provide a
* disconnected {@code RowSet}
* object with the ability to synchronize the data in the underlying data
* source with its data. These implementations are provided as
* the default <code>SyncProvider</code> implementations and are accessible via the
* <code>SyncProvider</code> SPI managed by the <code>SyncFactory</code>.
* the default {@code SyncProvider} implementations and are accessible via the
* {@code SyncProvider} SPI managed by the {@code SyncFactory}.
*
* <h2>1.0 <code>SyncProvider</code> Reference Implementations</h2>
* The main job of a <code>SyncProvider</code> implementation is to manage
* <h2>1.0 {@code SyncProvider} Reference Implementations</h2>
* The main job of a {@code SyncProvider} implementation is to manage
* the reader and writer mechanisms.
* The <code>SyncProvider</code> SPI, as specified in the <code>javax.sql.rowset.spi</code>
* package, provides a pluggable mechanism by which <code>javax.sql.RowSetReader</code>
* and <code>javax.sql.RowSetWriter</code> implementations can be supplied to a disconnected
* <code>RowSet</code> object.
* The {@code SyncProvider} SPI, as specified in the {@code javax.sql.rowset.spi}
* package, provides a pluggable mechanism by which {@code javax.sql.RowSetReader}
* and {@code javax.sql.RowSetWriter} implementations can be supplied to a disconnected
* {@code RowSet} object.
* <P>
* A reader, a <code>javax.sql.RowSetReader</code>
* object, does the work necessary to populate a <code>RowSet</code> object with data.
* A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for
* synchronizing a <code>RowSet</code> object's data with the data in the originating
* source of data. Put another way, a writer writes a <code>RowSet</code>
* A reader, a {@code javax.sql.RowSetReader}
* object, does the work necessary to populate a {@code RowSet} object with data.
* A writer, a {@code javax.sql.RowSetWriter} object, does the work necessary for
* synchronizing a {@code RowSet} object's data with the data in the originating
* source of data. Put another way, a writer writes a {@code RowSet}
* object's data back to the data source.
* <P>
* Generally speaking, the course of events is this. The reader makes a connection to
* the data source and reads the data from a <code>ResultSet</code> object into its
* <code>RowSet</code> object. Then it closes the connection. While
* the <code>RowSet</code> object is disconnected, an application makes some modifications
* to the data and calls the method <code>acceptChanges</code>. At this point, the
* the data source and reads the data from a {@code ResultSet} object into its
* {@code RowSet} object. Then it closes the connection. While
* the {@code RowSet} object is disconnected, an application makes some modifications
* to the data and calls the method {@code acceptChanges}. At this point, the
* writer is called to write the changes back to the database table or view
* from which the original data came. This is called <i>synchronization</i>.
* <P>
* If the data in the originating data source has not changed, there is no problem
* with just writing the <code>RowSet</code> object's new data to the data source.
* with just writing the {@code RowSet} object's new data to the data source.
* If it has changed, however, there is a conflict that needs to be resolved. One
* way to solve the problem is not to let the data in the data source be changed in
* the first place, which can be done by setting locks on a row, a table, or the
@ -65,44 +65,44 @@
* very expensive. Another approach, which is at the other end of the spectrum,
* is simply to assume that no conflicts will occur and thus do nothing to avoid
* conflicts.
* Different <code>SyncProvider</code> implementations may handle synchronization in
* Different {@code SyncProvider} implementations may handle synchronization in
* any of these ways, varying from doing no checking for
* conflicts, to doing various levels of checking, to guaranteeing that there are no
* conflicts.
* <P>
* The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code>
* The {@code SyncProvider} class offers methods to help a {@code RowSet}
* object discover and manage how a provider handles synchronization.
* The method <code>getProviderGrade</code> returns the
* The method {@code getProviderGrade} returns the
* grade of synchronization a provider offers. An application can
* direct the provider to use a particular level of locking by calling
* the method <code>setDataSourceLock</code> and specifying the level of locking desired.
* If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an
* application may call the method <code>supportsUpdatableView</code> to
* find out whether the <code>VIEW</code> can be updated.
* the method {@code setDataSourceLock} and specifying the level of locking desired.
* If a {@code RowSet} object's data came from an SQL {@code VIEW}, an
* application may call the method {@code supportsUpdatableView} to
* find out whether the {@code VIEW} can be updated.
* <P>
* Synchronization is done completely behind the scenes, so it is third party vendors of
* synchronization provider implementations who have to take care of this complex task.
* Application programmers can decide which provider to use and the level of locking to
* be done, but they are free from having to worry about the implementation details.
* <P>
* The JDBC <code>RowSet</code> Implementations reference implementation provides two
* implementations of the <code>SyncProvider</code> class:
* The JDBC {@code RowSet} Implementations reference implementation provides two
* implementations of the {@code SyncProvider} class:
*
* <UL>
* <LI>
* <b><code>RIOptimisticProvider</code></b> - provides the <code>javax.sql.RowSetReader</code>
* and <code>javax.sql.RowSetWriter</code> interface implementations and provides
* <b>{@code RIOptimisticProvider}</b> - provides the {@code javax.sql.RowSetReader}
* and {@code javax.sql.RowSetWriter} interface implementations and provides
* an optimistic concurrency model for synchronization. This model assumes that there
* will be few conflicts and therefore uses a relatively low grade of synchronization.
* If no other provider is available, this is the default provider that the
* <code>SyncFactory</code> will supply to a <code>RowSet</code> object.
* {@code SyncFactory} will supply to a {@code RowSet} object.
* <br>
* <LI>
* <b><code>RIXMLProvider</code></b> - provides the <code>XmlReader</code> (an extension
* of the <code>javax.sql.RowSetReader</code> interface) and the <code>XmlWriter</code>
* (an extension of the <code>javax.sql.RowSetWriter</code> interface) to enable
* <code>WebRowSet</code> objects to write their state to a
* well formed XML document according to the <code>WebRowSet</code> XML schema
* <b>{@code RIXMLProvider}</b> - provides the {@code XmlReader} (an extension
* of the {@code javax.sql.RowSetReader} interface) and the {@code XmlWriter}
* (an extension of the {@code javax.sql.RowSetWriter} interface) to enable
* {@code WebRowSet} objects to write their state to a
* well formed XML document according to the {@code WebRowSet} XML schema
* definition.<br>
* </UL>
*
@ -117,12 +117,12 @@
* properties. The general rule is that a RowSet is required to set only the
* properties that it uses.<br>
* <br>
* The <code>command</code> property contains the query that determines what
* data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's
* The {@code command} property contains the query that determines what
* data a {@code RowSet} will contain. Rowsets have methods for setting a query's
* parameter(s), which means that a query can be executed multiple times with
* different parameters to produce different result sets. Or the query can be
* changed to something completely new to get a new result set.
* <p>Once a rowset contains the rows from a <code>ResultSet</code> object or some
* <p>Once a rowset contains the rows from a {@code ResultSet} object or some
* other data source, its column values can be updated, and its rows can be
* inserted or deleted. Any method that causes a change in the rowset's values
* or cursor position also notifies any object that has been registered as
@ -134,13 +134,13 @@
* source to keep the rowset and its data source synchronized. Although this
* involves many operations behind the scenes, it is completely transparent
* to the application programmer and remains the concern of the RowSet provider
* developer. All an application has to do is invoke the method <code>acceptChanges</code>,
* developer. All an application has to do is invoke the method {@code acceptChanges},
* and the data source backing the rowset will be updated to match the current
* values in the rowset. </p>
*
* <p>A disconnected rowset, such as a <code>CachedRowSet</code> or <code>WebRowSet</code>
* <p>A disconnected rowset, such as a {@code CachedRowSet} or {@code WebRowSet}
* object, establishes a connection to populate itself with data from a database
* and then closes the connection. The <code>RowSet</code> object will remain
* and then closes the connection. The {@code RowSet} object will remain
* disconnected until it wants to propagate changes back to its database table,
* which is optional. To write its changes back to the database (synchronize with
* the database), the rowset establishes a connection, write the changes, and then
@ -148,9 +148,9 @@
* </p>
*
* <h2> 3.0 Other Possible Implementations</h2>
* There are many other possible implementations of the <code>SyncProvider</code> abstract
* There are many other possible implementations of the {@code SyncProvider} abstract
* class. One possibility is to employ a more robust synchronization model, which
* would give a <code>RowSet</code> object increased trust in the provider's
* would give a {@code RowSet} object increased trust in the provider's
* ability to get any updates back to the original data source. Another possibility
* is a more formal synchronization mechanism such as SyncML
* (<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br>

194
src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2017, 2020, 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
@ -24,9 +24,9 @@
*/
/**
* Standard interfaces and base classes for JDBC <code>RowSet</code>
* Standard interfaces and base classes for JDBC {@code RowSet}
* implementations. This package contains interfaces and classes
* that a standard <code>RowSet</code> implementation either implements or extends.
* that a standard {@code RowSet} implementation either implements or extends.
*
* <h2>Table of Contents</h2>
* <ul>
@ -38,133 +38,133 @@
* </ul>
*
* <h3><a id="pkgspec">1.0 Package Specification</a></h3>
* This package specifies five standard JDBC <code>RowSet</code> interfaces.
* This package specifies five standard JDBC {@code RowSet} interfaces.
* All five extend the
* <a href="{@docRoot}/java.sql/javax/sql/RowSet.html">RowSet</a> interface described in the JDBC 3.0
* specification. It is anticipated that additional definitions
* of more specialized JDBC <code>RowSet</code> types will emerge as this technology
* of more specialized JDBC {@code RowSet} types will emerge as this technology
* matures. Future definitions <i>should</i> be specified as subinterfaces using
* inheritance similar to the way it is used in this specification.
* <p>
* <i>Note:</i> The interface definitions provided in this package form the basis for
* all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
* developers who intend to provide their own compliant <code>RowSet</code> implementations
* all compliant JDBC {@code RowSet} implementations. Vendors and more advanced
* developers who intend to provide their own compliant {@code RowSet} implementations
* should pay particular attention to the assertions detailed in specification
* interfaces.
*
* <h3><a id="stdrowset">2.0 Standard RowSet Definitions</a></h3>
* <ul>
* <li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around
* a <code>ResultSet</code> object that makes it possible to use the result set as a
* <li><a href="JdbcRowSet.html"><b>{@code JdbcRowSet}</b></a> - A wrapper around
* a {@code ResultSet} object that makes it possible to use the result set as a
* JavaBeans&trade; component. Thus,
* a <code>JdbcRowSet</code> object can be a Bean that any tool
* a {@code JdbcRowSet} object can be a Bean that any tool
* makes available for assembling an application as part of a component based
* architecture. A <code>JdbcRowSet</code> object is a connected <code>RowSet</code>
* architecture. A {@code JdbcRowSet} object is a connected {@code RowSet}
* object, that is, it
* <b>must</b> continually maintain its connection to its data source using a JDBC
* technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
* technology-enabled driver ("JDBC driver"). In addition, a {@code JdbcRowSet}
* object provides a fully updatable and scrollable tabular
* data structure as defined in the JDBC 3.0 specification.
*
* <li><a href="CachedRowSet.html">
* <b><code>CachedRowSet</code>&trade;</b></a>
* - A <code>CachedRowSet</code> object is a JavaBeans&trade;
* <b>{@code CachedRowSet}&trade;</b></a>
* - A {@code CachedRowSet} object is a JavaBeans&trade;
* component that is scrollable, updatable, serializable, and generally disconnected from
* the source of its data. A <code>CachedRowSet</code> object
* the source of its data. A {@code CachedRowSet} object
* typically contains rows from a result set, but it can also contain rows from any
* file with a tabular format, such as a spreadsheet. <code>CachedRowSet</code> implementations
* <b>must</b> use the <code>SyncFactory</code> to manage and obtain pluggable
* <code>SyncProvider</code> objects to provide synchronization between the
* disconnected <code>RowSet</code> object and the originating data source.
* Typically a <code>SyncProvider</code> implementation relies upon a JDBC
* file with a tabular format, such as a spreadsheet. {@code CachedRowSet} implementations
* <b>must</b> use the {@code SyncFactory} to manage and obtain pluggable
* {@code SyncProvider} objects to provide synchronization between the
* disconnected {@code RowSet} object and the originating data source.
* Typically a {@code SyncProvider} implementation relies upon a JDBC
* driver to obtain connectivity to a particular data source.
* Further details on this mechanism are discussed in the <a
* href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
* href="spi/package-summary.html">{@code javax.sql.rowset.spi}</a> package
* specification.
*
* <li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A
* <code>WebRowSet</code> object is an extension of <code>CachedRowSet</code>
* that can read and write a <code>RowSet</code> object in a well formed XML format.
* This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object
* (an extension of the <a href="{@docRoot}/java.sql/javax/sql/RowSetReader.html"><code>RowSetReader</code></a>
* <li><a href="WebRowSet.html"><b>{@code WebRowSet}</b></a> - A
* {@code WebRowSet} object is an extension of {@code CachedRowSet}
* that can read and write a {@code RowSet} object in a well formed XML format.
* This class calls an <a href="spi/XmlReader.html">{@code XmlReader}</a> object
* (an extension of the <a href="{@docRoot}/java.sql/javax/sql/RowSetReader.html">{@code RowSetReader}</a>
* interface) to read a rowset in XML format. It calls an
* <a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the
* <a href="{@docRoot}/java.sql/javax/sql/RowSetWriter.html"><code>RowSetWriter</code></a> interface)
* <a href="spi/XmlWriter.html">{@code XmlWriter}</a> object (an extension of the
* <a href="{@docRoot}/java.sql/javax/sql/RowSetWriter.html">{@code RowSetWriter}</a> interface)
* to write a rowset in XML format. The reader and writer required by
* <code>WebRowSet</code> objects are provided by the
* <code>SyncFactory</code> in the form of <code>SyncProvider</code>
* {@code WebRowSet} objects are provided by the
* {@code SyncFactory} in the form of {@code SyncProvider}
* implementations. In order to ensure well formed XML usage, a standard generic XML
* Schema is defined and published at
* <a href="http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd">
* <code>http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd</code></a>.
* {@code http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd}</a>.
*
* <li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
* <code>FilteredRowSet</code> object provides filtering functionality in a programmatic
* and extensible way. There are many instances when a <code>RowSet</code> <code>object</code>
* <li><a href="FilteredRowSet.html"><b>{@code FilteredRowSet}</b></a> - A
* {@code FilteredRowSet} object provides filtering functionality in a programmatic
* and extensible way. There are many instances when a {@code RowSet} {@code object}
* has a need to provide filtering in its contents without sacrificing the disconnected
* environment, thus saving the expense of having to create a connection to the data source.
* Solutions to this need vary from providing heavyweight full scale
* SQL query abilities, to portable components, to more lightweight
* approaches. A <code>FilteredRowSet</code> object consumes
* an implementation of the <a href="Predicate.html"><code>Predicate</code></a>
* approaches. A {@code FilteredRowSet} object consumes
* an implementation of the <a href="Predicate.html">{@code Predicate}</a>
* interface, which <b>may</b> define a filter at run time. In turn, a
* <code>FilteredRowSet</code> object is tasked with enforcing the set filter for both
* {@code FilteredRowSet} object is tasked with enforcing the set filter for both
* inbound and outbound read and write operations. That is, all filters can be
* considered as bi-directional. No standard filters are defined;
* however, sufficient mechanics are specified to permit any required filter to be
* implemented.
*
* <li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <code>JoinRowSet</code>
* <li><a href="JoinRowSet.html"><b>{@code JoinRowSet}</b></a> - The {@code JoinRowSet}
* interface describes a mechanism by which relationships can be established between
* two or more standard <code>RowSet</code> implementations. Any number of <code>RowSet</code>
* objects can be added to a <code>JoinRowSet</code> object provided the <code>RowSet</code>objects
* can be related in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code>
* two or more standard {@code RowSet} implementations. Any number of {@code RowSet}
* objects can be added to a {@code JoinRowSet} object provided the {@code RowSet}objects
* can be related in a SQL {@code JOIN} like fashion. By definition, the SQL {@code JOIN}
* statement is used to combine the data contained in two (<i>or more</i>) relational
* database tables based upon a common attribute. By establishing and then enforcing
* column matches, a <code>JoinRowSet</code> object establishes relationships between
* <code>RowSet</code> instances without the need to touch the originating data source.
* column matches, a {@code JoinRowSet} object establishes relationships between
* {@code RowSet} instances without the need to touch the originating data source.
* </ul>
*
* <h3><a id="impl">3.0 Implementer's Guide</a></h3>
* Compliant implementations of JDBC <code>RowSet</code> Implementations
* Compliant implementations of JDBC {@code RowSet} Implementations
* <b>must</b> follow the assertions described in this specification. In accordance
* with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
* Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
* specification. The following paragraphs outline a number of starting points for
* implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
* implementers of the standard JDBC {@code RowSet} definitions. Implementers
* should also consult the <i>Implementer's Guide</i> in the <a
* href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
* on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
* on <a href="spi/SyncProvider.html">{@code SyncProvider}</a> implementations.
*
* <ul>
* <li><b>3.1 Constructor</b>
* <p>
* All <code>RowSet</code> implementations <strong>must</strong> provide a
* All {@code RowSet} implementations <strong>must</strong> provide a
* no-argument constructor.
* </li>
* <li><b>3.2 Role of the <code>BaseRowSet</code> Class</b>
* <li><b>3.2 Role of the {@code BaseRowSet} Class</b>
* <p>
* A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more
* A compliant JDBC {@code RowSet} implementation <b>must</b> implement one or more
* standard interfaces specified in this package and <b>may</b> extend the
* <a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a
* <code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>
* interface and extend the <code>BaseRowSet</code> abstract class. The
* <code>BaseRowSet</code> class provides the standard architecture on which all
* <code>RowSet</code> implementations should be built, regardless of whether the
* <code>RowSet</code> objects exist in a connected or disconnected environment.
* The <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> implementation
* <a href="BaseRowSet.html">{@code BaseRowSet}</a> abstract class. For example, a
* {@code CachedRowSet} implementation must implement the {@code CachedRowSet}
* interface and extend the {@code BaseRowSet} abstract class. The
* {@code BaseRowSet} class provides the standard architecture on which all
* {@code RowSet} implementations should be built, regardless of whether the
* {@code RowSet} objects exist in a connected or disconnected environment.
* The {@code BaseRowSet} abstract class provides any {@code RowSet} implementation
* with its base functionality, including property manipulation and event notification
* that is fully compliant with
* <a href="https://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html">JavaBeans</a>
* component requirements. As an example, all implementations provided in the
* reference implementations (contained in the <code>com.sun.rowset</code> package) use
* the <code>BaseRowSet</code> class as a basis for their implementations.
* reference implementations (contained in the {@code com.sun.rowset} package) use
* the {@code BaseRowSet} class as a basis for their implementations.
* <P>
* The following table illustrates the features that the <code>BaseRowSet</code>
* The following table illustrates the features that the {@code BaseRowSet}
* abstract class provides.
* <blockquote>
* <table class="striped" style="vertical-align:top; width:75%">
* <caption>Features in <code>BaseRowSet</code></caption>
* <caption>Features in {@code BaseRowSet}</caption>
* <thead>
* <tr>
* <th scope="col">Feature</th>
@ -175,15 +175,15 @@
* <tr>
* <th scope="row">Properties</th>
* <td>Provides standard JavaBeans property manipulation
* mechanisms to allow applications to get and set <code>RowSet</code> command and
* property values. Refer to the documentation of the <code>javax.sql.RowSet</code>
* mechanisms to allow applications to get and set {@code RowSet} command and
* property values. Refer to the documentation of the {@code javax.sql.RowSet}
* interface (available in the JDBC 3.0 specification) for more details on
* the standard <code>RowSet</code> properties.</td>
* the standard {@code RowSet} properties.</td>
* </tr>
* <tr>
* <th scope="row">Event notification</th>
* <td>Provides standard JavaBeans event notifications
* to registered event listeners. Refer to the documentation of <code>javax.sql.RowSetEvent</code>
* to registered event listeners. Refer to the documentation of {@code javax.sql.RowSetEvent}
* interface (available in the JDBC 3.0 specification) for
* more details on how to register and handle standard RowSet events generated
* by compliant implementations.</td>
@ -204,70 +204,70 @@
*
* <li><b>3.3 Connected RowSet Requirements</b>
* <p>
* The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
* be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
* The {@code JdbcRowSet} describes a {@code RowSet} object that <b>must</b> always
* be connected to the originating data source. Implementations of the {@code JdbcRowSet}
* should ensure that this connection is provided solely by a JDBC driver.
* Furthermore, <code>RowSet</code> objects that are implementations of the
* <code>JdbcRowSet</code> interface and are therefore operating in a connected environment
* do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
* or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
* Furthermore, {@code RowSet} objects that are implementations of the
* {@code JdbcRowSet} interface and are therefore operating in a connected environment
* do not use the {@code SyncFactory} to obtain a {@code RowSetReader} object
* or a {@code RowSetWriter} object. They can safely rely on the JDBC driver to
* supply their needs by virtue of the presence of an underlying updatable and scrollable
* <code>ResultSet</code> implementation.
* {@code ResultSet} implementation.
*
* <li>
* <b>3.4 Disconnected RowSet Requirements</b>
* <p>
* A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object,
* A disconnected {@code RowSet} object, such as a {@code CachedRowSet} object,
* <b>should</b> delegate
* connection management to a <code>SyncProvider</code> object provided by the
* <code>SyncFactory</code>. To ensure fully disconnected semantics, all
* disconnected <code>RowSet</code> objects <b>must</b> ensure
* that the original connection made to the data source to populate the <code>RowSet</code>
* connection management to a {@code SyncProvider} object provided by the
* {@code SyncFactory}. To ensure fully disconnected semantics, all
* disconnected {@code RowSet} objects <b>must</b> ensure
* that the original connection made to the data source to populate the {@code RowSet}
* object is closed to permit the garbage collector to recover and release resources. The
* <code>SyncProvider</code> object ensures that the critical JDBC properties are
* {@code SyncProvider} object ensures that the critical JDBC properties are
* maintained in order to re-establish a connection to the data source when a
* synchronization is required. A disconnected <code>RowSet</code> object should
* synchronization is required. A disconnected {@code RowSet} object should
* therefore ensure that no
* extraneous references remain on the <code>Connection</code> object.
* extraneous references remain on the {@code Connection} object.
*
* <li><b>3.5 Role of RowSetMetaDataImpl</b>
* <p>
* The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
* The {@code RowsetMetaDataImpl} class is a utility class that provides an implementation of the
* <a href="{@docRoot}/java.sql/javax/sql/RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
* method implementations for metadata for both connected and disconnected
* <code>RowSet</code> objects. All implementations are free to use this standard
* {@code RowSet} objects. All implementations are free to use this standard
* implementation but are not required to do so.
*
* <li><b>3.6 RowSetWarning Class</b>
* <p>
* The <code>RowSetWarning</code> class provides warnings that can be set
* on <code>RowSet</code> implementations.
* The {@code RowSetWarning} class provides warnings that can be set
* on {@code RowSet} implementations.
* Similar to <a href="{@docRoot}/java.sql/java/sql/SQLWarning.html">SQLWarning</a> objects,
* <code>RowSetWarning</code> objects are silently chained to the object whose method
* caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>
* {@code RowSetWarning} objects are silently chained to the object whose method
* caused the warning to be thrown. All {@code RowSet} implementations <b>should</b>
* ensure that this chaining occurs if a warning is generated and also ensure that the
* warnings are available via the <code>getRowSetWarnings</code> method defined in either
* the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface.
* warnings are available via the {@code getRowSetWarnings} method defined in either
* the {@code JdbcRowSet} interface or the {@code CachedRowSet} interface.
* After a warning has been retrieved with one of the
* <code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
* <code>getNextWarning</code> can be called on it to retrieve any warnings that might
* be chained on it. If a warning is returned, <code>getNextWarning</code> can be called
* {@code getRowSetWarnings} methods, the {@code RowSetWarning} method
* {@code getNextWarning} can be called on it to retrieve any warnings that might
* be chained on it. If a warning is returned, {@code getNextWarning} can be called
* on it, and so on until there are no more warnings.
*
* <li><b>3.7 The Joinable Interface</b>
* <P>
* The <code>Joinable</code> interface provides both connected and disconnected
* <code>RowSet</code> objects with the capability to be added to a
* <code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
* A <code>RowSet</code> object that has implemented the <code>Joinable</code>
* The {@code Joinable} interface provides both connected and disconnected
* {@code RowSet} objects with the capability to be added to a
* {@code JoinRowSet} object in an SQL {@code JOIN} operation.
* A {@code RowSet} object that has implemented the {@code Joinable}
* interface can set a match column, retrieve a match column, or unset a match column.
* A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
* match column as a basis for adding the <code>RowSet</code> object.
* A {@code JoinRowSet} object can then use the {@code RowSet} object's
* match column as a basis for adding the {@code RowSet} object.
* </li>
*
* <li><b>3.8 The RowSetFactory Interface</b>
* <p>
* A <code>RowSetFactory</code> implementation <strong>must</strong>
* A {@code RowSetFactory} implementation <strong>must</strong>
* be provided.
* </li>
* </ul>

129
src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@ -26,11 +26,11 @@
/**
* Provides utility classes to allow serializable mappings between SQL types
* and data types in the Java programming language.
* <p> Standard JDBC <code>RowSet</code> implementations may use these utility
* <p> Standard JDBC {@code RowSet} implementations may use these utility
* classes to
* assist in the serialization of disconnected <code>RowSet</code> objects.
* assist in the serialization of disconnected {@code RowSet} objects.
* This is useful
* when transmitting a disconnected <code>RowSet</code> object over the wire to
* when transmitting a disconnected {@code RowSet} object over the wire to
* a different VM or across layers within an application.<br>
* </p>
*
@ -38,40 +38,40 @@
* A serializable mapping in the Java programming language of an SQL ARRAY
* value. <br>
* <br>
* The <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
* The {@code SerialArray} class provides a constructor for creating a {@code SerialArray}
* instance from an Array object, methods for getting the base type and
* the SQL name for the base type, and methods for copying all or part of a
* <code>SerialArray</code> object. <br>
* {@code SerialArray} object. <br>
*
* <h2>2.0 SerialBlob</h2>
* A serializable mapping in the Java programming language of an SQL BLOB
* value. <br>
* <br>
* The <code>SerialBlob</code>class provides a constructor for creating an instance
* The {@code SerialBlob} class provides a constructor for creating an instance
* from a Blob object. Note that the Blob object should have brought the SQL
* BLOB value's data over to the client before a <code>SerialBlob</code>object
* BLOB value's data over to the client before a {@code SerialBlob} object
* is constructed from it. The data of an SQL BLOB value can be materialized
* on the client as an array of bytes (using the method <code>Blob.getBytes</code>)
* or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
* on the client as an array of bytes (using the method {@code Blob.getBytes})
* or as a stream of uninterpreted bytes (using the method {@code Blob.getBinaryStream}).
* <br>
* <br>
* <code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
* {@code SerialBlob} methods make it possible to make a copy of a {@code SerialBlob}
* object as an array of bytes or as a stream. They also make it possible
* to locate a given pattern of bytes or a <code>Blob</code> object within a <code>SerialBlob</code>
* to locate a given pattern of bytes or a {@code Blob} object within a {@code SerialBlob}
* object. <br>
*
* <h2>3.0 SerialClob</h2>
* A serializable mapping in the Java programming language of an SQL CLOB
* value. <br>
* <br>
* The <code>SerialClob</code> class provides a constructor for creating an instance
* from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
* brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
* The {@code SerialClob} class provides a constructor for creating an instance
* from a {@code Clob} object. Note that the {@code Clob} object should have
* brought the SQL CLOB value's data over to the client before a {@code SerialClob}
* object is constructed from it. The data of an SQL CLOB value can be
* materialized on the client as a stream of Unicode characters. <br>
* <br>
* <code>SerialClob</code> methods make it possible to get a substring from a
* <code>SerialClob</code> object or to locate the start of a pattern of characters.
* {@code SerialClob} methods make it possible to get a substring from a
* {@code SerialClob} object or to locate the start of a pattern of characters.
* <br>
*
* <h2>5.0 SerialDatalink</h2>
@ -79,11 +79,12 @@
* value. A DATALINK value references a file outside of the underlying data source
* that the originating data source manages. <br>
* <br>
* <code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
* a <code>java.net.URL</code> object, which can be used to manipulate the external data.
* {@code RowSet} implementations can use the method {@code RowSet.getURL()} to retrieve
* a {@code java.net.URL} object, which can be used to manipulate the external data.
* <br>
* <br>
* &nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</code><br>
* <PRE>
* java.net.URL url = rowset.getURL(1);
* </PRE>
*
* <h2>6.0 SerialJavaObject</h2>
* A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
@ -94,15 +95,15 @@
* object is not immediately serializable, this class will attempt to serialize
* all non static members to permit the object instance state to be serialized.
* Static or transient fields cannot be serialized and attempting to do so
* will result in a <code>SerialException</code> being thrown. <br>
* will result in a {@code SerialException} being thrown. <br>
*
* <h2>7.0 SerialRef</h2>
* A serializable mapping between the SQL REF type and the Java programming
* language. <br>
* <br>
* The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
* instance from a <code>Ref</code> type and provides methods for getting
* and setting the <code>Ref</code> object type. <br>
* The {@code SerialRef} class provides a constructor for creating a {@code SerialRef}
* instance from a {@code Ref} type and provides methods for getting
* and setting the {@code Ref} object type. <br>
*
* <h2>8.0 SerialStruct</h2>
* A serializable mapping in the Java programming language of an SQL structured
@ -110,36 +111,36 @@
* form, and if an attribute is itself a structured type, each of its attributes
* that is not already serializable is mapped to a serializable form. <br>
* <br>
* In addition, if a <code>Map</code> object is passed to one of the constructors or
* to the method <code>getAttributes</code>, the structured type is custom mapped
* according to the mapping specified in the <code>Map</code> object.
* In addition, if a {@code Map} object is passed to one of the constructors or
* to the method {@code getAttributes}, the structured type is custom mapped
* according to the mapping specified in the {@code Map} object.
* <br>
* The <code>SerialStruct</code> class provides a constructor for creating an
* instance from a <code>Struct</code> object, a method for retrieving the SQL
* The {@code SerialStruct} class provides a constructor for creating an
* instance from a {@code Struct} object, a method for retrieving the SQL
* type name of the SQL structured type in the database, and methods for retrieving
* its attribute values. <br>
*
* <h2>9.0 SQLInputImpl</h2>
* An input stream used for custom mapping user-defined types (UDTs). An
* <code>SQLInputImpl</code> object is an input stream that contains a stream of
* {@code SQLInputImpl} object is an input stream that contains a stream of
* values that are
* the attributes of a UDT. This class is used by the driver behind the scenes
* when the method <code>getObject</code> is called on an SQL structured or distinct
* type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
* when the method {@code getObject} is called on an SQL structured or distinct
* type that has a custom mapping; a programmer never invokes {@code SQLInputImpl}
* methods directly. <br>
* <br>
* The <code>SQLInputImpl</code> class provides a set of reader methods
* analogous to the <code>ResultSet</code> getter methods. These methods make it
* possible to read the values in an <code>SQLInputImpl</code> object. The method
* <code>wasNull</code> is used to determine whether the last value read was SQL NULL.
* The {@code SQLInputImpl} class provides a set of reader methods
* analogous to the {@code ResultSet} getter methods. These methods make it
* possible to read the values in an {@code SQLInputImpl} object. The method
* {@code wasNull} is used to determine whether the last value read was SQL NULL.
* <br>
* <br>
* When a constructor or getter method that takes a <code>Map</code> object is called,
* When a constructor or getter method that takes a {@code Map} object is called,
* the JDBC driver calls the method
* <code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom
* mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
* {@code SQLData.getSQLType} to determine the SQL type of the UDT being custom
* mapped. The driver creates an instance of {@code SQLInputImpl}, populating it with
* the attributes of the UDT. The driver then passes the input stream to the
* method <code>SQLData.readSQL</code>, which in turn calls the <code>SQLInputImpl</code>
* method {@code SQLData.readSQL}, which in turn calls the {@code SQLInputImpl}
* methods to read the attributes from the input stream. <br>
*
* <h2>10.0 SQLOutputImpl</h2>
@ -148,16 +149,16 @@
* and its methods are never directly invoked by an application programmer.
* <br>
* <br>
* When an application calls the method <code>PreparedStatement.setObject</code>, the
* When an application calls the method {@code PreparedStatement.setObject}, the
* driver checks to see whether the value to be written is a UDT with a custom
* mapping. If it is, there will be an entry in a type map containing the Class
* object for the class that implements <code>SQLData</code> for this UDT. If the
* value to be written is an instance of <code>SQLData</code>, the driver will
* create an instance of <code>SQLOutputImpl</code> and pass it to the method
* <code>SQLData.writeSQL</code>.
* The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
* writer methods to write data from the <code>SQLData</code> object to the
* <code>SQLOutputImpl</code>
* object for the class that implements {@code SQLData} for this UDT. If the
* value to be written is an instance of {@code SQLData}, the driver will
* create an instance of {@code SQLOutputImpl} and pass it to the method
* {@code SQLData.writeSQL}.
* The method {@code writeSQL} in turn calls the appropriate {@code SQLOutputImpl}
* writer methods to write data from the {@code SQLData} object to the
* {@code SQLOutputImpl}
* output stream as the representation of an SQL user-defined type.
*
* <h2>Custom Mapping</h2>
@ -167,12 +168,12 @@
* (A DISTINCT type can thought of as having one attribute.) However, there are
* many other possibilities, and there may be any number of different mappings.
* <P>
* A programmer defines the mapping by implementing the interface <code>SQLData</code>.
* A programmer defines the mapping by implementing the interface {@code SQLData}.
* For example, if an SQL structured type named AUTHORS has the attributes NAME,
* TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
* Authors class could have the fields name, title, and publisher, to which the
* attributes of AUTHORS are mapped. In such a case, the implementation of
* <code>SQLData</code> could look like the following:
* {@code SQLData} could look like the following:
* <PRE>
* public class Authors implements SQLData {
* public String name;
@ -200,27 +201,27 @@
* }
* </PRE>
*
* A <code>java.util.Map</code> object is used to associate the SQL structured
* type with its mapping to the class <code>Authors</code>. The following code fragment shows
* how a <code>Map</code> object might be created and given an entry associating
* <code>AUTHORS</code> and <code>Authors</code>.
* A {@code java.util.Map} object is used to associate the SQL structured
* type with its mapping to the class {@code Authors}. The following code fragment shows
* how a {@code Map} object might be created and given an entry associating
* {@code AUTHORS} and {@code Authors}.
* <PRE>
* java.util.Map map = new java.util.HashMap();
* map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
* </PRE>
*
* The <code>Map</code> object <i>map</i> now contains an entry with the
* fully qualified name of the SQL structured type and the <code>Class</code>
* object for the class <code>Authors</code>. It can be passed to a method
* to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
* The {@code Map} object <i>map</i> now contains an entry with the
* fully qualified name of the SQL structured type and the {@code Class}
* object for the class {@code Authors}. It can be passed to a method
* to tell the driver how to map {@code AUTHORS} to {@code Authors}.
* <P>
* For a disconnected <code>RowSet</code> object, custom mapping can be done
* only when a <code>Map</code> object is passed to the method or constructor
* For a disconnected {@code RowSet} object, custom mapping can be done
* only when a {@code Map} object is passed to the method or constructor
* that will be doing the custom mapping. The situation is different for
* connected <code>RowSet</code> objects because they maintain a connection
* connected {@code RowSet} objects because they maintain a connection
* with the data source. A method that does custom mapping and is called by
* a disconnected <code>RowSet</code> object may use the <code>Map</code>
* object that is associated with the <code>Connection</code> object being
* a disconnected {@code RowSet} object may use the {@code Map}
* object that is associated with the {@code Connection} object being
* used. So, in other words, if no map is specified, the connection's type
* map can be used by default.
*/

332
src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@ -27,9 +27,9 @@
* The standard classes and interfaces that a third party vendor has to
* use in its implementation of a synchronization provider. These classes and
* interfaces are referred to as the Service Provider Interface (SPI). To make it possible
* for a <code>RowSet</code> object to use an implementation, the vendor must register
* it with the <code>SyncFactory</code> singleton. (See the class comment for
* <code>SyncProvider</code> for a full explanation of the registration process and
* for a {@code RowSet} object to use an implementation, the vendor must register
* it with the {@code SyncFactory} singleton. (See the class comment for
* {@code SyncProvider} for a full explanation of the registration process and
* the naming convention to be used.)
*
* <h2>Table of Contents</h2>
@ -44,46 +44,46 @@
*
* <h3><a id="pkgspec">1.0 Package Specification</a></h3>
* <P>
* The following classes and interfaces make up the <code>javax.sql.rowset.spi</code>
* The following classes and interfaces make up the {@code javax.sql.rowset.spi}
* package:
* <UL>
* <LI><code>SyncFactory</code>
* <LI><code>SyncProvider</code>
* <LI><code>SyncFactoryException</code>
* <LI><code>SyncProviderException</code>
* <LI><code>SyncResolver</code>
* <LI><code>XmlReader</code>
* <LI><code>XmlWriter</code>
* <LI><code>TransactionalWriter</code>
* <LI>{@code SyncFactory}
* <LI>{@code SyncProvider}
* <LI>{@code SyncFactoryException}
* <LI>{@code SyncProviderException}
* <LI>{@code SyncResolver}
* <LI>{@code XmlReader}
* <LI>{@code XmlWriter}
* <LI>{@code TransactionalWriter}
* </UL>
* The following interfaces, in the <code>javax.sql</code> package, are also part of the SPI:
* The following interfaces, in the {@code javax.sql} package, are also part of the SPI:
* <UL>
* <LI><code>RowSetReader</code>
* <LI><code>RowSetWriter</code>
* <LI>{@code RowSetReader}
* <LI>{@code RowSetWriter}
* </UL>
* <P>
* A <code>SyncProvider</code> implementation provides a disconnected <code>RowSet</code>
* A {@code SyncProvider} implementation provides a disconnected {@code RowSet}
* object with the mechanisms for reading data into it and for writing data that has been
* modified in it
* back to the underlying data source. A <i>reader</i>, a <code>RowSetReader</code> or
* <code>XMLReader</code> object, reads data into a <code>RowSet</code> object when the
* <code>CachedRowSet</code> methods <code>execute</code> or <code>populate</code>
* are called. A <i>writer</i>, a <code>RowSetWriter</code> or <code>XMLWriter</code>
* back to the underlying data source. A <i>reader</i>, a {@code RowSetReader} or
* {@code XMLReader} object, reads data into a {@code RowSet} object when the
* {@code CachedRowSet} methods {@code execute} or {@code populate}
* are called. A <i>writer</i>, a {@code RowSetWriter} or {@code XMLWriter}
* object, writes changes back to the underlying data source when the
* <code>CachedRowSet</code> method <code>acceptChanges</code> is called.
* {@code CachedRowSet} method {@code acceptChanges} is called.
* <P>
* The process of writing changes in a <code>RowSet</code> object to its data source
* is known as <i>synchronization</i>. The <code>SyncProvider</code> implementation that a
* <code>RowSet</code> object is using determines the level of synchronization that the
* <code>RowSet</code> object's writer uses. The various levels of synchronization are
* The process of writing changes in a {@code RowSet} object to its data source
* is known as <i>synchronization</i>. The {@code SyncProvider} implementation that a
* {@code RowSet} object is using determines the level of synchronization that the
* {@code RowSet} object's writer uses. The various levels of synchronization are
* referred to as <i>grades</i>.
* <P>
* The lower grades of synchronization are
* known as <i>optimistic</i> concurrency levels because they optimistically
* assume that there will be no conflicts or very few conflicts. A conflict exists when
* the same data modified in the <code>RowSet</code> object has also been modified
* the same data modified in the {@code RowSet} object has also been modified
* in the data source. Using the optimistic concurrency model means that if there
* is a conflict, modifications to either the data source or the <code>RowSet</code>
* is a conflict, modifications to either the data source or the {@code RowSet}
* object will be lost.
* <P>
* Higher grades of synchronization are called <i>pessimistic</i> because they assume
@ -92,114 +92,114 @@
* occur.
* <P>
* The lowest level of synchronization is simply writing any changes made to the
* <code>RowSet</code> object to its underlying data source. The writer does
* {@code RowSet} object to its underlying data source. The writer does
* nothing to check for conflicts.
* If there is a conflict and the data
* source values are overwritten, the changes other parties have made by to the data
* source are lost.
* <P>
* The <code>RIXMLProvider</code> implementation uses the lowest level
* of synchronization and just writes <code>RowSet</code> changes to the data source.
* The {@code RIXMLProvider} implementation uses the lowest level
* of synchronization and just writes {@code RowSet} changes to the data source.
*
* <P>
* For the next level up, the
* writer checks to see if there are any conflicts, and if there are,
* it does not write anything to the data source. The problem with this concurrency
* level is that if another party has modified the corresponding data in the data source
* since the <code>RowSet</code> object got its data,
* the changes made to the <code>RowSet</code> object are lost. The
* <code>RIOptimisticProvider</code> implementation uses this level of synchronization.
* since the {@code RowSet} object got its data,
* the changes made to the {@code RowSet} object are lost. The
* {@code RIOptimisticProvider} implementation uses this level of synchronization.
* <P>
* At higher levels of synchronization, referred to as pessimistic concurrency,
* the writer take steps to avoid conflicts by setting locks. Setting locks
* can vary from setting a lock on a single row to setting a lock on a table
* or the entire data source. The level of synchronization is therefore a tradeoff
* between the ability of users to access the data source concurrently and the ability
* of the writer to keep the data in the <code>RowSet</code> object and its data source
* of the writer to keep the data in the {@code RowSet} object and its data source
* synchronized.
* <P>
* It is a requirement that all disconnected <code>RowSet</code> objects
* (<code>CachedRowSet</code>, <code>FilteredRowSet</code>, <code>JoinRowSet</code>,
* and <code>WebRowSet</code> objects) obtain their <code>SyncProvider</code> objects
* from the <code>SyncFactory</code> mechanism.
* It is a requirement that all disconnected {@code RowSet} objects
* ({@code CachedRowSet}, {@code FilteredRowSet}, {@code JoinRowSet},
* and {@code WebRowSet} objects) obtain their {@code SyncProvider} objects
* from the {@code SyncFactory} mechanism.
* <P>
* The reference implementation (RI) provides two synchronization providers.
* <UL>
* <LI><b><code>RIOptimisticProvider</code></b> <br>
* The default provider that the <code>SyncFactory</code> instance will
* supply to a disconnected <code>RowSet</code> object when no provider
* <LI><b>{@code RIOptimisticProvider}</b> <br>
* The default provider that the {@code SyncFactory} instance will
* supply to a disconnected {@code RowSet} object when no provider
* implementation is specified.<BR>
* This synchronization provider uses an optimistic concurrency model,
* assuming that there will be few conflicts among users
* who are accessing the same data in a database. It avoids
* using locks; rather, it checks to see if there is a conflict
* before trying to synchronize the <code>RowSet</code> object and the
* before trying to synchronize the {@code RowSet} object and the
* data source. If there is a conflict, it does nothing, meaning that
* changes to the <code>RowSet</code> object are not persisted to the data
* changes to the {@code RowSet} object are not persisted to the data
* source.
* <LI><B><code>RIXMLProvider</code></B> <BR>
* <LI><B>{@code RIXMLProvider}</B> <BR>
* A synchronization provider that can be used with a
* <code>WebRowSet</code> object, which is a rowset that can be written
* {@code WebRowSet} object, which is a rowset that can be written
* in XML format or read from XML format. The
* <code>RIXMLProvider</code> implementation does no checking at all for
* {@code RIXMLProvider} implementation does no checking at all for
* conflicts and simply writes any updated data in the
* <code>WebRowSet</code> object to the underlying data source.
* <code>WebRowSet</code> objects use this provider when they are
* {@code WebRowSet} object to the underlying data source.
* {@code WebRowSet} objects use this provider when they are
* dealing with XML data.
* </UL>
*
* These <code>SyncProvider</code> implementations
* These {@code SyncProvider} implementations
* are bundled with the reference implementation, which makes them always available to
* <code>RowSet</code> implementations.
* <code>SyncProvider</code> implementations make themselves available by being
* registered with the <code>SyncFactory</code> singleton. When a <code>RowSet</code>
* {@code RowSet} implementations.
* {@code SyncProvider} implementations make themselves available by being
* registered with the {@code SyncFactory} singleton. When a {@code RowSet}
* object requests a provider, by specifying it in the constructor or as an argument to the
* <code>CachedRowSet</code> method <code>setSyncProvider</code>,
* the <code>SyncFactory</code> singleton
* {@code CachedRowSet} method {@code setSyncProvider},
* the {@code SyncFactory} singleton
* checks to see if the requested provider has been registered with it.
* If it has, the <code>SyncFactory</code> creates an instance of it and passes it to the
* requesting <code>RowSet</code> object.
* If the <code>SyncProvider</code> implementation that is specified has not been registered,
* the <code>SyncFactory</code> singleton causes a <code>SyncFactoryException</code> object
* If it has, the {@code SyncFactory} creates an instance of it and passes it to the
* requesting {@code RowSet} object.
* If the {@code SyncProvider} implementation that is specified has not been registered,
* the {@code SyncFactory} singleton causes a {@code SyncFactoryException} object
* to be thrown. If no provider is specified,
* the <code>SyncFactory</code> singleton will create an instance of the default
* provider implementation, <code>RIOptimisticProvider</code>,
* and pass it to the requesting <code>RowSet</code> object.
* the {@code SyncFactory} singleton will create an instance of the default
* provider implementation, {@code RIOptimisticProvider},
* and pass it to the requesting {@code RowSet} object.
*
* <P>
* If a <code>WebRowSet</code> object does not specify a provider in its constructor, the
* <code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>.
* However, the constructor for <code>WebRowSet</code> is implemented to set the provider
* to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object
* If a {@code WebRowSet} object does not specify a provider in its constructor, the
* {@code SyncFactory} will give it an instance of {@code RIOptimisticProvider}.
* However, the constructor for {@code WebRowSet} is implemented to set the provider
* to the {@code RIXMLProvider}, which reads and writes a {@code RowSet} object
* in XML format.
* <P>
* See the <a href="SyncProvider.html">SyncProvider</a> class
* specification for further details.
* <p>
* Vendors may develop a <code>SyncProvider</code> implementation with any one of the possible
* levels of synchronization, thus giving <code>RowSet</code> objects a choice of
* Vendors may develop a {@code SyncProvider} implementation with any one of the possible
* levels of synchronization, thus giving {@code RowSet} objects a choice of
* synchronization mechanisms.
*
* <h3><a id="arch">2.0 Service Provider Interface Architecture</a></h3>
* <b>2.1 Overview</b>
* <p>
* The Service Provider Interface provides a pluggable mechanism by which
* <code>SyncProvider</code> implementations can be registered and then generated when
* required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits
* {@code SyncProvider} implementations can be registered and then generated when
* required. The lazy reference mechanism employed by the {@code SyncFactory} limits
* unnecessary resource consumption by not creating an instance until it is
* required by a disconnected
* <code>RowSet</code> object. The <code>SyncFactory</code> class also provides
* {@code RowSet} object. The {@code SyncFactory} class also provides
* a standard API to configure logging options and streams that <b>may</b> be provided
* by a particular <code>SyncProvider</code> implementation.
* by a particular {@code SyncProvider} implementation.
* <p>
* <b>2.2 Registering with the <code>SyncFactory</code></b>
* <b>2.2 Registering with the {@code SyncFactory}</b>
* <p>
* A third party <code>SyncProvider</code> implementation must be registered with the
* <code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object
* to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and
* <code>javax.sql.RowSetWriter</code>
* A third party {@code SyncProvider} implementation must be registered with the
* {@code SyncFactory} in order for a disconnected {@code RowSet} object
* to obtain it and thereby use its {@code javax.sql.RowSetReader} and
* {@code javax.sql.RowSetWriter}
* implementations. The following registration mechanisms are available to all
* <code>SyncProvider</code> implementations:
* {@code SyncProvider} implementations:
* <ul>
* <li><b>System properties</b> - Properties set at the command line. These
* properties are set at run time and apply system-wide per invocation of the Java
@ -210,159 +210,159 @@
* This can be specified using a System Property or by modifying a standard
* property file located in the platform run-time. The
* reference implementation of this technology includes a standard property
* file than can be edited to add additional <code>SyncProvider</code> objects.
* file than can be edited to add additional {@code SyncProvider} objects.
*
* <li><b>JNDI Context</b> - Available providers can be registered on a JNDI
* context. The <code>SyncFactory</code> will attempt to load <code>SyncProvider</code>
* context. The {@code SyncFactory} will attempt to load {@code SyncProvider}
* objects bound to the context and register them with the factory. This
* context must be supplied to the <code>SyncFactory</code> for the mechanism to
* context must be supplied to the {@code SyncFactory} for the mechanism to
* function correctly.
* </ul>
* <p>
* Details on how to specify the system properties or properties in a property file
* and how to configure the JNDI Context are explained in detail in the
* <a href="SyncFactory.html"><code>SyncFactory</code></a> class description.
* <a href="SyncFactory.html">{@code SyncFactory}</a> class description.
* <p>
* <b>2.3 SyncFactory Provider Instance Generation Policies</b>
* <p>
* The <code>SyncFactory</code> generates a requested <code>SyncProvider</code>
* The {@code SyncFactory} generates a requested {@code SyncProvider}
* object if the provider has been correctly registered. The
* following policies are adhered to when either a disconnected <code>RowSet</code> object
* is instantiated with a specified <code>SyncProvider</code> implementation or is
* reconfigured at runtime with an alternative <code>SyncProvider</code> object.
* following policies are adhered to when either a disconnected {@code RowSet} object
* is instantiated with a specified {@code SyncProvider} implementation or is
* reconfigured at runtime with an alternative {@code SyncProvider} object.
* <ul>
* <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
* contains <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is
* <li> If a {@code SyncProvider} object is specified and the {@code SyncFactory}
* contains <i>no</i> reference to the provider, a {@code SyncFactoryException} is
* thrown.
*
* <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
* <li> If a {@code SyncProvider} object is specified and the {@code SyncFactory}
* contains a reference to the provider, the requested provider is supplied.
*
* <li> If no <code>SyncProvider</code> object is specified, the reference
* implementation provider <code>RIOptimisticProvider</code> is supplied.
* <li> If no {@code SyncProvider} object is specified, the reference
* implementation provider {@code RIOptimisticProvider} is supplied.
* </ul>
* <p>
* These policies are explored in more detail in the <a href="SyncFactory.html">
* <code>SyncFactory</code></a> class.
* {@code SyncFactory}</a> class.
*
* <h3><a id="impl">3.0 SyncProvider Implementer's Guide</a></h3>
*
* <b>3.1 Requirements</b>
* <p>
* A compliant <code>SyncProvider</code> implementation that is fully pluggable
* into the <code>SyncFactory</code> <b>must</b> extend and implement all
* abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a>
* A compliant {@code SyncProvider} implementation that is fully pluggable
* into the {@code SyncFactory} <b>must</b> extend and implement all
* abstract methods in the <a href="SyncProvider.html">{@code SyncProvider}</a>
* class. In addition, an implementation <b>must</b> determine the
* grade, locking and updatable view capabilities defined in the
* <code>SyncProvider</code> class definition. One or more of the
* <code>SyncProvider</code> description criteria <b>must</b> be supported. It
* {@code SyncProvider} class definition. One or more of the
* {@code SyncProvider} description criteria <b>must</b> be supported. It
* is expected that vendor implementations will offer a range of grade, locking, and
* updatable view capabilities.
* <p>
* Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as
* detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class
* Furthermore, the {@code SyncProvider} naming convention <b>must</b> be followed as
* detailed in the <a href="SyncProvider.html">{@code SyncProvider}</a> class
* description.
* <p>
* <b>3.2 Grades</b>
* <p>
* JSR 114 defines a set of grades to describe the quality of synchronization
* a <code>SyncProvider</code> object can offer a disconnected <code>RowSet</code>
* a {@code SyncProvider} object can offer a disconnected {@code RowSet}
* object. These grades are listed from the lowest quality of service to the highest.
* <ul>
* <li><b>GRADE_NONE</b> - No synchronization with the originating data source is
* provided. A <code>SyncProvider</code> implementation returning this grade will simply
* attempt to write any data that has changed in the <code>RowSet</code> object to the
* provided. A {@code SyncProvider} implementation returning this grade will simply
* attempt to write any data that has changed in the {@code RowSet} object to the
*underlying data source, overwriting whatever is there. No attempt is made to compare
* original values with current values to see if there is a conflict. The
* <code>RIXMLProvider</code> is implemented with this grade.
* {@code RIXMLProvider} is implemented with this grade.
*
* <li><b>GRADE_CHECK_MODIFIED_AT_COMMIT</b> - A low grade of optimistic synchronization.
* A <code>SyncProvider</code> implementation returning this grade
* A {@code SyncProvider} implementation returning this grade
* will check for conflicts in rows that have changed between the last synchronization
* and the current synchronization under way. Any changes in the originating data source
* that have been modified will not be reflected in the disconnected <code>RowSet</code>
* object. If there are no conflicts, changes in the <code>RowSet</code> object will be
* that have been modified will not be reflected in the disconnected {@code RowSet}
* object. If there are no conflicts, changes in the {@code RowSet} object will be
* written to the data source. If there are conflicts, no changes are written.
* The <code>RIOptimisticProvider</code> implementation uses this grade.
* The {@code RIOptimisticProvider} implementation uses this grade.
*
* <li><b>GRADE_CHECK_ALL_AT_COMMIT</b> - A high grade of optimistic synchronization.
* A <code>SyncProvider</code> implementation returning this grade
* A {@code SyncProvider} implementation returning this grade
* will check all rows, including rows that have not changed in the disconnected
* <code>RowSet</code> object. In this way, any changes to rows in the underlying
* data source will be reflected in the disconnected <code>RowSet</code> object
* {@code RowSet} object. In this way, any changes to rows in the underlying
* data source will be reflected in the disconnected {@code RowSet} object
* when the synchronization finishes successfully.
*
* <li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization.
* <code>SyncProvider</code> implementations returning this grade will lock
* {@code SyncProvider} implementations returning this grade will lock
* the row in the originating data source that corresponds to the row being changed
* in the <code>RowSet</code> object to reduce the possibility of other
* in the {@code RowSet} object to reduce the possibility of other
* processes modifying the same data in the data source.
*
* <li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade.
* A <code>SyncProvider</code> implementation returning this grade will lock
* A {@code SyncProvider} implementation returning this grade will lock
* the entire view and/or table affected by the original query used to
* populate a <code>RowSet</code> object.
* populate a {@code RowSet} object.
* </ul>
* <p>
* <b>3.3 Locks</b>
* <p>
* JSR 114 defines a set of constants that specify whether any locks have been
* placed on a <code>RowSet</code> object's underlying data source and, if so,
* placed on a {@code RowSet} object's underlying data source and, if so,
* on which constructs the locks are placed. These locks will remain on the data
* source while the <code>RowSet</code> object is disconnected from the data source.
* source while the {@code RowSet} object is disconnected from the data source.
* <P>
* These constants <b>should</b> be considered complementary to the
* grade constants. The default setting for the majority of grade settings requires
* that no data source locks remain when a <code>RowSet</code> object is disconnected
* that no data source locks remain when a {@code RowSet} object is disconnected
* from its data source.
* The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and
* <code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object
* The grades {@code GRADE_LOCK_WHEN_MODIFIED} and
* {@code GRADE_LOCK_WHEN_LOADED} allow a disconnected {@code RowSet} object
* to have a fine-grained control over the degree of locking.
* <ul>
* <li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source.
* This is the default lock setting for all <code>SyncProvider</code> implementations
* unless otherwise directed by a <code>RowSet</code> object.
* This is the default lock setting for all {@code SyncProvider} implementations
* unless otherwise directed by a {@code RowSet} object.
*
* <li><b>DATASOURCE_ROW_LOCK</b> - A lock is placed on the rows that are touched by
* the original SQL query used to populate the <code>RowSet</code> object.
* the original SQL query used to populate the {@code RowSet} object.
*
* <li><b>DATASOURCE_TABLE_LOCK</b> - A lock is placed on all tables that are touched
* by the query that was used to populate the <code>RowSet</code> object.
* by the query that was used to populate the {@code RowSet} object.
*
* <li><b>DATASOURCE_DB_LOCK</b>
* A lock is placed on the entire data source that is used by the <code>RowSet</code>
* A lock is placed on the entire data source that is used by the {@code RowSet}
* object.
* </ul>
* <p>
* <b>3.4 Updatable Views</b>
* <p>
* A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>.
* The following constants indicate whether a <code>SyncProvider</code> object can
* update data in the table or tables from which the <code>VIEW</code> was derived.
* A {@code RowSet} object may be populated with data from an SQL {@code VIEW}.
* The following constants indicate whether a {@code SyncProvider} object can
* update data in the table or tables from which the {@code VIEW} was derived.
* <ul>
* <li><b>UPDATABLE_VIEW_SYNC</b>
* Indicates that a <code>SyncProvider</code> implementation supports synchronization
* to the table or tables from which the SQL <code>VIEW</code> used to populate
* a <code>RowSet</code> object is derived.
* Indicates that a {@code SyncProvider} implementation supports synchronization
* to the table or tables from which the SQL {@code VIEW} used to populate
* a {@code RowSet} object is derived.
*
* <li><b>NONUPDATABLE_VIEW_SYNC</b>
* Indicates that a <code>SyncProvider</code> implementation does <b>not</b> support
* synchronization to the table or tables from which the SQL <code>VIEW</code>
* used to populate a <code>RowSet</code> object is derived.
* Indicates that a {@code SyncProvider} implementation does <b>not</b> support
* synchronization to the table or tables from which the SQL {@code VIEW}
* used to populate a {@code RowSet} object is derived.
* </ul>
* <p>
* <b>3.5 Usage of <code>SyncProvider</code> Grading and Locking</b>
* <b>3.5 Usage of {@code SyncProvider} Grading and Locking</b>
* <p>
* In the example below, the reference <code>CachedRowSetImpl</code> implementation
* reconfigures its current <code>SyncProvider</code> object by calling the
* <code>setSyncProvider</code> method.<br>
* In the example below, the reference {@code CachedRowSetImpl} implementation
* reconfigures its current {@code SyncProvider} object by calling the
* {@code setSyncProvider} method.<br>
*
* <PRE>
* CachedRowSetImpl crs = new CachedRowSetImpl();
* crs.setSyncProvider("com.foo.bar.HASyncProvider");
* </PRE>
* An application can retrieve the <code>SyncProvider</code> object currently in use
* by a disconnected <code>RowSet</code> object. It can also retrieve the
* An application can retrieve the {@code SyncProvider} object currently in use
* by a disconnected {@code RowSet} object. It can also retrieve the
* grade of synchronization with which the provider was implemented and the degree of
* locking currently in use. In addition, an application has the flexibility to set
* the degree of locking to be used, which can increase the possibilities for successful
@ -388,10 +388,10 @@
* break;
* }
*
* switch (sync.getDataSourcLock() {
* switch (sync.getDataSourceLock() {
* case: SyncProvider.DATASOURCE_DB_LOCK
* // A lock is placed on the entire datasource that is used by the
* // <code>RowSet</code> object
* // {@code RowSet} object
* break;
*
* case: SyncProvider.DATASOURCE_NO_LOCK
@ -412,8 +412,8 @@
*
* </PRE>
* It is also possible using the static utility method in the
* <code>SyncFactory</code> class to determine the list of <code>SyncProvider</code>
* implementations currently registered with the <code>SyncFactory</code>.
* {@code SyncFactory} class to determine the list of {@code SyncProvider}
* implementations currently registered with the {@code SyncFactory}.
*
* <pre>
* Enumeration e = SyncFactory.getRegisteredProviders();
@ -422,48 +422,48 @@
*
* <h3><a id="resolving">4.0 Resolving Synchronization Conflicts</a></h3>
*
* The interface <code>SyncResolver</code> provides a way for an application to
* decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code>
* method <code>acceptChanges</code> finishes and has detected one or more conflicts,
* it throws a <code>SyncProviderException</code> object. An application can
* The interface {@code SyncResolver} provides a way for an application to
* decide manually what to do when a conflict occurs. When the {@code CachedRowSet}
* method {@code acceptChanges} finishes and has detected one or more conflicts,
* it throws a {@code SyncProviderException} object. An application can
* catch the exception and
* have it retrieve a <code>SyncResolver</code> object by calling the method
* <code>SyncProviderException.getSyncResolver()</code>.
* have it retrieve a {@code SyncResolver} object by calling the method
* {@code SyncProviderException.getSyncResolver()}.
* <P>
* A <code>SyncResolver</code> object, which is a special kind of
* <code>CachedRowSet</code> object or
* a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code>
* A {@code SyncResolver} object, which is a special kind of
* {@code CachedRowSet} object or
* a {@code JdbcRowSet} object that has implemented the {@code SyncResolver}
* interface, examines the conflicts row by row. It is a duplicate of the
* <code>RowSet</code> object being synchronized except that it contains only the data
* {@code RowSet} object being synchronized except that it contains only the data
* from the data source this is causing a conflict. All of the other column values are
* set to <code>null</code>. To navigate from one conflict value to another, a
* <code>SyncResolver</code> object provides the methods <code>nextConflict</code> and
* <code>previousConflict</code>.
* set to {@code null}. To navigate from one conflict value to another, a
* {@code SyncResolver} object provides the methods {@code nextConflict} and
* {@code previousConflict}.
* <P>
* The <code>SyncResolver</code> interface also
* The {@code SyncResolver} interface also
* provides methods for doing the following:
* <UL>
* <LI>finding out whether the conflict involved an update, a delete, or an insert
* <LI>getting the value in the data source that caused the conflict
* <LI>setting the value that should be in the data source if it needs to be changed
* or setting the value that should be in the <code>RowSet</code> object if it needs
* or setting the value that should be in the {@code RowSet} object if it needs
* to be changed
* </UL>
* <P>
* When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it
* delegates to the <code>RowSet</code> object's <code>SyncProvider</code> object.
* How the writer provided by that <code>SyncProvider</code> object is implemented
* When the {@code CachedRowSet} method {@code acceptChanges} is called, it
* delegates to the {@code RowSet} object's {@code SyncProvider} object.
* How the writer provided by that {@code SyncProvider} object is implemented
* determines what level (grade) of checking for conflicts will be done. After all
* checking for conflicts is completed and one or more conflicts has been found, the method
* <code>acceptChanges</code> throws a <code>SyncProviderException</code> object. The
* application can catch the exception and use it to obtain a <code>SyncResolver</code> object.
* {@code acceptChanges} throws a {@code SyncProviderException} object. The
* application can catch the exception and use it to obtain a {@code SyncResolver} object.
* <P>
* The application can then use <code>SyncResolver</code> methods to get information
* The application can then use {@code SyncResolver} methods to get information
* about each conflict and decide what to do. If the application logic or the user
* decides that a value in the <code>RowSet</code> object should be the one to
* decides that a value in the {@code RowSet} object should be the one to
* persist, the application or user can overwrite the data source value with it.
* <P>
* The comment for the <code>SyncResolver</code> interface has more detail.
* The comment for the {@code SyncResolver} interface has more detail.
*
* <h3><a id="relspec">5.0 Related Specifications</a></h3>
* <ul>

202
src/java.sql/share/classes/java/sql/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2020, 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
@ -34,17 +34,17 @@
* to passing SQL statements to a database, it provides for reading and
* writing data from any data source with a tabular format.
* The reader/writer facility, available through the
* <code>javax.sql.RowSet</code> group of interfaces, can be customized to
* {@code javax.sql.RowSet} group of interfaces, can be customized to
* use and update data from a spread sheet, flat file, or any other tabular
* data source.
*
* <h2>What the JDBC&trade; 4.3 API Includes</h2>
* The JDBC&trade; 4.3 API includes both
* the <code>java.sql</code> package, referred to as the JDBC core API,
* and the <code>javax.sql</code> package, referred to as the JDBC Optional
* the {@code java.sql} package, referred to as the JDBC core API,
* and the {@code javax.sql} package, referred to as the JDBC Optional
* Package API. This complete JDBC API
* is included in the Java&trade; Standard Edition (Java SE&trade;), version 7.
* The <code>javax.sql</code> package extends the functionality of the JDBC API
* The {@code javax.sql} package extends the functionality of the JDBC API
* from a client-side API to a server-side API, and it is an essential part
* of the Java&trade; Enterprise Edition
* (Java EE&trade;) technology.
@ -91,141 +91,141 @@
* check your driver's documentation to see whether it supports a feature before
* you try to use it.
* <P>
* <b>NOTE:</b> The class <code>SQLPermission</code> was added in the
* <b>NOTE:</b> The class {@code SQLPermission} was added in the
* Java&trade; 2 SDK, Standard Edition,
* version 1.3 release. This class is used to prevent unauthorized
* access to the logging stream associated with the <code>DriverManager</code>,
* access to the logging stream associated with the {@code DriverManager},
* which may contain information such as table names, column data, and so on.
*
* <h2>What the <code>java.sql</code> Package Contains</h2>
* The <code>java.sql</code> package contains API for the following:
* <h2>What the {@code java.sql} Package Contains</h2>
* The {@code java.sql} package contains API for the following:
* <UL>
* <LI>Making a connection with a database via the <code>DriverManager</code> facility
* <LI>Making a connection with a database via the {@code DriverManager} facility
* <UL>
* <LI><code>DriverManager</code> class -- makes a connection with a driver
* <LI><code>SQLPermission</code> class -- provides permission when code
* <LI>{@code DriverManager} class -- makes a connection with a driver
* <LI>{@code SQLPermission} class -- provides permission when code
* running within a Security Manager, such as an applet,
* attempts to set up a logging stream through the
* <code>DriverManager</code>
* <LI><code>Driver</code> interface -- provides the API for registering
* {@code DriverManager}
* <LI>{@code Driver} interface -- provides the API for registering
* and connecting drivers based on JDBC technology ("JDBC drivers");
* generally used only by the <code>DriverManager</code> class
* <LI><code>DriverPropertyInfo</code> class -- provides properties for a
* generally used only by the {@code DriverManager} class
* <LI>{@code DriverPropertyInfo} class -- provides properties for a
* JDBC driver; not used by the general user
* </UL>
* <LI>Sending SQL statements to a database
* <UL>
* <LI><code>Statement</code> -- used to send basic SQL statements
* <LI><code>PreparedStatement</code> -- used to send prepared statements or
* basic SQL statements (derived from <code>Statement</code>)
* <LI><code>CallableStatement</code> -- used to call database stored
* procedures (derived from <code>PreparedStatement</code>)
* <LI><code>Connection</code> interface -- provides methods for creating
* <LI>{@code Statement} -- used to send basic SQL statements
* <LI>{@code PreparedStatement} -- used to send prepared statements or
* basic SQL statements (derived from {@code Statement})
* <LI>{@code CallableStatement} -- used to call database stored
* procedures (derived from {@code PreparedStatement})
* <LI>{@code Connection} interface -- provides methods for creating
* statements and managing connections and their properties
* <LI><code>Savepoint</code> -- provides savepoints in a transaction
* <LI>{@code Savepoint} -- provides savepoints in a transaction
*
* </UL>
* <LI>Retrieving and updating the results of a query
* <UL>
* <LI><code>ResultSet</code> interface
* <LI>{@code ResultSet} interface
* </UL>
* <LI>Standard mappings for SQL types to classes and interfaces in the
* Java programming language
* <UL>
* <LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code>
* <LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code>
* <LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code>
* <LI><code>Date</code> class -- mapping for SQL <code>DATE</code>
* <LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code>
* <LI><code>Ref</code> interface -- mapping for SQL <code>REF</code>
* <LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code>
* <LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code>
* <LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code>
* <LI><code>Time</code> class -- mapping for SQL <code>TIME</code>
* <LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code>
* <LI><code>Types</code> class -- provides constants for SQL types
* <LI>{@code Array} interface -- mapping for SQL {@code ARRAY}
* <LI>{@code Blob} interface -- mapping for SQL {@code BLOB}
* <LI>{@code Clob} interface -- mapping for SQL {@code CLOB}
* <LI>{@code Date} class -- mapping for SQL {@code DATE}
* <LI>{@code NClob} interface -- mapping for SQL {@code NCLOB}
* <LI>{@code Ref} interface -- mapping for SQL {@code REF}
* <LI>{@code RowId} interface -- mapping for SQL {@code ROWID}
* <LI>{@code Struct} interface -- mapping for SQL {@code STRUCT}
* <LI>{@code SQLXML} interface -- mapping for SQL {@code XML}
* <LI>{@code Time} class -- mapping for SQL {@code TIME}
* <LI>{@code Timestamp} class -- mapping for SQL {@code TIMESTAMP}
* <LI>{@code Types} class -- provides constants for SQL types
* </UL>
* <LI>Custom mapping an SQL user-defined type (UDT) to a class in the
* Java programming language
* <UL>
* <LI><code>SQLData</code> interface -- specifies the mapping of
* <LI>{@code SQLData} interface -- specifies the mapping of
* a UDT to an instance of this class
* <LI><code>SQLInput</code> interface -- provides methods for reading
* <LI>{@code SQLInput} interface -- provides methods for reading
* UDT attributes from a stream
* <LI><code>SQLOutput</code> interface -- provides methods for writing
* <LI>{@code SQLOutput} interface -- provides methods for writing
* UDT attributes back to a stream
* </UL>
* <LI>Metadata
* <UL>
* <LI><code>DatabaseMetaData</code> interface -- provides information
* <LI>{@code DatabaseMetaData} interface -- provides information
* about the database
* <LI><code>ResultSetMetaData</code> interface -- provides information
* about the columns of a <code>ResultSet</code> object
* <LI><code>ParameterMetaData</code> interface -- provides information
* about the parameters to <code>PreparedStatement</code> commands
* <LI>{@code ResultSetMetaData} interface -- provides information
* about the columns of a {@code ResultSet} object
* <LI>{@code ParameterMetaData} interface -- provides information
* about the parameters to {@code PreparedStatement} commands
* </UL>
* <LI>Exceptions
* <UL>
* <LI><code>SQLException</code> -- thrown by most methods when there
* <LI>{@code SQLException} -- thrown by most methods when there
* is a problem accessing data and by some methods for other reasons
* <LI><code>SQLWarning</code> -- thrown to indicate a warning
* <LI><code>DataTruncation</code> -- thrown to indicate that data may have
* <LI>{@code SQLWarning} -- thrown to indicate a warning
* <LI>{@code DataTruncation} -- thrown to indicate that data may have
* been truncated
* <LI><code>BatchUpdateException</code> -- thrown to indicate that not all
* <LI>{@code BatchUpdateException} -- thrown to indicate that not all
* commands in a batch update executed successfully
* </UL>
* </UL>
*
* <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.3 API</h3>
* <h3>{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.3 API</h3>
* <UL>
* <LI>Added <code>Sharding</code> support</LI>
* <LI>Enhanced <code>Connection</code> to be able to provide hints
* <LI>Added {@code Sharding} support</LI>
* <LI>Enhanced {@code Connection} to be able to provide hints
* to the driver that a request, an independent unit of work,
* is beginning or ending</LI>
* <LI>Enhanced <code>DatabaseMetaData</code> to determine if Sharding is
* <LI>Enhanced {@code DatabaseMetaData} to determine if Sharding is
* supported</LI>
* <LI>Added the method <code>drivers</code> to <code>DriverManager</code>
* <LI>Added the method {@code drivers} to {@code DriverManager}
* to return a Stream of the currently loaded and
* available JDBC drivers</LI>
* <LI>Added support to <code>Statement</code> for enquoting literals
* <LI>Added support to {@code Statement} for enquoting literals
* and simple identifiers</LI>
* <LI>Clarified the Java SE version that methods were deprecated</LI>
* </UL>
*
* <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.2 API</h3>
* <h3>{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.2 API</h3>
* <UL>
* <LI>Added <code>JDBCType</code> enum and <code>SQLType</code> interface</li>
* <LI>Support for <code>REF CURSORS</code> in <code>CallableStatement</code>
* <LI>Added {@code JDBCType} enum and {@code SQLType} interface</li>
* <LI>Support for {@code REF CURSORS} in {@code CallableStatement}
* </LI>
* <LI><code>DatabaseMetaData</code> methods to return maximum Logical LOB size
* <LI>{@code DatabaseMetaData} methods to return maximum Logical LOB size
* and if Ref Cursors are supported</LI>
* <LI>Added support for large update counts</LI>
*
* </UL>
*
* <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.1 API</h3>
* <h3>{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.1 API</h3>
* <UL>
* <LI>Allow <code>Connection</code>,
* <code>ResultSet</code> and <code>Statement</code> objects to be
* <LI>Allow {@code Connection},
* {@code ResultSet} and {@code Statement} objects to be
* used with the try-with-resources statement</LI>
* <LI>Support added to <code>CallableStatement</code> and
* <code>ResultSet</code> to specify the Java type to convert to via the
* <code>getObject</code> method</LI>
* <LI><code>DatabaseMetaData</code> methods to return PseudoColumns and if a
* <LI>Support added to {@code CallableStatement} and
* {@code ResultSet} to specify the Java type to convert to via the
* {@code getObject} method</LI>
* <LI>{@code DatabaseMetaData} methods to return PseudoColumns and if a
* generated key is always returned</LI>
* <LI>Added support to <code>Connection</code> to specify a database schema,
* <LI>Added support to {@code Connection} to specify a database schema,
* abort and timeout a physical connection.</LI>
* <LI>Added support to close a <code>Statement</code> object when its dependent
* <LI>Added support to close a {@code Statement} object when its dependent
* objects have been closed</LI>
* <LI>Support for obtaining the parent logger for a <code>Driver</code>,
* <code>DataSource</code>, <code>ConnectionPoolDataSource</code> and
* <code>XADataSource</code></LI>
* <LI>Support for obtaining the parent logger for a {@code Driver},
* {@code DataSource}, {@code ConnectionPoolDataSource} and
* {@code XADataSource}</LI>
*
* </UL>
* <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.0 API</h3>
* <h3>{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.0 API</h3>
* <UL>
* <LI>auto java.sql.Driver discovery -- no longer need to load a
* <code>java.sql.Driver</code> class via <code>Class.forName</code>
* {@code java.sql.Driver} class via {@code Class.forName}
* <LI>National Character Set support added
* <li>Support added for the SQL:2003 XML data type
* <lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions
@ -236,92 +236,92 @@
* <li>Support added to allow a JDBC application to access an instance of a JDBC resource
* that has been wrapped by a vendor, usually in an application server or connection
* pooling environment.
* <li>Availability to be notified when a <code>PreparedStatement</code> that is associated
* with a <code>PooledConnection</code> has been closed or the driver determines is invalid
* <li>Availability to be notified when a {@code PreparedStatement} that is associated
* with a {@code PooledConnection} has been closed or the driver determines is invalid
*
*
* </UL>
*
*
* <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 3.0 API</h3>
* <h3>{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 3.0 API</h3>
* <UL>
* <LI>Pooled statements -- reuse of statements associated with a pooled
* connection
* <LI>Savepoints -- allow a transaction to be rolled back to a designated
* savepoint
* <LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify
* <LI>Properties defined for {@code ConnectionPoolDataSource} -- specify
* how connections are to be pooled
* <LI>Metadata for parameters of a <code>PreparedStatement</code> object
* <LI>Metadata for parameters of a {@code PreparedStatement} object
* <LI>Ability to retrieve values from automatically generated columns
* <LI>Ability to have multiple <code>ResultSet</code> objects
* returned from <code>CallableStatement</code> objects open at the
* <LI>Ability to have multiple {@code ResultSet} objects
* returned from {@code CallableStatement} objects open at the
* same time
* <LI>Ability to identify parameters to <code>CallableStatement</code>
* <LI>Ability to identify parameters to {@code CallableStatement}
* objects by name as well as by index
* <LI><code>ResultSet</code> holdability -- ability to specify whether cursors
* <LI>{@code ResultSet} holdability -- ability to specify whether cursors
* should be held open or closed at the end of a transaction
* <LI>Ability to retrieve and update the SQL structured type instance that a
* <code>Ref</code> object references
* <LI>Ability to programmatically update <code>BLOB</code>,
* <code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values.
* <LI>Addition of the <code>java.sql.Types.DATALINK</code> data type --
* {@code Ref} object references
* <LI>Ability to programmatically update {@code BLOB},
* {@code CLOB}, {@code ARRAY}, and {@code REF} values.
* <LI>Addition of the {@code java.sql.Types.DATALINK} data type --
* allows JDBC drivers access to objects stored outside a data source
* <LI>Addition of metadata for retrieving SQL type hierarchies
* </UL>
*
* <h3><code>java.sql</code> Features Introduced in the JDBC 2.1 Core API</h3>
* <h3>{@code java.sql} Features Introduced in the JDBC 2.1 Core API</h3>
* <UL>
* <LI>Scrollable result sets--using new methods in the <code>ResultSet</code>
* <LI>Scrollable result sets--using new methods in the {@code ResultSet}
* interface that allow the cursor to be moved to a particular row or to a
* position relative to its current position
* <LI>Batch updates
* <LI>Programmatic updates--using <code>ResultSet</code> updater methods
* <LI>Programmatic updates--using {@code ResultSet} updater methods
* <LI>New data types--interfaces mapping the SQL3 data types
* <LI>Custom mapping of user-defined types (UDTs)
* <LI>Miscellaneous features, including performance hints, the use of character
* streams, full precision for <code>java.math.BigDecimal</code> values,
* streams, full precision for {@code java.math.BigDecimal} values,
* additional security, and
* support for time zones in date, time, and timestamp values.
* </UL>
*
* <h3><code>javax.sql</code> Features Introduced in the JDBC 2.0 Optional
* <h3>{@code javax.sql} Features Introduced in the JDBC 2.0 Optional
* Package API</h3>
* <UL>
* <LI>The <code>DataSource</code> interface as a means of making a connection. The
* <LI>The {@code DataSource} interface as a means of making a connection. The
* Java Naming and Directory Interface&trade;
* (JNDI) is used for registering a <code>DataSource</code> object with a
* (JNDI) is used for registering a {@code DataSource} object with a
* naming service and also for retrieving it.
* <LI>Pooled connections -- allowing connections to be used and reused
* <LI>Distributed transactions -- allowing a transaction to span diverse
* DBMS servers
* <LI><code>RowSet</code> technology -- providing a convenient means of
* <LI>{@code RowSet} technology -- providing a convenient means of
* handling and passing data
* </UL>
*
*
* <h3>Custom Mapping of UDTs</h3>
* A user-defined type (UDT) defined in SQL can be mapped to a class in the Java
* programming language. An SQL structured type or an SQL <code>DISTINCT</code>
* programming language. An SQL structured type or an SQL {@code DISTINCT}
* type are the UDTs that may be custom mapped. The following three
* steps set up a custom mapping:
* <ol>
* <li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL
* <li>Defining the SQL structured type or {@code DISTINCT} type in SQL
* <li>Defining the class in the Java programming language to which the
* SQL UDT will be mapped. This class must implement the
* <code>SQLData</code> interface.
* <li>Making an entry in a <code>Connection</code> object's type map
* {@code SQLData} interface.
* <li>Making an entry in a {@code Connection} object's type map
* that contains two things:
* <ul>
* <li>the fully-qualified SQL name of the UDT
* <li>the <code>Class</code> object for the class that implements the
* <code>SQLData</code> interface
* <li>the {@code Class} object for the class that implements the
* {@code SQLData} interface
* </ul>
* </ol>
* <p>
* When these are in place for a UDT, calling the methods
* <code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code>
* {@code ResultSet.getObject} or {@code CallableStatement.getObject}
* on that UDT will automatically retrieve the custom mapping for it. Also, the
* <code>PreparedStatement.setObject</code> method will automatically map the
* {@code PreparedStatement.setObject} method will automatically map the
* object back to its SQL type to store it in the data source.
*
* <h2>Package Specification</h2>

186
src/java.sql/share/classes/javax/sql/package-info.java
View File

@ -1,5 +1,5 @@
/**
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 2020, 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
@ -26,36 +26,36 @@
/**
* Provides the API for server side data source access and processing from
* the Java&trade; programming language.
* This package supplements the <code>java.sql</code>
* This package supplements the {@code java.sql}
* package and, as of the version 1.4 release, is included in the
* Java Platform, Standard Edition (Java SE&trade;).
* It remains an essential part of the Java Platform, Enterprise Edition
* (Java EE&trade;).
* <p>
* The <code>javax.sql</code> package provides for the following:
* The {@code javax.sql} package provides for the following:
* <OL>
* <LI>The <code>DataSource</code> interface as an alternative to the
* <code>DriverManager</code> for establishing a
* <LI>The {@code DataSource} interface as an alternative to the
* {@code DriverManager} for establishing a
* connection with a data source
* <LI>Connection pooling and Statement pooling
* <LI>Distributed transactions
* <LI>Rowsets
* </OL>
* <p>
* Applications use the <code>DataSource</code> and <code>RowSet</code>
* Applications use the {@code DataSource} and {@code RowSet}
* APIs directly, but the connection pooling and distributed transaction
* APIs are used internally by the middle-tier infrastructure.
*
* <H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
* <H2>Using a {@code DataSource} Object to Make a Connection</H2>
* <p>
* The <code>javax.sql</code> package provides the preferred
* way to make a connection with a data source. The <code>DriverManager</code>
* The {@code javax.sql} package provides the preferred
* way to make a connection with a data source. The {@code DriverManager}
* class, the original mechanism, is still valid, and code using it will
* continue to run. However, the newer <code>DataSource</code> mechanism
* continue to run. However, the newer {@code DataSource} mechanism
* is preferred because it offers many advantages over the
* <code>DriverManager</code> mechanism.
* {@code DriverManager} mechanism.
* <p>
* These are the main advantages of using a <code>DataSource</code> object to
* These are the main advantages of using a {@code DataSource} object to
* make a connection:
* <UL>
*
@ -63,39 +63,39 @@
* that it is not necessary to make changes in application code when
* something about the data source or driver changes.
* <LI>Connection and Statement pooling and distributed transactions are available
* through a <code>DataSource</code> object that is
* through a {@code DataSource} object that is
* implemented to work with the middle-tier infrastructure.
* Connections made through the <code>DriverManager</code>
* Connections made through the {@code DriverManager}
* do not have connection and statement pooling or distributed transaction
* capabilities.
* </UL>
* <p>
* Driver vendors provide <code>DataSource</code> implementations. A
* particular <code>DataSource</code> object represents a particular
* physical data source, and each connection the <code>DataSource</code> object
* Driver vendors provide {@code DataSource} implementations. A
* particular {@code DataSource} object represents a particular
* physical data source, and each connection the {@code DataSource} object
* creates is a connection to that physical data source.
* <p>
* A logical name for the data source is registered with a naming service that
* uses the Java Naming and Directory Interface&trade;
* (JNDI) API, usually by a system administrator or someone performing the
* duties of a system administrator. An application can retrieve the
* <code>DataSource</code> object it wants by doing a lookup on the logical
* {@code DataSource} object it wants by doing a lookup on the logical
* name that has been registered for it. The application can then use the
* <code>DataSource</code> object to create a connection to the physical data
* {@code DataSource} object to create a connection to the physical data
* source it represents.
* <p>
* A <code>DataSource</code> object can be implemented to work with the
* A {@code DataSource} object can be implemented to work with the
* middle tier infrastructure so that the connections it produces will be
* pooled for reuse. An application that uses such a <code>DataSource</code>
* pooled for reuse. An application that uses such a {@code DataSource}
* implementation will automatically get a connection that participates in
* connection pooling.
* A <code>DataSource</code> object can also be implemented to work with the
* A {@code DataSource} object can also be implemented to work with the
* middle tier infrastructure so that the connections it produces can be
* used for distributed transactions without any special coding.
*
* <H2>Connection Pooling and Statement Pooling</H2>
* <p>
* Connections made via a <code>DataSource</code>
* Connections made via a {@code DataSource}
* object that is implemented to work with a middle tier connection pool manager
* will participate in connection pooling. This can improve performance
* dramatically because creating new connections is very expensive.
@ -106,40 +106,40 @@
* Connection pooling is totally transparent. It is done automatically
* in the middle tier of a Java EE configuration, so from an application's
* viewpoint, no change in code is required. An application simply uses
* the <code>DataSource.getConnection</code> method to get the pooled
* connection and uses it the same way it uses any <code>Connection</code>
* the {@code DataSource.getConnection} method to get the pooled
* connection and uses it the same way it uses any {@code Connection}
* object.
* <p>
* The classes and interfaces used for connection pooling are:
* <UL>
* <LI><code>ConnectionPoolDataSource</code>
* <LI><code>PooledConnection</code>
* <LI><code>ConnectionEvent</code>
* <LI><code>ConnectionEventListener</code>
* <LI><code>StatementEvent</code>
* <LI><code>StatementEventListener</code>
* <LI>{@code ConnectionPoolDataSource}
* <LI>{@code PooledConnection}
* <LI>{@code ConnectionEvent}
* <LI>{@code ConnectionEventListener}
* <LI>{@code StatementEvent}
* <LI>{@code StatementEventListener}
* </UL>
* The connection pool manager, a facility in the middle tier of
* a three-tier architecture, uses these classes and interfaces
* behind the scenes. When a <code>ConnectionPoolDataSource</code> object
* is called on to create a <code>PooledConnection</code> object, the
* connection pool manager will register as a <code>ConnectionEventListener</code>
* object with the new <code>PooledConnection</code> object. When the connection
* behind the scenes. When a {@code ConnectionPoolDataSource} object
* is called on to create a {@code PooledConnection} object, the
* connection pool manager will register as a {@code ConnectionEventListener}
* object with the new {@code PooledConnection} object. When the connection
* is closed or there is an error, the connection pool manager (being a listener)
* gets a notification that includes a <code>ConnectionEvent</code> object.
* gets a notification that includes a {@code ConnectionEvent} object.
* <p>
* If the connection pool manager supports <code>Statement</code> pooling, for
* <code>PreparedStatements</code>, which can be determined by invoking the method
* <code>DatabaseMetaData.supportsStatementPooling</code>, the
* connection pool manager will register as a <code>StatementEventListener</code>
* object with the new <code>PooledConnection</code> object. When the
* <code>PreparedStatement</code> is closed or there is an error, the connection
* If the connection pool manager supports {@code Statement} pooling, for
* {@code PreparedStatements}, which can be determined by invoking the method
* {@code DatabaseMetaData.supportsStatementPooling}, the
* connection pool manager will register as a {@code StatementEventListener}
* object with the new {@code PooledConnection} object. When the
* {@code PreparedStatement} is closed or there is an error, the connection
* pool manager (being a listener)
* gets a notification that includes a <code>StatementEvent</code> object.
* gets a notification that includes a {@code StatementEvent} object.
*
* <H2>Distributed Transactions</H2>
* <p>
* As with pooled connections, connections made via a <code>DataSource</code>
* As with pooled connections, connections made via a {@code DataSource}
* object that is implemented to work with the middle tier infrastructure
* may participate in distributed transactions. This gives an application
* the ability to involve data sources on multiple servers in a single
@ -147,112 +147,112 @@
* <p>
* The classes and interfaces used for distributed transactions are:
* <UL>
* <LI><code>XADataSource</code>
* <LI><code>XAConnection</code>
* <LI>{@code XADataSource}
* <LI>{@code XAConnection}
* </UL>
* These interfaces are used by the transaction manager; an application does
* not use them directly.
* <p>
* The <code>XAConnection</code> interface is derived from the
* <code>PooledConnection</code> interface, so what applies to a pooled connection
* The {@code XAConnection} interface is derived from the
* {@code PooledConnection} interface, so what applies to a pooled connection
* also applies to a connection that is part of a distributed transaction.
* A transaction manager in the middle tier handles everything transparently.
* The only change in application code is that an application cannot do anything
* that would interfere with the transaction manager's handling of the transaction.
* Specifically, an application cannot call the methods <code>Connection.commit</code>
* or <code>Connection.rollback</code>, and it cannot set the connection to be in
* Specifically, an application cannot call the methods {@code Connection.commit}
* or {@code Connection.rollback}, and it cannot set the connection to be in
* auto-commit mode (that is, it cannot call
* <code>Connection.setAutoCommit(true)</code>).
* {@code Connection.setAutoCommit(true)}).
* <p>
* An application does not need to do anything special to participate in a
* distributed transaction.
* It simply creates connections to the data sources it wants to use via
* the <code>DataSource.getConnection</code> method, just as it normally does.
* the {@code DataSource.getConnection} method, just as it normally does.
* The transaction manager manages the transaction behind the scenes. The
* <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
* each <code>XAConnection</code> object creates an <code>XAResource</code> object
* {@code XADataSource} interface creates {@code XAConnection} objects, and
* each {@code XAConnection} object creates an {@code XAResource} object
* that the transaction manager uses to manage the connection.
*
*
* <H2>Rowsets</H2>
* The <code>RowSet</code> interface works with various other classes and
* The {@code RowSet} interface works with various other classes and
* interfaces behind the scenes. These can be grouped into three categories.
* <OL>
* <LI>Event Notification
* <UL>
* <LI><code>RowSetListener</code><br>
* A <code>RowSet</code> object is a JavaBeans&trade;
* <LI>{@code RowSetListener}<br>
* A {@code RowSet} object is a JavaBeans&trade;
* component because it has properties and participates in the JavaBeans
* event notification mechanism. The <code>RowSetListener</code> interface
* event notification mechanism. The {@code RowSetListener} interface
* is implemented by a component that wants to be notified about events that
* occur to a particular <code>RowSet</code> object. Such a component registers
* itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
* occur to a particular {@code RowSet} object. Such a component registers
* itself as a listener with a rowset via the {@code RowSet.addRowSetListener}
* method.
* <p>
* When the <code>RowSet</code> object changes one of its rows, changes all of
* When the {@code RowSet} object changes one of its rows, changes all of
* it rows, or moves its cursor, it also notifies each listener that is registered
* with it. The listener reacts by carrying out its implementation of the
* notification method called on it.
* <LI><code>RowSetEvent</code><br>
* As part of its internal notification process, a <code>RowSet</code> object
* creates an instance of <code>RowSetEvent</code> and passes it to the listener.
* The listener can use this <code>RowSetEvent</code> object to find out which rowset
* <LI>{@code RowSetEvent}<br>
* As part of its internal notification process, a {@code RowSet} object
* creates an instance of {@code RowSetEvent} and passes it to the listener.
* The listener can use this {@code RowSetEvent} object to find out which rowset
* had the event.
* </UL>
* <LI>Metadata
* <UL>
* <LI><code>RowSetMetaData</code><br>
* <LI>{@code RowSetMetaData}<br>
* This interface, derived from the
* <code>ResultSetMetaData</code> interface, provides information about
* the columns in a <code>RowSet</code> object. An application can use
* <code>RowSetMetaData</code> methods to find out how many columns the
* {@code ResultSetMetaData} interface, provides information about
* the columns in a {@code RowSet} object. An application can use
* {@code RowSetMetaData} methods to find out how many columns the
* rowset contains and what kind of data each column can contain.
* <p>
* The <code>RowSetMetaData</code> interface provides methods for
* The {@code RowSetMetaData} interface provides methods for
* setting the information about columns, but an application would not
* normally use these methods. When an application calls the <code>RowSet</code>
* method <code>execute</code>, the <code>RowSet</code> object will contain
* a new set of rows, and its <code>RowSetMetaData</code> object will have been
* normally use these methods. When an application calls the {@code RowSet}
* method {@code execute}, the {@code RowSet} object will contain
* a new set of rows, and its {@code RowSetMetaData} object will have been
* internally updated to contain information about the new columns.
* </UL>
* <LI>The Reader/Writer Facility<br>
* A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
* interface can call on the <code>RowSetReader</code> object associated with it
* to populate itself with data. It can also call on the <code>RowSetWriter</code>
* A {@code RowSet} object that implements the {@code RowSetInternal}
* interface can call on the {@code RowSetReader} object associated with it
* to populate itself with data. It can also call on the {@code RowSetWriter}
* object associated with it to write any changes to its rows back to the
* data source from which it originally got the rows.
* A rowset that remains connected to its data source does not need to use a
* reader and writer because it can simply operate on the data source directly.
*
* <UL>
* <LI><code>RowSetInternal</code><br>
* By implementing the <code>RowSetInternal</code> interface, a
* <code>RowSet</code> object gets access to
* <LI>{@code RowSetInternal}<br>
* By implementing the {@code RowSetInternal} interface, a
* {@code RowSet} object gets access to
* its internal state and is able to call on its reader and writer. A rowset
* keeps track of the values in its current rows and of the values that immediately
* preceded the current ones, referred to as the <i>original</i> values. A rowset
* also keeps track of (1) the parameters that have been set for its command and
* (2) the connection that was passed to it, if any. A rowset uses the
* <code>RowSetInternal</code> methods behind the scenes to get access to
* {@code RowSetInternal} methods behind the scenes to get access to
* this information. An application does not normally invoke these methods directly.
*
* <LI><code>RowSetReader</code><br>
* A disconnected <code>RowSet</code> object that has implemented the
* <code>RowSetInternal</code> interface can call on its reader (the
* <code>RowSetReader</code> object associated with it) to populate it with
* data. When an application calls the <code>RowSet.execute</code> method,
* <LI>{@code RowSetReader}<br>
* A disconnected {@code RowSet} object that has implemented the
* {@code RowSetInternal} interface can call on its reader (the
* {@code RowSetReader} object associated with it) to populate it with
* data. When an application calls the {@code RowSet.execute} method,
* that method calls on the rowset's reader to do much of the work. Implementations
* can vary widely, but generally a reader makes a connection to the data source,
* reads data from the data source and populates the rowset with it, and closes
* the connection. A reader may also update the <code>RowSetMetaData</code> object
* the connection. A reader may also update the {@code RowSetMetaData} object
* for its rowset. The rowset's internal state is also updated, either by the
* reader or directly by the method <code>RowSet.execute</code>.
* reader or directly by the method {@code RowSet.execute}.
*
*
* <LI><code>RowSetWriter</code><br>
* A disconnected <code>RowSet</code> object that has implemented the
* <code>RowSetInternal</code> interface can call on its writer (the
* <code>RowSetWriter</code> object associated with it) to write changes
* <LI>{@code RowSetWriter}<br>
* A disconnected {@code RowSet} object that has implemented the
* {@code RowSetInternal} interface can call on its writer (the
* {@code RowSetWriter} object associated with it) to write changes
* back to the underlying data source. Implementations may vary widely, but
* generally, a writer will do the following:
*
@ -269,7 +269,7 @@
* </UL>
* </OL>
* <p>
* The <code>RowSet</code> interface may be implemented in any number of
* The {@code RowSet} interface may be implemented in any number of
* ways, and anyone may write an implementation. Developers are encouraged
* to use their imaginations in coming up with new ways to use rowsets.
*
@ -283,7 +283,7 @@
* <h2>Related Documentation</h2>
* <p>
* The Java Series book published by Addison-Wesley Longman provides detailed
* information about the classes and interfaces in the <code>javax.sql</code>
* information about the classes and interfaces in the {@code javax.sql}
* package:
*
* <ul>

2
src/jdk.jshell/share/classes/jdk/jshell/OuterWrap.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015-2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2016, 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

2
test/hotspot/jtreg/runtime/execstack/Test.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002-2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*

2
test/hotspot/jtreg/runtime/execstack/TestMT.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002-2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*

2
test/hotspot/jtreg/runtime/execstack/libtest-rw.c
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002-2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*

2
test/hotspot/jtreg/runtime/execstack/libtest-rwx.c
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002-2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*