{@code
- * int sumOfWeights = widgets.}parallelStream(){@code
+ * int sumOfWeights = widgets.parallelStream()
* .filter(b -> b.getColor() == RED)
* .mapToInt(b -> b.getWeight())
* .sum();
diff --git a/src/java.smartcardio/share/classes/javax/smartcardio/package-info.java b/src/java.smartcardio/share/classes/javax/smartcardio/package-info.java
index 180128c0a3d..ef6489509df 100644
--- a/src/java.smartcardio/share/classes/javax/smartcardio/package-info.java
+++ b/src/java.smartcardio/share/classes/javax/smartcardio/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -36,7 +36,7 @@
*
*
* The API is defined by classes in the package
- * javax.smartcardio. They can be classified as follows:
+ * {@code javax.smartcardio}. They can be classified as follows:
*
*
RowSet implementation
+ * Provides five standard implementations of the standard JDBC {@code RowSet} implementation
* interface definitions. These reference implementations are included with the J2SE version
- * 1.5 platform and represent the benchmark standard RowSet 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.
* JdbcRowSetImpl- Thejavax.sql.rowset.JdbcRowSet+ *{@code JdbcRowSetImpl} - The {@code javax.sql.rowset.JdbcRowSet} * interface reference implementation.* - * All details on their expected behavior, including their interactions with the
*
- *CachedRowSetImpl- Thejavax.sql.rowset.CachedRowSetinterface + * {@code CachedRowSetImpl} - The {@code javax.sql.rowset.CachedRowSet} interface * reference implementation.
*
- *WebRowSetImpl- Thejavax.sql.rowset.WebRowSetinterface + * {@code WebRowSetImpl} - The {@code javax.sql.rowset.WebRowSet} interface * reference implementation.
*
- *FilteredRowSetImpl- Thejavax.sql.rowset.FilteredRowSet+ * {@code FilteredRowSetImpl} - The {@code javax.sql.rowset.FilteredRowSet} * interface reference implementation.
*
- *JoinRowSetImpl- Thejavax.sql.rowset.JoinRowSetinterface + * {@code JoinRowSetImpl} - The {@code javax.sql.rowset.JoinRowSet} interface * reference implementation.
*SyncProvider- * SPI and helper classes are provided in the interface definitions in thejavax.sql.rowset+ * All details on their expected behavior, including their interactions with the {@code SyncProvider} + * SPI and helper classes are provided in the interface definitions in the {@code javax.sql.rowset} * package specification.
* *2.0 Usage
* The reference implementations represent robust implementations of the standard - *RowSetinterfaces defined in thejavax.sql.rowsetpackage. - * All disconnectedRowSetimplementations, such as theCachedRowSetImpl- * andWebRowSetImpl, are flexible enough to use theSyncFactorySPIs to - * leverage non-reference implementationSyncProviderimplementations to obtain + * {@code RowSet} interfaces defined in the {@code javax.sql.rowset} package. + * All disconnected {@code RowSet} implementations, such as the {@code CachedRowSetImpl} + * and {@code WebRowSetImpl}, are flexible enough to use the {@code SyncFactory} SPIs to + * leverage non-reference implementation {@code SyncProvider} implementations to obtain * differing synchronization semantics. Furthermore, developers and vendors alike are free * to use these implementations and integrate them into their products just as they * can with to other components of the Java platform.
* *3.0 Extending the JDBC RowSet Implementations
* - * The JDBCRowSetreference implementations are provided as non-final + * The JDBC {@code RowSet} reference implementations are provided as non-final * classes so that any developer can extend them to provide additional features * while maintaining the core required standard functionality and compatibility. It * is anticipated that many vendors and developers will extend the standard feature diff --git a/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java b/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java index e58a581625e..f25376c0e3b 100644 --- a/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java +++ b/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,39 +25,39 @@ /** * - * Repository for theRowSetreference implementations of the - *SyncProviderabstract class. These implementations provide a - * disconnectedRowSet+ * Repository for the {@code RowSet} reference implementations of the + * {@code SyncProvider} abstract class. These implementations provide a + * disconnected {@code RowSet} * object with the ability to synchronize the data in the underlying data * source with its data. These implementations are provided as - * the defaultSyncProviderimplementations and are accessible via the - *SyncProviderSPI managed by theSyncFactory. + * the default {@code SyncProvider} implementations and are accessible via the + * {@code SyncProvider} SPI managed by the {@code SyncFactory}. * - *1.0
- * The main job of aSyncProviderReference ImplementationsSyncProviderimplementation is to manage + *1.0 {@code SyncProvider} Reference Implementations
+ * The main job of a {@code SyncProvider} implementation is to manage * the reader and writer mechanisms. - * TheSyncProviderSPI, as specified in thejavax.sql.rowset.spi- * package, provides a pluggable mechanism by whichjavax.sql.RowSetReader- * andjavax.sql.RowSetWriterimplementations can be supplied to a disconnected - *RowSetobject. + * The {@code SyncProvider} SPI, as specified in the {@code javax.sql.rowset.spi} + * package, provides a pluggable mechanism by which {@code javax.sql.RowSetReader} + * and {@code javax.sql.RowSetWriter} implementations can be supplied to a disconnected + * {@code RowSet} object. *- * A reader, a
javax.sql.RowSetReader- * object, does the work necessary to populate aRowSetobject with data. - * A writer, ajavax.sql.RowSetWriterobject, does the work necessary for - * synchronizing aRowSetobject's data with the data in the originating - * source of data. Put another way, a writer writes aRowSet+ * A reader, a {@code javax.sql.RowSetReader} + * object, does the work necessary to populate a {@code RowSet} object with data. + * A writer, a {@code javax.sql.RowSetWriter} object, does the work necessary for + * synchronizing a {@code RowSet} object's data with the data in the originating + * source of data. Put another way, a writer writes a {@code RowSet} * object's data back to the data source. ** Generally speaking, the course of events is this. The reader makes a connection to - * the data source and reads the data from a
ResultSetobject into its - *RowSetobject. Then it closes the connection. While - * theRowSetobject is disconnected, an application makes some modifications - * to the data and calls the methodacceptChanges. At this point, the + * the data source and reads the data from a {@code ResultSet} object into its + * {@code RowSet} object. Then it closes the connection. While + * the {@code RowSet} object is disconnected, an application makes some modifications + * to the data and calls the method {@code acceptChanges}. At this point, the * writer is called to write the changes back to the database table or view * from which the original data came. This is called synchronization. ** If the data in the originating data source has not changed, there is no problem - * with just writing the
RowSetobject's new data to the data source. + * with just writing the {@code RowSet} object's new data to the data source. * If it has changed, however, there is a conflict that needs to be resolved. One * way to solve the problem is not to let the data in the data source be changed in * the first place, which can be done by setting locks on a row, a table, or the @@ -65,44 +65,44 @@ * very expensive. Another approach, which is at the other end of the spectrum, * is simply to assume that no conflicts will occur and thus do nothing to avoid * conflicts. - * DifferentSyncProviderimplementations may handle synchronization in + * Different {@code SyncProvider} implementations may handle synchronization in * any of these ways, varying from doing no checking for * conflicts, to doing various levels of checking, to guaranteeing that there are no * conflicts. *- * The
SyncProviderclass offers methods to help aRowSet+ * The {@code SyncProvider} class offers methods to help a {@code RowSet} * object discover and manage how a provider handles synchronization. - * The methodgetProviderGradereturns the + * The method {@code getProviderGrade} returns the * grade of synchronization a provider offers. An application can * direct the provider to use a particular level of locking by calling - * the methodsetDataSourceLockand specifying the level of locking desired. - * If aRowSetobject's data came from an SQLVIEW, an - * application may call the methodsupportsUpdatableViewto - * find out whether theVIEWcan be updated. + * the method {@code setDataSourceLock} and specifying the level of locking desired. + * If a {@code RowSet} object's data came from an SQL {@code VIEW}, an + * application may call the method {@code supportsUpdatableView} to + * find out whether the {@code VIEW} can be updated. ** Synchronization is done completely behind the scenes, so it is third party vendors of * synchronization provider implementations who have to take care of this complex task. * Application programmers can decide which provider to use and the level of locking to * be done, but they are free from having to worry about the implementation details. *
- * The JDBC
RowSetImplementations reference implementation provides two - * implementations of theSyncProviderclass: + * The JDBC {@code RowSet} Implementations reference implementation provides two + * implementations of the {@code SyncProvider} class: * **
* @@ -117,12 +117,12 @@ * properties. The general rule is that a RowSet is required to set only the * properties that it uses.- - *
RIOptimisticProvider- provides thejavax.sql.RowSetReader- * andjavax.sql.RowSetWriterinterface implementations and provides + * {@code RIOptimisticProvider} - provides the {@code javax.sql.RowSetReader} + * and {@code javax.sql.RowSetWriter} interface implementations and provides * an optimistic concurrency model for synchronization. This model assumes that there * will be few conflicts and therefore uses a relatively low grade of synchronization. * If no other provider is available, this is the default provider that the - *SyncFactorywill supply to aRowSetobject. + * {@code SyncFactory} will supply to a {@code RowSet} object. *
*- - *
RIXMLProvider- provides theXmlReader(an extension - * of thejavax.sql.RowSetReaderinterface) and theXmlWriter- * (an extension of thejavax.sql.RowSetWriterinterface) to enable - *WebRowSetobjects to write their state to a - * well formed XML document according to theWebRowSetXML schema + * {@code RIXMLProvider} - provides the {@code XmlReader} (an extension + * of the {@code javax.sql.RowSetReader} interface) and the {@code XmlWriter} + * (an extension of the {@code javax.sql.RowSetWriter} interface) to enable + * {@code WebRowSet} objects to write their state to a + * well formed XML document according to the {@code WebRowSet} XML schema * definition.
*
*
- * Thecommandproperty contains the query that determines what - * data aRowSetwill contain. Rowsets have methods for setting a query's + * The {@code command} property contains the query that determines what + * data a {@code RowSet} will contain. Rowsets have methods for setting a query's * parameter(s), which means that a query can be executed multiple times with * different parameters to produce different result sets. Or the query can be * changed to something completely new to get a new result set. - *Once a rowset contains the rows from a
ResultSetobject or some + *Once a rowset contains the rows from a {@code ResultSet} object or some * other data source, its column values can be updated, and its rows can be * inserted or deleted. Any method that causes a change in the rowset's values * or cursor position also notifies any object that has been registered as @@ -134,13 +134,13 @@ * source to keep the rowset and its data source synchronized. Although this * involves many operations behind the scenes, it is completely transparent * to the application programmer and remains the concern of the RowSet provider - * developer. All an application has to do is invoke the method
* - *acceptChanges, + * developer. All an application has to do is invoke the method {@code acceptChanges}, * and the data source backing the rowset will be updated to match the current * values in the rowset.A disconnected rowset, such as a
CachedRowSetorWebRowSet+ *A disconnected rowset, such as a {@code CachedRowSet} or {@code WebRowSet} * object, establishes a connection to populate itself with data from a database - * and then closes the connection. The
* *RowSetobject will remain + * and then closes the connection. The {@code RowSet} object will remain * disconnected until it wants to propagate changes back to its database table, * which is optional. To write its changes back to the database (synchronize with * the database), the rowset establishes a connection, write the changes, and then @@ -148,9 +148,9 @@ *3.0 Other Possible Implementations
- * There are many other possible implementations of theSyncProviderabstract + * There are many other possible implementations of the {@code SyncProvider} abstract * class. One possibility is to employ a more robust synchronization model, which - * would give aRowSetobject increased trust in the provider's + * would give a {@code RowSet} object increased trust in the provider's * ability to get any updates back to the original data source. Another possibility * is a more formal synchronization mechanism such as SyncML * (http://www.syncml.org/)
diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java b/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java index a2079df3d45..947a072c36f 100644 --- a/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java +++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -24,9 +24,9 @@ */ /** - * Standard interfaces and base classes for JDBCRowSet+ * Standard interfaces and base classes for JDBC {@code RowSet} * implementations. This package contains interfaces and classes - * that a standardRowSetimplementation either implements or extends. + * that a standard {@code RowSet} implementation either implements or extends. * *Table of Contents
*@@ -38,133 +38,133 @@ *
* *1.0 Package Specification
- * This package specifies five standard JDBCRowSetinterfaces. + * This package specifies five standard JDBC {@code RowSet} interfaces. * All five extend the * RowSet interface described in the JDBC 3.0 * specification. It is anticipated that additional definitions - * of more specialized JDBCRowSettypes will emerge as this technology + * of more specialized JDBC {@code RowSet} types will emerge as this technology * matures. Future definitions should be specified as subinterfaces using * inheritance similar to the way it is used in this specification. ** Note: The interface definitions provided in this package form the basis for - * all compliant JDBC
RowSetimplementations. Vendors and more advanced - * developers who intend to provide their own compliantRowSetimplementations + * all compliant JDBC {@code RowSet} implementations. Vendors and more advanced + * developers who intend to provide their own compliant {@code RowSet} implementations * should pay particular attention to the assertions detailed in specification * interfaces. * *2.0 Standard RowSet Definitions
*- *
* *JdbcRowSet- A wrapper around - * aResultSetobject that makes it possible to use the result set as a + *- {@code JdbcRowSet} - A wrapper around + * a {@code ResultSet} object that makes it possible to use the result set as a * JavaBeans™ component. Thus, - * a
JdbcRowSetobject can be a Bean that any tool + * a {@code JdbcRowSet} object can be a Bean that any tool * makes available for assembling an application as part of a component based - * architecture. AJdbcRowSetobject is a connectedRowSet+ * architecture. A {@code JdbcRowSet} object is a connected {@code RowSet} * object, that is, it * must continually maintain its connection to its data source using a JDBC - * technology-enabled driver ("JDBC driver"). In addition, aJdbcRowSet+ * technology-enabled driver ("JDBC driver"). In addition, a {@code JdbcRowSet} * object provides a fully updatable and scrollable tabular * data structure as defined in the JDBC 3.0 specification. * *- - *
CachedRowSet™ - * - ACachedRowSetobject is a JavaBeans™ + * {@code CachedRowSet}™ + * - A {@code CachedRowSet} object is a JavaBeans™ * component that is scrollable, updatable, serializable, and generally disconnected from - * the source of its data. ACachedRowSetobject + * the source of its data. A {@code CachedRowSet} object * typically contains rows from a result set, but it can also contain rows from any - * file with a tabular format, such as a spreadsheet.CachedRowSetimplementations - * must use theSyncFactoryto manage and obtain pluggable - *SyncProviderobjects to provide synchronization between the - * disconnectedRowSetobject and the originating data source. - * Typically aSyncProviderimplementation relies upon a JDBC + * file with a tabular format, such as a spreadsheet. {@code CachedRowSet} implementations + * must use the {@code SyncFactory} to manage and obtain pluggable + * {@code SyncProvider} objects to provide synchronization between the + * disconnected {@code RowSet} object and the originating data source. + * Typically a {@code SyncProvider} implementation relies upon a JDBC * driver to obtain connectivity to a particular data source. * Further details on this mechanism are discussed in thejavax.sql.rowset.spipackage + * href="spi/package-summary.html">{@code javax.sql.rowset.spi} package * specification. * - *WebRowSet- A - *WebRowSetobject is an extension ofCachedRowSet- * that can read and write aRowSetobject in a well formed XML format. - * This class calls anXmlReaderobject - * (an extension of theRowSetReader+ *- {@code WebRowSet} - A + * {@code WebRowSet} object is an extension of {@code CachedRowSet} + * that can read and write a {@code RowSet} object in a well formed XML format. + * This class calls an {@code XmlReader} object + * (an extension of the {@code RowSetReader} * interface) to read a rowset in XML format. It calls an - *
XmlWriterobject (an extension of the - *RowSetWriterinterface) + * {@code XmlWriter} object (an extension of the + * {@code RowSetWriter} interface) * to write a rowset in XML format. The reader and writer required by - *WebRowSetobjects are provided by the - *SyncFactoryin the form ofSyncProvider+ * {@code WebRowSet} objects are provided by the + * {@code SyncFactory} in the form of {@code SyncProvider} * implementations. In order to ensure well formed XML usage, a standard generic XML * Schema is defined and published at * - *http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd. + * {@code http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd}. * - *FilteredRowSet- A - *FilteredRowSetobject provides filtering functionality in a programmatic - * and extensible way. There are many instances when aRowSetobject+ *- {@code FilteredRowSet} - A + * {@code FilteredRowSet} object provides filtering functionality in a programmatic + * and extensible way. There are many instances when a {@code RowSet} {@code object} * has a need to provide filtering in its contents without sacrificing the disconnected * environment, thus saving the expense of having to create a connection to the data source. * Solutions to this need vary from providing heavyweight full scale * SQL query abilities, to portable components, to more lightweight - * approaches. A
FilteredRowSetobject consumes - * an implementation of thePredicate+ * approaches. A {@code FilteredRowSet} object consumes + * an implementation of the {@code Predicate} * interface, which may define a filter at run time. In turn, a - *FilteredRowSetobject is tasked with enforcing the set filter for both + * {@code FilteredRowSet} object is tasked with enforcing the set filter for both * inbound and outbound read and write operations. That is, all filters can be * considered as bi-directional. No standard filters are defined; * however, sufficient mechanics are specified to permit any required filter to be * implemented. * - *JoinRowSet- TheJoinRowSet+ *- {@code JoinRowSet} - The {@code JoinRowSet} * interface describes a mechanism by which relationships can be established between - * two or more standard
RowSetimplementations. Any number ofRowSet- * objects can be added to aJoinRowSetobject provided theRowSetobjects - * can be related in a SQLJOINlike fashion. By definition, the SQLJOIN+ * two or more standard {@code RowSet} implementations. Any number of {@code RowSet} + * objects can be added to a {@code JoinRowSet} object provided the {@code RowSet}objects + * can be related in a SQL {@code JOIN} like fashion. By definition, the SQL {@code JOIN} * statement is used to combine the data contained in two (or more) relational * database tables based upon a common attribute. By establishing and then enforcing - * column matches, aJoinRowSetobject establishes relationships between - *RowSetinstances without the need to touch the originating data source. + * column matches, a {@code JoinRowSet} object establishes relationships between + * {@code RowSet} instances without the need to touch the originating data source. *3.0 Implementer's Guide
- * Compliant implementations of JDBCRowSetImplementations + * Compliant implementations of JDBC {@code RowSet} Implementations * must follow the assertions described in this specification. In accordance * with the terms of the Java Community Process, a * Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the * specification. The following paragraphs outline a number of starting points for - * implementers of the standard JDBCRowSetdefinitions. Implementers + * implementers of the standard JDBC {@code RowSet} definitions. Implementers * should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines - * onSyncProviderimplementations. + * on {@code SyncProvider} implementations. * **
- 3.1 Constructor *
- *- * All
RowSetimplementations must provide a + * All {@code RowSet} implementations must provide a * no-argument constructor. *- 3.2 Role of the
BaseRowSetClass + *- 3.2 Role of the {@code BaseRowSet} Class *
- * A compliant JDBC
RowSetimplementation must implement one or more + * A compliant JDBC {@code RowSet} implementation must implement one or more * standard interfaces specified in this package and may extend the - *BaseRowSetabstract class. For example, a - *CachedRowSetimplementation must implement theCachedRowSet- * interface and extend theBaseRowSetabstract class. The - *BaseRowSetclass provides the standard architecture on which all - *RowSetimplementations should be built, regardless of whether the - *RowSetobjects exist in a connected or disconnected environment. - * TheBaseRowSetabstract class provides anyRowSetimplementation + * {@code BaseRowSet} abstract class. For example, a + * {@code CachedRowSet} implementation must implement the {@code CachedRowSet} + * interface and extend the {@code BaseRowSet} abstract class. The + * {@code BaseRowSet} class provides the standard architecture on which all + * {@code RowSet} implementations should be built, regardless of whether the + * {@code RowSet} objects exist in a connected or disconnected environment. + * The {@code BaseRowSet} abstract class provides any {@code RowSet} implementation * with its base functionality, including property manipulation and event notification * that is fully compliant with * JavaBeans * component requirements. As an example, all implementations provided in the - * reference implementations (contained in thecom.sun.rowsetpackage) use - * theBaseRowSetclass as a basis for their implementations. + * reference implementations (contained in the {@code com.sun.rowset} package) use + * the {@code BaseRowSet} class as a basis for their implementations. *- * The following table illustrates the features that the
BaseRowSet+ * The following table illustrates the features that the {@code BaseRowSet} * abstract class provides. **- *
Features in + *BaseRowSetFeatures in {@code BaseRowSet} * ** Feature @@ -175,15 +175,15 @@ ** *Properties *Provides standard JavaBeans property manipulation - * mechanisms to allow applications to get and set + * the standard {@code RowSet} properties. *RowSetcommand and - * property values. Refer to the documentation of thejavax.sql.RowSet+ * mechanisms to allow applications to get and set {@code RowSet} command and + * property values. Refer to the documentation of the {@code javax.sql.RowSet} * interface (available in the JDBC 3.0 specification) for more details on - * the standardRowSetproperties.* Event notification *Provides standard JavaBeans event notifications - * to registered event listeners. Refer to the documentation of @@ -204,70 +204,70 @@ * *javax.sql.RowSetEvent+ * to registered event listeners. Refer to the documentation of {@code javax.sql.RowSetEvent} * interface (available in the JDBC 3.0 specification) for * more details on how to register and handle standard RowSet events generated * by compliant implementations.- 3.3 Connected RowSet Requirements *
- * The
JdbcRowSetdescribes aRowSetobject that must always - * be connected to the originating data source. Implementations of theJdbcRowSet+ * The {@code JdbcRowSet} describes a {@code RowSet} object that must always + * be connected to the originating data source. Implementations of the {@code JdbcRowSet} * should ensure that this connection is provided solely by a JDBC driver. - * Furthermore,RowSetobjects that are implementations of the - *JdbcRowSetinterface and are therefore operating in a connected environment - * do not use theSyncFactoryto obtain aRowSetReaderobject - * or aRowSetWriterobject. They can safely rely on the JDBC driver to + * Furthermore, {@code RowSet} objects that are implementations of the + * {@code JdbcRowSet} interface and are therefore operating in a connected environment + * do not use the {@code SyncFactory} to obtain a {@code RowSetReader} object + * or a {@code RowSetWriter} object. They can safely rely on the JDBC driver to * supply their needs by virtue of the presence of an underlying updatable and scrollable - *ResultSetimplementation. + * {@code ResultSet} implementation. * *- * 3.4 Disconnected RowSet Requirements *
- * A disconnected
RowSetobject, such as aCachedRowSetobject, + * A disconnected {@code RowSet} object, such as a {@code CachedRowSet} object, * should delegate - * connection management to aSyncProviderobject provided by the - *SyncFactory. To ensure fully disconnected semantics, all - * disconnectedRowSetobjects must ensure - * that the original connection made to the data source to populate theRowSet+ * connection management to a {@code SyncProvider} object provided by the + * {@code SyncFactory}. To ensure fully disconnected semantics, all + * disconnected {@code RowSet} objects must ensure + * that the original connection made to the data source to populate the {@code RowSet} * object is closed to permit the garbage collector to recover and release resources. The - *SyncProviderobject ensures that the critical JDBC properties are + * {@code SyncProvider} object ensures that the critical JDBC properties are * maintained in order to re-establish a connection to the data source when a - * synchronization is required. A disconnectedRowSetobject should + * synchronization is required. A disconnected {@code RowSet} object should * therefore ensure that no - * extraneous references remain on theConnectionobject. + * extraneous references remain on the {@code Connection} object. * *- 3.5 Role of RowSetMetaDataImpl *
- * The
RowsetMetaDataImplclass is a utility class that provides an implementation of the + * The {@code RowsetMetaDataImpl} class is a utility class that provides an implementation of the * RowSetMetaData interface, supplying standard setter * method implementations for metadata for both connected and disconnected - *RowSetobjects. 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. * *- 3.6 RowSetWarning Class *
- * The
RowSetWarningclass provides warnings that can be set - * onRowSetimplementations. + * The {@code RowSetWarning} class provides warnings that can be set + * on {@code RowSet} implementations. * Similar to SQLWarning objects, - *RowSetWarningobjects are silently chained to the object whose method - * caused the warning to be thrown. AllRowSetimplementations should + * {@code RowSetWarning} objects are silently chained to the object whose method + * caused the warning to be thrown. All {@code RowSet} implementations should * ensure that this chaining occurs if a warning is generated and also ensure that the - * warnings are available via thegetRowSetWarningsmethod defined in either - * theJdbcRowSetinterface or theCachedRowSetinterface. + * warnings are available via the {@code getRowSetWarnings} method defined in either + * the {@code JdbcRowSet} interface or the {@code CachedRowSet} interface. * After a warning has been retrieved with one of the - *getRowSetWarningsmethods, theRowSetWarningmethod - *getNextWarningcan be called on it to retrieve any warnings that might - * be chained on it. If a warning is returned,getNextWarningcan be called + * {@code getRowSetWarnings} methods, the {@code RowSetWarning} method + * {@code getNextWarning} can be called on it to retrieve any warnings that might + * be chained on it. If a warning is returned, {@code getNextWarning} can be called * on it, and so on until there are no more warnings. * *- 3.7 The Joinable Interface *
* *- * The
Joinableinterface provides both connected and disconnected - *RowSetobjects with the capability to be added to a - *JoinRowSetobject in an SQLJOINoperation. - * ARowSetobject that has implemented theJoinable+ * The {@code Joinable} interface provides both connected and disconnected + * {@code RowSet} objects with the capability to be added to a + * {@code JoinRowSet} object in an SQL {@code JOIN} operation. + * A {@code RowSet} object that has implemented the {@code Joinable} * interface can set a match column, retrieve a match column, or unset a match column. - * AJoinRowSetobject can then use theRowSetobject's - * match column as a basis for adding theRowSetobject. + * A {@code JoinRowSet} object can then use the {@code RowSet} object's + * match column as a basis for adding the {@code RowSet} object. *- 3.8 The RowSetFactory Interface *
* diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java b/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java index c56afc0521c..3ee24f76843 100644 --- a/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java +++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,11 +26,11 @@ /** * Provides utility classes to allow serializable mappings between SQL types * and data types in the Java programming language. - *- * A
RowSetFactoryimplementation must + * A {@code RowSetFactory} implementation must * be provided. *Standard JDBC
RowSetimplementations may use these utility + *Standard JDBC {@code RowSet} implementations may use these utility * classes to - * assist in the serialization of disconnected
* @@ -38,40 +38,40 @@ * A serializable mapping in the Java programming language of an SQL ARRAY * value.RowSetobjects. + * assist in the serialization of disconnected {@code RowSet} objects. * This is useful - * when transmitting a disconnectedRowSetobject over the wire to + * when transmitting a disconnected {@code RowSet} object over the wire to * a different VM or across layers within an application.
*
*
- * TheSerialArrayclass provides a constructor for creating aSerialArray+ * The {@code SerialArray} class provides a constructor for creating a {@code SerialArray} * instance from an Array object, methods for getting the base type and * the SQL name for the base type, and methods for copying all or part of a - *SerialArrayobject.
+ * {@code SerialArray} object.
* *2.0 SerialBlob
* A serializable mapping in the Java programming language of an SQL BLOB * value.
*
- * TheSerialBlobclass provides a constructor for creating an instance + * The {@code SerialBlob} class provides a constructor for creating an instance * from a Blob object. Note that the Blob object should have brought the SQL - * BLOB value's data over to the client before aSerialBlobobject + * BLOB value's data over to the client before a {@code SerialBlob} object * is constructed from it. The data of an SQL BLOB value can be materialized - * on the client as an array of bytes (using the methodBlob.getBytes) - * or as a stream of uninterpreted bytes (using the methodBlob.getBinaryStream). + * 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}). *
*
- *SerialBlobmethods make it possible to make a copy of aSerialBlob+ * {@code SerialBlob} methods make it possible to make a copy of a {@code SerialBlob} * object as an array of bytes or as a stream. They also make it possible - * to locate a given pattern of bytes or aBlobobject within aSerialBlob+ * to locate a given pattern of bytes or a {@code Blob} object within a {@code SerialBlob} * object.
* *3.0 SerialClob
* A serializable mapping in the Java programming language of an SQL CLOB * value.
*
- * TheSerialClobclass provides a constructor for creating an instance - * from aClobobject. Note that theClobobject should have - * brought the SQL CLOB value's data over to the client before aSerialClob+ * The {@code SerialClob} class provides a constructor for creating an instance + * from a {@code Clob} object. Note that the {@code Clob} object should have + * brought the SQL CLOB value's data over to the client before a {@code SerialClob} * object is constructed from it. The data of an SQL CLOB value can be * materialized on the client as a stream of Unicode characters.
*
- *SerialClobmethods make it possible to get a substring from a - *SerialClobobject or to locate the start of a pattern of characters. + * {@code SerialClob} methods make it possible to get a substring from a + * {@code SerialClob} object or to locate the start of a pattern of characters. *
* *5.0 SerialDatalink
@@ -79,11 +79,12 @@ * value. A DATALINK value references a file outside of the underlying data source * that the originating data source manages.
*
- *RowSetimplementations can use the methodRowSet.getURL()to retrieve - * ajava.net.URLobject, which can be used to manipulate the external data. + * {@code RowSet} implementations can use the method {@code RowSet.getURL()} to retrieve + * a {@code java.net.URL} object, which can be used to manipulate the external data. *
- *
- *java.net.URL url = rowset.getURL(1);
+ *+ * java.net.URL url = rowset.getURL(1); + ** *6.0 SerialJavaObject
* A serializable mapping in the Java programming language of an SQL JAVA_OBJECT @@ -94,15 +95,15 @@ * object is not immediately serializable, this class will attempt to serialize * all non static members to permit the object instance state to be serialized. * Static or transient fields cannot be serialized and attempting to do so - * will result in aSerialExceptionbeing thrown.
+ * will result in a {@code SerialException} being thrown.
* *7.0 SerialRef
* A serializable mapping between the SQL REF type and the Java programming * language.
*
- * TheSerialRefclass provides a constructor for creating aSerialRef- * instance from aReftype and provides methods for getting - * and setting theRefobject type.
+ * The {@code SerialRef} class provides a constructor for creating a {@code SerialRef} + * instance from a {@code Ref} type and provides methods for getting + * and setting the {@code Ref} object type.
* *8.0 SerialStruct
* A serializable mapping in the Java programming language of an SQL structured @@ -110,36 +111,36 @@ * form, and if an attribute is itself a structured type, each of its attributes * that is not already serializable is mapped to a serializable form.
*
- * In addition, if aMapobject is passed to one of the constructors or - * to the methodgetAttributes, the structured type is custom mapped - * according to the mapping specified in theMapobject. + * In addition, if a {@code Map} object is passed to one of the constructors or + * to the method {@code getAttributes}, the structured type is custom mapped + * according to the mapping specified in the {@code Map} object. *
- * TheSerialStructclass provides a constructor for creating an - * instance from aStructobject, a method for retrieving the SQL + * The {@code SerialStruct} class provides a constructor for creating an + * instance from a {@code Struct} object, a method for retrieving the SQL * type name of the SQL structured type in the database, and methods for retrieving * its attribute values.
* *9.0 SQLInputImpl
* An input stream used for custom mapping user-defined types (UDTs). An - *SQLInputImplobject is an input stream that contains a stream of + * {@code SQLInputImpl} object is an input stream that contains a stream of * values that are * the attributes of a UDT. This class is used by the driver behind the scenes - * when the methodgetObjectis called on an SQL structured or distinct - * type that has a custom mapping; a programmer never invokesSQLInputImpl+ * when the method {@code getObject} is called on an SQL structured or distinct + * type that has a custom mapping; a programmer never invokes {@code SQLInputImpl} * methods directly.
*
- * TheSQLInputImplclass provides a set of reader methods - * analogous to theResultSetgetter methods. These methods make it - * possible to read the values in anSQLInputImplobject. The method - *wasNullis used to determine whether the last value read was SQL NULL. + * The {@code SQLInputImpl} class provides a set of reader methods + * analogous to the {@code ResultSet} getter methods. These methods make it + * possible to read the values in an {@code SQLInputImpl} object. The method + * {@code wasNull} is used to determine whether the last value read was SQL NULL. *
*
- * When a constructor or getter method that takes aMapobject is called, + * When a constructor or getter method that takes a {@code Map} object is called, * the JDBC driver calls the method - *SQLData.getSQLTypeto determine the SQL type of the UDT being custom - * mapped. The driver creates an instance ofSQLInputImpl, populating it with + * {@code SQLData.getSQLType} to determine the SQL type of the UDT being custom + * mapped. The driver creates an instance of {@code SQLInputImpl}, populating it with * the attributes of the UDT. The driver then passes the input stream to the - * methodSQLData.readSQL, which in turn calls theSQLInputImpl+ * method {@code SQLData.readSQL}, which in turn calls the {@code SQLInputImpl} * methods to read the attributes from the input stream.
* *10.0 SQLOutputImpl
@@ -148,16 +149,16 @@ * and its methods are never directly invoked by an application programmer. *
*
- * When an application calls the methodPreparedStatement.setObject, the + * When an application calls the method {@code PreparedStatement.setObject}, the * driver checks to see whether the value to be written is a UDT with a custom * mapping. If it is, there will be an entry in a type map containing the Class - * object for the class that implementsSQLDatafor this UDT. If the - * value to be written is an instance ofSQLData, the driver will - * create an instance ofSQLOutputImpland pass it to the method - *SQLData.writeSQL. - * The methodwriteSQLin turn calls the appropriateSQLOutputImpl- * writer methods to write data from theSQLDataobject to the - *SQLOutputImpl+ * object for the class that implements {@code SQLData} for this UDT. If the + * value to be written is an instance of {@code SQLData}, the driver will + * create an instance of {@code SQLOutputImpl} and pass it to the method + * {@code SQLData.writeSQL}. + * The method {@code writeSQL} in turn calls the appropriate {@code SQLOutputImpl} + * writer methods to write data from the {@code SQLData} object to the + * {@code SQLOutputImpl} * output stream as the representation of an SQL user-defined type. * *Custom Mapping
@@ -167,12 +168,12 @@ * (A DISTINCT type can thought of as having one attribute.) However, there are * many other possibilities, and there may be any number of different mappings. *- * A programmer defines the mapping by implementing the interface
SQLData. + * A programmer defines the mapping by implementing the interface {@code SQLData}. * For example, if an SQL structured type named AUTHORS has the attributes NAME, * TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The * Authors class could have the fields name, title, and publisher, to which the * attributes of AUTHORS are mapped. In such a case, the implementation of - *SQLDatacould look like the following: + * {@code SQLData} could look like the following: ** public class Authors implements SQLData { * public String name; @@ -200,27 +201,27 @@ * } ** - * Ajava.util.Mapobject is used to associate the SQL structured - * type with its mapping to the classAuthors. The following code fragment shows - * how aMapobject might be created and given an entry associating - *AUTHORSandAuthors. + * A {@code java.util.Map} object is used to associate the SQL structured + * type with its mapping to the class {@code Authors}. The following code fragment shows + * how a {@code Map} object might be created and given an entry associating + * {@code AUTHORS} and {@code Authors}. ** java.util.Map map = new java.util.HashMap(); * map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors"); ** - * TheMapobject map now contains an entry with the - * fully qualified name of the SQL structured type and theClass- * object for the classAuthors. It can be passed to a method - * to tell the driver how to mapAUTHORStoAuthors. + * The {@code Map} object map now contains an entry with the + * fully qualified name of the SQL structured type and the {@code Class} + * object for the class {@code Authors}. It can be passed to a method + * to tell the driver how to map {@code AUTHORS} to {@code Authors}. *- * For a disconnected
RowSetobject, custom mapping can be done - * only when aMapobject is passed to the method or constructor + * For a disconnected {@code RowSet} object, custom mapping can be done + * only when a {@code Map} object is passed to the method or constructor * that will be doing the custom mapping. The situation is different for - * connectedRowSetobjects because they maintain a connection + * connected {@code RowSet} objects because they maintain a connection * with the data source. A method that does custom mapping and is called by - * a disconnectedRowSetobject may use theMap- * object that is associated with theConnectionobject being + * a disconnected {@code RowSet} object may use the {@code Map} + * object that is associated with the {@code Connection} object being * used. So, in other words, if no map is specified, the connection's type * map can be used by default. */ diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java index 5c7f2661b82..2117e63ef93 100644 --- a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java +++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,9 +27,9 @@ * The standard classes and interfaces that a third party vendor has to * use in its implementation of a synchronization provider. These classes and * interfaces are referred to as the Service Provider Interface (SPI). To make it possible - * for aRowSetobject to use an implementation, the vendor must register - * it with theSyncFactorysingleton. (See the class comment for - *SyncProviderfor a full explanation of the registration process and + * for a {@code RowSet} object to use an implementation, the vendor must register + * it with the {@code SyncFactory} singleton. (See the class comment for + * {@code SyncProvider} for a full explanation of the registration process and * the naming convention to be used.) * *Table of Contents
@@ -44,46 +44,46 @@ * *1.0 Package Specification
*- * The following classes and interfaces make up the
javax.sql.rowset.spi+ * The following classes and interfaces make up the {@code javax.sql.rowset.spi} * package: *- *
- * The following interfaces, in theSyncFactory- *SyncProvider- *SyncFactoryException- *SyncProviderException- *SyncResolver- *XmlReader- *XmlWriter- *TransactionalWriter+ *- {@code SyncFactory} + *
- {@code SyncProvider} + *
- {@code SyncFactoryException} + *
- {@code SyncProviderException} + *
- {@code SyncResolver} + *
- {@code XmlReader} + *
- {@code XmlWriter} + *
- {@code TransactionalWriter} *
javax.sqlpackage, are also part of the SPI: + * The following interfaces, in the {@code javax.sql} package, are also part of the SPI: *- *
*RowSetReader- *RowSetWriter+ *- {@code RowSetReader} + *
- {@code RowSetWriter} *
- * A
SyncProviderimplementation provides a disconnectedRowSet+ * A {@code SyncProvider} implementation provides a disconnected {@code RowSet} * object with the mechanisms for reading data into it and for writing data that has been * modified in it - * back to the underlying data source. A reader, aRowSetReaderor - *XMLReaderobject, reads data into aRowSetobject when the - *CachedRowSetmethodsexecuteorpopulate- * are called. A writer, aRowSetWriterorXMLWriter+ * back to the underlying data source. A reader, a {@code RowSetReader} or + * {@code XMLReader} object, reads data into a {@code RowSet} object when the + * {@code CachedRowSet} methods {@code execute} or {@code populate} + * are called. A writer, a {@code RowSetWriter} or {@code XMLWriter} * object, writes changes back to the underlying data source when the - *CachedRowSetmethodacceptChangesis called. + * {@code CachedRowSet} method {@code acceptChanges} is called. *- * The process of writing changes in a
RowSetobject to its data source - * is known as synchronization. TheSyncProviderimplementation that a - *RowSetobject is using determines the level of synchronization that the - *RowSetobject's writer uses. The various levels of synchronization are + * The process of writing changes in a {@code RowSet} object to its data source + * is known as synchronization. The {@code SyncProvider} implementation that a + * {@code RowSet} object is using determines the level of synchronization that the + * {@code RowSet} object's writer uses. The various levels of synchronization are * referred to as grades. ** The lower grades of synchronization are * known as optimistic concurrency levels because they optimistically * assume that there will be no conflicts or very few conflicts. A conflict exists when - * the same data modified in the
RowSetobject has also been modified + * the same data modified in the {@code RowSet} object has also been modified * in the data source. Using the optimistic concurrency model means that if there - * is a conflict, modifications to either the data source or theRowSet+ * is a conflict, modifications to either the data source or the {@code RowSet} * object will be lost. ** Higher grades of synchronization are called pessimistic because they assume @@ -92,114 +92,114 @@ * occur. *
* The lowest level of synchronization is simply writing any changes made to the - *
RowSetobject to its underlying data source. The writer does + * {@code RowSet} object to its underlying data source. The writer does * nothing to check for conflicts. * If there is a conflict and the data * source values are overwritten, the changes other parties have made by to the data * source are lost. *- * The
RIXMLProviderimplementation uses the lowest level - * of synchronization and just writesRowSetchanges to the data source. + * The {@code RIXMLProvider} implementation uses the lowest level + * of synchronization and just writes {@code RowSet} changes to the data source. * ** For the next level up, the * writer checks to see if there are any conflicts, and if there are, * it does not write anything to the data source. The problem with this concurrency * level is that if another party has modified the corresponding data in the data source - * since the
RowSetobject got its data, - * the changes made to theRowSetobject are lost. The - *RIOptimisticProviderimplementation uses this level of synchronization. + * since the {@code RowSet} object got its data, + * the changes made to the {@code RowSet} object are lost. The + * {@code RIOptimisticProvider} implementation uses this level of synchronization. ** At higher levels of synchronization, referred to as pessimistic concurrency, * the writer take steps to avoid conflicts by setting locks. Setting locks * can vary from setting a lock on a single row to setting a lock on a table * or the entire data source. The level of synchronization is therefore a tradeoff * between the ability of users to access the data source concurrently and the ability - * of the writer to keep the data in the
RowSetobject and its data source + * of the writer to keep the data in the {@code RowSet} object and its data source * synchronized. *- * It is a requirement that all disconnected
RowSetobjects - * (CachedRowSet,FilteredRowSet,JoinRowSet, - * andWebRowSetobjects) obtain theirSyncProviderobjects - * from theSyncFactorymechanism. + * It is a requirement that all disconnected {@code RowSet} objects + * ({@code CachedRowSet}, {@code FilteredRowSet}, {@code JoinRowSet}, + * and {@code WebRowSet} objects) obtain their {@code SyncProvider} objects + * from the {@code SyncFactory} mechanism. ** The reference implementation (RI) provides two synchronization providers. *
- *
* - * TheseRIOptimisticProvider
- * The default provider that theSyncFactoryinstance will - * supply to a disconnectedRowSetobject when no provider + *- {@code RIOptimisticProvider}
+ * The default provider that the {@code SyncFactory} instance will + * supply to a disconnected {@code RowSet} object when no provider * implementation is specified.
* This synchronization provider uses an optimistic concurrency model, * assuming that there will be few conflicts among users * who are accessing the same data in a database. It avoids * using locks; rather, it checks to see if there is a conflict - * before trying to synchronize theRowSetobject and the + * before trying to synchronize the {@code RowSet} object and the * data source. If there is a conflict, it does nothing, meaning that - * changes to theRowSetobject are not persisted to the data + * changes to the {@code RowSet} object are not persisted to the data * source. - *RIXMLProvider
+ *- {@code RIXMLProvider}
* A synchronization provider that can be used with a - *WebRowSetobject, 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 - *RIXMLProviderimplementation does no checking at all for + * {@code RIXMLProvider} implementation does no checking at all for * conflicts and simply writes any updated data in the - *WebRowSetobject to the underlying data source. - *WebRowSetobjects use this provider when they are + * {@code WebRowSet} object to the underlying data source. + * {@code WebRowSet} objects use this provider when they are * dealing with XML data. *SyncProviderimplementations + * These {@code SyncProvider} implementations * are bundled with the reference implementation, which makes them always available to - *RowSetimplementations. - *SyncProviderimplementations make themselves available by being - * registered with theSyncFactorysingleton. When aRowSet+ * {@code RowSet} implementations. + * {@code SyncProvider} implementations make themselves available by being + * registered with the {@code SyncFactory} singleton. When a {@code RowSet} * object requests a provider, by specifying it in the constructor or as an argument to the - *CachedRowSetmethodsetSyncProvider, - * theSyncFactorysingleton + * {@code CachedRowSet} method {@code setSyncProvider}, + * the {@code SyncFactory} singleton * checks to see if the requested provider has been registered with it. - * If it has, theSyncFactorycreates an instance of it and passes it to the - * requestingRowSetobject. - * If theSyncProviderimplementation that is specified has not been registered, - * theSyncFactorysingleton causes aSyncFactoryExceptionobject + * If it has, the {@code SyncFactory} creates an instance of it and passes it to the + * requesting {@code RowSet} object. + * If the {@code SyncProvider} implementation that is specified has not been registered, + * the {@code SyncFactory} singleton causes a {@code SyncFactoryException} object * to be thrown. If no provider is specified, - * theSyncFactorysingleton will create an instance of the default - * provider implementation,RIOptimisticProvider, - * and pass it to the requestingRowSetobject. + * the {@code SyncFactory} singleton will create an instance of the default + * provider implementation, {@code RIOptimisticProvider}, + * and pass it to the requesting {@code RowSet} object. * *- * If a
WebRowSetobject does not specify a provider in its constructor, the - *SyncFactorywill give it an instance ofRIOptimisticProvider. - * However, the constructor forWebRowSetis implemented to set the provider - * to theRIXMLProvider, which reads and writes aRowSetobject + * If a {@code WebRowSet} object does not specify a provider in its constructor, the + * {@code SyncFactory} will give it an instance of {@code RIOptimisticProvider}. + * However, the constructor for {@code WebRowSet} is implemented to set the provider + * to the {@code RIXMLProvider}, which reads and writes a {@code RowSet} object * in XML format. ** See the SyncProvider class * specification for further details. *
- * Vendors may develop a
SyncProviderimplementation with any one of the possible - * levels of synchronization, thus givingRowSetobjects a choice of + * Vendors may develop a {@code SyncProvider} implementation with any one of the possible + * levels of synchronization, thus giving {@code RowSet} objects a choice of * synchronization mechanisms. * *2.0 Service Provider Interface Architecture
* 2.1 Overview ** The Service Provider Interface provides a pluggable mechanism by which - *
SyncProviderimplementations can be registered and then generated when - * required. The lazy reference mechanism employed by theSyncFactorylimits + * {@code SyncProvider} implementations can be registered and then generated when + * required. The lazy reference mechanism employed by the {@code SyncFactory} limits * unnecessary resource consumption by not creating an instance until it is * required by a disconnected - *RowSetobject. TheSyncFactoryclass also provides + * {@code RowSet} object. The {@code SyncFactory} class also provides * a standard API to configure logging options and streams that may be provided - * by a particularSyncProviderimplementation. + * by a particular {@code SyncProvider} implementation. *- * 2.2 Registering with the
SyncFactory+ * 2.2 Registering with the {@code SyncFactory} *- * A third party
SyncProviderimplementation must be registered with the - *SyncFactoryin order for a disconnectedRowSetobject - * to obtain it and thereby use itsjavax.sql.RowSetReaderand - *javax.sql.RowSetWriter+ * A third party {@code SyncProvider} implementation must be registered with the + * {@code SyncFactory} in order for a disconnected {@code RowSet} object + * to obtain it and thereby use its {@code javax.sql.RowSetReader} and + * {@code javax.sql.RowSetWriter} * implementations. The following registration mechanisms are available to all - *SyncProviderimplementations: + * {@code SyncProvider} implementations: **
*- System properties - Properties set at the command line. These * properties are set at run time and apply system-wide per invocation of the Java @@ -210,159 +210,159 @@ * This can be specified using a System Property or by modifying a standard * property file located in the platform run-time. The * reference implementation of this technology includes a standard property - * file than can be edited to add additional
SyncProviderobjects. + * file than can be edited to add additional {@code SyncProvider} objects. * *- JNDI Context - Available providers can be registered on a JNDI - * context. The
SyncFactorywill attempt to loadSyncProvider+ * context. The {@code SyncFactory} will attempt to load {@code SyncProvider} * objects bound to the context and register them with the factory. This - * context must be supplied to theSyncFactoryfor the mechanism to + * context must be supplied to the {@code SyncFactory} for the mechanism to * function correctly. ** 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 - *
SyncFactoryclass description. + * {@code SyncFactory} class description. ** 2.3 SyncFactory Provider Instance Generation Policies *
- * The
SyncFactorygenerates a requestedSyncProvider+ * The {@code SyncFactory} generates a requested {@code SyncProvider} * object if the provider has been correctly registered. The - * following policies are adhered to when either a disconnectedRowSetobject - * is instantiated with a specifiedSyncProviderimplementation or is - * reconfigured at runtime with an alternativeSyncProviderobject. + * following policies are adhered to when either a disconnected {@code RowSet} object + * is instantiated with a specified {@code SyncProvider} implementation or is + * reconfigured at runtime with an alternative {@code SyncProvider} object. *- *
*- If a
SyncProviderobject is specified and theSyncFactory- * contains no reference to the provider, aSyncFactoryExceptionis + *- If a {@code SyncProvider} object is specified and the {@code SyncFactory} + * contains no reference to the provider, a {@code SyncFactoryException} is * thrown. * - *
- If a
SyncProviderobject is specified and theSyncFactory+ *- If a {@code SyncProvider} object is specified and the {@code SyncFactory} * contains a reference to the provider, the requested provider is supplied. * - *
- If no
SyncProviderobject is specified, the reference - * implementation providerRIOptimisticProvideris supplied. + *- If no {@code SyncProvider} object is specified, the reference + * implementation provider {@code RIOptimisticProvider} is supplied. *
* These policies are explored in more detail in the - *
SyncFactoryclass. + * {@code SyncFactory} class. * *3.0 SyncProvider Implementer's Guide
* * 3.1 Requirements *- * A compliant
SyncProviderimplementation that is fully pluggable - * into theSyncFactorymust extend and implement all - * abstract methods in theSyncProvider+ * A compliant {@code SyncProvider} implementation that is fully pluggable + * into the {@code SyncFactory} must extend and implement all + * abstract methods in the {@code SyncProvider} * class. In addition, an implementation must determine the * grade, locking and updatable view capabilities defined in the - *SyncProviderclass definition. One or more of the - *SyncProviderdescription criteria must be supported. It + * {@code SyncProvider} class definition. One or more of the + * {@code SyncProvider} description criteria must be supported. It * is expected that vendor implementations will offer a range of grade, locking, and * updatable view capabilities. *- * Furthermore, the
SyncProvidernaming convention must be followed as - * detailed in theSyncProviderclass + * Furthermore, the {@code SyncProvider} naming convention must be followed as + * detailed in the {@code SyncProvider} class * description. ** 3.2 Grades *
* JSR 114 defines a set of grades to describe the quality of synchronization - * a
SyncProviderobject can offer a disconnectedRowSet+ * a {@code SyncProvider} object can offer a disconnected {@code RowSet} * object. These grades are listed from the lowest quality of service to the highest. **
*- GRADE_NONE - No synchronization with the originating data source is - * provided. A
SyncProviderimplementation returning this grade will simply - * attempt to write any data that has changed in theRowSetobject to the + * provided. A {@code SyncProvider} implementation returning this grade will simply + * attempt to write any data that has changed in the {@code RowSet} object to the *underlying data source, overwriting whatever is there. No attempt is made to compare * original values with current values to see if there is a conflict. The - *RIXMLProvideris implemented with this grade. + * {@code RIXMLProvider} is implemented with this grade. * *- GRADE_CHECK_MODIFIED_AT_COMMIT - A low grade of optimistic synchronization. - * A
SyncProviderimplementation returning this grade + * A {@code SyncProvider} implementation returning this grade * will check for conflicts in rows that have changed between the last synchronization * and the current synchronization under way. Any changes in the originating data source - * that have been modified will not be reflected in the disconnectedRowSet- * object. If there are no conflicts, changes in theRowSetobject will be + * that have been modified will not be reflected in the disconnected {@code RowSet} + * object. If there are no conflicts, changes in the {@code RowSet} object will be * written to the data source. If there are conflicts, no changes are written. - * TheRIOptimisticProviderimplementation uses this grade. + * The {@code RIOptimisticProvider} implementation uses this grade. * *- GRADE_CHECK_ALL_AT_COMMIT - A high grade of optimistic synchronization. - * A
SyncProviderimplementation returning this grade + * A {@code SyncProvider} implementation returning this grade * will check all rows, including rows that have not changed in the disconnected - *RowSetobject. In this way, any changes to rows in the underlying - * data source will be reflected in the disconnectedRowSetobject + * {@code RowSet} object. In this way, any changes to rows in the underlying + * data source will be reflected in the disconnected {@code RowSet} object * when the synchronization finishes successfully. * *- GRADE_LOCK_WHEN_MODIFIED - A pessimistic grade of synchronization. - *
SyncProviderimplementations returning this grade will lock + * {@code SyncProvider} implementations returning this grade will lock * the row in the originating data source that corresponds to the row being changed - * in theRowSetobject 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. * *- GRADE_LOCK_WHEN_LOADED - A higher pessimistic synchronization grade. - * A
SyncProviderimplementation returning this grade will lock + * A {@code SyncProvider} implementation returning this grade will lock * the entire view and/or table affected by the original query used to - * populate aRowSetobject. + * populate a {@code RowSet} object. ** 3.3 Locks *
* JSR 114 defines a set of constants that specify whether any locks have been - * placed on a
RowSetobject's underlying data source and, if so, + * placed on a {@code RowSet} object's underlying data source and, if so, * on which constructs the locks are placed. These locks will remain on the data - * source while theRowSetobject is disconnected from the data source. + * source while the {@code RowSet} object is disconnected from the data source. ** These constants should be considered complementary to the * grade constants. The default setting for the majority of grade settings requires - * that no data source locks remain when a
RowSetobject is disconnected + * that no data source locks remain when a {@code RowSet} object is disconnected * from its data source. - * The gradesGRADE_LOCK_WHEN_MODIFIEDand - *GRADE_LOCK_WHEN_LOADEDallow a disconnectedRowSetobject + * The grades {@code GRADE_LOCK_WHEN_MODIFIED} and + * {@code GRADE_LOCK_WHEN_LOADED} allow a disconnected {@code RowSet} object * to have a fine-grained control over the degree of locking. **
*- DATASOURCE_NO_LOCK - No locks remain on the originating data source. - * This is the default lock setting for all
SyncProviderimplementations - * unless otherwise directed by aRowSetobject. + * This is the default lock setting for all {@code SyncProvider} implementations + * unless otherwise directed by a {@code RowSet} object. * *- DATASOURCE_ROW_LOCK - A lock is placed on the rows that are touched by - * the original SQL query used to populate the
RowSetobject. + * the original SQL query used to populate the {@code RowSet} object. * *- DATASOURCE_TABLE_LOCK - A lock is placed on all tables that are touched - * by the query that was used to populate the
RowSetobject. + * by the query that was used to populate the {@code RowSet} object. * *- DATASOURCE_DB_LOCK - * A lock is placed on the entire data source that is used by the
RowSet+ * A lock is placed on the entire data source that is used by the {@code RowSet} * object. ** 3.4 Updatable Views *
- * A
RowSetobject may be populated with data from an SQLVIEW. - * The following constants indicate whether aSyncProviderobject can - * update data in the table or tables from which theVIEWwas derived. + * A {@code RowSet} object may be populated with data from an SQL {@code VIEW}. + * The following constants indicate whether a {@code SyncProvider} object can + * update data in the table or tables from which the {@code VIEW} was derived. **
*- UPDATABLE_VIEW_SYNC - * Indicates that a
SyncProviderimplementation supports synchronization - * to the table or tables from which the SQLVIEWused to populate - * aRowSetobject is derived. + * Indicates that a {@code SyncProvider} implementation supports synchronization + * to the table or tables from which the SQL {@code VIEW} used to populate + * a {@code RowSet} object is derived. * *- NONUPDATABLE_VIEW_SYNC - * Indicates that a
SyncProviderimplementation does not support - * synchronization to the table or tables from which the SQLVIEW- * used to populate aRowSetobject is derived. + * Indicates that a {@code SyncProvider} implementation does not support + * synchronization to the table or tables from which the SQL {@code VIEW} + * used to populate a {@code RowSet} object is derived. *- * 3.5 Usage of
SyncProviderGrading and Locking + * 3.5 Usage of {@code SyncProvider} Grading and Locking *- * In the example below, the reference
CachedRowSetImplimplementation - * reconfigures its currentSyncProviderobject by calling the - *setSyncProvidermethod.
+ * In the example below, the reference {@code CachedRowSetImpl} implementation + * reconfigures its current {@code SyncProvider} object by calling the + * {@code setSyncProvider} method.
* ** CachedRowSetImpl crs = new CachedRowSetImpl(); * crs.setSyncProvider("com.foo.bar.HASyncProvider"); *- * An application can retrieve theSyncProviderobject currently in use - * by a disconnectedRowSetobject. It can also retrieve the + * An application can retrieve the {@code SyncProvider} object currently in use + * by a disconnected {@code RowSet} object. It can also retrieve the * grade of synchronization with which the provider was implemented and the degree of * locking currently in use. In addition, an application has the flexibility to set * the degree of locking to be used, which can increase the possibilities for successful @@ -388,10 +388,10 @@ * break; * } * - * switch (sync.getDataSourcLock() { + * switch (sync.getDataSourceLock() { * case: SyncProvider.DATASOURCE_DB_LOCK * // A lock is placed on the entire datasource that is used by the - * //RowSetobject + * // {@code RowSet} object * break; * * case: SyncProvider.DATASOURCE_NO_LOCK @@ -412,8 +412,8 @@ * * * It is also possible using the static utility method in the - *SyncFactoryclass to determine the list ofSyncProvider- * implementations currently registered with theSyncFactory. + * {@code SyncFactory} class to determine the list of {@code SyncProvider} + * implementations currently registered with the {@code SyncFactory}. * ** Enumeration e = SyncFactory.getRegisteredProviders(); @@ -422,48 +422,48 @@ * *4.0 Resolving Synchronization Conflicts
* - * The interfaceSyncResolverprovides a way for an application to - * decide manually what to do when a conflict occurs. When theCachedRowSet- * methodacceptChangesfinishes and has detected one or more conflicts, - * it throws aSyncProviderExceptionobject. An application can + * The interface {@code SyncResolver} provides a way for an application to + * decide manually what to do when a conflict occurs. When the {@code CachedRowSet} + * method {@code acceptChanges} finishes and has detected one or more conflicts, + * it throws a {@code SyncProviderException} object. An application can * catch the exception and - * have it retrieve aSyncResolverobject by calling the method - *SyncProviderException.getSyncResolver(). + * have it retrieve a {@code SyncResolver} object by calling the method + * {@code SyncProviderException.getSyncResolver()}. *- * A
SyncResolverobject, which is a special kind of - *CachedRowSetobject or - * aJdbcRowSetobject that has implemented theSyncResolver+ * A {@code SyncResolver} object, which is a special kind of + * {@code CachedRowSet} object or + * a {@code JdbcRowSet} object that has implemented the {@code SyncResolver} * interface, examines the conflicts row by row. It is a duplicate of the - *RowSetobject being synchronized except that it contains only the data + * {@code RowSet} object being synchronized except that it contains only the data * from the data source this is causing a conflict. All of the other column values are - * set tonull. To navigate from one conflict value to another, a - *SyncResolverobject provides the methodsnextConflictand - *previousConflict. + * set to {@code null}. To navigate from one conflict value to another, a + * {@code SyncResolver} object provides the methods {@code nextConflict} and + * {@code previousConflict}. *- * The
SyncResolverinterface also + * The {@code SyncResolver} interface also * provides methods for doing the following: **
*- finding out whether the conflict involved an update, a delete, or an insert *
- getting the value in the data source that caused the conflict *
- 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
RowSetobject if it needs + * or setting the value that should be in the {@code RowSet} object if it needs * to be changed *- * When the
CachedRowSetmethodacceptChangesis called, it - * delegates to theRowSetobject'sSyncProviderobject. - * How the writer provided by thatSyncProviderobject is implemented + * When the {@code CachedRowSet} method {@code acceptChanges} is called, it + * delegates to the {@code RowSet} object's {@code SyncProvider} object. + * How the writer provided by that {@code SyncProvider} object is implemented * determines what level (grade) of checking for conflicts will be done. After all * checking for conflicts is completed and one or more conflicts has been found, the method - *acceptChangesthrows aSyncProviderExceptionobject. The - * application can catch the exception and use it to obtain aSyncResolverobject. + * {@code acceptChanges} throws a {@code SyncProviderException} object. The + * application can catch the exception and use it to obtain a {@code SyncResolver} object. *- * The application can then use
SyncResolvermethods to get information + * The application can then use {@code SyncResolver} methods to get information * about each conflict and decide what to do. If the application logic or the user - * decides that a value in theRowSetobject 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. *- * The comment for the
SyncResolverinterface has more detail. + * The comment for the {@code SyncResolver} interface has more detail. * *5.0 Related Specifications
*diff --git a/src/java.sql/share/classes/java/sql/package-info.java b/src/java.sql/share/classes/java/sql/package-info.java index 374c2a04b00..2e15beb4b7b 100644 --- a/src/java.sql/share/classes/java/sql/package-info.java +++ b/src/java.sql/share/classes/java/sql/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -34,17 +34,17 @@ * to passing SQL statements to a database, it provides for reading and * writing data from any data source with a tabular format. * The reader/writer facility, available through the - *
javax.sql.RowSetgroup of interfaces, can be customized to + * {@code javax.sql.RowSet} group of interfaces, can be customized to * use and update data from a spread sheet, flat file, or any other tabular * data source. * *What the JDBC™ 4.3 API Includes
* The JDBC™ 4.3 API includes both - * thejava.sqlpackage, referred to as the JDBC core API, - * and thejavax.sqlpackage, referred to as the JDBC Optional + * the {@code java.sql} package, referred to as the JDBC core API, + * and the {@code javax.sql} package, referred to as the JDBC Optional * Package API. This complete JDBC API * is included in the Java™ Standard Edition (Java SE™), version 7. - * Thejavax.sqlpackage extends the functionality of the JDBC API + * The {@code javax.sql} package extends the functionality of the JDBC API * from a client-side API to a server-side API, and it is an essential part * of the Java™ Enterprise Edition * (Java EE™) technology. @@ -91,141 +91,141 @@ * check your driver's documentation to see whether it supports a feature before * you try to use it. *- * NOTE: The class
SQLPermissionwas added in the + * NOTE: The class {@code SQLPermission} was added in the * Java™ 2 SDK, Standard Edition, * version 1.3 release. This class is used to prevent unauthorized - * access to the logging stream associated with theDriverManager, + * access to the logging stream associated with the {@code DriverManager}, * which may contain information such as table names, column data, and so on. * - *What the
- * Thejava.sqlPackage Containsjava.sqlpackage contains API for the following: + *What the {@code java.sql} Package Contains
+ * The {@code java.sql} package contains API for the following: *- *
* - *- Making a connection with a database via the
DriverManagerfacility + *- Making a connection with a database via the {@code DriverManager} facility *
- *
*DriverManagerclass -- makes a connection with a driver - *SQLPermissionclass -- provides permission when code + *- {@code DriverManager} class -- makes a connection with a driver + *
- {@code SQLPermission} class -- provides permission when code * running within a Security Manager, such as an applet, * attempts to set up a logging stream through the - *
DriverManager- *Driverinterface -- provides the API for registering + * {@code DriverManager} + *- {@code Driver} interface -- provides the API for registering * and connecting drivers based on JDBC technology ("JDBC drivers"); - * generally used only by the
DriverManagerclass - *DriverPropertyInfoclass -- provides properties for a + * generally used only by the {@code DriverManager} class + *- {@code DriverPropertyInfo} class -- provides properties for a * JDBC driver; not used by the general user *
- Sending SQL statements to a database *
- *
*Statement-- used to send basic SQL statements - *PreparedStatement-- used to send prepared statements or - * basic SQL statements (derived fromStatement) - *CallableStatement-- used to call database stored - * procedures (derived fromPreparedStatement) - *Connectioninterface -- provides methods for creating + *- {@code Statement} -- used to send basic SQL statements + *
- {@code PreparedStatement} -- used to send prepared statements or + * basic SQL statements (derived from {@code Statement}) + *
- {@code CallableStatement} -- used to call database stored + * procedures (derived from {@code PreparedStatement}) + *
- {@code Connection} interface -- provides methods for creating * statements and managing connections and their properties - *
Savepoint-- provides savepoints in a transaction + *- {@code Savepoint} -- provides savepoints in a transaction * *
- Retrieving and updating the results of a query *
- *
*ResultSetinterface + *- {@code ResultSet} interface *
- Standard mappings for SQL types to classes and interfaces in the * Java programming language *
- *
*Arrayinterface -- mapping for SQLARRAY- *Blobinterface -- mapping for SQLBLOB- *Clobinterface -- mapping for SQLCLOB- *Dateclass -- mapping for SQLDATE- *NClobinterface -- mapping for SQLNCLOB- *Refinterface -- mapping for SQLREF- *RowIdinterface -- mapping for SQLROWID- *Structinterface -- mapping for SQLSTRUCT- *SQLXMLinterface -- mapping for SQLXML- *Timeclass -- mapping for SQLTIME- *Timestampclass -- mapping for SQLTIMESTAMP- *Typesclass -- provides constants for SQL types + *- {@code Array} interface -- mapping for SQL {@code ARRAY} + *
- {@code Blob} interface -- mapping for SQL {@code BLOB} + *
- {@code Clob} interface -- mapping for SQL {@code CLOB} + *
- {@code Date} class -- mapping for SQL {@code DATE} + *
- {@code NClob} interface -- mapping for SQL {@code NCLOB} + *
- {@code Ref} interface -- mapping for SQL {@code REF} + *
- {@code RowId} interface -- mapping for SQL {@code ROWID} + *
- {@code Struct} interface -- mapping for SQL {@code STRUCT} + *
- {@code SQLXML} interface -- mapping for SQL {@code XML} + *
- {@code Time} class -- mapping for SQL {@code TIME} + *
- {@code Timestamp} class -- mapping for SQL {@code TIMESTAMP} + *
- {@code Types} class -- provides constants for SQL types *
- Custom mapping an SQL user-defined type (UDT) to a class in the * Java programming language *
- *
*SQLDatainterface -- specifies the mapping of + *- {@code SQLData} interface -- specifies the mapping of * a UDT to an instance of this class - *
SQLInputinterface -- provides methods for reading + *- {@code SQLInput} interface -- provides methods for reading * UDT attributes from a stream - *
SQLOutputinterface -- provides methods for writing + *- {@code SQLOutput} interface -- provides methods for writing * UDT attributes back to a stream *
- Metadata *
- *
*DatabaseMetaDatainterface -- provides information + *- {@code DatabaseMetaData} interface -- provides information * about the database - *
ResultSetMetaDatainterface -- provides information - * about the columns of aResultSetobject - *ParameterMetaDatainterface -- provides information - * about the parameters toPreparedStatementcommands + *- {@code ResultSetMetaData} interface -- provides information + * about the columns of a {@code ResultSet} object + *
- {@code ParameterMetaData} interface -- provides information + * about the parameters to {@code PreparedStatement} commands *
- Exceptions *
- *
*SQLException-- thrown by most methods when there + *- {@code SQLException} -- thrown by most methods when there * is a problem accessing data and by some methods for other reasons - *
SQLWarning-- thrown to indicate a warning - *DataTruncation-- thrown to indicate that data may have + *- {@code SQLWarning} -- thrown to indicate a warning + *
- {@code DataTruncation} -- thrown to indicate that data may have * been truncated - *
BatchUpdateException-- thrown to indicate that not all + *- {@code BatchUpdateException} -- thrown to indicate that not all * commands in a batch update executed successfully *
+ *
java.sqlandjavax.sqlFeatures Introduced in the JDBC 4.3 API{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.3 API
*- *
* - *- Added
- *Shardingsupport- Enhanced
Connectionto be able to provide hints + *- Added {@code Sharding} support
+ *- Enhanced {@code Connection} to be able to provide hints * to the driver that a request, an independent unit of work, * is beginning or ending
- *- Enhanced
DatabaseMetaDatato determine if Sharding is + *- Enhanced {@code DatabaseMetaData} to determine if Sharding is * supported
- *- Added the method
driverstoDriverManager+ *- Added the method {@code drivers} to {@code DriverManager} * to return a Stream of the currently loaded and * available JDBC drivers
- *- Added support to
Statementfor enquoting literals + *- Added support to {@code Statement} for enquoting literals * and simple identifiers
*- Clarified the Java SE version that methods were deprecated
*+ *
java.sqlandjavax.sqlFeatures Introduced in the JDBC 4.2 API{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.2 API
*- *
* - *- Added
- *JDBCTypeenum andSQLTypeinterface- Support for
REF CURSORSinCallableStatement+ *- Added {@code JDBCType} enum and {@code SQLType} interface
+ *- Support for {@code REF CURSORS} in {@code CallableStatement} *
- *DatabaseMetaDatamethods to return maximum Logical LOB size + *- {@code DatabaseMetaData} methods to return maximum Logical LOB size * and if Ref Cursors are supported
*- Added support for large update counts
* *+ *
java.sqlandjavax.sqlFeatures Introduced in the JDBC 4.1 API{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.1 API
*- *
- *- Allow
Connection, - *ResultSetandStatementobjects to be + *- Allow {@code Connection}, + * {@code ResultSet} and {@code Statement} objects to be * used with the try-with-resources statement
- *- Support added to
- *CallableStatementand - *ResultSetto specify the Java type to convert to via the - *getObjectmethodDatabaseMetaDatamethods to return PseudoColumns and if a + *- Support added to {@code CallableStatement} and + * {@code ResultSet} to specify the Java type to convert to via the + * {@code getObject} method
+ *- {@code DatabaseMetaData} methods to return PseudoColumns and if a * generated key is always returned
- *- Added support to
Connectionto specify a database schema, + *- Added support to {@code Connection} to specify a database schema, * abort and timeout a physical connection.
- *- Added support to close a
Statementobject when its dependent + *- Added support to close a {@code Statement} object when its dependent * objects have been closed
- *- Support for obtaining the parent logger for a
+ *Driver, - *DataSource,ConnectionPoolDataSourceand - *XADataSource- Support for obtaining the parent logger for a {@code Driver}, + * {@code DataSource}, {@code ConnectionPoolDataSource} and + * {@code XADataSource}
* *+ *
java.sqlandjavax.sqlFeatures Introduced in the JDBC 4.0 API{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 4.0 API
**
* * - *- auto java.sql.Driver discovery -- no longer need to load a - *
java.sql.Driverclass viaClass.forName+ * {@code java.sql.Driver} class via {@code Class.forName} *- National Character Set support added *
- Support added for the SQL:2003 XML data type *
- SQLException enhancements -- Added support for cause chaining; New SQLExceptions @@ -236,92 +236,92 @@ *
- Support added to allow a JDBC application to access an instance of a JDBC resource * that has been wrapped by a vendor, usually in an application server or connection * pooling environment. - *
- Availability to be notified when a
PreparedStatementthat is associated - * with aPooledConnectionhas been closed or the driver determines is invalid + *- Availability to be notified when a {@code PreparedStatement} that is associated + * with a {@code PooledConnection} has been closed or the driver determines is invalid * * *
+ *
java.sqlandjavax.sqlFeatures Introduced in the JDBC 3.0 API{@code java.sql} and {@code javax.sql} Features Introduced in the JDBC 3.0 API
**
* - *- Pooled statements -- reuse of statements associated with a pooled * connection *
- Savepoints -- allow a transaction to be rolled back to a designated * savepoint - *
- Properties defined for
ConnectionPoolDataSource-- specify + *- Properties defined for {@code ConnectionPoolDataSource} -- specify * how connections are to be pooled - *
- Metadata for parameters of a
PreparedStatementobject + *- Metadata for parameters of a {@code PreparedStatement} object *
- Ability to retrieve values from automatically generated columns - *
- Ability to have multiple
ResultSetobjects - * returned fromCallableStatementobjects open at the + *- Ability to have multiple {@code ResultSet} objects + * returned from {@code CallableStatement} objects open at the * same time - *
- Ability to identify parameters to
CallableStatement+ *- Ability to identify parameters to {@code CallableStatement} * objects by name as well as by index - *
ResultSetholdability -- ability to specify whether cursors + *- {@code ResultSet} holdability -- ability to specify whether cursors * should be held open or closed at the end of a transaction *
- Ability to retrieve and update the SQL structured type instance that a - *
Refobject references - *- Ability to programmatically update
BLOB, - *CLOB,ARRAY, andREFvalues. - *- Addition of the
java.sql.Types.DATALINKdata type -- + * {@code Ref} object references + *- Ability to programmatically update {@code BLOB}, + * {@code CLOB}, {@code ARRAY}, and {@code REF} values. + *
- Addition of the {@code java.sql.Types.DATALINK} data type -- * allows JDBC drivers access to objects stored outside a data source *
- Addition of metadata for retrieving SQL type hierarchies *
+ *
java.sqlFeatures Introduced in the JDBC 2.1 Core API{@code java.sql} Features Introduced in the JDBC 2.1 Core API
*- *
* - *- Scrollable result sets--using new methods in the
ResultSet+ *- Scrollable result sets--using new methods in the {@code ResultSet} * interface that allow the cursor to be moved to a particular row or to a * position relative to its current position *
- Batch updates - *
- Programmatic updates--using
ResultSetupdater methods + *- Programmatic updates--using {@code ResultSet} updater methods *
- New data types--interfaces mapping the SQL3 data types *
- Custom mapping of user-defined types (UDTs) *
- Miscellaneous features, including performance hints, the use of character - * streams, full precision for
java.math.BigDecimalvalues, + * streams, full precision for {@code java.math.BigDecimal} values, * additional security, and * support for time zones in date, time, and timestamp values. *
javax.sqlFeatures Introduced in the JDBC 2.0 Optional + *{@code javax.sql} Features Introduced in the JDBC 2.0 Optional * Package API
*- *
* * *- The
DataSourceinterface as a means of making a connection. The + *- The {@code DataSource} interface as a means of making a connection. The * Java Naming and Directory Interface™ - * (JNDI) is used for registering a
DataSourceobject with a + * (JNDI) is used for registering a {@code DataSource} object with a * naming service and also for retrieving it. *- Pooled connections -- allowing connections to be used and reused *
- Distributed transactions -- allowing a transaction to span diverse * DBMS servers - *
RowSettechnology -- providing a convenient means of + *- {@code RowSet} technology -- providing a convenient means of * handling and passing data *
Custom Mapping of UDTs
* 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 SQLDISTINCT+ * programming language. An SQL structured type or an SQL {@code DISTINCT} * type are the UDTs that may be custom mapped. The following three * steps set up a custom mapping: *- *
*- Defining the SQL structured type or
DISTINCTtype in SQL + *- Defining the SQL structured type or {@code DISTINCT} type in SQL *
- Defining the class in the Java programming language to which the * SQL UDT will be mapped. This class must implement the - *
SQLDatainterface. - *- Making an entry in a
Connectionobject's type map + * {@code SQLData} interface. + *- Making an entry in a {@code Connection} object's type map * that contains two things: *
*
*- the fully-qualified SQL name of the UDT - *
- the
Classobject for the class that implements the - *SQLDatainterface + *- the {@code Class} object for the class that implements the + * {@code SQLData} interface *
* When these are in place for a UDT, calling the methods - *
ResultSet.getObjectorCallableStatement.getObject+ * {@code ResultSet.getObject} or {@code CallableStatement.getObject} * on that UDT will automatically retrieve the custom mapping for it. Also, the - *PreparedStatement.setObjectmethod 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. * *Package Specification
diff --git a/src/java.sql/share/classes/javax/sql/package-info.java b/src/java.sql/share/classes/javax/sql/package-info.java index 628b4d36030..64028801302 100644 --- a/src/java.sql/share/classes/javax/sql/package-info.java +++ b/src/java.sql/share/classes/javax/sql/package-info.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,36 +26,36 @@ /** * Provides the API for server side data source access and processing from * the Java™ programming language. - * This package supplements thejava.sql+ * This package supplements the {@code java.sql} * package and, as of the version 1.4 release, is included in the * Java Platform, Standard Edition (Java SE™). * It remains an essential part of the Java Platform, Enterprise Edition * (Java EE™). *- * The
javax.sqlpackage provides for the following: + * The {@code javax.sql} package provides for the following: *- *
*- The
DataSourceinterface as an alternative to the - *DriverManagerfor establishing a + *- The {@code DataSource} interface as an alternative to the + * {@code DriverManager} for establishing a * connection with a data source *
- Connection pooling and Statement pooling *
- Distributed transactions *
- Rowsets *
- * Applications use the
DataSourceandRowSet+ * Applications use the {@code DataSource} and {@code RowSet} * APIs directly, but the connection pooling and distributed transaction * APIs are used internally by the middle-tier infrastructure. * - *Using a
+ *DataSourceObject to Make a ConnectionUsing a {@code DataSource} Object to Make a Connection
*- * The
javax.sqlpackage provides the preferred - * way to make a connection with a data source. TheDriverManager+ * The {@code javax.sql} package provides the preferred + * way to make a connection with a data source. The {@code DriverManager} * class, the original mechanism, is still valid, and code using it will - * continue to run. However, the newerDataSourcemechanism + * continue to run. However, the newer {@code DataSource} mechanism * is preferred because it offers many advantages over the - *DriverManagermechanism. + * {@code DriverManager} mechanism. *- * These are the main advantages of using a
DataSourceobject to + * These are the main advantages of using a {@code DataSource} object to * make a connection: ** @@ -63,39 +63,39 @@ * that it is not necessary to make changes in application code when * something about the data source or driver changes. *
*- Connection and Statement pooling and distributed transactions are available - * through a
DataSourceobject that is + * through a {@code DataSource} object that is * implemented to work with the middle-tier infrastructure. - * Connections made through theDriverManager+ * Connections made through the {@code DriverManager} * do not have connection and statement pooling or distributed transaction * capabilities. *- * Driver vendors provide
DataSourceimplementations. A - * particularDataSourceobject represents a particular - * physical data source, and each connection theDataSourceobject + * Driver vendors provide {@code DataSource} implementations. A + * particular {@code DataSource} object represents a particular + * physical data source, and each connection the {@code DataSource} object * creates is a connection to that physical data source. ** A logical name for the data source is registered with a naming service that * uses the Java Naming and Directory Interface™ * (JNDI) API, usually by a system administrator or someone performing the * duties of a system administrator. An application can retrieve the - *
DataSourceobject 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 - *DataSourceobject to create a connection to the physical data + * {@code DataSource} object to create a connection to the physical data * source it represents. *- * A
DataSourceobject can be implemented to work with the + * A {@code DataSource} object can be implemented to work with the * middle tier infrastructure so that the connections it produces will be - * pooled for reuse. An application that uses such aDataSource+ * pooled for reuse. An application that uses such a {@code DataSource} * implementation will automatically get a connection that participates in * connection pooling. - * ADataSourceobject can also be implemented to work with the + * A {@code DataSource} object can also be implemented to work with the * middle tier infrastructure so that the connections it produces can be * used for distributed transactions without any special coding. * *Connection Pooling and Statement Pooling
*- * Connections made via a
DataSource+ * Connections made via a {@code DataSource} * object that is implemented to work with a middle tier connection pool manager * will participate in connection pooling. This can improve performance * dramatically because creating new connections is very expensive. @@ -106,40 +106,40 @@ * Connection pooling is totally transparent. It is done automatically * in the middle tier of a Java EE configuration, so from an application's * viewpoint, no change in code is required. An application simply uses - * theDataSource.getConnectionmethod to get the pooled - * connection and uses it the same way it uses anyConnection+ * the {@code DataSource.getConnection} method to get the pooled + * connection and uses it the same way it uses any {@code Connection} * object. ** The classes and interfaces used for connection pooling are: *
- *
* The connection pool manager, a facility in the middle tier of * a three-tier architecture, uses these classes and interfaces - * behind the scenes. When aConnectionPoolDataSource- *PooledConnection- *ConnectionEvent- *ConnectionEventListener- *StatementEvent- *StatementEventListener+ *- {@code ConnectionPoolDataSource} + *
- {@code PooledConnection} + *
- {@code ConnectionEvent} + *
- {@code ConnectionEventListener} + *
- {@code StatementEvent} + *
- {@code StatementEventListener} *
ConnectionPoolDataSourceobject - * is called on to create aPooledConnectionobject, the - * connection pool manager will register as aConnectionEventListener- * object with the newPooledConnectionobject. When the connection + * behind the scenes. When a {@code ConnectionPoolDataSource} object + * is called on to create a {@code PooledConnection} object, the + * connection pool manager will register as a {@code ConnectionEventListener} + * object with the new {@code PooledConnection} object. When the connection * is closed or there is an error, the connection pool manager (being a listener) - * gets a notification that includes aConnectionEventobject. + * gets a notification that includes a {@code ConnectionEvent} object. *- * If the connection pool manager supports
Statementpooling, for - *PreparedStatements, which can be determined by invoking the method - *DatabaseMetaData.supportsStatementPooling, the - * connection pool manager will register as aStatementEventListener- * object with the newPooledConnectionobject. When the - *PreparedStatementis closed or there is an error, the connection + * If the connection pool manager supports {@code Statement} pooling, for + * {@code PreparedStatements}, which can be determined by invoking the method + * {@code DatabaseMetaData.supportsStatementPooling}, the + * connection pool manager will register as a {@code StatementEventListener} + * object with the new {@code PooledConnection} object. When the + * {@code PreparedStatement} is closed or there is an error, the connection * pool manager (being a listener) - * gets a notification that includes aStatementEventobject. + * gets a notification that includes a {@code StatementEvent} object. * *Distributed Transactions
*- * As with pooled connections, connections made via a
DataSource+ * As with pooled connections, connections made via a {@code DataSource} * object that is implemented to work with the middle tier infrastructure * may participate in distributed transactions. This gives an application * the ability to involve data sources on multiple servers in a single @@ -147,112 +147,112 @@ ** The classes and interfaces used for distributed transactions are: *
- *
* These interfaces are used by the transaction manager; an application does * not use them directly. *XADataSource- *XAConnection+ *- {@code XADataSource} + *
- {@code XAConnection} *
- * The
XAConnectioninterface is derived from the - *PooledConnectioninterface, so what applies to a pooled connection + * The {@code XAConnection} interface is derived from the + * {@code PooledConnection} interface, so what applies to a pooled connection * also applies to a connection that is part of a distributed transaction. * A transaction manager in the middle tier handles everything transparently. * The only change in application code is that an application cannot do anything * that would interfere with the transaction manager's handling of the transaction. - * Specifically, an application cannot call the methodsConnection.commit- * orConnection.rollback, and it cannot set the connection to be in + * Specifically, an application cannot call the methods {@code Connection.commit} + * or {@code Connection.rollback}, and it cannot set the connection to be in * auto-commit mode (that is, it cannot call - *Connection.setAutoCommit(true)). + * {@code Connection.setAutoCommit(true)}). ** An application does not need to do anything special to participate in a * distributed transaction. * It simply creates connections to the data sources it wants to use via - * the
DataSource.getConnectionmethod, 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 - *XADataSourceinterface createsXAConnectionobjects, and - * eachXAConnectionobject creates anXAResourceobject + * {@code XADataSource} interface creates {@code XAConnection} objects, and + * each {@code XAConnection} object creates an {@code XAResource} object * that the transaction manager uses to manage the connection. * * *Rowsets
- * TheRowSetinterface 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. **
*- Event Notification *
- *
*RowSetListener
- * ARowSetobject is a JavaBeans™ + *- {@code RowSetListener}
+ * A {@code RowSet} object is a JavaBeans™ * component because it has properties and participates in the JavaBeans - * event notification mechanism. TheRowSetListenerinterface + * event notification mechanism. The {@code RowSetListener} interface * is implemented by a component that wants to be notified about events that - * occur to a particularRowSetobject. Such a component registers - * itself as a listener with a rowset via theRowSet.addRowSetListener+ * occur to a particular {@code RowSet} object. Such a component registers + * itself as a listener with a rowset via the {@code RowSet.addRowSetListener} * method. *- * When the
RowSetobject changes one of its rows, changes all of + * When the {@code RowSet} object changes one of its rows, changes all of * it rows, or moves its cursor, it also notifies each listener that is registered * with it. The listener reacts by carrying out its implementation of the * notification method called on it. - *RowSetEvent
- * As part of its internal notification process, aRowSetobject - * creates an instance ofRowSetEventand passes it to the listener. - * The listener can use thisRowSetEventobject to find out which rowset + *- {@code RowSetEvent}
+ * As part of its internal notification process, a {@code RowSet} object + * creates an instance of {@code RowSetEvent} and passes it to the listener. + * The listener can use this {@code RowSetEvent} object to find out which rowset * had the event. *- Metadata *
- *
*RowSetMetaData
+ *- {@code RowSetMetaData}
* This interface, derived from the - *ResultSetMetaDatainterface, provides information about - * the columns in aRowSetobject. An application can use - *RowSetMetaDatamethods to find out how many columns the + * {@code ResultSetMetaData} interface, provides information about + * the columns in a {@code RowSet} object. An application can use + * {@code RowSetMetaData} methods to find out how many columns the * rowset contains and what kind of data each column can contain. *- * The
RowSetMetaDatainterface provides methods for + * The {@code RowSetMetaData} interface provides methods for * setting the information about columns, but an application would not - * normally use these methods. When an application calls theRowSet- * methodexecute, theRowSetobject will contain - * a new set of rows, and itsRowSetMetaDataobject will have been + * normally use these methods. When an application calls the {@code RowSet} + * method {@code execute}, the {@code RowSet} object will contain + * a new set of rows, and its {@code RowSetMetaData} object will have been * internally updated to contain information about the new columns. *- The Reader/Writer Facility
- * ARowSetobject that implements theRowSetInternal- * interface can call on theRowSetReaderobject associated with it - * to populate itself with data. It can also call on theRowSetWriter+ * A {@code RowSet} object that implements the {@code RowSetInternal} + * interface can call on the {@code RowSetReader} object associated with it + * to populate itself with data. It can also call on the {@code RowSetWriter} * object associated with it to write any changes to its rows back to the * data source from which it originally got the rows. * A rowset that remains connected to its data source does not need to use a * reader and writer because it can simply operate on the data source directly. * *- *
*RowSetInternal
- * By implementing theRowSetInternalinterface, a - *RowSetobject gets access to + *- {@code RowSetInternal}
+ * By implementing the {@code RowSetInternal} interface, a + * {@code RowSet} object gets access to * its internal state and is able to call on its reader and writer. A rowset * keeps track of the values in its current rows and of the values that immediately * preceded the current ones, referred to as the original values. A rowset * also keeps track of (1) the parameters that have been set for its command and * (2) the connection that was passed to it, if any. A rowset uses the - *RowSetInternalmethods 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. * - *RowSetReader
- * A disconnectedRowSetobject that has implemented the - *RowSetInternalinterface can call on its reader (the - *RowSetReaderobject associated with it) to populate it with - * data. When an application calls theRowSet.executemethod, + *- {@code RowSetReader}
+ * A disconnected {@code RowSet} object that has implemented the + * {@code RowSetInternal} interface can call on its reader (the + * {@code RowSetReader} object associated with it) to populate it with + * data. When an application calls the {@code RowSet.execute} method, * that method calls on the rowset's reader to do much of the work. Implementations * can vary widely, but generally a reader makes a connection to the data source, * reads data from the data source and populates the rowset with it, and closes - * the connection. A reader may also update theRowSetMetaDataobject + * the connection. A reader may also update the {@code RowSetMetaData} object * for its rowset. The rowset's internal state is also updated, either by the - * reader or directly by the methodRowSet.execute. + * reader or directly by the method {@code RowSet.execute}. * * - *RowSetWriter
- * A disconnectedRowSetobject that has implemented the - *RowSetInternalinterface can call on its writer (the - *RowSetWriterobject associated with it) to write changes + *- {@code RowSetWriter}
+ * A disconnected {@code RowSet} object that has implemented the + * {@code RowSetInternal} interface can call on its writer (the + * {@code RowSetWriter} object associated with it) to write changes * back to the underlying data source. Implementations may vary widely, but * generally, a writer will do the following: * @@ -269,7 +269,7 @@ *- * The
RowSetinterface may be implemented in any number of + * The {@code RowSet} interface may be implemented in any number of * ways, and anyone may write an implementation. Developers are encouraged * to use their imaginations in coming up with new ways to use rowsets. * @@ -283,7 +283,7 @@ *Related Documentation
** The Java Series book published by Addison-Wesley Longman provides detailed - * information about the classes and interfaces in the
javax.sql+ * information about the classes and interfaces in the {@code javax.sql} * package: * *