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> * <p>
* The filter is configured during the initialization of the {@code ObjectInputFilter.Config} * The filter is configured during the initialization of the {@code ObjectInputFilter.Config}
* class. For example, by calling {@link #getSerialFilter() Config.getSerialFilter}. * class. For example, by calling {@link #getSerialFilter() Config.getSerialFilter}.
* If the system property {@systemProperty jdk.serialFilter} is defined on the command line, * If the Java virtual machine is started with the system property
* it is used to configure the filter. * {@systemProperty jdk.serialFilter}, its value is used to configure the filter.
* If the system property is not defined on the command line, and the * If the system property is not defined, and the {@link java.security.Security} property
* {@link java.security.Security} property {@code jdk.serialFilter} is defined * {@code jdk.serialFilter} is defined then it is used to configure the filter.
* then it is used to configure the filter.
* Otherwise, the filter is not configured during initialization and * Otherwise, the filter is not configured during initialization and
* can be set with {@link #setSerialFilter(ObjectInputFilter) Config.setSerialFilter}. * can be set with {@link #setSerialFilter(ObjectInputFilter) Config.setSerialFilter}.
* Setting the {@code jdk.serialFilter} with {@link System#setProperty(String, String) * 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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -176,7 +176,7 @@
* do: * do:
* *
* <pre>{@code * <pre>{@code
* int sumOfWeights = widgets.}<code><b>parallelStream()</b></code>{@code * int sumOfWeights = widgets.<b>parallelStream()</b>
* .filter(b -> b.getColor() == RED) * .filter(b -> b.getColor() == RED)
* .mapToInt(b -> b.getWeight()) * .mapToInt(b -> b.getWeight())
* .sum(); * .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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -36,7 +36,7 @@
* *
* <p> * <p>
* The API is defined by classes in the package * 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> * <dl>
* <dt>Classes describing the corresponding Smart Card structures * <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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * 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. * by the Test Compatibility Kit (TCK) as mandated by the Java Community Process.
* <br> * <br>
* *
* <h2>1.0 Available JDBC RowSet Reference Implementations </h2> * <h2>1.0 Available JDBC RowSet Reference Implementations </h2>
* The following implementations are provided:<br> * 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> * interface reference implementation. <br>
* <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> * reference implementation.<br>
* <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> * reference implementation.<br>
* <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> * interface reference implementation.<br>
* <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> * reference implementation.<br>
* </blockquote> * </blockquote>
* *
* All details on their expected behavior, including their interactions with the <code>SyncProvider</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</code> * SPI and helper classes are provided in the interface definitions in the {@code javax.sql.rowset}
* package specification.<br> * package specification.<br>
* *
* <h2>2.0 Usage</h2> * <h2>2.0 Usage</h2>
* The reference implementations represent robust implementations of the standard * The reference implementations represent robust implementations of the standard
* <code>RowSet</code> interfaces defined in the <code>javax.sql.rowset</code> package. * {@code RowSet} interfaces defined in the {@code javax.sql.rowset} package.
* All disconnected <code>RowSet</code> implementations, such as the <code>CachedRowSetImpl</code> * All disconnected {@code RowSet} implementations, such as the {@code CachedRowSetImpl}
* and <code>WebRowSetImpl</code>, are flexible enough to use the <code>SyncFactory</code> SPIs to * and {@code WebRowSetImpl}, are flexible enough to use the {@code SyncFactory} SPIs to
* leverage non-reference implementation <code>SyncProvider</code> implementations to obtain * leverage non-reference implementation {@code SyncProvider} implementations to obtain
* differing synchronization semantics. Furthermore, developers and vendors alike are free * differing synchronization semantics. Furthermore, developers and vendors alike are free
* to use these implementations and integrate them into their products just as they * to use these implementations and integrate them into their products just as they
* can with to other components of the Java platform.<br> * can with to other components of the Java platform.<br>
* *
* <h2>3.0 Extending the JDBC RowSet Implementations</h2> * <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 * classes so that any developer can extend them to provide additional features
* while maintaining the core required standard functionality and compatibility. It * while maintaining the core required standard functionality and compatibility. It
* is anticipated that many vendors and developers will extend the standard feature * 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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * Repository for the {@code RowSet} reference implementations of the
* <code>SyncProvider</code> abstract class. These implementations provide a * {@code SyncProvider} abstract class. These implementations provide a
* disconnected <code>RowSet</code> * disconnected {@code RowSet}
* object with the ability to synchronize the data in the underlying data * object with the ability to synchronize the data in the underlying data
* source with its data. These implementations are provided as * source with its data. These implementations are provided as
* the default <code>SyncProvider</code> implementations and are accessible via the * the default {@code SyncProvider} implementations and are accessible via the
* <code>SyncProvider</code> SPI managed by the <code>SyncFactory</code>. * {@code SyncProvider} SPI managed by the {@code SyncFactory}.
* *
* <h2>1.0 <code>SyncProvider</code> Reference Implementations</h2> * <h2>1.0 {@code SyncProvider} Reference Implementations</h2>
* The main job of a <code>SyncProvider</code> implementation is to manage * The main job of a {@code SyncProvider} implementation is to manage
* the reader and writer mechanisms. * the reader and writer mechanisms.
* The <code>SyncProvider</code> SPI, as specified in the <code>javax.sql.rowset.spi</code> * The {@code SyncProvider} SPI, as specified in the {@code javax.sql.rowset.spi}
* package, provides a pluggable mechanism by which <code>javax.sql.RowSetReader</code> * package, provides a pluggable mechanism by which {@code javax.sql.RowSetReader}
* and <code>javax.sql.RowSetWriter</code> implementations can be supplied to a disconnected * and {@code javax.sql.RowSetWriter} implementations can be supplied to a disconnected
* <code>RowSet</code> object. * {@code RowSet} object.
* <P> * <P>
* A reader, a <code>javax.sql.RowSetReader</code> * A reader, a {@code javax.sql.RowSetReader}
* object, does the work necessary to populate a <code>RowSet</code> object with data. * object, does the work necessary to populate a {@code RowSet} object with data.
* A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for * A writer, a {@code javax.sql.RowSetWriter} object, does the work necessary for
* synchronizing a <code>RowSet</code> object's data with the data in the originating * 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</code> * source of data. Put another way, a writer writes a {@code RowSet}
* object's data back to the data source. * object's data back to the data source.
* <P> * <P>
* Generally speaking, the course of events is this. The reader makes a connection to * 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 * the data source and reads the data from a {@code ResultSet} object into its
* <code>RowSet</code> object. Then it closes the connection. While * {@code RowSet} object. Then it closes the connection. While
* the <code>RowSet</code> object is disconnected, an application makes some modifications * the {@code RowSet} object is disconnected, an application makes some modifications
* to the data and calls the method <code>acceptChanges</code>. At this point, the * 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 * 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>. * from which the original data came. This is called <i>synchronization</i>.
* <P> * <P>
* If the data in the originating data source has not changed, there is no problem * 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 * 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 * 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 * 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, * 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 * is simply to assume that no conflicts will occur and thus do nothing to avoid
* conflicts. * 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 * any of these ways, varying from doing no checking for
* conflicts, to doing various levels of checking, to guaranteeing that there are no * conflicts, to doing various levels of checking, to guaranteeing that there are no
* conflicts. * conflicts.
* <P> * <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. * 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 * grade of synchronization a provider offers. An application can
* direct the provider to use a particular level of locking by calling * direct the provider to use a particular level of locking by calling
* the method <code>setDataSourceLock</code> and specifying the level of locking desired. * the method {@code setDataSourceLock} and specifying the level of locking desired.
* If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an * If a {@code RowSet} object's data came from an SQL {@code VIEW}, an
* application may call the method <code>supportsUpdatableView</code> to * application may call the method {@code supportsUpdatableView} to
* find out whether the <code>VIEW</code> can be updated. * find out whether the {@code VIEW} can be updated.
* <P> * <P>
* Synchronization is done completely behind the scenes, so it is third party vendors of * 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. * 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 * 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. * be done, but they are free from having to worry about the implementation details.
* <P> * <P>
* The JDBC <code>RowSet</code> Implementations reference implementation provides two * The JDBC {@code RowSet} Implementations reference implementation provides two
* implementations of the <code>SyncProvider</code> class: * implementations of the {@code SyncProvider} class:
* *
* <UL> * <UL>
* <LI> * <LI>
* <b><code>RIOptimisticProvider</code></b> - provides the <code>javax.sql.RowSetReader</code> * <b>{@code RIOptimisticProvider}</b> - provides the {@code javax.sql.RowSetReader}
* and <code>javax.sql.RowSetWriter</code> interface implementations and provides * and {@code javax.sql.RowSetWriter} interface implementations and provides
* an optimistic concurrency model for synchronization. This model assumes that there * an optimistic concurrency model for synchronization. This model assumes that there
* will be few conflicts and therefore uses a relatively low grade of synchronization. * 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 * 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> * <br>
* <LI> * <LI>
* <b><code>RIXMLProvider</code></b> - provides the <code>XmlReader</code> (an extension * <b>{@code RIXMLProvider}</b> - provides the {@code XmlReader} (an extension
* of the <code>javax.sql.RowSetReader</code> interface) and the <code>XmlWriter</code> * of the {@code javax.sql.RowSetReader} interface) and the {@code XmlWriter}
* (an extension of the <code>javax.sql.RowSetWriter</code> interface) to enable * (an extension of the {@code javax.sql.RowSetWriter} interface) to enable
* <code>WebRowSet</code> objects to write their state to a * {@code WebRowSet} objects to write their state to a
* well formed XML document according to the <code>WebRowSet</code> XML schema * well formed XML document according to the {@code WebRowSet} XML schema
* definition.<br> * definition.<br>
* </UL> * </UL>
* *
@ -117,12 +117,12 @@
* properties. The general rule is that a RowSet is required to set only the * properties. The general rule is that a RowSet is required to set only the
* properties that it uses.<br> * properties that it uses.<br>
* <br> * <br>
* The <code>command</code> property contains the query that determines what * The {@code command} property contains the query that determines what
* data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's * 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 * 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 * different parameters to produce different result sets. Or the query can be
* changed to something completely new to get a new result set. * 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 * 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 * 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 * 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 * source to keep the rowset and its data source synchronized. Although this
* involves many operations behind the scenes, it is completely transparent * involves many operations behind the scenes, it is completely transparent
* to the application programmer and remains the concern of the RowSet provider * 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 * and the data source backing the rowset will be updated to match the current
* values in the rowset. </p> * 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 * 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, * 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 * 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 * the database), the rowset establishes a connection, write the changes, and then
@ -148,9 +148,9 @@
* </p> * </p>
* *
* <h2> 3.0 Other Possible Implementations</h2> * <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 * 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 * ability to get any updates back to the original data source. Another possibility
* is a more formal synchronization mechanism such as SyncML * is a more formal synchronization mechanism such as SyncML
* (<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br> * (<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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * 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> * <h2>Table of Contents</h2>
* <ul> * <ul>
@ -38,133 +38,133 @@
* </ul> * </ul>
* *
* <h3><a id="pkgspec">1.0 Package Specification</a></h3> * <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 * All five extend the
* <a href="{@docRoot}/java.sql/javax/sql/RowSet.html">RowSet</a> interface described in the JDBC 3.0 * <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 * 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 * matures. Future definitions <i>should</i> be specified as subinterfaces using
* inheritance similar to the way it is used in this specification. * inheritance similar to the way it is used in this specification.
* <p> * <p>
* <i>Note:</i> The interface definitions provided in this package form the basis for * <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 * all compliant JDBC {@code RowSet} implementations. Vendors and more advanced
* developers who intend to provide their own compliant <code>RowSet</code> implementations * developers who intend to provide their own compliant {@code RowSet} implementations
* should pay particular attention to the assertions detailed in specification * should pay particular attention to the assertions detailed in specification
* interfaces. * interfaces.
* *
* <h3><a id="stdrowset">2.0 Standard RowSet Definitions</a></h3> * <h3><a id="stdrowset">2.0 Standard RowSet Definitions</a></h3>
* <ul> * <ul>
* <li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around * <li><a href="JdbcRowSet.html"><b>{@code JdbcRowSet}</b></a> - A wrapper around
* a <code>ResultSet</code> object that makes it possible to use the result set as a * a {@code ResultSet} object that makes it possible to use the result set as a
* JavaBeans&trade; component. Thus, * 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 * 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 * object, that is, it
* <b>must</b> continually maintain its connection to its data source using a JDBC * <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 * object provides a fully updatable and scrollable tabular
* data structure as defined in the JDBC 3.0 specification. * data structure as defined in the JDBC 3.0 specification.
* *
* <li><a href="CachedRowSet.html"> * <li><a href="CachedRowSet.html">
* <b><code>CachedRowSet</code>&trade;</b></a> * <b>{@code CachedRowSet}&trade;</b></a>
* - A <code>CachedRowSet</code> object is a JavaBeans&trade; * - A {@code CachedRowSet} object is a JavaBeans&trade;
* component that is scrollable, updatable, serializable, and generally disconnected from * 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 * 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 * file with a tabular format, such as a spreadsheet. {@code CachedRowSet} implementations
* <b>must</b> use the <code>SyncFactory</code> to manage and obtain pluggable * <b>must</b> use the {@code SyncFactory} to manage and obtain pluggable
* <code>SyncProvider</code> objects to provide synchronization between the * {@code SyncProvider} objects to provide synchronization between the
* disconnected <code>RowSet</code> object and the originating data source. * disconnected {@code RowSet} object and the originating data source.
* Typically a <code>SyncProvider</code> implementation relies upon a JDBC * Typically a {@code SyncProvider} implementation relies upon a JDBC
* driver to obtain connectivity to a particular data source. * driver to obtain connectivity to a particular data source.
* Further details on this mechanism are discussed in the <a * 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. * specification.
* *
* <li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A * <li><a href="WebRowSet.html"><b>{@code WebRowSet}</b></a> - A
* <code>WebRowSet</code> object is an extension of <code>CachedRowSet</code> * {@code WebRowSet} object is an extension of {@code CachedRowSet}
* that can read and write a <code>RowSet</code> object in a well formed XML format. * 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</code></a> object * 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</code></a> * (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 * 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="spi/XmlWriter.html">{@code XmlWriter}</a> object (an extension of the
* <a href="{@docRoot}/java.sql/javax/sql/RowSetWriter.html"><code>RowSetWriter</code></a> interface) * <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 * to write a rowset in XML format. The reader and writer required by
* <code>WebRowSet</code> objects are provided by the * {@code WebRowSet} objects are provided by the
* <code>SyncFactory</code> in the form of <code>SyncProvider</code> * {@code SyncFactory} in the form of {@code SyncProvider}
* implementations. In order to ensure well formed XML usage, a standard generic XML * implementations. In order to ensure well formed XML usage, a standard generic XML
* Schema is defined and published at * Schema is defined and published at
* <a href="http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd"> * <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 * <li><a href="FilteredRowSet.html"><b>{@code FilteredRowSet}</b></a> - A
* <code>FilteredRowSet</code> object provides filtering functionality in a programmatic * {@code FilteredRowSet} object provides filtering functionality in a programmatic
* and extensible way. There are many instances when a <code>RowSet</code> <code>object</code> * 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 * 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. * 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 * Solutions to this need vary from providing heavyweight full scale
* SQL query abilities, to portable components, to more lightweight * SQL query abilities, to portable components, to more lightweight
* approaches. A <code>FilteredRowSet</code> object consumes * approaches. A {@code FilteredRowSet} object consumes
* an implementation of the <a href="Predicate.html"><code>Predicate</code></a> * 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 * 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 * inbound and outbound read and write operations. That is, all filters can be
* considered as bi-directional. No standard filters are defined; * considered as bi-directional. No standard filters are defined;
* however, sufficient mechanics are specified to permit any required filter to be * however, sufficient mechanics are specified to permit any required filter to be
* implemented. * 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 * 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> * two or more standard {@code RowSet} implementations. Any number of {@code RowSet}
* objects can be added to a <code>JoinRowSet</code> object provided the <code>RowSet</code>objects * objects can be added to a {@code JoinRowSet} object provided the {@code RowSet}objects
* can be related in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code> * 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 * 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 * database tables based upon a common attribute. By establishing and then enforcing
* column matches, a <code>JoinRowSet</code> object establishes relationships between * column matches, a {@code JoinRowSet} object establishes relationships between
* <code>RowSet</code> instances without the need to touch the originating data source. * {@code RowSet} instances without the need to touch the originating data source.
* </ul> * </ul>
* *
* <h3><a id="impl">3.0 Implementer's Guide</a></h3> * <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 * <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 * 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 * Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
* specification. The following paragraphs outline a number of starting points for * 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 * 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 * 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> * <ul>
* <li><b>3.1 Constructor</b> * <li><b>3.1 Constructor</b>
* <p> * <p>
* All <code>RowSet</code> implementations <strong>must</strong> provide a * All {@code RowSet} implementations <strong>must</strong> provide a
* no-argument constructor. * no-argument constructor.
* </li> * </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> * <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 * 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 * <a href="BaseRowSet.html">{@code BaseRowSet}</a> abstract class. For example, a
* <code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code> * {@code CachedRowSet} implementation must implement the {@code CachedRowSet}
* interface and extend the <code>BaseRowSet</code> abstract class. The * interface and extend the {@code BaseRowSet} abstract class. The
* <code>BaseRowSet</code> class provides the standard architecture on which all * {@code BaseRowSet} class provides the standard architecture on which all
* <code>RowSet</code> implementations should be built, regardless of whether the * {@code RowSet} implementations should be built, regardless of whether the
* <code>RowSet</code> objects exist in a connected or disconnected environment. * {@code RowSet} objects exist in a connected or disconnected environment.
* The <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> implementation * The {@code BaseRowSet} abstract class provides any {@code RowSet} implementation
* with its base functionality, including property manipulation and event notification * with its base functionality, including property manipulation and event notification
* that is fully compliant with * that is fully compliant with
* <a href="https://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html">JavaBeans</a> * <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 * component requirements. As an example, all implementations provided in the
* reference implementations (contained in the <code>com.sun.rowset</code> package) use * reference implementations (contained in the {@code com.sun.rowset} package) use
* the <code>BaseRowSet</code> class as a basis for their implementations. * the {@code BaseRowSet} class as a basis for their implementations.
* <P> * <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. * abstract class provides.
* <blockquote> * <blockquote>
* <table class="striped" style="vertical-align:top; width:75%"> * <table class="striped" style="vertical-align:top; width:75%">
* <caption>Features in <code>BaseRowSet</code></caption> * <caption>Features in {@code BaseRowSet}</caption>
* <thead> * <thead>
* <tr> * <tr>
* <th scope="col">Feature</th> * <th scope="col">Feature</th>
@ -175,15 +175,15 @@
* <tr> * <tr>
* <th scope="row">Properties</th> * <th scope="row">Properties</th>
* <td>Provides standard JavaBeans property manipulation * <td>Provides standard JavaBeans property manipulation
* mechanisms to allow applications to get and set <code>RowSet</code> command and * mechanisms to allow applications to get and set {@code RowSet} command and
* property values. Refer to the documentation of the <code>javax.sql.RowSet</code> * property values. Refer to the documentation of the {@code javax.sql.RowSet}
* interface (available in the JDBC 3.0 specification) for more details on * 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>
* <tr> * <tr>
* <th scope="row">Event notification</th> * <th scope="row">Event notification</th>
* <td>Provides standard JavaBeans event notifications * <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 * interface (available in the JDBC 3.0 specification) for
* more details on how to register and handle standard RowSet events generated * more details on how to register and handle standard RowSet events generated
* by compliant implementations.</td> * by compliant implementations.</td>
@ -204,70 +204,70 @@
* *
* <li><b>3.3 Connected RowSet Requirements</b> * <li><b>3.3 Connected RowSet Requirements</b>
* <p> * <p>
* The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always * 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</code> * be connected to the originating data source. Implementations of the {@code JdbcRowSet}
* should ensure that this connection is provided solely by a JDBC driver. * should ensure that this connection is provided solely by a JDBC driver.
* Furthermore, <code>RowSet</code> objects that are implementations of the * Furthermore, {@code RowSet} objects that are implementations of the
* <code>JdbcRowSet</code> interface and are therefore operating in a connected environment * {@code JdbcRowSet} interface and are therefore operating in a connected environment
* do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object * do not use the {@code SyncFactory} to obtain a {@code RowSetReader} object
* or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to * 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 * supply their needs by virtue of the presence of an underlying updatable and scrollable
* <code>ResultSet</code> implementation. * {@code ResultSet} implementation.
* *
* <li> * <li>
* <b>3.4 Disconnected RowSet Requirements</b> * <b>3.4 Disconnected RowSet Requirements</b>
* <p> * <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 * <b>should</b> delegate
* connection management to a <code>SyncProvider</code> object provided by the * connection management to a {@code SyncProvider} object provided by the
* <code>SyncFactory</code>. To ensure fully disconnected semantics, all * {@code SyncFactory}. To ensure fully disconnected semantics, all
* disconnected <code>RowSet</code> objects <b>must</b> ensure * disconnected {@code RowSet} objects <b>must</b> ensure
* that the original connection made to the data source to populate the <code>RowSet</code> * 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 * 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 * 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 * 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> * <li><b>3.5 Role of RowSetMetaDataImpl</b>
* <p> * <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 * <a href="{@docRoot}/java.sql/javax/sql/RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
* method implementations for metadata for both connected and disconnected * 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. * implementation but are not required to do so.
* *
* <li><b>3.6 RowSetWarning Class</b> * <li><b>3.6 RowSetWarning Class</b>
* <p> * <p>
* The <code>RowSetWarning</code> class provides warnings that can be set * The {@code RowSetWarning} class provides warnings that can be set
* on <code>RowSet</code> implementations. * on {@code RowSet} implementations.
* Similar to <a href="{@docRoot}/java.sql/java/sql/SQLWarning.html">SQLWarning</a> objects, * 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 * {@code RowSetWarning} objects are silently chained to the object whose method
* caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b> * 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 * 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 * warnings are available via the {@code getRowSetWarnings} method defined in either
* the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface. * the {@code JdbcRowSet} interface or the {@code CachedRowSet} interface.
* After a warning has been retrieved with one of the * After a warning has been retrieved with one of the
* <code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method * {@code getRowSetWarnings} methods, the {@code RowSetWarning} method
* <code>getNextWarning</code> can be called on it to retrieve any warnings that might * {@code getNextWarning} 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 * 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. * on it, and so on until there are no more warnings.
* *
* <li><b>3.7 The Joinable Interface</b> * <li><b>3.7 The Joinable Interface</b>
* <P> * <P>
* The <code>Joinable</code> interface provides both connected and disconnected * The {@code Joinable} interface provides both connected and disconnected
* <code>RowSet</code> objects with the capability to be added to a * {@code RowSet} objects with the capability to be added to a
* <code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation. * {@code JoinRowSet} object in an SQL {@code JOIN} operation.
* A <code>RowSet</code> object that has implemented the <code>Joinable</code> * 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. * 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 * A {@code JoinRowSet} object can then use the {@code RowSet} object's
* match column as a basis for adding the <code>RowSet</code> object. * match column as a basis for adding the {@code RowSet} object.
* </li> * </li>
* *
* <li><b>3.8 The RowSetFactory Interface</b> * <li><b>3.8 The RowSetFactory Interface</b>
* <p> * <p>
* A <code>RowSetFactory</code> implementation <strong>must</strong> * A {@code RowSetFactory} implementation <strong>must</strong>
* be provided. * be provided.
* </li> * </li>
* </ul> * </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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * Provides utility classes to allow serializable mappings between SQL types
* and data types in the Java programming language. * 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 * classes to
* assist in the serialization of disconnected <code>RowSet</code> objects. * assist in the serialization of disconnected {@code RowSet} objects.
* This is useful * 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> * a different VM or across layers within an application.<br>
* </p> * </p>
* *
@ -38,40 +38,40 @@
* A serializable mapping in the Java programming language of an SQL ARRAY * A serializable mapping in the Java programming language of an SQL ARRAY
* value. <br> * value. <br>
* <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 * 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 * 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> * <h2>2.0 SerialBlob</h2>
* A serializable mapping in the Java programming language of an SQL BLOB * A serializable mapping in the Java programming language of an SQL BLOB
* value. <br> * value. <br>
* <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 * 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 * 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>) * 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</code>). * or as a stream of uninterpreted bytes (using the method {@code Blob.getBinaryStream}).
* <br> * <br>
* <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 * 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> * object. <br>
* *
* <h2>3.0 SerialClob</h2> * <h2>3.0 SerialClob</h2>
* A serializable mapping in the Java programming language of an SQL CLOB * A serializable mapping in the Java programming language of an SQL CLOB
* value. <br> * value. <br>
* <br> * <br>
* The <code>SerialClob</code> class provides a constructor for creating an instance * The {@code SerialClob} class provides a constructor for creating an instance
* from a <code>Clob</code> object. Note that the <code>Clob</code> object should have * 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</code> * 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 * 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> * materialized on the client as a stream of Unicode characters. <br>
* <br> * <br>
* <code>SerialClob</code> methods make it possible to get a substring from a * {@code SerialClob} 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} object or to locate the start of a pattern of characters.
* <br> * <br>
* *
* <h2>5.0 SerialDatalink</h2> * <h2>5.0 SerialDatalink</h2>
@ -79,11 +79,12 @@
* value. A DATALINK value references a file outside of the underlying data source * value. A DATALINK value references a file outside of the underlying data source
* that the originating data source manages. <br> * that the originating data source manages. <br>
* <br> * <br>
* <code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve * {@code RowSet} implementations can use the method {@code RowSet.getURL()} to retrieve
* a <code>java.net.URL</code> object, which can be used to manipulate the external data. * a {@code java.net.URL} object, which can be used to manipulate the external data.
* <br> * <br>
* <br> * <PRE>
* &nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</code><br> * java.net.URL url = rowset.getURL(1);
* </PRE>
* *
* <h2>6.0 SerialJavaObject</h2> * <h2>6.0 SerialJavaObject</h2>
* A serializable mapping in the Java programming language of an SQL JAVA_OBJECT * 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 * object is not immediately serializable, this class will attempt to serialize
* all non static members to permit the object instance state to be serialized. * 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 * 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> * <h2>7.0 SerialRef</h2>
* A serializable mapping between the SQL REF type and the Java programming * A serializable mapping between the SQL REF type and the Java programming
* language. <br> * language. <br>
* <br> * <br>
* The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code> * The {@code SerialRef} class provides a constructor for creating a {@code SerialRef}
* instance from a <code>Ref</code> type and provides methods for getting * instance from a {@code Ref} type and provides methods for getting
* and setting the <code>Ref</code> object type. <br> * and setting the {@code Ref} object type. <br>
* *
* <h2>8.0 SerialStruct</h2> * <h2>8.0 SerialStruct</h2>
* A serializable mapping in the Java programming language of an SQL structured * 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 * 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> * that is not already serializable is mapped to a serializable form. <br>
* <br> * <br>
* In addition, if a <code>Map</code> object is passed to one of the constructors or * In addition, if a {@code Map} object is passed to one of the constructors or
* to the method <code>getAttributes</code>, the structured type is custom mapped * to the method {@code getAttributes}, the structured type is custom mapped
* according to the mapping specified in the <code>Map</code> object. * according to the mapping specified in the {@code Map} object.
* <br> * <br>
* The <code>SerialStruct</code> class provides a constructor for creating an * The {@code SerialStruct} class provides a constructor for creating an
* instance from a <code>Struct</code> object, a method for retrieving the SQL * 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 * type name of the SQL structured type in the database, and methods for retrieving
* its attribute values. <br> * its attribute values. <br>
* *
* <h2>9.0 SQLInputImpl</h2> * <h2>9.0 SQLInputImpl</h2>
* An input stream used for custom mapping user-defined types (UDTs). An * 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 * values that are
* the attributes of a UDT. This class is used by the driver behind the scenes * 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 * 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</code> * type that has a custom mapping; a programmer never invokes {@code SQLInputImpl}
* methods directly. <br> * methods directly. <br>
* <br> * <br>
* The <code>SQLInputImpl</code> class provides a set of reader methods * The {@code SQLInputImpl} class provides a set of reader methods
* analogous to the <code>ResultSet</code> getter methods. These methods make it * analogous to the {@code ResultSet} getter methods. These methods make it
* possible to read the values in an <code>SQLInputImpl</code> object. The method * possible to read the values in an {@code SQLInputImpl} object. The method
* <code>wasNull</code> is used to determine whether the last value read was SQL NULL. * {@code wasNull} is used to determine whether the last value read was SQL NULL.
* <br> * <br>
* <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 * the JDBC driver calls the method
* <code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom * {@code SQLData.getSQLType} to determine the SQL type of the UDT being custom
* mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with * 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 * 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> * methods to read the attributes from the input stream. <br>
* *
* <h2>10.0 SQLOutputImpl</h2> * <h2>10.0 SQLOutputImpl</h2>
@ -148,16 +149,16 @@
* and its methods are never directly invoked by an application programmer. * and its methods are never directly invoked by an application programmer.
* <br> * <br>
* <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 * 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 * 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 * object for the class that implements {@code SQLData} for this UDT. If the
* value to be written is an instance of <code>SQLData</code>, the driver will * value to be written is an instance of {@code SQLData}, the driver will
* create an instance of <code>SQLOutputImpl</code> and pass it to the method * create an instance of {@code SQLOutputImpl} and pass it to the method
* <code>SQLData.writeSQL</code>. * {@code SQLData.writeSQL}.
* The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code> * The method {@code writeSQL} in turn calls the appropriate {@code SQLOutputImpl}
* writer methods to write data from the <code>SQLData</code> object to the * writer methods to write data from the {@code SQLData} object to the
* <code>SQLOutputImpl</code> * {@code SQLOutputImpl}
* output stream as the representation of an SQL user-defined type. * output stream as the representation of an SQL user-defined type.
* *
* <h2>Custom Mapping</h2> * <h2>Custom Mapping</h2>
@ -167,12 +168,12 @@
* (A DISTINCT type can thought of as having one attribute.) However, there are * (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. * many other possibilities, and there may be any number of different mappings.
* <P> * <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, * 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 * 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 * 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 * 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> * <PRE>
* public class Authors implements SQLData { * public class Authors implements SQLData {
* public String name; * public String name;
@ -200,27 +201,27 @@
* } * }
* </PRE> * </PRE>
* *
* A <code>java.util.Map</code> object is used to associate the SQL structured * A {@code java.util.Map} object is used to associate the SQL structured
* type with its mapping to the class <code>Authors</code>. The following code fragment shows * type with its mapping to the class {@code Authors}. The following code fragment shows
* how a <code>Map</code> object might be created and given an entry associating * how a {@code Map} object might be created and given an entry associating
* <code>AUTHORS</code> and <code>Authors</code>. * {@code AUTHORS} and {@code Authors}.
* <PRE> * <PRE>
* java.util.Map map = new java.util.HashMap(); * java.util.Map map = new java.util.HashMap();
* map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors"); * map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
* </PRE> * </PRE>
* *
* The <code>Map</code> object <i>map</i> now contains an entry with the * 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</code> * fully qualified name of the SQL structured type and the {@code Class}
* object for the class <code>Authors</code>. It can be passed to a method * object for the class {@code Authors}. It can be passed to a method
* to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>. * to tell the driver how to map {@code AUTHORS} to {@code Authors}.
* <P> * <P>
* For a disconnected <code>RowSet</code> object, custom mapping can be done * For a disconnected {@code RowSet} object, custom mapping can be done
* only when a <code>Map</code> object is passed to the method or constructor * 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 * 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 * 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> * a disconnected {@code RowSet} object may use the {@code Map}
* object that is associated with the <code>Connection</code> object being * object that is associated with the {@code Connection} object being
* used. So, in other words, if no map is specified, the connection's type * used. So, in other words, if no map is specified, the connection's type
* map can be used by default. * 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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * The standard classes and interfaces that a third party vendor has to
* use in its implementation of a synchronization provider. These classes and * 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 * 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 * for a {@code RowSet} object to use an implementation, the vendor must register
* it with the <code>SyncFactory</code> singleton. (See the class comment for * it with the {@code SyncFactory} singleton. (See the class comment for
* <code>SyncProvider</code> for a full explanation of the registration process and * {@code SyncProvider} for a full explanation of the registration process and
* the naming convention to be used.) * the naming convention to be used.)
* *
* <h2>Table of Contents</h2> * <h2>Table of Contents</h2>
@ -44,46 +44,46 @@
* *
* <h3><a id="pkgspec">1.0 Package Specification</a></h3> * <h3><a id="pkgspec">1.0 Package Specification</a></h3>
* <P> * <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: * package:
* <UL> * <UL>
* <LI><code>SyncFactory</code> * <LI>{@code SyncFactory}
* <LI><code>SyncProvider</code> * <LI>{@code SyncProvider}
* <LI><code>SyncFactoryException</code> * <LI>{@code SyncFactoryException}
* <LI><code>SyncProviderException</code> * <LI>{@code SyncProviderException}
* <LI><code>SyncResolver</code> * <LI>{@code SyncResolver}
* <LI><code>XmlReader</code> * <LI>{@code XmlReader}
* <LI><code>XmlWriter</code> * <LI>{@code XmlWriter}
* <LI><code>TransactionalWriter</code> * <LI>{@code TransactionalWriter}
* </UL> * </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> * <UL>
* <LI><code>RowSetReader</code> * <LI>{@code RowSetReader}
* <LI><code>RowSetWriter</code> * <LI>{@code RowSetWriter}
* </UL> * </UL>
* <P> * <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 * object with the mechanisms for reading data into it and for writing data that has been
* modified in it * modified in it
* back to the underlying data source. A <i>reader</i>, a <code>RowSetReader</code> or * back to the underlying data source. A <i>reader</i>, a {@code RowSetReader} or
* <code>XMLReader</code> object, reads data into a <code>RowSet</code> object when the * {@code XMLReader} object, reads data into a {@code RowSet} object when the
* <code>CachedRowSet</code> methods <code>execute</code> or <code>populate</code> * {@code CachedRowSet} methods {@code execute} or {@code populate}
* are called. A <i>writer</i>, a <code>RowSetWriter</code> or <code>XMLWriter</code> * are called. A <i>writer</i>, a {@code RowSetWriter} or {@code XMLWriter}
* object, writes changes back to the underlying data source when the * 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> * <P>
* The process of writing changes in a <code>RowSet</code> object to its data source * The process of writing changes in a {@code RowSet} object to its data source
* is known as <i>synchronization</i>. The <code>SyncProvider</code> implementation that a * is known as <i>synchronization</i>. The {@code SyncProvider} implementation that a
* <code>RowSet</code> object is using determines the level of synchronization that the * {@code RowSet} object is using determines the level of synchronization that the
* <code>RowSet</code> object's writer uses. The various levels of synchronization are * {@code RowSet} object's writer uses. The various levels of synchronization are
* referred to as <i>grades</i>. * referred to as <i>grades</i>.
* <P> * <P>
* The lower grades of synchronization are * The lower grades of synchronization are
* known as <i>optimistic</i> concurrency levels because they optimistically * 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 * 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 * 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. * object will be lost.
* <P> * <P>
* Higher grades of synchronization are called <i>pessimistic</i> because they assume * Higher grades of synchronization are called <i>pessimistic</i> because they assume
@ -92,114 +92,114 @@
* occur. * occur.
* <P> * <P>
* The lowest level of synchronization is simply writing any changes made to the * 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. * nothing to check for conflicts.
* If there is a conflict and the data * If there is a conflict and the data
* source values are overwritten, the changes other parties have made by to the data * source values are overwritten, the changes other parties have made by to the data
* source are lost. * source are lost.
* <P> * <P>
* The <code>RIXMLProvider</code> implementation uses the lowest level * The {@code RIXMLProvider} implementation uses the lowest level
* of synchronization and just writes <code>RowSet</code> changes to the data source. * of synchronization and just writes {@code RowSet} changes to the data source.
* *
* <P> * <P>
* For the next level up, the * For the next level up, the
* writer checks to see if there are any conflicts, and if there are, * 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 * 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 * level is that if another party has modified the corresponding data in the data source
* since the <code>RowSet</code> object got its data, * since the {@code RowSet} object got its data,
* the changes made to the <code>RowSet</code> object are lost. The * the changes made to the {@code RowSet} object are lost. The
* <code>RIOptimisticProvider</code> implementation uses this level of synchronization. * {@code RIOptimisticProvider} implementation uses this level of synchronization.
* <P> * <P>
* At higher levels of synchronization, referred to as pessimistic concurrency, * At higher levels of synchronization, referred to as pessimistic concurrency,
* the writer take steps to avoid conflicts by setting locks. Setting locks * 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 * 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 * 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 * 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. * synchronized.
* <P> * <P>
* It is a requirement that all disconnected <code>RowSet</code> objects * It is a requirement that all disconnected {@code RowSet} objects
* (<code>CachedRowSet</code>, <code>FilteredRowSet</code>, <code>JoinRowSet</code>, * ({@code CachedRowSet}, {@code FilteredRowSet}, {@code JoinRowSet},
* and <code>WebRowSet</code> objects) obtain their <code>SyncProvider</code> objects * and {@code WebRowSet} objects) obtain their {@code SyncProvider} objects
* from the <code>SyncFactory</code> mechanism. * from the {@code SyncFactory} mechanism.
* <P> * <P>
* The reference implementation (RI) provides two synchronization providers. * The reference implementation (RI) provides two synchronization providers.
* <UL> * <UL>
* <LI><b><code>RIOptimisticProvider</code></b> <br> * <LI><b>{@code RIOptimisticProvider}</b> <br>
* The default provider that the <code>SyncFactory</code> instance will * The default provider that the {@code SyncFactory} instance will
* supply to a disconnected <code>RowSet</code> object when no provider * supply to a disconnected {@code RowSet} object when no provider
* implementation is specified.<BR> * implementation is specified.<BR>
* This synchronization provider uses an optimistic concurrency model, * This synchronization provider uses an optimistic concurrency model,
* assuming that there will be few conflicts among users * assuming that there will be few conflicts among users
* who are accessing the same data in a database. It avoids * who are accessing the same data in a database. It avoids
* using locks; rather, it checks to see if there is a conflict * 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 * 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. * source.
* <LI><B><code>RIXMLProvider</code></B> <BR> * <LI><B>{@code RIXMLProvider}</B> <BR>
* A synchronization provider that can be used with a * 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 * 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 * conflicts and simply writes any updated data in the
* <code>WebRowSet</code> object to the underlying data source. * {@code WebRowSet} object to the underlying data source.
* <code>WebRowSet</code> objects use this provider when they are * {@code WebRowSet} objects use this provider when they are
* dealing with XML data. * dealing with XML data.
* </UL> * </UL>
* *
* These <code>SyncProvider</code> implementations * These {@code SyncProvider} implementations
* are bundled with the reference implementation, which makes them always available to * are bundled with the reference implementation, which makes them always available to
* <code>RowSet</code> implementations. * {@code RowSet} implementations.
* <code>SyncProvider</code> implementations make themselves available by being * {@code SyncProvider} implementations make themselves available by being
* registered with the <code>SyncFactory</code> singleton. When a <code>RowSet</code> * 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 * object requests a provider, by specifying it in the constructor or as an argument to the
* <code>CachedRowSet</code> method <code>setSyncProvider</code>, * {@code CachedRowSet} method {@code setSyncProvider},
* the <code>SyncFactory</code> singleton * the {@code SyncFactory} singleton
* checks to see if the requested provider has been registered with it. * 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 * If it has, the {@code SyncFactory} creates an instance of it and passes it to the
* requesting <code>RowSet</code> object. * requesting {@code RowSet} object.
* If the <code>SyncProvider</code> implementation that is specified has not been registered, * If the {@code SyncProvider} implementation that is specified has not been registered,
* the <code>SyncFactory</code> singleton causes a <code>SyncFactoryException</code> object * the {@code SyncFactory} singleton causes a {@code SyncFactoryException} object
* to be thrown. If no provider is specified, * to be thrown. If no provider is specified,
* the <code>SyncFactory</code> singleton will create an instance of the default * the {@code SyncFactory} singleton will create an instance of the default
* provider implementation, <code>RIOptimisticProvider</code>, * provider implementation, {@code RIOptimisticProvider},
* and pass it to the requesting <code>RowSet</code> object. * and pass it to the requesting {@code RowSet} object.
* *
* <P> * <P>
* If a <code>WebRowSet</code> object does not specify a provider in its constructor, the * If a {@code WebRowSet} object does not specify a provider in its constructor, the
* <code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>. * {@code SyncFactory} will give it an instance of {@code RIOptimisticProvider}.
* However, the constructor for <code>WebRowSet</code> is implemented to set the provider * However, the constructor for {@code WebRowSet} is implemented to set the provider
* to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object * to the {@code RIXMLProvider}, which reads and writes a {@code RowSet} object
* in XML format. * in XML format.
* <P> * <P>
* See the <a href="SyncProvider.html">SyncProvider</a> class * See the <a href="SyncProvider.html">SyncProvider</a> class
* specification for further details. * specification for further details.
* <p> * <p>
* Vendors may develop a <code>SyncProvider</code> implementation with any one of the possible * Vendors may develop a {@code SyncProvider} implementation with any one of the possible
* levels of synchronization, thus giving <code>RowSet</code> objects a choice of * levels of synchronization, thus giving {@code RowSet} objects a choice of
* synchronization mechanisms. * synchronization mechanisms.
* *
* <h3><a id="arch">2.0 Service Provider Interface Architecture</a></h3> * <h3><a id="arch">2.0 Service Provider Interface Architecture</a></h3>
* <b>2.1 Overview</b> * <b>2.1 Overview</b>
* <p> * <p>
* The Service Provider Interface provides a pluggable mechanism by which * The Service Provider Interface provides a pluggable mechanism by which
* <code>SyncProvider</code> implementations can be registered and then generated when * {@code SyncProvider} implementations can be registered and then generated when
* required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits * required. The lazy reference mechanism employed by the {@code SyncFactory} limits
* unnecessary resource consumption by not creating an instance until it is * unnecessary resource consumption by not creating an instance until it is
* required by a disconnected * 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 * 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> * <p>
* <b>2.2 Registering with the <code>SyncFactory</code></b> * <b>2.2 Registering with the {@code SyncFactory}</b>
* <p> * <p>
* A third party <code>SyncProvider</code> implementation must be registered with the * A third party {@code SyncProvider} implementation must be registered with the
* <code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object * {@code SyncFactory} in order for a disconnected {@code RowSet} object
* to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and * to obtain it and thereby use its {@code javax.sql.RowSetReader} and
* <code>javax.sql.RowSetWriter</code> * {@code javax.sql.RowSetWriter}
* implementations. The following registration mechanisms are available to all * implementations. The following registration mechanisms are available to all
* <code>SyncProvider</code> implementations: * {@code SyncProvider} implementations:
* <ul> * <ul>
* <li><b>System properties</b> - Properties set at the command line. These * <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 * 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 * This can be specified using a System Property or by modifying a standard
* property file located in the platform run-time. The * property file located in the platform run-time. The
* reference implementation of this technology includes a standard property * 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 * <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 * 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. * function correctly.
* </ul> * </ul>
* <p> * <p>
* Details on how to specify the system properties or properties in a property file * 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 * 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> * <p>
* <b>2.3 SyncFactory Provider Instance Generation Policies</b> * <b>2.3 SyncFactory Provider Instance Generation Policies</b>
* <p> * <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 * object if the provider has been correctly registered. The
* following policies are adhered to when either a disconnected <code>RowSet</code> object * following policies are adhered to when either a disconnected {@code RowSet} object
* is instantiated with a specified <code>SyncProvider</code> implementation or is * is instantiated with a specified {@code SyncProvider} implementation or is
* reconfigured at runtime with an alternative <code>SyncProvider</code> object. * reconfigured at runtime with an alternative {@code SyncProvider} object.
* <ul> * <ul>
* <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 <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is * contains <i>no</i> reference to the provider, a {@code SyncFactoryException} is
* thrown. * 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. * contains a reference to the provider, the requested provider is supplied.
* *
* <li> If no <code>SyncProvider</code> object is specified, the reference * <li> If no {@code SyncProvider} object is specified, the reference
* implementation provider <code>RIOptimisticProvider</code> is supplied. * implementation provider {@code RIOptimisticProvider} is supplied.
* </ul> * </ul>
* <p> * <p>
* These policies are explored in more detail in the <a href="SyncFactory.html"> * 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> * <h3><a id="impl">3.0 SyncProvider Implementer's Guide</a></h3>
* *
* <b>3.1 Requirements</b> * <b>3.1 Requirements</b>
* <p> * <p>
* A compliant <code>SyncProvider</code> implementation that is fully pluggable * A compliant {@code SyncProvider} implementation that is fully pluggable
* into the <code>SyncFactory</code> <b>must</b> extend and implement all * into the {@code SyncFactory} <b>must</b> extend and implement all
* abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a> * abstract methods in the <a href="SyncProvider.html">{@code SyncProvider}</a>
* class. In addition, an implementation <b>must</b> determine the * class. In addition, an implementation <b>must</b> determine the
* grade, locking and updatable view capabilities defined in the * grade, locking and updatable view capabilities defined in the
* <code>SyncProvider</code> class definition. One or more of the * {@code SyncProvider} class definition. One or more of the
* <code>SyncProvider</code> description criteria <b>must</b> be supported. It * {@code SyncProvider} description criteria <b>must</b> be supported. It
* is expected that vendor implementations will offer a range of grade, locking, and * is expected that vendor implementations will offer a range of grade, locking, and
* updatable view capabilities. * updatable view capabilities.
* <p> * <p>
* Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as * Furthermore, the {@code SyncProvider} naming convention <b>must</b> be followed as
* detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class * detailed in the <a href="SyncProvider.html">{@code SyncProvider}</a> class
* description. * description.
* <p> * <p>
* <b>3.2 Grades</b> * <b>3.2 Grades</b>
* <p> * <p>
* JSR 114 defines a set of grades to describe the quality of synchronization * 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. * object. These grades are listed from the lowest quality of service to the highest.
* <ul> * <ul>
* <li><b>GRADE_NONE</b> - No synchronization with the originating data source is * <li><b>GRADE_NONE</b> - No synchronization with the originating data source is
* provided. A <code>SyncProvider</code> implementation returning this grade will simply * provided. A {@code SyncProvider} implementation returning this grade will simply
* attempt to write any data that has changed in the <code>RowSet</code> object to the * 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 *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 * 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. * <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 * 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 * 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> * that have been modified will not be reflected in the disconnected {@code RowSet}
* object. If there are no conflicts, changes in the <code>RowSet</code> object will be * 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. * 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. * <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 * 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 * {@code RowSet} object. In this way, any changes to rows in the underlying
* data source will be reflected in the disconnected <code>RowSet</code> object * data source will be reflected in the disconnected {@code RowSet} object
* when the synchronization finishes successfully. * when the synchronization finishes successfully.
* *
* <li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization. * <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 * 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. * processes modifying the same data in the data source.
* *
* <li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade. * <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 * 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> * </ul>
* <p> * <p>
* <b>3.3 Locks</b> * <b>3.3 Locks</b>
* <p> * <p>
* JSR 114 defines a set of constants that specify whether any locks have been * 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 * 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> * <P>
* These constants <b>should</b> be considered complementary to the * These constants <b>should</b> be considered complementary to the
* grade constants. The default setting for the majority of grade settings requires * 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. * from its data source.
* The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and * The grades {@code GRADE_LOCK_WHEN_MODIFIED} and
* <code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object * {@code GRADE_LOCK_WHEN_LOADED} allow a disconnected {@code RowSet} object
* to have a fine-grained control over the degree of locking. * to have a fine-grained control over the degree of locking.
* <ul> * <ul>
* <li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source. * <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 * This is the default lock setting for all {@code SyncProvider} implementations
* unless otherwise directed by a <code>RowSet</code> object. * 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 * <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 * <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> * <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. * object.
* </ul> * </ul>
* <p> * <p>
* <b>3.4 Updatable Views</b> * <b>3.4 Updatable Views</b>
* <p> * <p>
* A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>. * A {@code RowSet} object may be populated with data from an SQL {@code VIEW}.
* The following constants indicate whether a <code>SyncProvider</code> object can * The following constants indicate whether a {@code SyncProvider} object can
* update data in the table or tables from which the <code>VIEW</code> was derived. * update data in the table or tables from which the {@code VIEW} was derived.
* <ul> * <ul>
* <li><b>UPDATABLE_VIEW_SYNC</b> * <li><b>UPDATABLE_VIEW_SYNC</b>
* Indicates that a <code>SyncProvider</code> implementation supports synchronization * Indicates that a {@code SyncProvider} implementation supports synchronization
* to the table or tables from which the SQL <code>VIEW</code> used to populate * to the table or tables from which the SQL {@code VIEW} used to populate
* a <code>RowSet</code> object is derived. * a {@code RowSet} object is derived.
* *
* <li><b>NONUPDATABLE_VIEW_SYNC</b> * <li><b>NONUPDATABLE_VIEW_SYNC</b>
* Indicates that a <code>SyncProvider</code> implementation does <b>not</b> support * Indicates that a {@code SyncProvider} implementation does <b>not</b> support
* synchronization to the table or tables from which the SQL <code>VIEW</code> * synchronization to the table or tables from which the SQL {@code VIEW}
* used to populate a <code>RowSet</code> object is derived. * used to populate a {@code RowSet} object is derived.
* </ul> * </ul>
* <p> * <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> * <p>
* In the example below, the reference <code>CachedRowSetImpl</code> implementation * In the example below, the reference {@code CachedRowSetImpl} implementation
* reconfigures its current <code>SyncProvider</code> object by calling the * reconfigures its current {@code SyncProvider} object by calling the
* <code>setSyncProvider</code> method.<br> * {@code setSyncProvider} method.<br>
* *
* <PRE> * <PRE>
* CachedRowSetImpl crs = new CachedRowSetImpl(); * CachedRowSetImpl crs = new CachedRowSetImpl();
* crs.setSyncProvider("com.foo.bar.HASyncProvider"); * crs.setSyncProvider("com.foo.bar.HASyncProvider");
* </PRE> * </PRE>
* An application can retrieve the <code>SyncProvider</code> object currently in use * An application can retrieve the {@code SyncProvider} object currently in use
* by a disconnected <code>RowSet</code> object. It can also retrieve the * by a disconnected {@code RowSet} object. It can also retrieve the
* grade of synchronization with which the provider was implemented and the degree of * 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 * 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 * the degree of locking to be used, which can increase the possibilities for successful
@ -388,10 +388,10 @@
* break; * break;
* } * }
* *
* switch (sync.getDataSourcLock() { * switch (sync.getDataSourceLock() {
* case: SyncProvider.DATASOURCE_DB_LOCK * case: SyncProvider.DATASOURCE_DB_LOCK
* // A lock is placed on the entire datasource that is used by the * // A lock is placed on the entire datasource that is used by the
* // <code>RowSet</code> object * // {@code RowSet} object
* break; * break;
* *
* case: SyncProvider.DATASOURCE_NO_LOCK * case: SyncProvider.DATASOURCE_NO_LOCK
@ -412,8 +412,8 @@
* *
* </PRE> * </PRE>
* It is also possible using the static utility method in the * It is also possible using the static utility method in the
* <code>SyncFactory</code> class to determine the list of <code>SyncProvider</code> * {@code SyncFactory} class to determine the list of {@code SyncProvider}
* implementations currently registered with the <code>SyncFactory</code>. * implementations currently registered with the {@code SyncFactory}.
* *
* <pre> * <pre>
* Enumeration e = SyncFactory.getRegisteredProviders(); * Enumeration e = SyncFactory.getRegisteredProviders();
@ -422,48 +422,48 @@
* *
* <h3><a id="resolving">4.0 Resolving Synchronization Conflicts</a></h3> * <h3><a id="resolving">4.0 Resolving Synchronization Conflicts</a></h3>
* *
* The interface <code>SyncResolver</code> provides a way for an application to * The interface {@code SyncResolver} provides a way for an application to
* decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code> * decide manually what to do when a conflict occurs. When the {@code CachedRowSet}
* method <code>acceptChanges</code> finishes and has detected one or more conflicts, * method {@code acceptChanges} finishes and has detected one or more conflicts,
* it throws a <code>SyncProviderException</code> object. An application can * it throws a {@code SyncProviderException} object. An application can
* catch the exception and * catch the exception and
* have it retrieve a <code>SyncResolver</code> object by calling the method * have it retrieve a {@code SyncResolver} object by calling the method
* <code>SyncProviderException.getSyncResolver()</code>. * {@code SyncProviderException.getSyncResolver()}.
* <P> * <P>
* A <code>SyncResolver</code> object, which is a special kind of * A {@code SyncResolver} object, which is a special kind of
* <code>CachedRowSet</code> object or * {@code CachedRowSet} object or
* a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code> * a {@code JdbcRowSet} object that has implemented the {@code SyncResolver}
* interface, examines the conflicts row by row. It is a duplicate of the * 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 * 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 * set to {@code null}. To navigate from one conflict value to another, a
* <code>SyncResolver</code> object provides the methods <code>nextConflict</code> and * {@code SyncResolver} object provides the methods {@code nextConflict} and
* <code>previousConflict</code>. * {@code previousConflict}.
* <P> * <P>
* The <code>SyncResolver</code> interface also * The {@code SyncResolver} interface also
* provides methods for doing the following: * provides methods for doing the following:
* <UL> * <UL>
* <LI>finding out whether the conflict involved an update, a delete, or an insert * <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>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 * <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 * to be changed
* </UL> * </UL>
* <P> * <P>
* When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it * When the {@code CachedRowSet} method {@code acceptChanges} is called, it
* delegates to the <code>RowSet</code> object's <code>SyncProvider</code> object. * delegates to the {@code RowSet} object's {@code SyncProvider} object.
* How the writer provided by that <code>SyncProvider</code> object is implemented * How the writer provided by that {@code SyncProvider} object is implemented
* determines what level (grade) of checking for conflicts will be done. After all * 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 * 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 * {@code acceptChanges} throws a {@code SyncProviderException} object. The
* application can catch the exception and use it to obtain a <code>SyncResolver</code> object. * application can catch the exception and use it to obtain a {@code SyncResolver} object.
* <P> * <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 * 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. * persist, the application or user can overwrite the data source value with it.
* <P> * <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> * <h3><a id="relspec">5.0 Related Specifications</a></h3>
* <ul> * <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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * to passing SQL statements to a database, it provides for reading and
* writing data from any data source with a tabular format. * writing data from any data source with a tabular format.
* The reader/writer facility, available through the * 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 * use and update data from a spread sheet, flat file, or any other tabular
* data source. * data source.
* *
* <h2>What the JDBC&trade; 4.3 API Includes</h2> * <h2>What the JDBC&trade; 4.3 API Includes</h2>
* The JDBC&trade; 4.3 API includes both * The JDBC&trade; 4.3 API includes both
* the <code>java.sql</code> package, referred to as the JDBC core API, * the {@code java.sql} package, referred to as the JDBC core API,
* and the <code>javax.sql</code> package, referred to as the JDBC Optional * and the {@code javax.sql} package, referred to as the JDBC Optional
* Package API. This complete JDBC API * Package API. This complete JDBC API
* is included in the Java&trade; Standard Edition (Java SE&trade;), version 7. * 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 * from a client-side API to a server-side API, and it is an essential part
* of the Java&trade; Enterprise Edition * of the Java&trade; Enterprise Edition
* (Java EE&trade;) technology. * (Java EE&trade;) technology.
@ -91,141 +91,141 @@
* check your driver's documentation to see whether it supports a feature before * check your driver's documentation to see whether it supports a feature before
* you try to use it. * you try to use it.
* <P> * <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, * Java&trade; 2 SDK, Standard Edition,
* version 1.3 release. This class is used to prevent unauthorized * 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. * which may contain information such as table names, column data, and so on.
* *
* <h2>What the <code>java.sql</code> Package Contains</h2> * <h2>What the {@code java.sql} Package Contains</h2>
* The <code>java.sql</code> package contains API for the following: * The {@code java.sql} package contains API for the following:
* <UL> * <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> * <UL>
* <LI><code>DriverManager</code> class -- makes a connection with a driver * <LI>{@code DriverManager} class -- makes a connection with a driver
* <LI><code>SQLPermission</code> class -- provides permission when code * <LI>{@code SQLPermission} class -- provides permission when code
* running within a Security Manager, such as an applet, * running within a Security Manager, such as an applet,
* attempts to set up a logging stream through the * attempts to set up a logging stream through the
* <code>DriverManager</code> * {@code DriverManager}
* <LI><code>Driver</code> interface -- provides the API for registering * <LI>{@code Driver} interface -- provides the API for registering
* and connecting drivers based on JDBC technology ("JDBC drivers"); * and connecting drivers based on JDBC technology ("JDBC drivers");
* generally used only by the <code>DriverManager</code> class * generally used only by the {@code DriverManager} class
* <LI><code>DriverPropertyInfo</code> class -- provides properties for a * <LI>{@code DriverPropertyInfo} class -- provides properties for a
* JDBC driver; not used by the general user * JDBC driver; not used by the general user
* </UL> * </UL>
* <LI>Sending SQL statements to a database * <LI>Sending SQL statements to a database
* <UL> * <UL>
* <LI><code>Statement</code> -- used to send basic SQL statements * <LI>{@code Statement} -- used to send basic SQL statements
* <LI><code>PreparedStatement</code> -- used to send prepared statements or * <LI>{@code PreparedStatement} -- used to send prepared statements or
* basic SQL statements (derived from <code>Statement</code>) * basic SQL statements (derived from {@code Statement})
* <LI><code>CallableStatement</code> -- used to call database stored * <LI>{@code CallableStatement} -- used to call database stored
* procedures (derived from <code>PreparedStatement</code>) * procedures (derived from {@code PreparedStatement})
* <LI><code>Connection</code> interface -- provides methods for creating * <LI>{@code Connection} interface -- provides methods for creating
* statements and managing connections and their properties * 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> * </UL>
* <LI>Retrieving and updating the results of a query * <LI>Retrieving and updating the results of a query
* <UL> * <UL>
* <LI><code>ResultSet</code> interface * <LI>{@code ResultSet} interface
* </UL> * </UL>
* <LI>Standard mappings for SQL types to classes and interfaces in the * <LI>Standard mappings for SQL types to classes and interfaces in the
* Java programming language * Java programming language
* <UL> * <UL>
* <LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code> * <LI>{@code Array} interface -- mapping for SQL {@code ARRAY}
* <LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code> * <LI>{@code Blob} interface -- mapping for SQL {@code BLOB}
* <LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code> * <LI>{@code Clob} interface -- mapping for SQL {@code CLOB}
* <LI><code>Date</code> class -- mapping for SQL <code>DATE</code> * <LI>{@code Date} class -- mapping for SQL {@code DATE}
* <LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code> * <LI>{@code NClob} interface -- mapping for SQL {@code NCLOB}
* <LI><code>Ref</code> interface -- mapping for SQL <code>REF</code> * <LI>{@code Ref} interface -- mapping for SQL {@code REF}
* <LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code> * <LI>{@code RowId} interface -- mapping for SQL {@code ROWID}
* <LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code> * <LI>{@code Struct} interface -- mapping for SQL {@code STRUCT}
* <LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code> * <LI>{@code SQLXML} interface -- mapping for SQL {@code XML}
* <LI><code>Time</code> class -- mapping for SQL <code>TIME</code> * <LI>{@code Time} class -- mapping for SQL {@code TIME}
* <LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code> * <LI>{@code Timestamp} class -- mapping for SQL {@code TIMESTAMP}
* <LI><code>Types</code> class -- provides constants for SQL types * <LI>{@code Types} class -- provides constants for SQL types
* </UL> * </UL>
* <LI>Custom mapping an SQL user-defined type (UDT) to a class in the * <LI>Custom mapping an SQL user-defined type (UDT) to a class in the
* Java programming language * Java programming language
* <UL> * <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 * 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 * 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 * UDT attributes back to a stream
* </UL> * </UL>
* <LI>Metadata * <LI>Metadata
* <UL> * <UL>
* <LI><code>DatabaseMetaData</code> interface -- provides information * <LI>{@code DatabaseMetaData} interface -- provides information
* about the database * about the database
* <LI><code>ResultSetMetaData</code> interface -- provides information * <LI>{@code ResultSetMetaData} interface -- provides information
* about the columns of a <code>ResultSet</code> object * about the columns of a {@code ResultSet} object
* <LI><code>ParameterMetaData</code> interface -- provides information * <LI>{@code ParameterMetaData} interface -- provides information
* about the parameters to <code>PreparedStatement</code> commands * about the parameters to {@code PreparedStatement} commands
* </UL> * </UL>
* <LI>Exceptions * <LI>Exceptions
* <UL> * <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 * is a problem accessing data and by some methods for other reasons
* <LI><code>SQLWarning</code> -- thrown to indicate a warning * <LI>{@code SQLWarning} -- thrown to indicate a warning
* <LI><code>DataTruncation</code> -- thrown to indicate that data may have * <LI>{@code DataTruncation} -- thrown to indicate that data may have
* been truncated * 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 * commands in a batch update executed successfully
* </UL> * </UL>
* </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> * <UL>
* <LI>Added <code>Sharding</code> support</LI> * <LI>Added {@code Sharding} support</LI>
* <LI>Enhanced <code>Connection</code> to be able to provide hints * <LI>Enhanced {@code Connection} to be able to provide hints
* to the driver that a request, an independent unit of work, * to the driver that a request, an independent unit of work,
* is beginning or ending</LI> * 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> * 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 * to return a Stream of the currently loaded and
* available JDBC drivers</LI> * 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> * and simple identifiers</LI>
* <LI>Clarified the Java SE version that methods were deprecated</LI> * <LI>Clarified the Java SE version that methods were deprecated</LI>
* </UL> * </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> * <UL>
* <LI>Added <code>JDBCType</code> enum and <code>SQLType</code> interface</li> * <LI>Added {@code JDBCType} enum and {@code SQLType} interface</li>
* <LI>Support for <code>REF CURSORS</code> in <code>CallableStatement</code> * <LI>Support for {@code REF CURSORS} in {@code CallableStatement}
* </LI> * </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> * and if Ref Cursors are supported</LI>
* <LI>Added support for large update counts</LI> * <LI>Added support for large update counts</LI>
* *
* </UL> * </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> * <UL>
* <LI>Allow <code>Connection</code>, * <LI>Allow {@code Connection},
* <code>ResultSet</code> and <code>Statement</code> objects to be * {@code ResultSet} and {@code Statement} objects to be
* used with the try-with-resources statement</LI> * used with the try-with-resources statement</LI>
* <LI>Support added to <code>CallableStatement</code> and * <LI>Support added to {@code CallableStatement} and
* <code>ResultSet</code> to specify the Java type to convert to via the * {@code ResultSet} to specify the Java type to convert to via the
* <code>getObject</code> method</LI> * {@code getObject} method</LI>
* <LI><code>DatabaseMetaData</code> methods to return PseudoColumns and if a * <LI>{@code DatabaseMetaData} methods to return PseudoColumns and if a
* generated key is always returned</LI> * 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> * 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> * objects have been closed</LI>
* <LI>Support for obtaining the parent logger for a <code>Driver</code>, * <LI>Support for obtaining the parent logger for a {@code Driver},
* <code>DataSource</code>, <code>ConnectionPoolDataSource</code> and * {@code DataSource}, {@code ConnectionPoolDataSource} and
* <code>XADataSource</code></LI> * {@code XADataSource}</LI>
* *
* </UL> * </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> * <UL>
* <LI>auto java.sql.Driver discovery -- no longer need to load a * <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>National Character Set support added
* <li>Support added for the SQL:2003 XML data type * <li>Support added for the SQL:2003 XML data type
* <lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions * <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 * <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 * that has been wrapped by a vendor, usually in an application server or connection
* pooling environment. * pooling environment.
* <li>Availability to be notified when a <code>PreparedStatement</code> that is associated * <li>Availability to be notified when a {@code PreparedStatement} that is associated
* with a <code>PooledConnection</code> has been closed or the driver determines is invalid * with a {@code PooledConnection} has been closed or the driver determines is invalid
* *
* *
* </UL> * </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> * <UL>
* <LI>Pooled statements -- reuse of statements associated with a pooled * <LI>Pooled statements -- reuse of statements associated with a pooled
* connection * connection
* <LI>Savepoints -- allow a transaction to be rolled back to a designated * <LI>Savepoints -- allow a transaction to be rolled back to a designated
* savepoint * savepoint
* <LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify * <LI>Properties defined for {@code ConnectionPoolDataSource} -- specify
* how connections are to be pooled * 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 retrieve values from automatically generated columns
* <LI>Ability to have multiple <code>ResultSet</code> objects * <LI>Ability to have multiple {@code ResultSet} objects
* returned from <code>CallableStatement</code> objects open at the * returned from {@code CallableStatement} objects open at the
* same time * 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 * 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 * 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 * <LI>Ability to retrieve and update the SQL structured type instance that a
* <code>Ref</code> object references * {@code Ref} object references
* <LI>Ability to programmatically update <code>BLOB</code>, * <LI>Ability to programmatically update {@code BLOB},
* <code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values. * {@code CLOB}, {@code ARRAY}, and {@code REF} values.
* <LI>Addition of the <code>java.sql.Types.DATALINK</code> data type -- * <LI>Addition of the {@code java.sql.Types.DATALINK} data type --
* allows JDBC drivers access to objects stored outside a data source * allows JDBC drivers access to objects stored outside a data source
* <LI>Addition of metadata for retrieving SQL type hierarchies * <LI>Addition of metadata for retrieving SQL type hierarchies
* </UL> * </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> * <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 * interface that allow the cursor to be moved to a particular row or to a
* position relative to its current position * position relative to its current position
* <LI>Batch updates * <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>New data types--interfaces mapping the SQL3 data types
* <LI>Custom mapping of user-defined types (UDTs) * <LI>Custom mapping of user-defined types (UDTs)
* <LI>Miscellaneous features, including performance hints, the use of character * <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 * additional security, and
* support for time zones in date, time, and timestamp values. * support for time zones in date, time, and timestamp values.
* </UL> * </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> * Package API</h3>
* <UL> * <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; * 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. * naming service and also for retrieving it.
* <LI>Pooled connections -- allowing connections to be used and reused * <LI>Pooled connections -- allowing connections to be used and reused
* <LI>Distributed transactions -- allowing a transaction to span diverse * <LI>Distributed transactions -- allowing a transaction to span diverse
* DBMS servers * 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 * handling and passing data
* </UL> * </UL>
* *
* *
* <h3>Custom Mapping of UDTs</h3> * <h3>Custom Mapping of UDTs</h3>
* A user-defined type (UDT) defined in SQL can be mapped to a class in the Java * 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 * type are the UDTs that may be custom mapped. The following three
* steps set up a custom mapping: * steps set up a custom mapping:
* <ol> * <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 * <li>Defining the class in the Java programming language to which the
* SQL UDT will be mapped. This class must implement the * SQL UDT will be mapped. This class must implement the
* <code>SQLData</code> interface. * {@code SQLData} interface.
* <li>Making an entry in a <code>Connection</code> object's type map * <li>Making an entry in a {@code Connection} object's type map
* that contains two things: * that contains two things:
* <ul> * <ul>
* <li>the fully-qualified SQL name of the UDT * <li>the fully-qualified SQL name of the UDT
* <li>the <code>Class</code> object for the class that implements the * <li>the {@code Class} object for the class that implements the
* <code>SQLData</code> interface * {@code SQLData} interface
* </ul> * </ul>
* </ol> * </ol>
* <p> * <p>
* When these are in place for a UDT, calling the methods * 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 * 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. * object back to its SQL type to store it in the data source.
* *
* <h2>Package Specification</h2> * <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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * Provides the API for server side data source access and processing from
* the Java&trade; programming language. * 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 * package and, as of the version 1.4 release, is included in the
* Java Platform, Standard Edition (Java SE&trade;). * Java Platform, Standard Edition (Java SE&trade;).
* It remains an essential part of the Java Platform, Enterprise Edition * It remains an essential part of the Java Platform, Enterprise Edition
* (Java EE&trade;). * (Java EE&trade;).
* <p> * <p>
* The <code>javax.sql</code> package provides for the following: * The {@code javax.sql} package provides for the following:
* <OL> * <OL>
* <LI>The <code>DataSource</code> interface as an alternative to the * <LI>The {@code DataSource} interface as an alternative to the
* <code>DriverManager</code> for establishing a * {@code DriverManager} for establishing a
* connection with a data source * connection with a data source
* <LI>Connection pooling and Statement pooling * <LI>Connection pooling and Statement pooling
* <LI>Distributed transactions * <LI>Distributed transactions
* <LI>Rowsets * <LI>Rowsets
* </OL> * </OL>
* <p> * <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 directly, but the connection pooling and distributed transaction
* APIs are used internally by the middle-tier infrastructure. * 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> * <p>
* The <code>javax.sql</code> package provides the preferred * The {@code javax.sql} package provides the preferred
* way to make a connection with a data source. The <code>DriverManager</code> * way to make a connection with a data source. The {@code DriverManager}
* class, the original mechanism, is still valid, and code using it will * 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 * is preferred because it offers many advantages over the
* <code>DriverManager</code> mechanism. * {@code DriverManager} mechanism.
* <p> * <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: * make a connection:
* <UL> * <UL>
* *
@ -63,39 +63,39 @@
* that it is not necessary to make changes in application code when * that it is not necessary to make changes in application code when
* something about the data source or driver changes. * something about the data source or driver changes.
* <LI>Connection and Statement pooling and distributed transactions are available * <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. * 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 * do not have connection and statement pooling or distributed transaction
* capabilities. * capabilities.
* </UL> * </UL>
* <p> * <p>
* Driver vendors provide <code>DataSource</code> implementations. A * Driver vendors provide {@code DataSource} implementations. A
* particular <code>DataSource</code> object represents a particular * particular {@code DataSource} object represents a particular
* physical data source, and each connection the <code>DataSource</code> object * physical data source, and each connection the {@code DataSource} object
* creates is a connection to that physical data source. * creates is a connection to that physical data source.
* <p> * <p>
* A logical name for the data source is registered with a naming service that * A logical name for the data source is registered with a naming service that
* uses the Java Naming and Directory Interface&trade; * uses the Java Naming and Directory Interface&trade;
* (JNDI) API, usually by a system administrator or someone performing the * (JNDI) API, usually by a system administrator or someone performing the
* duties of a system administrator. An application can retrieve 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 * 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. * source it represents.
* <p> * <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 * 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 * implementation will automatically get a connection that participates in
* connection pooling. * 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 * middle tier infrastructure so that the connections it produces can be
* used for distributed transactions without any special coding. * used for distributed transactions without any special coding.
* *
* <H2>Connection Pooling and Statement Pooling</H2> * <H2>Connection Pooling and Statement Pooling</H2>
* <p> * <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 * object that is implemented to work with a middle tier connection pool manager
* will participate in connection pooling. This can improve performance * will participate in connection pooling. This can improve performance
* dramatically because creating new connections is very expensive. * dramatically because creating new connections is very expensive.
@ -106,40 +106,40 @@
* Connection pooling is totally transparent. It is done automatically * Connection pooling is totally transparent. It is done automatically
* in the middle tier of a Java EE configuration, so from an application's * 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 * viewpoint, no change in code is required. An application simply uses
* the <code>DataSource.getConnection</code> method to get the pooled * the {@code DataSource.getConnection} method to get the pooled
* connection and uses it the same way it uses any <code>Connection</code> * connection and uses it the same way it uses any {@code Connection}
* object. * object.
* <p> * <p>
* The classes and interfaces used for connection pooling are: * The classes and interfaces used for connection pooling are:
* <UL> * <UL>
* <LI><code>ConnectionPoolDataSource</code> * <LI>{@code ConnectionPoolDataSource}
* <LI><code>PooledConnection</code> * <LI>{@code PooledConnection}
* <LI><code>ConnectionEvent</code> * <LI>{@code ConnectionEvent}
* <LI><code>ConnectionEventListener</code> * <LI>{@code ConnectionEventListener}
* <LI><code>StatementEvent</code> * <LI>{@code StatementEvent}
* <LI><code>StatementEventListener</code> * <LI>{@code StatementEventListener}
* </UL> * </UL>
* The connection pool manager, a facility in the middle tier of * The connection pool manager, a facility in the middle tier of
* a three-tier architecture, uses these classes and interfaces * a three-tier architecture, uses these classes and interfaces
* behind the scenes. When a <code>ConnectionPoolDataSource</code> object * behind the scenes. When a {@code ConnectionPoolDataSource} object
* is called on to create a <code>PooledConnection</code> object, the * is called on to create a {@code PooledConnection} object, the
* connection pool manager will register as a <code>ConnectionEventListener</code> * connection pool manager will register as a {@code ConnectionEventListener}
* object with the new <code>PooledConnection</code> object. When the connection * object with the new {@code PooledConnection} object. When the connection
* is closed or there is an error, the connection pool manager (being a listener) * 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> * <p>
* If the connection pool manager supports <code>Statement</code> pooling, for * If the connection pool manager supports {@code Statement} pooling, for
* <code>PreparedStatements</code>, which can be determined by invoking the method * {@code PreparedStatements}, which can be determined by invoking the method
* <code>DatabaseMetaData.supportsStatementPooling</code>, the * {@code DatabaseMetaData.supportsStatementPooling}, the
* connection pool manager will register as a <code>StatementEventListener</code> * connection pool manager will register as a {@code StatementEventListener}
* object with the new <code>PooledConnection</code> object. When the * object with the new {@code PooledConnection} object. When the
* <code>PreparedStatement</code> is closed or there is an error, the connection * {@code PreparedStatement} is closed or there is an error, the connection
* pool manager (being a listener) * 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> * <H2>Distributed Transactions</H2>
* <p> * <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 * object that is implemented to work with the middle tier infrastructure
* may participate in distributed transactions. This gives an application * may participate in distributed transactions. This gives an application
* the ability to involve data sources on multiple servers in a single * the ability to involve data sources on multiple servers in a single
@ -147,112 +147,112 @@
* <p> * <p>
* The classes and interfaces used for distributed transactions are: * The classes and interfaces used for distributed transactions are:
* <UL> * <UL>
* <LI><code>XADataSource</code> * <LI>{@code XADataSource}
* <LI><code>XAConnection</code> * <LI>{@code XAConnection}
* </UL> * </UL>
* These interfaces are used by the transaction manager; an application does * These interfaces are used by the transaction manager; an application does
* not use them directly. * not use them directly.
* <p> * <p>
* The <code>XAConnection</code> interface is derived from the * The {@code XAConnection} interface is derived from the
* <code>PooledConnection</code> interface, so what applies to a pooled connection * {@code PooledConnection} interface, so what applies to a pooled connection
* also applies to a connection that is part of a distributed transaction. * also applies to a connection that is part of a distributed transaction.
* A transaction manager in the middle tier handles everything transparently. * A transaction manager in the middle tier handles everything transparently.
* The only change in application code is that an application cannot do anything * 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. * that would interfere with the transaction manager's handling of the transaction.
* Specifically, an application cannot call the methods <code>Connection.commit</code> * Specifically, an application cannot call the methods {@code Connection.commit}
* or <code>Connection.rollback</code>, and it cannot set the connection to be in * or {@code Connection.rollback}, and it cannot set the connection to be in
* auto-commit mode (that is, it cannot call * auto-commit mode (that is, it cannot call
* <code>Connection.setAutoCommit(true)</code>). * {@code Connection.setAutoCommit(true)}).
* <p> * <p>
* An application does not need to do anything special to participate in a * An application does not need to do anything special to participate in a
* distributed transaction. * distributed transaction.
* It simply creates connections to the data sources it wants to use via * 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 * The transaction manager manages the transaction behind the scenes. The
* <code>XADataSource</code> interface creates <code>XAConnection</code> objects, and * {@code XADataSource} interface creates {@code XAConnection} objects, and
* each <code>XAConnection</code> object creates an <code>XAResource</code> object * each {@code XAConnection} object creates an {@code XAResource} object
* that the transaction manager uses to manage the connection. * that the transaction manager uses to manage the connection.
* *
* *
* <H2>Rowsets</H2> * <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. * interfaces behind the scenes. These can be grouped into three categories.
* <OL> * <OL>
* <LI>Event Notification * <LI>Event Notification
* <UL> * <UL>
* <LI><code>RowSetListener</code><br> * <LI>{@code RowSetListener}<br>
* A <code>RowSet</code> object is a JavaBeans&trade; * A {@code RowSet} object is a JavaBeans&trade;
* component because it has properties and participates in the JavaBeans * 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 * 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 * occur to a particular {@code RowSet} object. Such a component registers
* itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code> * itself as a listener with a rowset via the {@code RowSet.addRowSetListener}
* method. * method.
* <p> * <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 * 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 * with it. The listener reacts by carrying out its implementation of the
* notification method called on it. * notification method called on it.
* <LI><code>RowSetEvent</code><br> * <LI>{@code RowSetEvent}<br>
* As part of its internal notification process, a <code>RowSet</code> object * As part of its internal notification process, a {@code RowSet} object
* creates an instance of <code>RowSetEvent</code> and passes it to the listener. * creates an instance of {@code RowSetEvent} and passes it to the listener.
* The listener can use this <code>RowSetEvent</code> object to find out which rowset * The listener can use this {@code RowSetEvent} object to find out which rowset
* had the event. * had the event.
* </UL> * </UL>
* <LI>Metadata * <LI>Metadata
* <UL> * <UL>
* <LI><code>RowSetMetaData</code><br> * <LI>{@code RowSetMetaData}<br>
* This interface, derived from the * This interface, derived from the
* <code>ResultSetMetaData</code> interface, provides information about * {@code ResultSetMetaData} interface, provides information about
* the columns in a <code>RowSet</code> object. An application can use * the columns in a {@code RowSet} object. An application can use
* <code>RowSetMetaData</code> methods to find out how many columns the * {@code RowSetMetaData} methods to find out how many columns the
* rowset contains and what kind of data each column can contain. * rowset contains and what kind of data each column can contain.
* <p> * <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 * setting the information about columns, but an application would not
* normally use these methods. When an application calls the <code>RowSet</code> * normally use these methods. When an application calls the {@code RowSet}
* method <code>execute</code>, the <code>RowSet</code> object will contain * method {@code execute}, the {@code RowSet} object will contain
* a new set of rows, and its <code>RowSetMetaData</code> object will have been * a new set of rows, and its {@code RowSetMetaData} object will have been
* internally updated to contain information about the new columns. * internally updated to contain information about the new columns.
* </UL> * </UL>
* <LI>The Reader/Writer Facility<br> * <LI>The Reader/Writer Facility<br>
* A <code>RowSet</code> object that implements the <code>RowSetInternal</code> * A {@code RowSet} object that implements the {@code RowSetInternal}
* interface can call on the <code>RowSetReader</code> object associated with it * interface can call on the {@code RowSetReader} object associated with it
* to populate itself with data. It can also call on the <code>RowSetWriter</code> * 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 * object associated with it to write any changes to its rows back to the
* data source from which it originally got the rows. * data source from which it originally got the rows.
* A rowset that remains connected to its data source does not need to use a * 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. * reader and writer because it can simply operate on the data source directly.
* *
* <UL> * <UL>
* <LI><code>RowSetInternal</code><br> * <LI>{@code RowSetInternal}<br>
* By implementing the <code>RowSetInternal</code> interface, a * By implementing the {@code RowSetInternal} interface, a
* <code>RowSet</code> object gets access to * {@code RowSet} object gets access to
* its internal state and is able to call on its reader and writer. A rowset * 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 * 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 * 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 * 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 * (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. * this information. An application does not normally invoke these methods directly.
* *
* <LI><code>RowSetReader</code><br> * <LI>{@code RowSetReader}<br>
* A disconnected <code>RowSet</code> object that has implemented the * A disconnected {@code RowSet} object that has implemented the
* <code>RowSetInternal</code> interface can call on its reader (the * {@code RowSetInternal} interface can call on its reader (the
* <code>RowSetReader</code> object associated with it) to populate it with * {@code RowSetReader} object associated with it) to populate it with
* data. When an application calls the <code>RowSet.execute</code> method, * 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 * 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, * 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 * 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 * 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> * <LI>{@code RowSetWriter}<br>
* A disconnected <code>RowSet</code> object that has implemented the * A disconnected {@code RowSet} object that has implemented the
* <code>RowSetInternal</code> interface can call on its writer (the * {@code RowSetInternal} interface can call on its writer (the
* <code>RowSetWriter</code> object associated with it) to write changes * {@code RowSetWriter} object associated with it) to write changes
* back to the underlying data source. Implementations may vary widely, but * back to the underlying data source. Implementations may vary widely, but
* generally, a writer will do the following: * generally, a writer will do the following:
* *
@ -269,7 +269,7 @@
* </UL> * </UL>
* </OL> * </OL>
* <p> * <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 * ways, and anyone may write an implementation. Developers are encouraged
* to use their imaginations in coming up with new ways to use rowsets. * to use their imaginations in coming up with new ways to use rowsets.
* *
@ -283,7 +283,7 @@
* <h2>Related Documentation</h2> * <h2>Related Documentation</h2>
* <p> * <p>
* The Java Series book published by Addison-Wesley Longman provides detailed * 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: * package:
* *
* <ul> * <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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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. * Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * 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. * Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * 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. * Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * 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. * Copyright (c) 2011 SAP AG. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *