archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8215309: Convert package.html files to package-info.java files

Browse source 
Reviewed-by: darcy, lancea
This commit is contained in:
Roger Riggs 2018-12-12 15:35:20 -05:00
parent 3623c99b27
commit 40d7e4c2e9
28 changed files with 1590 additions and 1761 deletions
Download patch file Download diff file Expand all files Collapse all files

76
src/java.sql.rowset/share/classes/com/sun/rowset/package-info.java Normal file
View file

@ -0,0 +1,76 @@
/*
* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* Provides five standard implementations of the standard JDBC <code>RowSet</code> implementation
* interface definitions. These reference implementations are included with the J2SE version
* 1.5 platform and represent the benchmark standard <code>RowSet</code> implementations as verified
* by the Test Compatibility Kit (TCK) as mandated by the Java Community Process.
* <br>
*
* <h3>1.0 Available JDBC RowSet Reference Implementations </h3>
* The following implementations are provided:<br>
*
* <blockquote><code><b>JdbcRowSetImpl</b></code> - The <code>javax.sql.rowset.JdbcRowSet</code>
* interface reference implementation. <br>
* <br>
* <code><b>CachedRowSetImpl</b></code> - The <code>javax.sql.rowset.CachedRowSet</code> interface
* reference implementation.<br>
* <br>
* <code><b>WebRowSetImpl</b></code> - The <code>javax.sql.rowset.WebRowSet</code> interface
* reference implementation.<br>
* <br>
* <code><b>FilteredRowSetImpl</b></code> - The <code>javax.sql.rowset.FilteredRowSet</code>
* interface reference implementation.<br>
* <br>
* <code><b>JoinRowSetImpl</b></code> - The <code>javax.sql.rowset.JoinRowSet</code> interface
* reference implementation.<br>
* </blockquote>
*
* All details on their expected behavior, including their interactions with the <code>SyncProvider</code>
* SPI and helper classes are provided in the interface definitions in the <code>javax.sql.rowset</code>
* package specification.<br>
*
* <h3>2.0 Usage</h3>
* The reference implementations represent robust implementations of the standard
* <code>RowSet</code> interfaces defined in the <code>javax.sql.rowset</code> package.
* All disconnected <code>RowSet</code> implementations, such as the <code>CachedRowSetImpl</code>
* and <code>WebRowSetImpl</code>, are flexible enough to use the <code>SyncFactory</code> SPIs to
* leverage non-reference implementation <code>SyncProvider</code> implementations to obtain
* differing synchronization semantics. Furthermore, developers and vendors alike are free
* to use these implementations and integrate them into their products just as they
* can with to other components of the Java platform.<br>
*
* <h3>3.0 Extending the JDBC RowSet Implementations</h3>
*
* The JDBC <code>RowSet</code> 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
* set to their their particular needs. The website for JDBC Technology will
* provider a portal where implementations can be listed, similar to the way it
* provides a site for JDBC drivers.
*/
package com.sun.rowset;

86
src/java.sql.rowset/share/classes/com/sun/rowset/package.html
View file

@ -1,86 +0,0 @@
<!--
Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<title>com.sun.rowset Package</title>
</head>
<body bgcolor="#ffffff">
Provides five standard implementations of the standard JDBC <code>RowSet</code> implementation
interface definitions. These reference implementations are included with the J2SE version
1.5 platform and represent the benchmark standard <code>RowSet</code> implementations as verified
by the Test Compatibility Kit (TCK) as mandated by the Java Community Process.
<br>
<h3>1.0 Available JDBC RowSet Reference Implementations </h3>
The following implementations are provided:<br>
<blockquote><code><b>JdbcRowSetImpl</b></code> - The <code>javax.sql.rowset.JdbcRowSet</code>
interface reference implementation. <br>
<br>
<code><b>CachedRowSetImpl</b></code> - The <code>javax.sql.rowset.CachedRowSet</code> interface
reference implementation.<br>
<br>
<code><b>WebRowSetImpl</b></code> - The <code>javax.sql.rowset.WebRowSet</code> interface
reference implementation.<br>
<br>
<code><b>FilteredRowSetImpl</b></code> - The <code>javax.sql.rowset.FilteredRowSet</code>
interface reference implementation.<br>
<br>
<code><b>JoinRowSetImpl</b></code> - The <code>javax.sql.rowset.JoinRowSet</code> interface
reference implementation.<br>
</blockquote>
All details on their expected behavior, including their interactions with the <code>SyncProvider</code>
SPI and helper classes are provided in the interface definitions in the <code>javax.sql.rowset</code>
package specification.<br>
<h3>2.0 Usage</h3>
The reference implementations represent robust implementations of the standard
<code>RowSet</code> interfaces defined in the <code>javax.sql.rowset</code> package.
All disconnected <code>RowSet</code> implementations, such as the <code>CachedRowSetImpl</code>
and <code>WebRowSetImpl</code>, are flexible enough to use the <code>SyncFactory</code> SPIs to
leverage non-reference implementation <code>SyncProvider</code> implementations to obtain
differing synchronization semantics. Furthermore, developers and vendors alike are free
to use these implementations and integrate them into their products just as they
can with to other components of the Java platform.<br>
<h3>3.0 Extending the JDBC RowSet Implementations</h3>
The JDBC <code>RowSet</code> 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
set to their their particular needs. The website for JDBC Technology will
provider a portal where implementations can be listed, similar to the way it
provides a site for JDBC drivers.
<br>
<br>
</body>
</html>

158
src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java Normal file
View file

@ -0,0 +1,158 @@
/*
* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
*
* Repository for the <code>RowSet</code> reference implementations of the
* <code>SyncProvider</code> abstract class. These implementations provide a
* disconnected <code>RowSet</code>
* object with the ability to synchronize the data in the underlying data
* source with its data. These implementations are provided as
* the default <code>SyncProvider</code> implementations and are accessible via the
* <code>SyncProvider</code> SPI managed by the <code>SyncFactory</code>.
*
* <h3>1.0 <code>SyncProvider</code> Reference Implementations</h3>
* The main job of a <code>SyncProvider</code> implementation is to manage
* the reader and writer mechanisms.
* The <code>SyncProvider</code> SPI, as specified in the <code>javax.sql.rowset.spi</code>
* package, provides a pluggable mechanism by which <code>javax.sql.RowSetReader</code>
* and <code>javax.sql.RowSetWriter</code> implementations can be supplied to a disconnected
* <code>RowSet</code> object.
* <P>
* A reader, a <code>javax.sql.RowSetReader</code>
* object, does the work necessary to populate a <code>RowSet</code> object with data.
* A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for
* synchronizing a <code>RowSet</code> object's data with the data in the originating
* source of data. Put another way, a writer writes a <code>RowSet</code>
* object's data back to the data source.
* <P>
* Generally speaking, the course of events is this. The reader makes a connection to
* the data source and reads the data from a <code>ResultSet</code> object into its
* <code>RowSet</code> object. Then it closes the connection. While
* the <code>RowSet</code> object is disconnected, an application makes some modifications
* to the data and calls the method <code>acceptChanges</code>. At this point, the
* writer is called to write the changes back to the database table or view
* from which the original data came. This is called <i>synchronization</i>.
* <P>
* If the data in the originating data source has not changed, there is no problem
* with just writing the <code>RowSet</code> object's new data to the data source.
* 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
* whole data source. Setting locks is a way to avoid conflicts, but it can be
* very expensive. Another approach, which is at the other end of the spectrum,
* is simply to assume that no conflicts will occur and thus do nothing to avoid
* conflicts.
* Different <code>SyncProvider</code> implementations may handle synchronization in
* any of these ways, varying from doing no checking for
* conflicts, to doing various levels of checking, to guaranteeing that there are no
* conflicts.
* <P>
* The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code>
* object discover and manage how a provider handles synchronization.
* The method <code>getProviderGrade</code> returns the
* grade of synchronization a provider offers. An application can
* direct the provider to use a particular level of locking by calling
* the method <code>setDataSourceLock</code> and specifying the level of locking desired.
* If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an
* application may call the method <code>supportsUpdatableView</code> to
* find out whether the <code>VIEW</code> can be updated.
* <P>
* Synchronization is done completely behind the scenes, so it is third party vendors of
* synchronization provider implementations who have to take care of this complex task.
* Application programmers can decide which provider to use and the level of locking to
* be done, but they are free from having to worry about the implementation details.
* <P>
* The JDBC <code>RowSet</code> Implementations reference implementation provides two
* implementations of the <code>SyncProvider</code> class:
*
* <UL>
* <LI>
* <b><code>RIOptimisticProvider</code></b> - provides the <code>javax.sql.RowSetReader</code>
* and <code>javax.sql.RowSetWriter</code> interface implementations and provides
* an optimistic concurrency model for synchronization. This model assumes that there
* will be few conflicts and therefore uses a relatively low grade of synchronization.
* If no other provider is available, this is the default provider that the
* <code>SyncFactory</code> will supply to a <code>RowSet</code> object.
* <br>
* <LI>
* <b><code>RIXMLProvider</code></b> - provides the <code>XmlReader</code> (an extension
* of the <code>javax.sql.RowSetReader</code> interface) and the <code>XmlWriter</code>
* (an extension of the <code>javax.sql.RowSetWriter</code> interface) to enable
* <code>WebRowSet</code> objects to write their state to a
* well formed XML document according to the <code>WebRowSet</code> XML schema
* definition.<br>
* </UL>
*
* <h3>2.0 Basics in RowSet Population &amp; Synchronization</h3>
* A rowset's first task is to populate itself with rows of column values.
* Generally, these rows will come from a relational database, so a rowset
* has properties that supply what is necessary for making a connection to
* a database and executing a query. A rowset that does not need to establish
* a connection and execute a command, such as one that gets its data from
* a tabular file instead of a relational database, does not need to have these
* properties set. The vast majority of RowSets, however, do need to set these
* properties. The general rule is that a RowSet is required to set only the
* properties that it uses.<br>
* <br>
* The <code>command</code> property contains the query that determines what
* data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's
* parameter(s), which means that a query can be executed multiple times with
* different parameters to produce different result sets. Or the query can be
* changed to something completely new to get a new result set.
* <p>Once a rowset contains the rows from a <code>ResultSet</code> object or some
* 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
* a listener with the rowset. So, for example, a table that displays the rowset's
* data in an applet can be notified of changes and make updates as they
* occur.<br>
* <br>
* The changes made to a rowset can be propagated back to the original data
* source to keep the rowset and its data source synchronized. Although this
* involves many operations behind the scenes, it is completely transparent
* to the application programmer and remains the concern of the RowSet provider
* developer. All an application has to do is invoke the method <code>acceptChanges</code>,
* and the data source backing the rowset will be updated to match the current
* values in the rowset. </p>
*
* <p>A disconnected rowset, such as a <code>CachedRowSet</code> or <code>WebRowSet</code>
* object, establishes a connection to populate itself with data from a database
* and then closes the connection. The <code>RowSet</code> 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
* once again disconnects itself.<br>
* </p>
*
* <h3> 3.0 Other Possible Implementations</h3>
* There are many other possible implementations of the <code>SyncProvider</code> abstract
* class. One possibility is to employ a more robust synchronization model, which
* would give a <code>RowSet</code> object increased trust in the provider's
* ability to get any updates back to the original data source. Another possibility
* is a more formal synchronization mechanism such as SyncML
* (<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br>
*/
package com.sun.rowset.providers;

170
src/java.sql.rowset/share/classes/com/sun/rowset/providers/package.html
View file

@ -1,170 +0,0 @@
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR"
content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
<!--
Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<title>javax.sql.rowset.providers Package</title>
</head>
<body bgcolor="#ffffff">
Repository for the <code>RowSet</code> reference implementations of the
<code>SyncProvider</code> abstract class. These implementations provide a
disconnected <code>RowSet</code>
object with the ability to synchronize the data in the underlying data
source with its data. These implementations are provided as
the default <code>SyncProvider</code> implementations and are accessible via the
<code>SyncProvider</code> SPI managed by the <code>SyncFactory</code>.
<h3>1.0 <code>SyncProvider</code> Reference Implementations</h3>
The main job of a <code>SyncProvider</code> implementation is to manage
the reader and writer mechanisms.
The <code>SyncProvider</code> SPI, as specified in the <code>javax.sql.rowset.spi</code>
package, provides a pluggable mechanism by which <code>javax.sql.RowSetReader</code>
and <code>javax.sql.RowSetWriter</code> implementations can be supplied to a disconnected
<code>RowSet</code> object.
<P>
A reader, a <code>javax.sql.RowSetReader</code>
object, does the work necessary to populate a <code>RowSet</code> object with data.
A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for
synchronizing a <code>RowSet</code> object's data with the data in the originating
source of data. Put another way, a writer writes a <code>RowSet</code>
object's data back to the data source.
<P>
Generally speaking, the course of events is this. The reader makes a connection to
the data source and reads the data from a <code>ResultSet</code> object into its
<code>RowSet</code> object. Then it closes the connection. While
the <code>RowSet</code> object is disconnected, an application makes some modifications
to the data and calls the method <code>acceptChanges</code>. At this point, the
writer is called to write the changes back to the database table or view
from which the original data came. This is called <i>synchronization</i>.
<P>
If the data in the originating data source has not changed, there is no problem
with just writing the <code>RowSet</code> object's new data to the data source.
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
whole data source. Setting locks is a way to avoid conflicts, but it can be
very expensive. Another approach, which is at the other end of the spectrum,
is simply to assume that no conflicts will occur and thus do nothing to avoid
conflicts.
Different <code>SyncProvider</code> implementations may handle synchronization in
any of these ways, varying from doing no checking for
conflicts, to doing various levels of checking, to guaranteeing that there are no
conflicts.
<P>
The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code>
object discover and manage how a provider handles synchronization.
The method <code>getProviderGrade</code> returns the
grade of synchronization a provider offers. An application can
direct the provider to use a particular level of locking by calling
the method <code>setDataSourceLock</code> and specifying the level of locking desired.
If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an
application may call the method <code>supportsUpdatableView</code> to
find out whether the <code>VIEW</code> can be updated.
<P>
Synchronization is done completely behind the scenes, so it is third party vendors of
synchronization provider implementations who have to take care of this complex task.
Application programmers can decide which provider to use and the level of locking to
be done, but they are free from having to worry about the implementation details.
<P>
The JDBC <code>RowSet</code> Implementations reference implementation provides two
implementations of the <code>SyncProvider</code> class:
<UL>
<LI>
<b><code>RIOptimisticProvider</code></b> - provides the <code>javax.sql.RowSetReader</code>
and <code>javax.sql.RowSetWriter</code> interface implementations and provides
an optimistic concurrency model for synchronization. This model assumes that there
will be few conflicts and therefore uses a relatively low grade of synchronization.
If no other provider is available, this is the default provider that the
<code>SyncFactory</code> will supply to a <code>RowSet</code> object.
<br>
<LI>
<b><code>RIXMLProvider</code></b> - provides the <code>XmlReader</code> (an extension
of the <code>javax.sql.RowSetReader</code> interface) and the <code>XmlWriter</code>
(an extension of the <code>javax.sql.RowSetWriter</code> interface) to enable
<code>WebRowSet</code> objects to write their state to a
well formed XML document according to the <code>WebRowSet</code> XML schema
definition.<br>
</UL>
<h3>2.0 Basics in RowSet Population &amp; Synchronization</h3>
A rowset's first task is to populate itself with rows of column values.
Generally, these rows will come from a relational database, so a rowset
has properties that supply what is necessary for making a connection to
a database and executing a query. A rowset that does not need to establish
a connection and execute a command, such as one that gets its data from
a tabular file instead of a relational database, does not need to have these
properties set. The vast majority of RowSets, however, do need to set these
properties. The general rule is that a RowSet is required to set only the
properties that it uses.<br>
<br>
The <code>command</code> property contains the query that determines what
data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's
parameter(s), which means that a query can be executed multiple times with
different parameters to produce different result sets. Or the query can be
changed to something completely new to get a new result set.
<p>Once a rowset contains the rows from a <code>ResultSet</code> object or some
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
a listener with the rowset. So, for example, a table that displays the rowset's
data in an applet can be notified of changes and make updates as they
occur.<br>
<br>
The changes made to a rowset can be propagated back to the original data
source to keep the rowset and its data source synchronized. Although this
involves many operations behind the scenes, it is completely transparent
to the application programmer and remains the concern of the RowSet provider
developer. All an application has to do is invoke the method <code>acceptChanges</code>,
and the data source backing the rowset will be updated to match the current
values in the rowset. </p>
<p>A disconnected rowset, such as a <code>CachedRowSet</code> or <code>WebRowSet</code>
object, establishes a connection to populate itself with data from a database
and then closes the connection. The <code>RowSet</code> 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
once again disconnects itself.<br>
</p>
<h3> 3.0 Other Possible Implementations</h3>
There are many other possible implementations of the <code>SyncProvider</code> abstract
class. One possibility is to employ a more robust synchronization model, which
would give a <code>RowSet</code> object increased trust in the provider's
ability to get any updates back to the original data source. Another possibility
is a more formal synchronization mechanism such as SyncML
(<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br>
<br>
<br>
</body>
</html>

227
src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java Normal file
View file

@ -0,0 +1,227 @@
/*
* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* Provides utility classes to allow serializable mappings between SQL types
* and data types in the Java programming language.
* <p> Standard JDBC <code>RowSet</code> implementations may use these utility
* classes to
* assist in the serialization of disconnected <code>RowSet</code> objects.
* This is useful
* when transmitting a disconnected <code>RowSet</code> object over the wire to
* a different VM or across layers within an application.<br>
* </p>
*
* <h3>1.0 SerialArray</h3>
* A serializable mapping in the Java programming language of an SQL ARRAY
* value. <br>
* <br>
* The <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
* instance from an Array object, methods for getting the base type and
* the SQL name for the base type, and methods for copying all or part of a
* <code>SerialArray</code> object. <br>
*
* <h3>2.0 SerialBlob</h3>
* A serializable mapping in the Java programming language of an SQL BLOB
* value. <br>
* <br>
* The <code>SerialBlob</code>class provides a constructor for creating an instance
* from a Blob object. Note that the Blob object should have brought the SQL
* BLOB value's data over to the client before a <code>SerialBlob</code>object
* is constructed from it. The data of an SQL BLOB value can be materialized
* on the client as an array of bytes (using the method <code>Blob.getBytes</code>)
* or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
* <br>
* <br>
* <code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
* object as an array of bytes or as a stream. They also make it possible
* to locate a given pattern of bytes or a <code>Blob</code> object within a <code>SerialBlob</code>
* object. <br>
*
* <h3>3.0 SerialClob</h3>
* A serializable mapping in the Java programming language of an SQL CLOB
* value. <br>
* <br>
* The <code>SerialClob</code> class provides a constructor for creating an instance
* from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
* brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
* object is constructed from it. The data of an SQL CLOB value can be
* materialized on the client as a stream of Unicode characters. <br>
* <br>
* <code>SerialClob</code> methods make it possible to get a substring from a
* <code>SerialClob</code> object or to locate the start of a pattern of characters.
* <br>
*
* <h3>5.0 SerialDatalink</h3>
* A serializable mapping in the Java programming language of an SQL DATALINK
* value. A DATALINK value references a file outside of the underlying data source
* that the originating data source manages. <br>
* <br>
* <code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
* a <code>java.net.URL</code> object, which can be used to manipulate the external data.
* <br>
* <br>
* &nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</code><br>
*
* <h3>6.0 SerialJavaObject</h3>
* A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
* value. Assuming the Java object instance implements the Serializable interface,
* this simply wraps the serialization process. <br>
* <br>
* If however, the serialization is not possible in the case where the Java
* object is not immediately serializable, this class will attempt to serialize
* all non static members to permit the object instance state to be serialized.
* Static or transient fields cannot be serialized and attempting to do so
* will result in a <code>SerialException</code> being thrown. <br>
*
* <h3>7.0 SerialRef</h3>
* A serializable mapping between the SQL REF type and the Java programming
* language. <br>
* <br>
* The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
* instance from a <code>Ref</code> type and provides methods for getting
* and setting the <code>Ref</code> object type. <br>
*
* <h3>8.0 SerialStruct</h3>
* A serializable mapping in the Java programming language of an SQL structured
* type. Each attribute that is not already serializable is mapped to a serializable
* form, and if an attribute is itself a structured type, each of its attributes
* that is not already serializable is mapped to a serializable form. <br>
* <br>
* In addition, if a <code>Map</code> object is passed to one of the constructors or
* to the method <code>getAttributes</code>, the structured type is custom mapped
* according to the mapping specified in the <code>Map</code> object.
* <br>
* The <code>SerialStruct</code> class provides a constructor for creating an
* instance from a <code>Struct</code> object, a method for retrieving the SQL
* type name of the SQL structured type in the database, and methods for retrieving
* its attribute values. <br>
*
* <h3>9.0 SQLInputImpl</h3>
* An input stream used for custom mapping user-defined types (UDTs). An
* <code>SQLInputImpl</code> object is an input stream that contains a stream of
* values that are
* the attributes of a UDT. This class is used by the driver behind the scenes
* when the method <code>getObject</code> is called on an SQL structured or distinct
* type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
* methods directly. <br>
* <br>
* The <code>SQLInputImpl</code> class provides a set of reader methods
* analogous to the <code>ResultSet</code> getter methods. These methods make it
* possible to read the values in an <code>SQLInputImpl</code> object. The method
* <code>wasNull</code> is used to determine whether the last value read was SQL NULL.
* <br>
* <br>
* When a constructor or getter method that takes a <code>Map</code> object is called,
* the JDBC driver calls the method
* <code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom
* mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
* the attributes of the UDT. The driver then passes the input stream to the
* method <code>SQLData.readSQL</code>, which in turn calls the <code>SQLInputImpl</code>
* methods to read the attributes from the input stream. <br>
*
* <h3>10.0 SQLOutputImpl</h3>
* The output stream for writing the attributes of a custom mapped user-defined
* type (UDT) back to the database. The driver uses this interface internally,
* and its methods are never directly invoked by an application programmer.
* <br>
* <br>
* When an application calls the method <code>PreparedStatement.setObject</code>, the
* driver checks to see whether the value to be written is a UDT with a custom
* mapping. If it is, there will be an entry in a type map containing the Class
* object for the class that implements <code>SQLData</code> for this UDT. If the
* value to be written is an instance of <code>SQLData</code>, the driver will
* create an instance of <code>SQLOutputImpl</code> and pass it to the method
* <code>SQLData.writeSQL</code>.
* The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
* writer methods to write data from the <code>SQLData</code> object to the
* <code>SQLOutputImpl</code>
* output stream as the representation of an SQL user-defined type.
*
* <h3>Custom Mapping</h3>
* The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
* type to the Java programming language. Typically, a structured type is mapped
* to a class, and its attributes are mapped to fields in the class.
* (A DISTINCT type can thought of as having one attribute.) However, there are
* many other possibilities, and there may be any number of different mappings.
* <P>
* A programmer defines the mapping by implementing the interface <code>SQLData</code>.
* For example, if an SQL structured type named AUTHORS has the attributes NAME,
* TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
* Authors class could have the fields name, title, and publisher, to which the
* attributes of AUTHORS are mapped. In such a case, the implementation of
* <code>SQLData</code> could look like the following:
* <PRE>
* public class Authors implements SQLData {
* public String name;
* public String title;
* public String publisher;
*
* private String sql_type;
* public String getSQLTypeName() {
* return sql_type;
* }
*
* public void readSQL(SQLInput stream, String type)
* throws SQLException {
* sql_type = type;
* name = stream.readString();
* title = stream.readString();
* publisher = stream.readString();
* }
*
* public void writeSQL(SQLOutput stream) throws SQLException {
* stream.writeString(name);
* stream.writeString(title);
* stream.writeString(publisher);
* }
* }
* </PRE>
*
* A <code>java.util.Map</code> object is used to associate the SQL structured
* type with its mapping to the class <code>Authors</code>. The following code fragment shows
* how a <code>Map</code> object might be created and given an entry associating
* <code>AUTHORS</code> and <code>Authors</code>.
* <PRE>
* java.util.Map map = new java.util.HashMap();
* map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
* </PRE>
*
* The <code>Map</code> object <i>map</i> now contains an entry with the
* fully qualified name of the SQL structured type and the <code>Class</code>
* object for the class <code>Authors</code>. It can be passed to a method
* to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
* <P>
* For a disconnected <code>RowSet</code> object, custom mapping can be done
* only when a <code>Map</code> object is passed to the method or constructor
* that will be doing the custom mapping. The situation is different for
* connected <code>RowSet</code> objects because they maintain a connection
* with the data source. A method that does custom mapping and is called by
* a disconnected <code>RowSet</code> object may use the <code>Map</code>
* object that is associated with the <code>Connection</code> object being
* used. So, in other words, if no map is specified, the connection's type
* map can be used by default.
*/
package javax.sql.rowset.serial;

239
src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package.html
View file

@ -1,239 +0,0 @@
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR"
content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
<!--
Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<title>javax.sql.rowset.serial</title>
</head>
<body bgcolor="#ffffff">
Provides utility classes to allow serializable mappings between SQL types
and data types in the Java programming language.
<p> Standard JDBC <code>RowSet</code> implementations may use these utility
classes to
assist in the serialization of disconnected <code>RowSet</code> objects.
This is useful
when transmitting a disconnected <code>RowSet</code> object over the wire to
a different VM or across layers within an application.<br>
</p>
<h3>1.0 SerialArray</h3>
A serializable mapping in the Java programming language of an SQL ARRAY
value. <br>
<br>
The <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
instance from an Array object, methods for getting the base type and
the SQL name for the base type, and methods for copying all or part of a
<code>SerialArray</code> object. <br>
<h3>2.0 SerialBlob</h3>
A serializable mapping in the Java programming language of an SQL BLOB
value. <br>
<br>
The <code>SerialBlob</code>class provides a constructor for creating an instance
from a Blob object. Note that the Blob object should have brought the SQL
BLOB value's data over to the client before a <code>SerialBlob</code>object
is constructed from it. The data of an SQL BLOB value can be materialized
on the client as an array of bytes (using the method <code>Blob.getBytes</code>)
or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
<br>
<br>
<code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
object as an array of bytes or as a stream. They also make it possible
to locate a given pattern of bytes or a <code>Blob</code> object within a <code>SerialBlob</code>
object. <br>
<h3>3.0 SerialClob</h3>
A serializable mapping in the Java programming language of an SQL CLOB
value. <br>
<br>
The <code>SerialClob</code> class provides a constructor for creating an instance
from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
object is constructed from it. The data of an SQL CLOB value can be
materialized on the client as a stream of Unicode characters. <br>
<br>
<code>SerialClob</code> methods make it possible to get a substring from a
<code>SerialClob</code> object or to locate the start of a pattern of characters.
<br>
<h3>5.0 SerialDatalink</h3>
A serializable mapping in the Java programming language of an SQL DATALINK
value. A DATALINK value references a file outside of the underlying data source
that the originating data source manages. <br>
<br>
<code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
a <code>java.net.URL</code> object, which can be used to manipulate the external data.
<br>
<br>
&nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</code><br>
<h3>6.0 SerialJavaObject</h3>
A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
value. Assuming the Java object instance implements the Serializable interface,
this simply wraps the serialization process. <br>
<br>
If however, the serialization is not possible in the case where the Java
object is not immediately serializable, this class will attempt to serialize
all non static members to permit the object instance state to be serialized.
Static or transient fields cannot be serialized and attempting to do so
will result in a <code>SerialException</code> being thrown. <br>
<h3>7.0 SerialRef</h3>
A serializable mapping between the SQL REF type and the Java programming
language. <br>
<br>
The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
instance from a <code>Ref</code> type and provides methods for getting
and setting the <code>Ref</code> object type. <br>
<h3>8.0 SerialStruct</h3>
A serializable mapping in the Java programming language of an SQL structured
type. Each attribute that is not already serializable is mapped to a serializable
form, and if an attribute is itself a structured type, each of its attributes
that is not already serializable is mapped to a serializable form. <br>
<br>
In addition, if a <code>Map</code> object is passed to one of the constructors or
to the method <code>getAttributes</code>, the structured type is custom mapped
according to the mapping specified in the <code>Map</code> object.
<br>
The <code>SerialStruct</code> class provides a constructor for creating an
instance from a <code>Struct</code> object, a method for retrieving the SQL
type name of the SQL structured type in the database, and methods for retrieving
its attribute values. <br>
<h3>9.0 SQLInputImpl</h3>
An input stream used for custom mapping user-defined types (UDTs). An
<code>SQLInputImpl</code> object is an input stream that contains a stream of
values that are
the attributes of a UDT. This class is used by the driver behind the scenes
when the method <code>getObject</code> is called on an SQL structured or distinct
type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
methods directly. <br>
<br>
The <code>SQLInputImpl</code> class provides a set of reader methods
analogous to the <code>ResultSet</code> getter methods. These methods make it
possible to read the values in an <code>SQLInputImpl</code> object. The method
<code>wasNull</code> is used to determine whether the last value read was SQL NULL.
<br>
<br>
When a constructor or getter method that takes a <code>Map</code> object is called,
the JDBC driver calls the method
<code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom
mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
the attributes of the UDT. The driver then passes the input stream to the
method <code>SQLData.readSQL</code>, which in turn calls the <code>SQLInputImpl</code>
methods to read the attributes from the input stream. <br>
<h3>10.0 SQLOutputImpl</h3>
The output stream for writing the attributes of a custom mapped user-defined
type (UDT) back to the database. The driver uses this interface internally,
and its methods are never directly invoked by an application programmer.
<br>
<br>
When an application calls the method <code>PreparedStatement.setObject</code>, the
driver checks to see whether the value to be written is a UDT with a custom
mapping. If it is, there will be an entry in a type map containing the Class
object for the class that implements <code>SQLData</code> for this UDT. If the
value to be written is an instance of <code>SQLData</code>, the driver will
create an instance of <code>SQLOutputImpl</code> and pass it to the method
<code>SQLData.writeSQL</code>.
The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
writer methods to write data from the <code>SQLData</code> object to the
<code>SQLOutputImpl</code>
output stream as the representation of an SQL user-defined type.
<h3>Custom Mapping</h3>
The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
type to the Java programming language. Typically, a structured type is mapped
to a class, and its attributes are mapped to fields in the class.
(A DISTINCT type can thought of as having one attribute.) However, there are
many other possibilities, and there may be any number of different mappings.
<P>
A programmer defines the mapping by implementing the interface <code>SQLData</code>.
For example, if an SQL structured type named AUTHORS has the attributes NAME,
TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
Authors class could have the fields name, title, and publisher, to which the
attributes of AUTHORS are mapped. In such a case, the implementation of
<code>SQLData</code> could look like the following:
<PRE>
public class Authors implements SQLData {
public String name;
public String title;
public String publisher;
private String sql_type;
public String getSQLTypeName() {
return sql_type;
}
public void readSQL(SQLInput stream, String type)
throws SQLException {
sql_type = type;
name = stream.readString();
title = stream.readString();
publisher = stream.readString();
}
public void writeSQL(SQLOutput stream) throws SQLException {
stream.writeString(name);
stream.writeString(title);
stream.writeString(publisher);
}
}
</PRE>
A <code>java.util.Map</code> object is used to associate the SQL structured
type with its mapping to the class <code>Authors</code>. The following code fragment shows
how a <code>Map</code> object might be created and given an entry associating
<code>AUTHORS</code> and <code>Authors</code>.
<PRE>
java.util.Map map = new java.util.HashMap();
map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
</PRE>
The <code>Map</code> object <i>map</i> now contains an entry with the
fully qualified name of the SQL structured type and the <code>Class</code>
object for the class <code>Authors</code>. It can be passed to a method
to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
<P>
For a disconnected <code>RowSet</code> object, custom mapping can be done
only when a <code>Map</code> object is passed to the method or constructor
that will be doing the custom mapping. The situation is different for
connected <code>RowSet</code> objects because they maintain a connection
with the data source. A method that does custom mapping and is called by
a disconnected <code>RowSet</code> object may use the <code>Map</code>
object that is associated with the <code>Connection</code> object being
used. So, in other words, if no map is specified, the connection's type
map can be used by default.
<br>
</body>
</html>