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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
src/java.logging/share/classes/java/util/logging/package-info.java Normal file
View File

@ -0,0 +1,118 @@
/*
* Copyright (c) 2001, 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 the classes and interfaces of
* the Java™ 2 platform's core logging facilities.
* The central goal of the logging APIs is to support maintaining and servicing
* software at customer sites.
*
* <P>
* There are four main target uses of the logs:
* </P>
*
* <OL>
* <LI> <I>Problem diagnosis by end users and system administrators</I>.
* This consists of simple logging of common problems that can be fixed
* or tracked locally, such as running out of resources, security failures,
* and simple configuration errors.
*
* <LI> <I>Problem diagnosis by field service engineers</I>. The logging information
* used by field service engineers may be considerably more complex and
* verbose than that required by system administrators. Typically such information
* will require extra logging within particular subsystems.
*
* <LI> <I>Problem diagnosis by the development organization</I>.
* When a problem occurs in the field, it may be necessary to return the captured logging
* information to the original development team for diagnosis. This logging
* information may be extremely detailed and fairly inscrutable. Such information might include
* detailed tracing on the internal execution of particular subsystems.
*
* <LI> <I>Problem diagnosis by developers</I>. The Logging APIs may also be
* used to help debug an application under development. This may
* include logging information generated by the target application
* as well as logging information generated by lower-level libraries.
* Note however that while this use is perfectly reasonable,
* the logging APIs are not intended to replace the normal debugging
* and profiling tools that may already exist in the development environment.
* </OL>
*
* <p>
* The key elements of this package include:
* <UL>
* <LI> <I>Logger</I>: The main entity on which applications make
* logging calls. A Logger object is used to log messages
* for a specific system or application
* component.
* <LI> <I>LogRecord</I>: Used to pass logging requests between the logging
* framework and individual log handlers.
* <LI> <I>Handler</I>: Exports LogRecord objects to a variety of destinations
* including memory, output streams, consoles, files, and sockets.
* A variety of Handler subclasses exist for this purpose. Additional Handlers
* may be developed by third parties and delivered on top of the core platform.
* <LI> <I>Level</I>: Defines a set of standard logging levels that can be used
* to control logging output. Programs can be configured to output logging
* for some levels while ignoring output for others.
* <LI> <I>Filter</I>: Provides fine-grained control over what gets logged,
* beyond the control provided by log levels. The logging APIs support a general-purpose
* filter mechanism that allows application code to attach arbitrary filters to
* control logging output.
*
* <LI> <I>Formatter</I>: Provides support for formatting LogRecord objects. This
* package includes two formatters, SimpleFormatter and
* XMLFormatter, for formatting log records in plain text
* or XML respectively. As with Handlers, additional Formatters
* may be developed by third parties.
* </UL>
* <P>
* The Logging APIs offer both static and dynamic configuration control.
* Static control enables field service staff to set up a particular configuration and then re-launch the
* application with the new logging settings. Dynamic control allows for updates to the
* logging configuration within a currently running program. The APIs also allow for logging to be
* enabled or disabled for different functional areas of the system. For example,
* a field service engineer might be interested in tracing all AWT events, but might have no interest in
* socket events or memory management.
* </P>
*
* <h2>Null Pointers</h2>
* <p>
* In general, unless otherwise noted in the javadoc, methods and
* constructors will throw NullPointerException if passed a null argument.
* The one broad exception to this rule is that the logging convenience
* methods in the Logger class (the config, entering, exiting, fine, finer, finest,
* log, logp, logrb, severe, throwing, and warning methods)
* will accept null values
* for all arguments except for the initial Level argument (if any).
*
* <H2>Related Documentation</H2>
* <P>
* For an overview of control flow,
* please refer to the
* {@extLink logging_overview Java Logging Overview}
* </P>
*
* @since 1.4
*/
package java.util.logging;

127
src/java.logging/share/classes/java/util/logging/package.html
View File

@ -1,127 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2001, 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.
-->
</head>
<body bgcolor="white">
<P>
Provides the classes and interfaces of
the Java&trade; 2 platform's core logging facilities.
The central goal of the logging APIs is to support maintaining and servicing
software at customer sites.
<P>
There are four main target uses of the logs:
</P>
<OL>
<LI> <I>Problem diagnosis by end users and system administrators</I>.
This consists of simple logging of common problems that can be fixed
or tracked locally, such as running out of resources, security failures,
and simple configuration errors.
<LI> <I>Problem diagnosis by field service engineers</I>. The logging information
used by field service engineers may be considerably more complex and
verbose than that required by system administrators. Typically such information
will require extra logging within particular subsystems.
<LI> <I>Problem diagnosis by the development organization</I>.
When a problem occurs in the field, it may be necessary to return the captured logging
information to the original development team for diagnosis. This logging
information may be extremely detailed and fairly inscrutable. Such information might include
detailed tracing on the internal execution of particular subsystems.
<LI> <I>Problem diagnosis by developers</I>. The Logging APIs may also be
used to help debug an application under development. This may
include logging information generated by the target application
as well as logging information generated by lower-level libraries.
Note however that while this use is perfectly reasonable,
the logging APIs are not intended to replace the normal debugging
and profiling tools that may already exist in the development environment.
</OL>
<p>
The key elements of this package include:
<UL>
<LI> <I>Logger</I>: The main entity on which applications make
logging calls. A Logger object is used to log messages
for a specific system or application
component.
<LI> <I>LogRecord</I>: Used to pass logging requests between the logging
framework and individual log handlers.
<LI> <I>Handler</I>: Exports LogRecord objects to a variety of destinations
including memory, output streams, consoles, files, and sockets.
A variety of Handler subclasses exist for this purpose. Additional Handlers
may be developed by third parties and delivered on top of the core platform.
<LI> <I>Level</I>: Defines a set of standard logging levels that can be used
to control logging output. Programs can be configured to output logging
for some levels while ignoring output for others.
<LI> <I>Filter</I>: Provides fine-grained control over what gets logged,
beyond the control provided by log levels. The logging APIs support a general-purpose
filter mechanism that allows application code to attach arbitrary filters to
control logging output.
<LI> <I>Formatter</I>: Provides support for formatting LogRecord objects. This
package includes two formatters, SimpleFormatter and
XMLFormatter, for formatting log records in plain text
or XML respectively. As with Handlers, additional Formatters
may be developed by third parties.
</UL>
<P>
The Logging APIs offer both static and dynamic configuration control.
Static control enables field service staff to set up a particular configuration and then re-launch the
application with the new logging settings. Dynamic control allows for updates to the
logging configuration within a currently running program. The APIs also allow for logging to be
enabled or disabled for different functional areas of the system. For example,
a field service engineer might be interested in tracing all AWT events, but might have no interest in
socket events or memory management.
</P>
<h2>Null Pointers</h2>
<p>
In general, unless otherwise noted in the javadoc, methods and
constructors will throw NullPointerException if passed a null argument.
The one broad exception to this rule is that the logging convenience
methods in the Logger class (the config, entering, exiting, fine, finer, finest,
log, logp, logrb, severe, throwing, and warning methods)
will accept null values
for all arguments except for the initial Level argument (if any).
<H2>Related Documentation</H2>
<P>
For an overview of control flow,
please refer to the
{@extLink logging_overview Java Logging Overview}
</P>
<!-- Put @see and @since tags down here. -->
@since 1.4
</body>
</html>

34
src/java.prefs/share/classes/java/util/prefs/package-info.java Normal file
View File

@ -0,0 +1,34 @@
/*
* Copyright (c) 2000, 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.
*/
/**
* This package allows applications to store and retrieve user and system
* preference and configuration data. This data is stored persistently in an
* implementation-dependent backing store. There are two separate trees of
* preference nodes, one for user preferences and one for system preferences.
*
* @since 1.4
*/
package java.util.prefs;

44
src/java.prefs/share/classes/java/util/prefs/package.html
View File

@ -1,44 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2000, 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.
-->
</head>
<body bgcolor="white">
This package allows applications to store and retrieve user and system
preference and configuration data. This data is stored persistently in an
implementation-dependent backing store. There are two separate trees of
preference nodes, one for user preferences and one for system preferences.
<!--
<h2>Package Specification</h2>
<h2>Related Documentation</h2>
-->
@since 1.4
</body>
</html>

42
src/java.rmi/share/classes/java/rmi/activation/package-info.java Normal file
View File

@ -0,0 +1,42 @@
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* <p>
* 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.
* <p>
* 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).
* <p>
* 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.
* <p>
* 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 support for RMI Object Activation. A remote
* object's reference can be made ``persistent'' and later activated into a
* ``live'' object using the RMI activation mechanism.
*
* <p>Implementations are not required to support the activation
* mechanism. If activation is not supported by this implementation,
* several specific activation API methods are all required to throw
* {@code UnsupportedOperationException}. If activation is supported by this
* implementation, these methods must never throw {@code
* UnsupportedOperationException}. These methods are denoted by the
* presence of an entry for {@code UnsupportedOperationException} in the
* <strong>Throws</strong> section of each method's specification.
*
* @since 1.2
*/
package java.rmi.activation;

61
src/java.rmi/share/classes/java/rmi/activation/package.html
View File

@ -1,61 +0,0 @@
<!--
Copyright (c) 1998, 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 HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">
Provides support for RMI Object Activation. A remote
object's reference can be made ``persistent'' and later activated into a
``live'' object using the RMI activation mechanism.
<p>Implementations are not required to support the activation
mechanism. If activation is not supported by this implementation,
several specific activation API methods are all required to throw
{@code UnsupportedOperationException}. If activation is supported by this
implementation, these methods must never throw {@code
UnsupportedOperationException}. These methods are denoted by the
presence of an entry for {@code UnsupportedOperationException} in the
<strong>Throws</strong> section of each method's specification.
<!--
<h2>Package Specification</h2>
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
<h2>Related Documentation</h2>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
@since 1.2
</body>
</html>

37
src/java.rmi/share/classes/java/rmi/dgc/package-info.java Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* <p>
* 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.
* <p>
* 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).
* <p>
* 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.
* <p>
* 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 classes and interface for RMI distributed
* garbage-collection (DGC). When the RMI server returns an object to
* its client (caller of the remote method), it tracks the remote
* object's usage in the client. When there are no more references to the
* remote object on the client, or if the reference's ``lease'' expires and
* not renewed, the server garbage-collects the remote object.
*
*
* @since 1.1
*/
package java.rmi.dgc;

55
src/java.rmi/share/classes/java/rmi/dgc/package.html
View File

@ -1,55 +0,0 @@
<!--
Copyright (c) 1998, 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 HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">
Provides classes and interface for RMI distributed
garbage-collection (DGC). When the RMI server returns an object to
its client (caller of the remote method), it tracks the remote
object's usage in the client. When there are no more references to the
remote object on the client, or if the reference's ``lease'' expires and
not renewed, the server garbage-collects the remote object.
<!--
<h2>Package Specification</h2>
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
<h2>Related Documentation</h2>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
@since 1.1
</body>
</html>

40
src/java.rmi/share/classes/java/rmi/package-info.java Normal file
View File

@ -0,0 +1,40 @@
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* <p>
* 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.
* <p>
* 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).
* <p>
* 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.
* <p>
* 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 the RMI package. RMI is Remote Method Invocation. It is a
* mechanism that enables an object on one Java virtual machine to invoke
* methods on an object in another Java virtual machine. Any object that
* can be invoked this way must implement the Remote interface. When such
* an object is invoked, its arguments are ``marshalled'' and sent from the
* local virtual machine to the remote one, where the arguments are
* ``unmarshalled.'' When the method terminates, the results are
* marshalled from the remote machine and sent to the caller's virtual
* machine. If the method invocation results in an exception being
* thrown, the exception is indicated to caller.
*
* @since 1.1
*/
package java.rmi;

59
src/java.rmi/share/classes/java/rmi/package.html
View File

@ -1,59 +0,0 @@
<!--
Copyright (c) 1998, 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 HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">
Provides the RMI package. RMI is Remote Method Invocation. It is a
mechanism that enables an object on one Java virtual machine to invoke
methods on an object in another Java virtual machine. Any object that
can be invoked this way must implement the Remote interface. When such
an object is invoked, its arguments are ``marshalled'' and sent from the
local virtual machine to the remote one, where the arguments are
``unmarshalled.'' When the method terminates, the results are
marshalled from the remote machine and sent to the caller's virtual
machine. If the method invocation results in an exception being
thrown, the exception is indicated to caller.
<!--
<h2>Package Specification</h2>
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
<h2>Related Documentation</h2>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
@since 1.1
</body>
</html>

37
src/java.rmi/share/classes/java/rmi/registry/package-info.java Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* <p>
* 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.
* <p>
* 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).
* <p>
* 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.
* <p>
* 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 a class and two interfaces for the RMI registry.
* A registry is a remote object that maps names to remote objects. A
* server registers its remote objects with the registry so that they can
* be looked up. When an object wants to invoke a method on a remote
* object, it must first lookup the remote object using its name. The
* registry returns to the calling object a reference to the remote
* object, using which a remote method can be invoked.
*
* @since 1.1
*/
package java.rmi.registry;

57
src/java.rmi/share/classes/java/rmi/registry/package.html
View File

@ -1,57 +0,0 @@
<!--
Copyright (c) 1998, 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 HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
</head>
<body bgcolor="white">
Provides a class and two interfaces for the RMI registry.
A registry is a remote object that maps names to remote objects. A
server registers its remote objects with the registry so that they can
be looked up. When an object wants to invoke a method on a remote
object, it must first lookup the remote object using its name. The
registry returns to the calling object a reference to the remote
object, using which a remote method can be invoked.
<!--
<h2>Package Specification</h2>
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
<h2>Related Documentation</h2>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
@since 1.1
</body>
</html>

55
src/java.rmi/share/classes/java/rmi/server/package-info.java Normal file
View File

@ -0,0 +1,55 @@
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* <p>
* 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.
* <p>
* 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).
* <p>
* 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.
* <p>
* 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 classes and interfaces for supporting the server
* side of RMI. A group of classes are used by the stubs and skeletons
* generated by the rmic stub compiler. Another group of classes
* implements the RMI Transport protocol and HTTP tunneling.
*
* <p><strong>Deprecated: HTTP Tunneling.</strong> <em>The HTTP tunneling
* mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for
* further information.</em>
*
* <p><strong>Deprecated: Skeletons and Static Stubs.</strong>
*
* <em>Skeletons and statically generated stubs are deprecated. This
* includes the APIs in this package that require the use of skeletons
* or static stubs, the runtime support for them, and the use of the
* {@code rmic} stub compiler to generate them. Support for skeletons
* and static stubs may be removed in a future release of the
* platform. Skeletons are unnecessary, as server-side method dispatching
* is handled directly by the RMI runtime. Statically generated stubs are
* unnecessary, as stubs are generated dynamically using {@link
* java.lang.reflect.Proxy Proxy} objects. See {@link
* java.rmi.server.UnicastRemoteObject UnicastRemoteObject} for
* information about dynamic stub generation. Generation of skeletons and
* static stubs was typically performed as part of an application's build
* process by calling the {@code rmic} tool. This is unnecessary, and
* calls to {@code rmic} can simply be omitted.</em>
*
* @since 1.1
*/
package java.rmi.server;

74
src/java.rmi/share/classes/java/rmi/server/package.html
View File

@ -1,74 +0,0 @@
<!--
Copyright (c) 1998, 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 HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">
Provides classes and interfaces for supporting the server
side of RMI. A group of classes are used by the stubs and skeletons
generated by the rmic stub compiler. Another group of classes
implements the RMI Transport protocol and HTTP tunneling.
<p><strong>Deprecated: HTTP Tunneling.</strong> <em>The HTTP tunneling
mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for
further information.</em>
<p><strong>Deprecated: Skeletons and Static Stubs.</strong>
<em>Skeletons and statically generated stubs are deprecated. This
includes the APIs in this package that require the use of skeletons
or static stubs, the runtime support for them, and the use of the
{@code rmic} stub compiler to generate them. Support for skeletons
and static stubs may be removed in a future release of the
platform. Skeletons are unnecessary, as server-side method dispatching
is handled directly by the RMI runtime. Statically generated stubs are
unnecessary, as stubs are generated dynamically using {@link
java.lang.reflect.Proxy Proxy} objects. See {@link
java.rmi.server.UnicastRemoteObject UnicastRemoteObject} for
information about dynamic stub generation. Generation of skeletons and
static stubs was typically performed as part of an application's build
process by calling the {@code rmic} tool. This is unnecessary, and
calls to {@code rmic} can simply be omitted.</em>
<!--
<h2>Package Specification</h2>
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
<h2>Related Documentation</h2>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
@since 1.1
</body>
</html>

33
src/java.rmi/share/classes/javax/rmi/ssl/package-info.java Normal file
View File

@ -0,0 +1,33 @@
/*
* Copyright (c) 2004, 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 implementations of {@link java.rmi.server.RMIClientSocketFactory}
* and {@link java.rmi.server.RMIServerSocketFactory} over
* the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
*
* @since 1.5
*/
package javax.rmi.ssl;

38
src/java.rmi/share/classes/javax/rmi/ssl/package.html
View File

@ -1,38 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2004, 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.
-->
</head>
<body bgcolor="white">
Provides implementations of {@link java.rmi.server.RMIClientSocketFactory}
and {@link java.rmi.server.RMIServerSocketFactory} over
the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
@since 1.5
</body>
</html>

96
src/java.smartcardio/share/classes/javax/smartcardio/package-info.java Normal file
View File

@ -0,0 +1,96 @@
/*
* Copyright (c) 2005, 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.
*/
/**
* Java&#x2122; Smart Card I/O API.
*
* This specification describes the Java Smart Card I/O API defined by
* <a href="http://jcp.org/en/jsr/detail?id=268">JSR 268</a>.
*
* It defines a Java API for communication with Smart Cards
* using ISO/IEC 7816-4 APDUs. It thereby allows Java applications to interact with
* applications running on the Smart Card, to store and retrieve data
* on the card, etc.
*
* <p>
* The API is defined by classes in the package
* <code>javax.smartcardio</code>. They can be classified as follows:
*
* <dl>
* <dt>Classes describing the corresponding Smart Card structures
* <dd>
* <a href="ATR.html">ATR</a>,
* <a href="CommandAPDU.html">CommandAPDU</a>,
* <a href="ResponseAPDU.html">ResponseAPDU</a>
*
* <dt>Factory to obtain implementations
* <dd>
* <a href="TerminalFactory.html">TerminalFactory</a>
*
* <dt>Main classes for card and terminal functions
* <dd>
* <a href="CardTerminals.html">CardTerminals</a>,
* <a href="CardTerminal.html">CardTerminal</a>,
* <a href="Card.html">Card</a>,
* <a href="CardChannel.html">CardChannel</a>
*
* <dt>Supporting permission and exception classes
* <dd>
* <a href="CardPermission.html">CardPermission</a>,
* <a href="CardException.html">CardException</a>,
* <a href="CardNotPresentException.html">CardNotPresentException</a>
*
* <dt>Service provider interface, not accessed directly by applications
* <dd>
* <a href="TerminalFactorySpi.html">TerminalFactorySpi</a>
*
* </dl>
*
*
* <h3>API Example</h3>
*
* A simple example of using the API is:
* <pre>
* // show the list of available terminals
* TerminalFactory factory = TerminalFactory.getDefault();
* List&lt;CardTerminal&gt; terminals = factory.terminals().list();
* System.out.println("Terminals: " + terminals);
* // get the first terminal
* CardTerminal terminal = terminals.get(0);
* // establish a connection with the card
* Card card = terminal.connect("T=0");
* System.out.println("card: " + card);
* CardChannel channel = card.getBasicChannel();
* ResponseAPDU r = channel.transmit(new CommandAPDU(c1));
* System.out.println("response: " + toString(r.getBytes()));
* // disconnect
* card.disconnect(false);
* </pre>
*
* @since 1.6
* @author Andreas Sterbenz
* @author JSR 268 Expert Group
*/
package javax.smartcardio;

98
src/java.smartcardio/share/classes/javax/smartcardio/package.html
View File

@ -1,98 +0,0 @@
<!--
Copyright (c) 2005, 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.
-->
<html>
<body>
<h2>Java&#x2122; Smart Card I/O API</h2>
This specification describes the Java Smart Card I/O API defined by
<a href="http://jcp.org/en/jsr/detail?id=268">JSR 268</a>.
It defines a Java API for communication with Smart Cards
using ISO/IEC 7816-4 APDUs. It thereby allows Java applications to interact with
applications running on the Smart Card, to store and retrieve data
on the card, etc.
<p>
The API is defined by classes in the package
<code>javax.smartcardio</code>. They can be classified as follows:
<dl>
<dt>Classes describing the corresponding Smart Card structures
<dd>
<a href="ATR.html">ATR</a>,
<a href="CommandAPDU.html">CommandAPDU</a>,
<a href="ResponseAPDU.html">ResponseAPDU</a>
<dt>Factory to obtain implementations
<dd>
<a href="TerminalFactory.html">TerminalFactory</a>
<dt>Main classes for card and terminal functions
<dd>
<a href="CardTerminals.html">CardTerminals</a>,
<a href="CardTerminal.html">CardTerminal</a>,
<a href="Card.html">Card</a>,
<a href="CardChannel.html">CardChannel</a>
<dt>Supporting permission and exception classes
<dd>
<a href="CardPermission.html">CardPermission</a>,
<a href="CardException.html">CardException</a>,
<a href="CardNotPresentException.html">CardNotPresentException</a>
<dt>Service provider interface, not accessed directly by applications
<dd>
<a href="TerminalFactorySpi.html">TerminalFactorySpi</a>
</dl>
<h3>API Example</h3>
A simple example of using the API is:
<pre>
// show the list of available terminals
TerminalFactory factory = TerminalFactory.getDefault();
List&lt;CardTerminal&gt; terminals = factory.terminals().list();
System.out.println("Terminals: " + terminals);
// get the first terminal
CardTerminal terminal = terminals.get(0);
// establish a connection with the card
Card card = terminal.connect("T=0");
System.out.println("card: " + card);
CardChannel channel = card.getBasicChannel();
ResponseAPDU r = channel.transmit(new CommandAPDU(c1));
System.out.println("response: " + toString(r.getBytes()));
// disconnect
card.disconnect(false);
</pre>
@since 1.6
@author Andreas Sterbenz
@author JSR 268 Expert Group
</body>
</html>

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>

343
src/java.sql/share/classes/java/sql/package-info.java Normal file
View File

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

351
src/java.sql/share/classes/java/sql/package.html
View File

@ -1,351 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 1998, 2017, 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.
-->
</head>
<body bgcolor="white">
Provides the API for accessing and processing data stored in a
data source (usually a relational database) using the
Java&trade; programming language.
This API includes a framework whereby different
drivers can be installed dynamically to access different data sources.
Although the JDBC&trade; API is mainly geared
to passing SQL statements to a database, it provides for reading and
writing data from any data source with a tabular format.
The reader/writer facility, available through the
<code>javax.sql.RowSet</code> group of interfaces, can be customized to
use and update data from a spread sheet, flat file, or any other tabular
data source.
<h2>What the JDBC&trade; 4.3 API Includes</h2>
The JDBC&trade; 4.3 API includes both
the <code>java.sql</code> package, referred to as the JDBC core API,
and the <code>javax.sql</code> package, referred to as the JDBC Optional
Package API. This complete JDBC API
is included in the Java&trade; Standard Edition (Java SE&trade;), version 7.
The <code>javax.sql</code> package extends the functionality of the JDBC API
from a client-side API to a server-side API, and it is an essential part
of the Java&trade; Enterprise Edition
(Java EE&trade;) technology.
<h2>Versions</h2>
The JDBC 4.3 API incorporates all of the previous JDBC API versions:
<UL>
<LI> The JDBC 4.2 API</li>
<LI> The JDBC 4.1 API</li>
<LI> The JDBC 4.0 API</li>
<LI> The JDBC 3.0 API</li>
<LI> The JDBC 2.1 core API</li>
<LI> The JDBC 2.0 Optional Package API<br>
(Note that the JDBC 2.1 core API and the JDBC 2.0 Optional Package
API together are referred to as the JDBC 2.0 API.)</li>
<LI> The JDBC 1.2 API</li>
<LI> The JDBC 1.0 API</li>
</UL>
<P>
Classes, interfaces, methods, fields, constructors, and exceptions
have the following "since" tags that indicate when they were introduced
into the Java platform. When these "since" tags are used in
Javadoc&trade; comments for the JDBC API,
they indicate the following:
<UL>
<LI>Since 9 -- new in the JDBC 4.3 API and part of the Java SE platform,
version 9</li>
<LI>Since 1.8 -- new in the JDBC 4.2 API and part of the Java SE platform,
version 8</li>
<LI>Since 1.7 -- new in the JDBC 4.1 API and part of the Java SE platform,
version 7</li>
<LI>Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform,
version 6</li>
<LI>Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform,
version 1.4</li>
<LI>Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform,
version 1.2</li>
<LI>Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of
the JDK&trade;, version 1.1</li>
</UL>
<P>
<b>NOTE:</b> Many of the new features are optional; consequently, there is
some variation in drivers and the features they support. Always
check your driver's documentation to see whether it supports a feature before
you try to use it.
<P>
<b>NOTE:</b> The class <code>SQLPermission</code> was added in the
Java&trade; 2 SDK, Standard Edition,
version 1.3 release. This class is used to prevent unauthorized
access to the logging stream associated with the <code>DriverManager</code>,
which may contain information such as table names, column data, and so on.
<h2>What the <code>java.sql</code> Package Contains</h2>
The <code>java.sql</code> package contains API for the following:
<UL>
<LI>Making a connection with a database via the <code>DriverManager</code> facility
<UL>
<LI><code>DriverManager</code> class -- makes a connection with a driver
<LI><code>SQLPermission</code> class -- provides permission when code
running within a Security Manager, such as an applet,
attempts to set up a logging stream through the
<code>DriverManager</code>
<LI><code>Driver</code> interface -- provides the API for registering
and connecting drivers based on JDBC technology ("JDBC drivers");
generally used only by the <code>DriverManager</code> class
<LI><code>DriverPropertyInfo</code> class -- provides properties for a
JDBC driver; not used by the general user
</UL>
<LI>Sending SQL statements to a database
<UL>
<LI><code>Statement</code> -- used to send basic SQL statements
<LI><code>PreparedStatement</code> -- used to send prepared statements or
basic SQL statements (derived from <code>Statement</code>)
<LI><code>CallableStatement</code> -- used to call database stored
procedures (derived from <code>PreparedStatement</code>)
<LI><code>Connection</code> interface -- provides methods for creating
statements and managing connections and their properties
<LI><code>Savepoint</code> -- provides savepoints in a transaction
</UL>
<LI>Retrieving and updating the results of a query
<UL>
<LI><code>ResultSet</code> interface
</UL>
<LI>Standard mappings for SQL types to classes and interfaces in the
Java programming language
<UL>
<LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code>
<LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code>
<LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code>
<LI><code>Date</code> class -- mapping for SQL <code>DATE</code>
<LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code>
<LI><code>Ref</code> interface -- mapping for SQL <code>REF</code>
<LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code>
<LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code>
<LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code>
<LI><code>Time</code> class -- mapping for SQL <code>TIME</code>
<LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code>
<LI><code>Types</code> class -- provides constants for SQL types
</UL>
<LI>Custom mapping an SQL user-defined type (UDT) to a class in the
Java programming language
<UL>
<LI><code>SQLData</code> interface -- specifies the mapping of
a UDT to an instance of this class
<LI><code>SQLInput</code> interface -- provides methods for reading
UDT attributes from a stream
<LI><code>SQLOutput</code> interface -- provides methods for writing
UDT attributes back to a stream
</UL>
<LI>Metadata
<UL>
<LI><code>DatabaseMetaData</code> interface -- provides information
about the database
<LI><code>ResultSetMetaData</code> interface -- provides information
about the columns of a <code>ResultSet</code> object
<LI><code>ParameterMetaData</code> interface -- provides information
about the parameters to <code>PreparedStatement</code> commands
</UL>
<LI>Exceptions
<UL>
<LI><code>SQLException</code> -- thrown by most methods when there
is a problem accessing data and by some methods for other reasons
<LI><code>SQLWarning</code> -- thrown to indicate a warning
<LI><code>DataTruncation</code> -- thrown to indicate that data may have
been truncated
<LI><code>BatchUpdateException</code> -- thrown to indicate that not all
commands in a batch update executed successfully
</UL>
</UL>
<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.3 API</h3>
<UL>
<LI>Added <code>Sharding</code> support</LI>
<LI>Enhanced <code>Connection</code> to be able to provide hints
to the driver that a request, an independent unit of work,
is beginning or ending</LI>
<LI>Enhanced <code>DatabaseMetaData</code> to determine if Sharding is
supported</LI>
<LI>Added the method <code>drivers</code> to <code>DriverManager</code>
to return a Stream of the currently loaded and
available JDBC drivers</LI>
<LI>Added support to <code>Statement</code> for enquoting literals
and simple identifiers</LI>
<LI>Clarified the Java SE version that methods were deprecated</LI>
</UL>
<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.2 API</h3>
<UL>
<LI>Added <code>JDBCType</code> enum and <code>SQLType</code> interface</li>
<LI>Support for <code>REF CURSORS</code> in <code>CallableStatement</code>
</LI>
<LI><code>DatabaseMetaData</code> methods to return maximum Logical LOB size
and if Ref Cursors are supported</LI>
<LI>Added support for large update counts</LI>
</UL>
<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.1 API</h3>
<UL>
<LI>Allow <code>Connection</code>,
<code>ResultSet</code> and <code>Statement</code> objects to be
used with the try-with-resources statement</LI>
<LI>Support added to <code>CallableStatement</code> and
<code>ResultSet</code> to specify the Java type to convert to via the
<code>getObject</code> method</LI>
<LI><code>DatabaseMetaData</code> methods to return PseudoColumns and if a
generated key is always returned</LI>
<LI>Added support to <code>Connection</code> to specify a database schema,
abort and timeout a physical connection.</LI>
<LI>Added support to close a <code>Statement</code> object when its dependent
objects have been closed</LI>
<LI>Support for obtaining the parent logger for a <code>Driver</code>,
<code>DataSource</code>, <code>ConnectionPoolDataSource</code> and
<code>XADataSource</code></LI>
</UL>
<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.0 API</h3>
<UL>
<LI>auto java.sql.Driver discovery -- no longer need to load a
<code>java.sql.Driver</code> class via <code>Class.forName</code>
<LI>National Character Set support added
<li>Support added for the SQL:2003 XML data type
<lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions
added for common SQLState class value codes
<li>Enhanced Blob/Clob functionality -- Support provided to create and free a Blob/Clob instance
as well as additional methods added to improve accessibility
<li>Support added for accessing a SQL ROWID
<li>Support added to allow a JDBC application to access an instance of a JDBC resource
that has been wrapped by a vendor, usually in an application server or connection
pooling environment.
<li>Availability to be notified when a <code>PreparedStatement</code> that is associated
with a <code>PooledConnection</code> has been closed or the driver determines is invalid
</UL>
<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 3.0 API</h3>
<UL>
<LI>Pooled statements -- reuse of statements associated with a pooled
connection
<LI>Savepoints -- allow a transaction to be rolled back to a designated
savepoint
<LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify
how connections are to be pooled
<LI>Metadata for parameters of a <code>PreparedStatement</code> object
<LI>Ability to retrieve values from automatically generated columns
<LI>Ability to have multiple <code>ResultSet</code> objects
returned from <code>CallableStatement</code> objects open at the
same time
<LI>Ability to identify parameters to <code>CallableStatement</code>
objects by name as well as by index
<LI><code>ResultSet</code> holdability -- ability to specify whether cursors
should be held open or closed at the end of a transaction
<LI>Ability to retrieve and update the SQL structured type instance that a
<code>Ref</code> object references
<LI>Ability to programmatically update <code>BLOB</code>,
<code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values.
<LI>Addition of the <code>java.sql.Types.DATALINK</code> data type --
allows JDBC drivers access to objects stored outside a data source
<LI>Addition of metadata for retrieving SQL type hierarchies
</UL>
<h3><code>java.sql</code> Features Introduced in the JDBC 2.1 Core API</h3>
<UL>
<LI>Scrollable result sets--using new methods in the <code>ResultSet</code>
interface that allow the cursor to be moved to a particular row or to a
position relative to its current position
<LI>Batch updates
<LI>Programmatic updates--using <code>ResultSet</code> updater methods
<LI>New data types--interfaces mapping the SQL3 data types
<LI>Custom mapping of user-defined types (UDTs)
<LI>Miscellaneous features, including performance hints, the use of character
streams, full precision for <code>java.math.BigDecimal</code> values,
additional security, and
support for time zones in date, time, and timestamp values.
</UL>
<h3><code>javax.sql</code> Features Introduced in the JDBC 2.0 Optional
Package API</h3>
<UL>
<LI>The <code>DataSource</code> interface as a means of making a connection. The
Java Naming and Directory Interface&trade;
(JNDI) is used for registering a <code>DataSource</code> object with a
naming service and also for retrieving it.
<LI>Pooled connections -- allowing connections to be used and reused
<LI>Distributed transactions -- allowing a transaction to span diverse
DBMS servers
<LI><code>RowSet</code> technology -- providing a convenient means of
handling and passing data
</UL>
<h3>Custom Mapping of UDTs</h3>
A user-defined type (UDT) defined in SQL can be mapped to a class in the Java
programming language. An SQL structured type or an SQL <code>DISTINCT</code>
type are the UDTs that may be custom mapped. The following three
steps set up a custom mapping:
<ol>
<li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL
<li>Defining the class in the Java programming language to which the
SQL UDT will be mapped. This class must implement the
<code>SQLData</code> interface.
<li>Making an entry in a <code>Connection</code> object's type map
that contains two things:
<ul>
<li>the fully-qualified SQL name of the UDT
<li>the <code>Class</code> object for the class that implements the
<code>SQLData</code> interface
</ul>
</ol>
<p>
When these are in place for a UDT, calling the methods
<code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code>
on that UDT will automatically retrieve the custom mapping for it. Also, the
<code>PreparedStatement.setObject</code> method will automatically map the
object back to its SQL type to store it in the data source.
<h2>Package Specification</h2>
<ul>
<li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
</ul>
<h2>Related Documentation</h2>
<ul>
<li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/index.html">
Lesson:JDBC Basics(The Javaxx Tutorials &gt; JDBC&trade; Database Access)</a>
<li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
<i>JDBC&trade; API Tutorial and Reference, Third Edition</i></a>
</ul>
</body>
</html>

294
src/java.sql/share/classes/javax/sql/package-info.java Normal file
View File

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

302
src/java.sql/share/classes/javax/sql/package.html
View File

@ -1,302 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2000, 2017, 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.
-->
</head>
<body bgcolor="white">
Provides the API for server side data source access and processing from
the Java&trade; programming language.
This package supplements the <code>java.sql</code>
package and, as of the version 1.4 release, is included in the
Java Platform, Standard Edition (Java SE&trade;).
It remains an essential part of the Java Platform, Enterprise Edition
(Java EE&trade;).
<P>
The <code>javax.sql</code> package provides for the following:
<OL>
<LI>The <code>DataSource</code> interface as an alternative to the
<code>DriverManager</code> for establishing a
connection with a data source
<LI>Connection pooling and Statement pooling
<LI>Distributed transactions
<LI>Rowsets
</OL>
<P>
Applications use the <code>DataSource</code> and <code>RowSet</code>
APIs directly, but the connection pooling and distributed transaction
APIs are used internally by the middle-tier infrastructure.
<H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
The <code>javax.sql</code> package provides the preferred
way to make a connection with a data source. The <code>DriverManager</code>
class, the original mechanism, is still valid, and code using it will
continue to run. However, the newer <code>DataSource</code> mechanism
is preferred because it offers many advantages over the
<code>DriverManager</code> mechanism.
<P>
These are the main advantages of using a <code>DataSource</code> object to
make a connection:
<UL>
<LI>Changes can be made to a data source's properties, which means
that it is not necessary to make changes in application code when
something about the data source or driver changes.
<LI>Connection and Statement pooling and distributed transactions are available
through a <code>DataSource</code> object that is
implemented to work with the middle-tier infrastructure.
Connections made through the <code>DriverManager</code>
do not have connection and statement pooling or distributed transaction
capabilities.
</UL>
<P>
Driver vendors provide <code>DataSource</code> implementations. A
particular <code>DataSource</code> object represents a particular
physical data source, and each connection the <code>DataSource</code> object
creates is a connection to that physical data source.
<P>
A logical name for the data source is registered with a naming service that
uses the Java Naming and Directory Interface&trade;
(JNDI) API, usually by a system administrator or someone performing the
duties of a system administrator. An application can retrieve the
<code>DataSource</code> object it wants by doing a lookup on the logical
name that has been registered for it. The application can then use the
<code>DataSource</code> object to create a connection to the physical data
source it represents.
<P>
A <code>DataSource</code> object can be implemented to work with the
middle tier infrastructure so that the connections it produces will be
pooled for reuse. An application that uses such a <code>DataSource</code>
implementation will automatically get a connection that participates in
connection pooling.
A <code>DataSource</code> object can also be implemented to work with the
middle tier infrastructure so that the connections it produces can be
used for distributed transactions without any special coding.
<H2>Connection Pooling and Statement Pooling</H2>
Connections made via a <code>DataSource</code>
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.
Connection pooling allows a connection to be used and reused,
thus cutting down substantially on the number of new connections
that need to be created.
<P>
Connection pooling is totally transparent. It is done automatically
in the middle tier of a Java EE configuration, so from an application's
viewpoint, no change in code is required. An application simply uses
the <code>DataSource.getConnection</code> method to get the pooled
connection and uses it the same way it uses any <code>Connection</code>
object.
<P>
The classes and interfaces used for connection pooling are:
<UL>
<LI><code>ConnectionPoolDataSource</code>
<LI><code>PooledConnection</code>
<LI><code>ConnectionEvent</code>
<LI><code>ConnectionEventListener</code>
<LI><code>StatementEvent</code>
<LI><code>StatementEventListener</code>
</UL>
The connection pool manager, a facility in the middle tier of
a three-tier architecture, uses these classes and interfaces
behind the scenes. When a <code>ConnectionPoolDataSource</code> object
is called on to create a <code>PooledConnection</code> object, the
connection pool manager will register as a <code>ConnectionEventListener</code>
object with the new <code>PooledConnection</code> object. When the connection
is closed or there is an error, the connection pool manager (being a listener)
gets a notification that includes a <code>ConnectionEvent</code> object.
<p>
If the connection pool manager supports <code>Statement</code> pooling, for
<code>PreparedStatements</code>, which can be determined by invoking the method
<code>DatabaseMetaData.supportsStatementPooling</code>, the
connection pool manager will register as a <code>StatementEventListener</code>
object with the new <code>PooledConnection</code> object. When the
<code>PreparedStatement</code> is closed or there is an error, the connection
pool manager (being a listener)
gets a notification that includes a <code>StatementEvent</code> object.
<H2>Distributed Transactions</H2>
As with pooled connections, connections made via a <code>DataSource</code>
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
transaction.
<P>
The classes and interfaces used for distributed transactions are:
<UL>
<LI><code>XADataSource</code>
<LI><code>XAConnection</code>
</UL>
These interfaces are used by the transaction manager; an application does
not use them directly.
<P>
The <code>XAConnection</code> interface is derived from the
<code>PooledConnection</code> interface, so what applies to a pooled connection
also applies to a connection that is part of a distributed transaction.
A transaction manager in the middle tier handles everything transparently.
The only change in application code is that an application cannot do anything
that would interfere with the transaction manager's handling of the transaction.
Specifically, an application cannot call the methods <code>Connection.commit</code>
or <code>Connection.rollback</code>, and it cannot set the connection to be in
auto-commit mode (that is, it cannot call
<code>Connection.setAutoCommit(true)</code>).
<P>
An application does not need to do anything special to participate in a
distributed transaction.
It simply creates connections to the data sources it wants to use via
the <code>DataSource.getConnection</code> method, just as it normally does.
The transaction manager manages the transaction behind the scenes. The
<code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
each <code>XAConnection</code> object creates an <code>XAResource</code> object
that the transaction manager uses to manage the connection.
<H2>Rowsets</H2>
The <code>RowSet</code> interface works with various other classes and
interfaces behind the scenes. These can be grouped into three categories.
<OL>
<LI>Event Notification
<UL>
<LI><code>RowSetListener</code><br>
A <code>RowSet</code> object is a JavaBeans&trade;
component because it has properties and participates in the JavaBeans
event notification mechanism. The <code>RowSetListener</code> interface
is implemented by a component that wants to be notified about events that
occur to a particular <code>RowSet</code> object. Such a component registers
itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
method.
<P>
When the <code>RowSet</code> object changes one of its rows, changes all of
it rows, or moves its cursor, it also notifies each listener that is registered
with it. The listener reacts by carrying out its implementation of the
notification method called on it.
<LI><code>RowSetEvent</code><br>
As part of its internal notification process, a <code>RowSet</code> object
creates an instance of <code>RowSetEvent</code> and passes it to the listener.
The listener can use this <code>RowSetEvent</code> object to find out which rowset
had the event.
</UL>
<LI>Metadata
<UL>
<LI><code>RowSetMetaData</code><br>
This interface, derived from the
<code>ResultSetMetaData</code> interface, provides information about
the columns in a <code>RowSet</code> object. An application can use
<code>RowSetMetaData</code> methods to find out how many columns the
rowset contains and what kind of data each column can contain.
<P>
The <code>RowSetMetaData</code> interface provides methods for
setting the information about columns, but an application would not
normally use these methods. When an application calls the <code>RowSet</code>
method <code>execute</code>, the <code>RowSet</code> object will contain
a new set of rows, and its <code>RowSetMetaData</code> object will have been
internally updated to contain information about the new columns.
</UL>
<LI>The Reader/Writer Facility<br>
A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
interface can call on the <code>RowSetReader</code> object associated with it
to populate itself with data. It can also call on the <code>RowSetWriter</code>
object associated with it to write any changes to its rows back to the
data source from which it originally got the rows.
A rowset that remains connected to its data source does not need to use a
reader and writer because it can simply operate on the data source directly.
<UL>
<LI><code>RowSetInternal</code><br>
By implementing the <code>RowSetInternal</code> interface, a
<code>RowSet</code> object gets access to
its internal state and is able to call on its reader and writer. A rowset
keeps track of the values in its current rows and of the values that immediately
preceded the current ones, referred to as the <i>original</i> values. A rowset
also keeps track of (1) the parameters that have been set for its command and
(2) the connection that was passed to it, if any. A rowset uses the
<code>RowSetInternal</code> methods behind the scenes to get access to
this information. An application does not normally invoke these methods directly.
<LI><code>RowSetReader</code><br>
A disconnected <code>RowSet</code> object that has implemented the
<code>RowSetInternal</code> interface can call on its reader (the
<code>RowSetReader</code> object associated with it) to populate it with
data. When an application calls the <code>RowSet.execute</code> method,
that method calls on the rowset's reader to do much of the work. Implementations
can vary widely, but generally a reader makes a connection to the data source,
reads data from the data source and populates the rowset with it, and closes
the connection. A reader may also update the <code>RowSetMetaData</code> object
for its rowset. The rowset's internal state is also updated, either by the
reader or directly by the method <code>RowSet.execute</code>.
<LI><code>RowSetWriter</code><br>
A disconnected <code>RowSet</code> object that has implemented the
<code>RowSetInternal</code> interface can call on its writer (the
<code>RowSetWriter</code> object associated with it) to write changes
back to the underlying data source. Implementations may vary widely, but
generally, a writer will do the following:
<UL>
<LI>Make a connection to the data source
<LI>Check to see whether there is a conflict, that is, whether
a value that has been changed in the rowset has also been changed
in the data source
<LI>Write the new values to the data source if there is no conflict
<LI>Close the connection
</UL>
</UL>
</OL>
<P>
The <code>RowSet</code> 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.
<h2>Package Specification</h2>
<ul>
<li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
</ul>
<h2>Related Documentation</h2>
The Java Series book published by Addison-Wesley Longman provides detailed
information about the classes and interfaces in the <code>javax.sql</code>
package:
<ul>
<li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
<i>JDBC&#8482;API Tutorial and Reference, Third Edition</i></a>
</ul>
</body>
</html>