--- old/src/java.logging/share/classes/java/util/logging/package.html 2018-12-12 14:01:29.820321869 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,127 +0,0 @@ - - - - - - - -

-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. - -

-There are four main target uses of the logs: -

- -
    -
  1. Problem diagnosis by end users and system administrators. - 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. - -
  2. Problem diagnosis by field service engineers. 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. - -
  3. Problem diagnosis by the development organization. - 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. - -
  4. Problem diagnosis by developers. 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. -
- -

-The key elements of this package include: -

-

-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. -

- -

Null Pointers

-

-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). - -

Related Documentation

-

-For an overview of control flow, -please refer to the -{@extLink logging_overview Java Logging Overview} -

- - - -@since 1.4 - - - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.logging/share/classes/java/util/logging/package-info.java 2018-12-12 14:01:29.552320540 -0500 @@ -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. + * + *

+ * There are four main target uses of the logs: + *

+ * + *
    + *
  1. Problem diagnosis by end users and system administrators. + * 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. + * + *
  2. Problem diagnosis by field service engineers. 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. + * + *
  3. Problem diagnosis by the development organization. + * 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. + * + *
  4. Problem diagnosis by developers. 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. + *
+ * + *

+ * The key elements of this package include: + *

+ *

+ * 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. + *

+ * + *

Null Pointers

+ *

+ * 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). + * + *

Related Documentation

+ *

+ * For an overview of control flow, + * please refer to the + * {@extLink logging_overview Java Logging Overview} + *

+ * + * @since 1.4 + */ +package java.util.logging; --- old/src/java.prefs/share/classes/java/util/prefs/package.html 2018-12-12 14:01:30.684326153 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,44 +0,0 @@ - - - - - - - - -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 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.prefs/share/classes/java/util/prefs/package-info.java 2018-12-12 14:01:30.412324805 -0500 @@ -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; \ No newline at end of file --- old/src/java.rmi/share/classes/java/rmi/activation/package.html 2018-12-12 14:01:31.536330378 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,61 +0,0 @@ - - - - - - -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. - -

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 -Throws section of each method's specification. - - - -@since 1.2 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/java/rmi/activation/package-info.java 2018-12-12 14:01:31.272329069 -0500 @@ -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. + *

+ * 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 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. + * + *

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 + * Throws section of each method's specification. + * + * @since 1.2 + */ +package java.rmi.activation; --- old/src/java.rmi/share/classes/java/rmi/dgc/package.html 2018-12-12 14:01:32.396334643 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,55 +0,0 @@ - - - - - - -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 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/java/rmi/dgc/package-info.java 2018-12-12 14:01:32.136333354 -0500 @@ -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. + *

+ * 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 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; --- old/src/java.rmi/share/classes/java/rmi/package.html 2018-12-12 14:01:33.260338927 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,59 +0,0 @@ - - - - - - -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 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/java/rmi/package-info.java 2018-12-12 14:01:32.988337578 -0500 @@ -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. + *

+ * 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 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; --- old/src/java.rmi/share/classes/java/rmi/registry/package.html 2018-12-12 14:01:34.112343152 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,57 +0,0 @@ - - - - - - - -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 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/java/rmi/registry/package-info.java 2018-12-12 14:01:33.856341883 -0500 @@ -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. + *

+ * 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 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; --- old/src/java.rmi/share/classes/java/rmi/server/package.html 2018-12-12 14:01:34.992347516 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,74 +0,0 @@ - - - - - - -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. - -

Deprecated: HTTP Tunneling. The HTTP tunneling -mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for -further information. - -

Deprecated: Skeletons and Static Stubs. - -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. - - - -@since 1.1 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/java/rmi/server/package-info.java 2018-12-12 14:01:34.720346167 -0500 @@ -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. + *

+ * 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 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. + * + *

Deprecated: HTTP Tunneling. The HTTP tunneling + * mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for + * further information. + * + *

Deprecated: Skeletons and Static Stubs. + * + * 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. + * + * @since 1.1 + */ +package java.rmi.server; --- old/src/java.rmi/share/classes/javax/rmi/ssl/package.html 2018-12-12 14:01:35.860351820 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,38 +0,0 @@ - - - - - - - - -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 - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.rmi/share/classes/javax/rmi/ssl/package-info.java 2018-12-12 14:01:35.588350471 -0500 @@ -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; --- old/src/java.smartcardio/share/classes/javax/smartcardio/package.html 2018-12-12 14:01:36.740356184 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,98 +0,0 @@ - - - - -

Java™ Smart Card I/O API

- -This specification describes the Java Smart Card I/O API defined by -JSR 268. - -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. - -

-The API is defined by classes in the package -javax.smartcardio. They can be classified as follows: - -

-
Classes describing the corresponding Smart Card structures -
-ATR, -CommandAPDU, -ResponseAPDU - -
Factory to obtain implementations -
-TerminalFactory - -
Main classes for card and terminal functions -
-CardTerminals, -CardTerminal, -Card, -CardChannel - -
Supporting permission and exception classes -
-CardPermission, -CardException, -CardNotPresentException - -
Service provider interface, not accessed directly by applications -
-TerminalFactorySpi - -
- - -

API Example

- -A simple example of using the API is: -
-	// show the list of available terminals
-	TerminalFactory factory = TerminalFactory.getDefault();
-	List<CardTerminal> 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);
-
- -@since 1.6 -@author Andreas Sterbenz -@author JSR 268 Expert Group - - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.smartcardio/share/classes/javax/smartcardio/package-info.java 2018-12-12 14:01:36.464354815 -0500 @@ -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™ Smart Card I/O API. + * + * This specification describes the Java Smart Card I/O API defined by + * JSR 268. + * + * 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. + * + *

+ * The API is defined by classes in the package + * javax.smartcardio. They can be classified as follows: + * + *

+ *
Classes describing the corresponding Smart Card structures + *
+ * ATR, + * CommandAPDU, + * ResponseAPDU + * + *
Factory to obtain implementations + *
+ * TerminalFactory + * + *
Main classes for card and terminal functions + *
+ * CardTerminals, + * CardTerminal, + * Card, + * CardChannel + * + *
Supporting permission and exception classes + *
+ * CardPermission, + * CardException, + * CardNotPresentException + * + *
Service provider interface, not accessed directly by applications + *
+ * TerminalFactorySpi + * + *
+ * + * + *

API Example

+ * + * A simple example of using the API is: + * 
+ * 	// show the list of available terminals
+ * 	TerminalFactory factory = TerminalFactory.getDefault();
+ * 	List<CardTerminal> 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);
+ *
+ * + * @since 1.6 + * @author Andreas Sterbenz + * @author JSR 268 Expert Group + */ +package javax.smartcardio; --- old/src/java.sql.rowset/share/classes/com/sun/rowset/package.html 2018-12-12 14:01:37.636360627 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,86 +0,0 @@ - - - - - - - - com.sun.rowset Package - - -Provides five standard implementations of the standard JDBC RowSet implementation -interface definitions. These reference implementations are included with the J2SE version -1.5 platform and represent the benchmark standard RowSet implementations as verified -by the Test Compatibility Kit (TCK) as mandated by the Java Community Process. -
- -

1.0 Available JDBC RowSet Reference Implementations

-The following implementations are provided:
- -
JdbcRowSetImpl - The javax.sql.rowset.JdbcRowSet -interface reference implementation.
-
-CachedRowSetImpl - The javax.sql.rowset.CachedRowSet interface -reference implementation.
-
-WebRowSetImpl - The javax.sql.rowset.WebRowSet interface -reference implementation.
-
-FilteredRowSetImpl - The javax.sql.rowset.FilteredRowSet -interface reference implementation.
-
-JoinRowSetImpl - The javax.sql.rowset.JoinRowSet interface -reference implementation.
-
- -All details on their expected behavior, including their interactions with the SyncProvider -SPI and helper classes are provided in the interface definitions in the javax.sql.rowset -package specification.
- -

2.0 Usage

-The reference implementations represent robust implementations of the standard -RowSet interfaces defined in the javax.sql.rowset package. -All disconnected RowSet implementations, such as the CachedRowSetImpl -and WebRowSetImpl, are flexible enough to use the SyncFactory SPIs to -leverage non-reference implementation SyncProvider implementations to obtain -differing synchronization semantics. Furthermore, developers and vendors alike are free -to use these implementations and integrate them into their products just as they -can with to other components of the Java platform.
- -

3.0 Extending the JDBC RowSet Implementations

- -The JDBC RowSet reference implementations are provided as non-final -classes so that any developer can extend them to provide additional features -while maintaining the core required standard functionality and compatibility. It -is anticipated that many vendors and developers will extend the standard feature -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. -
-
- - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.sql.rowset/share/classes/com/sun/rowset/package-info.java 2018-12-12 14:01:37.356359238 -0500 @@ -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 RowSet implementation + * interface definitions. These reference implementations are included with the J2SE version + * 1.5 platform and represent the benchmark standard RowSet implementations as verified + * by the Test Compatibility Kit (TCK) as mandated by the Java Community Process. + *
+ * + *

1.0 Available JDBC RowSet Reference Implementations

+ * The following implementations are provided:
+ * + *
JdbcRowSetImpl - The javax.sql.rowset.JdbcRowSet + * interface reference implementation.
+ *
+ * CachedRowSetImpl - The javax.sql.rowset.CachedRowSet interface + * reference implementation.
+ *
+ * WebRowSetImpl - The javax.sql.rowset.WebRowSet interface + * reference implementation.
+ *
+ * FilteredRowSetImpl - The javax.sql.rowset.FilteredRowSet + * interface reference implementation.
+ *
+ * JoinRowSetImpl - The javax.sql.rowset.JoinRowSet interface + * reference implementation.
+ *
+ * + * All details on their expected behavior, including their interactions with the SyncProvider + * SPI and helper classes are provided in the interface definitions in the javax.sql.rowset + * package specification.
+ * + *

2.0 Usage

+ * The reference implementations represent robust implementations of the standard + * RowSet interfaces defined in the javax.sql.rowset package. + * All disconnected RowSet implementations, such as the CachedRowSetImpl + * and WebRowSetImpl, are flexible enough to use the SyncFactory SPIs to + * leverage non-reference implementation SyncProvider implementations to obtain + * differing synchronization semantics. Furthermore, developers and vendors alike are free + * to use these implementations and integrate them into their products just as they + * can with to other components of the Java platform.
+ * + *

3.0 Extending the JDBC RowSet Implementations

+ * + * The JDBC RowSet reference implementations are provided as non-final + * classes so that any developer can extend them to provide additional features + * while maintaining the core required standard functionality and compatibility. It + * is anticipated that many vendors and developers will extend the standard feature + * 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; --- old/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package.html 2018-12-12 14:01:38.508364951 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,170 +0,0 @@ - - - - - - - - - javax.sql.rowset.providers Package - - -Repository for the RowSet reference implementations of the -SyncProvider abstract class. These implementations provide a -disconnected RowSet -object with the ability to synchronize the data in the underlying data -source with its data. These implementations are provided as -the default SyncProvider implementations and are accessible via the -SyncProvider SPI managed by the SyncFactory. - -

1.0 SyncProvider Reference Implementations

- The main job of a SyncProvider implementation is to manage -the reader and writer mechanisms. - The SyncProvider SPI, as specified in the javax.sql.rowset.spi -package, provides a pluggable mechanism by which javax.sql.RowSetReader -and javax.sql.RowSetWriter implementations can be supplied to a disconnected -RowSet object. -

- A reader, a javax.sql.RowSetReader -object, does the work necessary to populate a RowSet object with data. -A writer, a javax.sql.RowSetWriter object, does the work necessary for -synchronizing a RowSet object's data with the data in the originating -source of data. Put another way, a writer writes a RowSet -object's data back to the data source. -

-Generally speaking, the course of events is this. The reader makes a connection to -the data source and reads the data from a ResultSet object into its -RowSet object. Then it closes the connection. While -the RowSet object is disconnected, an application makes some modifications -to the data and calls the method acceptChanges. At this point, the -writer is called to write the changes back to the database table or view -from which the original data came. This is called synchronization. -

-If the data in the originating data source has not changed, there is no problem -with just writing the RowSet object's new data to the data source. -If it has changed, however, there is a conflict that needs to be resolved. One -way to solve the problem is not to let the data in the data source be changed in -the first place, which can be done by setting locks on a row, a table, or the -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 SyncProvider implementations may handle synchronization in -any of these ways, varying from doing no checking for -conflicts, to doing various levels of checking, to guaranteeing that there are no -conflicts. -

-The SyncProvider class offers methods to help a RowSet -object discover and manage how a provider handles synchronization. -The method getProviderGrade returns the -grade of synchronization a provider offers. An application can -direct the provider to use a particular level of locking by calling -the method setDataSourceLock and specifying the level of locking desired. -If a RowSet object's data came from an SQL VIEW, an -application may call the method supportsUpdatableView to -find out whether the VIEW can be updated. -

-Synchronization is done completely behind the scenes, so it is third party vendors of -synchronization provider implementations who have to take care of this complex task. -Application programmers can decide which provider to use and the level of locking to -be done, but they are free from having to worry about the implementation details. -

-The JDBC RowSet Implementations reference implementation provides two -implementations of the SyncProvider class: - -

- -

2.0 Basics in RowSet Population & Synchronization

-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.
-
-The command property contains the query that determines what -data a RowSet will contain. Rowsets have methods for setting a query's -parameter(s), which means that a query can be executed multiple times with -different parameters to produce different result sets. Or the query can be -changed to something completely new to get a new result set. -

Once a rowset contains the rows from a ResultSet object or some -other data source, its column values can be updated, and its rows can be -inserted or deleted. Any method that causes a change in the rowset's values -or cursor position also notifies any object that has been registered as -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.
-
-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 acceptChanges, -and the data source backing the rowset will be updated to match the current -values in the rowset.

- -

A disconnected rowset, such as a CachedRowSet or WebRowSet - object, establishes a connection to populate itself with data from a database - and then closes the connection. The RowSet object will remain - disconnected until it wants to propagate changes back to its database table, - which is optional. To write its changes back to the database (synchronize with - the database), the rowset establishes a connection, write the changes, and then - once again disconnects itself.
-

- -

3.0 Other Possible Implementations

- There are many other possible implementations of the SyncProvider abstract - class. One possibility is to employ a more robust synchronization model, which - would give a RowSet object increased trust in the provider's - ability to get any updates back to the original data source. Another possibility - is a more formal synchronization mechanism such as SyncML - (http://www.syncml.org/)
-
-
- - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package-info.java 2018-12-12 14:01:38.236363602 -0500 @@ -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 RowSet reference implementations of the + * SyncProvider abstract class. These implementations provide a + * disconnected RowSet + * object with the ability to synchronize the data in the underlying data + * source with its data. These implementations are provided as + * the default SyncProvider implementations and are accessible via the + * SyncProvider SPI managed by the SyncFactory. + * + *

1.0 SyncProvider Reference Implementations

+ * The main job of a SyncProvider implementation is to manage + * the reader and writer mechanisms. + * The SyncProvider SPI, as specified in the javax.sql.rowset.spi + * package, provides a pluggable mechanism by which javax.sql.RowSetReader + * and javax.sql.RowSetWriter implementations can be supplied to a disconnected + * RowSet object. + *

+ * A reader, a javax.sql.RowSetReader + * object, does the work necessary to populate a RowSet object with data. + * A writer, a javax.sql.RowSetWriter object, does the work necessary for + * synchronizing a RowSet object's data with the data in the originating + * source of data. Put another way, a writer writes a RowSet + * object's data back to the data source. + *

+ * Generally speaking, the course of events is this. The reader makes a connection to + * the data source and reads the data from a ResultSet object into its + * RowSet object. Then it closes the connection. While + * the RowSet object is disconnected, an application makes some modifications + * to the data and calls the method acceptChanges. At this point, the + * writer is called to write the changes back to the database table or view + * from which the original data came. This is called synchronization. + *

+ * If the data in the originating data source has not changed, there is no problem + * with just writing the RowSet object's new data to the data source. + * If it has changed, however, there is a conflict that needs to be resolved. One + * way to solve the problem is not to let the data in the data source be changed in + * the first place, which can be done by setting locks on a row, a table, or the + * 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 SyncProvider implementations may handle synchronization in + * any of these ways, varying from doing no checking for + * conflicts, to doing various levels of checking, to guaranteeing that there are no + * conflicts. + *

+ * The SyncProvider class offers methods to help a RowSet + * object discover and manage how a provider handles synchronization. + * The method getProviderGrade returns the + * grade of synchronization a provider offers. An application can + * direct the provider to use a particular level of locking by calling + * the method setDataSourceLock and specifying the level of locking desired. + * If a RowSet object's data came from an SQL VIEW, an + * application may call the method supportsUpdatableView to + * find out whether the VIEW can be updated. + *

+ * Synchronization is done completely behind the scenes, so it is third party vendors of + * synchronization provider implementations who have to take care of this complex task. + * Application programmers can decide which provider to use and the level of locking to + * be done, but they are free from having to worry about the implementation details. + *

+ * The JDBC RowSet Implementations reference implementation provides two + * implementations of the SyncProvider class: + * + *

+ * + *

2.0 Basics in RowSet Population & Synchronization

+ * 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.
+ *
+ * The command property contains the query that determines what + * data a RowSet will contain. Rowsets have methods for setting a query's + * parameter(s), which means that a query can be executed multiple times with + * different parameters to produce different result sets. Or the query can be + * changed to something completely new to get a new result set. + *

Once a rowset contains the rows from a ResultSet object or some + * other data source, its column values can be updated, and its rows can be + * inserted or deleted. Any method that causes a change in the rowset's values + * or cursor position also notifies any object that has been registered as + * 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.
+ *
+ * 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 acceptChanges, + * and the data source backing the rowset will be updated to match the current + * values in the rowset.

+ * + *

A disconnected rowset, such as a CachedRowSet or WebRowSet + * object, establishes a connection to populate itself with data from a database + * and then closes the connection. The RowSet object will remain + * disconnected until it wants to propagate changes back to its database table, + * which is optional. To write its changes back to the database (synchronize with + * the database), the rowset establishes a connection, write the changes, and then + * once again disconnects itself.
+ *

+ * + *

3.0 Other Possible Implementations

+ * There are many other possible implementations of the SyncProvider abstract + * class. One possibility is to employ a more robust synchronization model, which + * would give a RowSet object increased trust in the provider's + * ability to get any updates back to the original data source. Another possibility + * is a more formal synchronization mechanism such as SyncML + * (http://www.syncml.org/)
+ */ +package com.sun.rowset.providers; --- old/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package.html 2018-12-12 14:01:39.380369275 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,239 +0,0 @@ - - - - - - - - -javax.sql.rowset.serial - - -Provides utility classes to allow serializable mappings between SQL types -and data types in the Java programming language. -

Standard JDBC RowSet implementations may use these utility -classes to -assist in the serialization of disconnected RowSet objects. -This is useful -when transmitting a disconnected RowSet object over the wire to -a different VM or across layers within an application.
-

- -

1.0 SerialArray

-A serializable mapping in the Java programming language of an SQL ARRAY -value.
-
-The SerialArray class provides a constructor for creating a SerialArray -instance from an Array object, methods for getting the base type and -the SQL name for the base type, and methods for copying all or part of a -SerialArray object.
- -

2.0 SerialBlob

-A serializable mapping in the Java programming language of an SQL BLOB -value.
-
-The SerialBlobclass 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 SerialBlobobject -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 Blob.getBytes) -or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream). -
-
-SerialBlob methods make it possible to make a copy of a SerialBlob -object as an array of bytes or as a stream. They also make it possible -to locate a given pattern of bytes or a Blob object within a SerialBlob -object.
- -

3.0 SerialClob

-A serializable mapping in the Java programming language of an SQL CLOB -value.
-
-The SerialClob class provides a constructor for creating an instance -from a Clob object. Note that the Clob object should have -brought the SQL CLOB value's data over to the client before a SerialClob -object is constructed from it. The data of an SQL CLOB value can be -materialized on the client as a stream of Unicode characters.
-
-SerialClob methods make it possible to get a substring from a -SerialClob object or to locate the start of a pattern of characters. -
- -

5.0 SerialDatalink

-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.
-
-RowSet implementations can use the method RowSet.getURL() to retrieve -a java.net.URL object, which can be used to manipulate the external data. -
-
-      java.net.URL url = rowset.getURL(1);
- -

6.0 SerialJavaObject

-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.
-
-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 SerialException being thrown.
- -

7.0 SerialRef

-A serializable mapping between the SQL REF type and the Java programming -language.
-
-The SerialRef class provides a constructor for creating a SerialRef -instance from a Ref type and provides methods for getting -and setting the Ref object type.
- -

8.0 SerialStruct

-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.
-
-In addition, if a Map object is passed to one of the constructors or -to the method getAttributes, the structured type is custom mapped -according to the mapping specified in the Map object. -
-The SerialStruct class provides a constructor for creating an -instance from a Struct object, a method for retrieving the SQL -type name of the SQL structured type in the database, and methods for retrieving -its attribute values.
- -

9.0 SQLInputImpl

- An input stream used for custom mapping user-defined types (UDTs). An - SQLInputImpl object is an input stream that contains a stream of - values that are -the attributes of a UDT. This class is used by the driver behind the scenes -when the method getObject is called on an SQL structured or distinct -type that has a custom mapping; a programmer never invokes SQLInputImpl -methods directly.
-
-The SQLInputImpl class provides a set of reader methods -analogous to the ResultSet getter methods. These methods make it -possible to read the values in an SQLInputImpl object. The method -wasNull is used to determine whether the last value read was SQL NULL. -
-
-When a constructor or getter method that takes a Map object is called, -the JDBC driver calls the method -SQLData.getSQLType to determine the SQL type of the UDT being custom -mapped. The driver creates an instance of SQLInputImpl, populating it with -the attributes of the UDT. The driver then passes the input stream to the -method SQLData.readSQL, which in turn calls the SQLInputImpl -methods to read the attributes from the input stream.
- -

10.0 SQLOutputImpl

- 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. -
-
-When an application calls the method PreparedStatement.setObject, the -driver checks to see whether the value to be written is a UDT with a custom -mapping. If it is, there will be an entry in a type map containing the Class -object for the class that implements SQLData for this UDT. If the -value to be written is an instance of SQLData, the driver will -create an instance of SQLOutputImpl and pass it to the method -SQLData.writeSQL. -The method writeSQL in turn calls the appropriate SQLOutputImpl -writer methods to write data from the SQLData object to the -SQLOutputImpl -output stream as the representation of an SQL user-defined type. - -

Custom Mapping

-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. -

-A programmer defines the mapping by implementing the interface SQLData. -For example, if an SQL structured type named AUTHORS has the attributes NAME, -TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The -Authors class could have the fields name, title, and publisher, to which the -attributes of AUTHORS are mapped. In such a case, the implementation of -SQLData could look like the following: -

-   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);
-       }
-   } 
-
- -A java.util.Map object is used to associate the SQL structured -type with its mapping to the class Authors. The following code fragment shows -how a Map object might be created and given an entry associating -AUTHORS and Authors. -
-    java.util.Map map = new java.util.HashMap();
-    map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
-
- -The Map object map now contains an entry with the -fully qualified name of the SQL structured type and the Class - object for the class Authors. It can be passed to a method -to tell the driver how to map AUTHORS to Authors. -

-For a disconnected RowSet object, custom mapping can be done -only when a Map object is passed to the method or constructor -that will be doing the custom mapping. The situation is different for -connected RowSet objects because they maintain a connection -with the data source. A method that does custom mapping and is called by -a disconnected RowSet object may use the Map -object that is associated with the Connection object being -used. So, in other words, if no map is specified, the connection's type -map can be used by default. - -
- - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java 2018-12-12 14:01:39.104367906 -0500 @@ -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. + *

Standard JDBC RowSet implementations may use these utility + * classes to + * assist in the serialization of disconnected RowSet objects. + * This is useful + * when transmitting a disconnected RowSet object over the wire to + * a different VM or across layers within an application.
+ *

+ * + *

1.0 SerialArray

+ * A serializable mapping in the Java programming language of an SQL ARRAY + * value.
+ *
+ * The SerialArray class provides a constructor for creating a SerialArray + * instance from an Array object, methods for getting the base type and + * the SQL name for the base type, and methods for copying all or part of a + * SerialArray object.
+ * + *

2.0 SerialBlob

+ * A serializable mapping in the Java programming language of an SQL BLOB + * value.
+ *
+ * The SerialBlobclass 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 SerialBlobobject + * 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 Blob.getBytes) + * or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream). + *
+ *
+ * SerialBlob methods make it possible to make a copy of a SerialBlob + * object as an array of bytes or as a stream. They also make it possible + * to locate a given pattern of bytes or a Blob object within a SerialBlob + * object.
+ * + *

3.0 SerialClob

+ * A serializable mapping in the Java programming language of an SQL CLOB + * value.
+ *
+ * The SerialClob class provides a constructor for creating an instance + * from a Clob object. Note that the Clob object should have + * brought the SQL CLOB value's data over to the client before a SerialClob + * object is constructed from it. The data of an SQL CLOB value can be + * materialized on the client as a stream of Unicode characters.
+ *
+ * SerialClob methods make it possible to get a substring from a + * SerialClob object or to locate the start of a pattern of characters. + *
+ * + *

5.0 SerialDatalink

+ * 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.
+ *
+ * RowSet implementations can use the method RowSet.getURL() to retrieve + * a java.net.URL object, which can be used to manipulate the external data. + *
+ *
+ *       java.net.URL url = rowset.getURL(1);
+ * + *

6.0 SerialJavaObject

+ * 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.
+ *
+ * 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 SerialException being thrown.
+ * + *

7.0 SerialRef

+ * A serializable mapping between the SQL REF type and the Java programming + * language.
+ *
+ * The SerialRef class provides a constructor for creating a SerialRef + * instance from a Ref type and provides methods for getting + * and setting the Ref object type.
+ * + *

8.0 SerialStruct

+ * 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.
+ *
+ * In addition, if a Map object is passed to one of the constructors or + * to the method getAttributes, the structured type is custom mapped + * according to the mapping specified in the Map object. + *
+ * The SerialStruct class provides a constructor for creating an + * instance from a Struct object, a method for retrieving the SQL + * type name of the SQL structured type in the database, and methods for retrieving + * its attribute values.
+ * + *

9.0 SQLInputImpl

+ * An input stream used for custom mapping user-defined types (UDTs). An + * SQLInputImpl object is an input stream that contains a stream of + * values that are + * the attributes of a UDT. This class is used by the driver behind the scenes + * when the method getObject is called on an SQL structured or distinct + * type that has a custom mapping; a programmer never invokes SQLInputImpl + * methods directly.
+ *
+ * The SQLInputImpl class provides a set of reader methods + * analogous to the ResultSet getter methods. These methods make it + * possible to read the values in an SQLInputImpl object. The method + * wasNull is used to determine whether the last value read was SQL NULL. + *
+ *
+ * When a constructor or getter method that takes a Map object is called, + * the JDBC driver calls the method + * SQLData.getSQLType to determine the SQL type of the UDT being custom + * mapped. The driver creates an instance of SQLInputImpl, populating it with + * the attributes of the UDT. The driver then passes the input stream to the + * method SQLData.readSQL, which in turn calls the SQLInputImpl + * methods to read the attributes from the input stream.
+ * + *

10.0 SQLOutputImpl

+ * 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. + *
+ *
+ * When an application calls the method PreparedStatement.setObject, the + * driver checks to see whether the value to be written is a UDT with a custom + * mapping. If it is, there will be an entry in a type map containing the Class + * object for the class that implements SQLData for this UDT. If the + * value to be written is an instance of SQLData, the driver will + * create an instance of SQLOutputImpl and pass it to the method + * SQLData.writeSQL. + * The method writeSQL in turn calls the appropriate SQLOutputImpl + * writer methods to write data from the SQLData object to the + * SQLOutputImpl + * output stream as the representation of an SQL user-defined type. + * + *

Custom Mapping

+ * 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. + *

+ * A programmer defines the mapping by implementing the interface SQLData. + * For example, if an SQL structured type named AUTHORS has the attributes NAME, + * TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The + * Authors class could have the fields name, title, and publisher, to which the + * attributes of AUTHORS are mapped. In such a case, the implementation of + * SQLData could look like the following: + * 

+ *    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);
+ *        }
+ *    }
+ *
+ * + * A java.util.Map object is used to associate the SQL structured + * type with its mapping to the class Authors. The following code fragment shows + * how a Map object might be created and given an entry associating + * AUTHORS and Authors. + * 
+ *     java.util.Map map = new java.util.HashMap();
+ *     map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
+ *
+ * + * The Map object map now contains an entry with the + * fully qualified name of the SQL structured type and the Class + * object for the class Authors. It can be passed to a method + * to tell the driver how to map AUTHORS to Authors. + *

+ * For a disconnected RowSet object, custom mapping can be done + * only when a Map object is passed to the method or constructor + * that will be doing the custom mapping. The situation is different for + * connected RowSet objects because they maintain a connection + * with the data source. A method that does custom mapping and is called by + * a disconnected RowSet object may use the Map + * object that is associated with the Connection 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; --- old/src/java.sql/share/classes/java/sql/package.html 2018-12-12 14:01:40.252373599 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,351 +0,0 @@ - - - - - - - - - - - -Provides the API for accessing and processing data stored in a -data source (usually a relational database) using the -Java™ programming language. -This API includes a framework whereby different -drivers can be installed dynamically to access different data sources. -Although the JDBC™ 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 -javax.sql.RowSet group of interfaces, can be customized to -use and update data from a spread sheet, flat file, or any other tabular -data source. - -

What the JDBC™ 4.3 API Includes

-The JDBC™ 4.3 API includes both -the java.sql package, referred to as the JDBC core API, -and the javax.sql package, referred to as the JDBC Optional -Package API. This complete JDBC API -is included in the Java™ Standard Edition (Java SE™), version 7. -The javax.sql package extends the functionality of the JDBC API -from a client-side API to a server-side API, and it is an essential part -of the Java™ Enterprise Edition -(Java EE™) technology. - -

Versions

-The JDBC 4.3 API incorporates all of the previous JDBC API versions: - -

-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™ comments for the JDBC API, -they indicate the following: -

-

-NOTE: 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. -

-NOTE: The class SQLPermission was added in the -Java™ 2 SDK, Standard Edition, -version 1.3 release. This class is used to prevent unauthorized -access to the logging stream associated with the DriverManager, -which may contain information such as table names, column data, and so on. - -

What the java.sql Package Contains

-The java.sql package contains API for the following: - - -

java.sql and javax.sql Features Introduced in the JDBC 4.3 API

- - -

java.sql and javax.sql Features Introduced in the JDBC 4.2 API

- - -

java.sql and javax.sql Features Introduced in the JDBC 4.1 API

- -

java.sql and javax.sql Features Introduced in the JDBC 4.0 API

- - - -

java.sql and javax.sql Features Introduced in the JDBC 3.0 API

- - -

java.sql Features Introduced in the JDBC 2.1 Core API

- - -

javax.sql Features Introduced in the JDBC 2.0 Optional -Package API

- - - -

Custom Mapping of UDTs

-A user-defined type (UDT) defined in SQL can be mapped to a class in the Java -programming language. An SQL structured type or an SQL DISTINCT -type are the UDTs that may be custom mapped. The following three -steps set up a custom mapping: -
    -
  1. Defining the SQL structured type or DISTINCT type in SQL -
  2. Defining the class in the Java programming language to which the - SQL UDT will be mapped. This class must implement the - SQLData interface. -
  3. Making an entry in a Connection object's type map - that contains two things: - -
-

-When these are in place for a UDT, calling the methods -ResultSet.getObject or CallableStatement.getObject -on that UDT will automatically retrieve the custom mapping for it. Also, the -PreparedStatement.setObject method will automatically map the -object back to its SQL type to store it in the data source. - -

Package Specification

- - - -

Related Documentation

- - - - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.sql/share/classes/java/sql/package-info.java 2018-12-12 14:01:39.988372290 -0500 @@ -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™ programming language. + * This API includes a framework whereby different + * drivers can be installed dynamically to access different data sources. + * Although the JDBC™ 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 + * javax.sql.RowSet group of interfaces, can be customized to + * use and update data from a spread sheet, flat file, or any other tabular + * data source. + * + *

What the JDBC™ 4.3 API Includes

+ * The JDBC™ 4.3 API includes both + * the java.sql package, referred to as the JDBC core API, + * and the javax.sql package, referred to as the JDBC Optional + * Package API. This complete JDBC API + * is included in the Java™ Standard Edition (Java SE™), version 7. + * The javax.sql package extends the functionality of the JDBC API + * from a client-side API to a server-side API, and it is an essential part + * of the Java™ Enterprise Edition + * (Java EE™) technology. + * + *

Versions

+ * The JDBC 4.3 API incorporates all of the previous JDBC API versions: + * + *

+ * 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™ comments for the JDBC API, + * they indicate the following: + *

+ *

+ * NOTE: 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. + *

+ * NOTE: The class SQLPermission was added in the + * Java™ 2 SDK, Standard Edition, + * version 1.3 release. This class is used to prevent unauthorized + * access to the logging stream associated with the DriverManager, + * which may contain information such as table names, column data, and so on. + * + *

What the java.sql Package Contains

+ * The java.sql package contains API for the following: + * + * + *

java.sql and javax.sql Features Introduced in the JDBC 4.3 API

+ * + * + *

java.sql and javax.sql Features Introduced in the JDBC 4.2 API

+ * + * + *

java.sql and javax.sql Features Introduced in the JDBC 4.1 API

+ * + *

java.sql and javax.sql Features Introduced in the JDBC 4.0 API

+ * + * + * + *

java.sql and javax.sql Features Introduced in the JDBC 3.0 API

+ * + * + *

java.sql Features Introduced in the JDBC 2.1 Core API

+ * + * + *

javax.sql Features Introduced in the JDBC 2.0 Optional + * Package API

+ * + * + * + *

Custom Mapping of UDTs

+ * A user-defined type (UDT) defined in SQL can be mapped to a class in the Java + * programming language. An SQL structured type or an SQL DISTINCT + * type are the UDTs that may be custom mapped. The following three + * steps set up a custom mapping: + *
    + *
  1. Defining the SQL structured type or DISTINCT type in SQL + *
  2. Defining the class in the Java programming language to which the + * SQL UDT will be mapped. This class must implement the + * SQLData interface. + *
  3. Making an entry in a Connection object's type map + * that contains two things: + * + *
+ *

+ * When these are in place for a UDT, calling the methods + * ResultSet.getObject or CallableStatement.getObject + * on that UDT will automatically retrieve the custom mapping for it. Also, the + * PreparedStatement.setObject method will automatically map the + * object back to its SQL type to store it in the data source. + * + *

Package Specification

+ * + * + * + *

Related Documentation

+ * + * + */ +package java.sql; --- old/src/java.sql/share/classes/javax/sql/package.html 2018-12-12 14:01:41.128377943 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,302 +0,0 @@ - - - - - - - - - - - -Provides the API for server side data source access and processing from -the Java™ programming language. -This package supplements the java.sql -package and, as of the version 1.4 release, is included in the -Java Platform, Standard Edition (Java SE™). -It remains an essential part of the Java Platform, Enterprise Edition -(Java EE™). -

-The javax.sql package provides for the following: -

    -
  1. The DataSource interface as an alternative to the - DriverManager for establishing a - connection with a data source -
  2. Connection pooling and Statement pooling -
  3. Distributed transactions -
  4. Rowsets -
-

-Applications use the DataSource and RowSet -APIs directly, but the connection pooling and distributed transaction -APIs are used internally by the middle-tier infrastructure. - -

Using a DataSource Object to Make a Connection

- -The javax.sql package provides the preferred -way to make a connection with a data source. The DriverManager -class, the original mechanism, is still valid, and code using it will -continue to run. However, the newer DataSource mechanism -is preferred because it offers many advantages over the -DriverManager mechanism. -

-These are the main advantages of using a DataSource object to -make a connection: -

-

-Driver vendors provide DataSource implementations. A -particular DataSource object represents a particular -physical data source, and each connection the DataSource object -creates is a connection to that physical data source. -

-A logical name for the data source is registered with a naming service that -uses the Java Naming and Directory Interface™ -(JNDI) API, usually by a system administrator or someone performing the -duties of a system administrator. An application can retrieve the -DataSource object it wants by doing a lookup on the logical -name that has been registered for it. The application can then use the -DataSource object to create a connection to the physical data -source it represents. -

-A DataSource object can be implemented to work with the -middle tier infrastructure so that the connections it produces will be -pooled for reuse. An application that uses such a DataSource -implementation will automatically get a connection that participates in -connection pooling. -A DataSource object can also be implemented to work with the -middle tier infrastructure so that the connections it produces can be -used for distributed transactions without any special coding. - -

Connection Pooling and Statement Pooling

- -Connections made via a DataSource -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. -

-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 DataSource.getConnection method to get the pooled -connection and uses it the same way it uses any Connection -object. -

-The classes and interfaces used for connection pooling are: -

-The connection pool manager, a facility in the middle tier of -a three-tier architecture, uses these classes and interfaces -behind the scenes. When a ConnectionPoolDataSource object -is called on to create a PooledConnection object, the -connection pool manager will register as a ConnectionEventListener -object with the new PooledConnection object. When the connection -is closed or there is an error, the connection pool manager (being a listener) -gets a notification that includes a ConnectionEvent object. -

-If the connection pool manager supports Statement pooling, for -PreparedStatements, which can be determined by invoking the method -DatabaseMetaData.supportsStatementPooling, the -connection pool manager will register as a StatementEventListener -object with the new PooledConnection object. When the -PreparedStatement is closed or there is an error, the connection -pool manager (being a listener) -gets a notification that includes a StatementEvent object. - -

Distributed Transactions

- -As with pooled connections, connections made via a DataSource -object that is implemented to work with the middle tier infrastructure -may participate in distributed transactions. This gives an application -the ability to involve data sources on multiple servers in a single -transaction. -

-The classes and interfaces used for distributed transactions are: -

-These interfaces are used by the transaction manager; an application does -not use them directly. -

-The XAConnection interface is derived from the -PooledConnection interface, so what applies to a pooled connection -also applies to a connection that is part of a distributed transaction. -A transaction manager in the middle tier handles everything transparently. -The only change in application code is that an application cannot do anything -that would interfere with the transaction manager's handling of the transaction. -Specifically, an application cannot call the methods Connection.commit -or Connection.rollback, and it cannot set the connection to be in -auto-commit mode (that is, it cannot call -Connection.setAutoCommit(true)). -

-An application does not need to do anything special to participate in a -distributed transaction. -It simply creates connections to the data sources it wants to use via -the DataSource.getConnection method, just as it normally does. -The transaction manager manages the transaction behind the scenes. The -XADataSource interface creates XAConnection objects, and -each XAConnection object creates an XAResource object -that the transaction manager uses to manage the connection. - - -

Rowsets

-The RowSet interface works with various other classes and -interfaces behind the scenes. These can be grouped into three categories. -
    -
  1. Event Notification - -
  2. Metadata - -
  3. The Reader/Writer Facility
    -A RowSet object that implements the RowSetInternal -interface can call on the RowSetReader object associated with it -to populate itself with data. It can also call on the RowSetWriter -object associated with it to write any changes to its rows back to the -data source from which it originally got the rows. -A rowset that remains connected to its data source does not need to use a -reader and writer because it can simply operate on the data source directly. - - -
-

-The RowSet interface may be implemented in any number of -ways, and anyone may write an implementation. Developers are encouraged -to use their imaginations in coming up with new ways to use rowsets. - - -

Package Specification

- - - -

Related Documentation

- -The Java Series book published by Addison-Wesley Longman provides detailed -information about the classes and interfaces in the javax.sql -package: - - - - --- /dev/null 2018-12-11 14:42:27.088072338 -0500 +++ new/src/java.sql/share/classes/javax/sql/package-info.java 2018-12-12 14:01:40.852376574 -0500 @@ -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. + *

+ * 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 server side data source access and processing from + * the Java™ programming language. + * This package supplements the java.sql + * package and, as of the version 1.4 release, is included in the + * Java Platform, Standard Edition (Java SE™). + * It remains an essential part of the Java Platform, Enterprise Edition + * (Java EE™). + *

+ * The javax.sql package provides for the following: + *

    + *
  1. The DataSource interface as an alternative to the + * DriverManager for establishing a + * connection with a data source + *
  2. Connection pooling and Statement pooling + *
  3. Distributed transactions + *
  4. Rowsets + *
+ *

+ * Applications use the DataSource and RowSet + * APIs directly, but the connection pooling and distributed transaction + * APIs are used internally by the middle-tier infrastructure. + * + *

Using a DataSource Object to Make a Connection

+ *

+ * The javax.sql package provides the preferred + * way to make a connection with a data source. The DriverManager + * class, the original mechanism, is still valid, and code using it will + * continue to run. However, the newer DataSource mechanism + * is preferred because it offers many advantages over the + * DriverManager mechanism. + *

+ * These are the main advantages of using a DataSource object to + * make a connection: + *

+ *

+ * Driver vendors provide DataSource implementations. A + * particular DataSource object represents a particular + * physical data source, and each connection the DataSource object + * creates is a connection to that physical data source. + *

+ * A logical name for the data source is registered with a naming service that + * uses the Java Naming and Directory Interface™ + * (JNDI) API, usually by a system administrator or someone performing the + * duties of a system administrator. An application can retrieve the + * DataSource object it wants by doing a lookup on the logical + * name that has been registered for it. The application can then use the + * DataSource object to create a connection to the physical data + * source it represents. + *

+ * A DataSource object can be implemented to work with the + * middle tier infrastructure so that the connections it produces will be + * pooled for reuse. An application that uses such a DataSource + * implementation will automatically get a connection that participates in + * connection pooling. + * A DataSource object can also be implemented to work with the + * middle tier infrastructure so that the connections it produces can be + * used for distributed transactions without any special coding. + * + *

Connection Pooling and Statement Pooling

+ *

+ * Connections made via a DataSource + * 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. + *

+ * 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 DataSource.getConnection method to get the pooled + * connection and uses it the same way it uses any Connection + * object. + *

+ * The classes and interfaces used for connection pooling are: + *

+ * The connection pool manager, a facility in the middle tier of + * a three-tier architecture, uses these classes and interfaces + * behind the scenes. When a ConnectionPoolDataSource object + * is called on to create a PooledConnection object, the + * connection pool manager will register as a ConnectionEventListener + * object with the new PooledConnection object. When the connection + * is closed or there is an error, the connection pool manager (being a listener) + * gets a notification that includes a ConnectionEvent object. + *

+ * If the connection pool manager supports Statement pooling, for + * PreparedStatements, which can be determined by invoking the method + * DatabaseMetaData.supportsStatementPooling, the + * connection pool manager will register as a StatementEventListener + * object with the new PooledConnection object. When the + * PreparedStatement is closed or there is an error, the connection + * pool manager (being a listener) + * gets a notification that includes a StatementEvent object. + * + *

Distributed Transactions

+ *

+ * As with pooled connections, connections made via a DataSource + * object that is implemented to work with the middle tier infrastructure + * may participate in distributed transactions. This gives an application + * the ability to involve data sources on multiple servers in a single + * transaction. + *

+ * The classes and interfaces used for distributed transactions are: + *

+ * These interfaces are used by the transaction manager; an application does + * not use them directly. + *

+ * The XAConnection interface is derived from the + * PooledConnection interface, so what applies to a pooled connection + * also applies to a connection that is part of a distributed transaction. + * A transaction manager in the middle tier handles everything transparently. + * The only change in application code is that an application cannot do anything + * that would interfere with the transaction manager's handling of the transaction. + * Specifically, an application cannot call the methods Connection.commit + * or Connection.rollback, and it cannot set the connection to be in + * auto-commit mode (that is, it cannot call + * Connection.setAutoCommit(true)). + *

+ * An application does not need to do anything special to participate in a + * distributed transaction. + * It simply creates connections to the data sources it wants to use via + * the DataSource.getConnection method, just as it normally does. + * The transaction manager manages the transaction behind the scenes. The + * XADataSource interface creates XAConnection objects, and + * each XAConnection object creates an XAResource object + * that the transaction manager uses to manage the connection. + * + * + *

Rowsets

+ * The RowSet interface works with various other classes and + * interfaces behind the scenes. These can be grouped into three categories. + *
    + *
  1. Event Notification + * + *
  2. Metadata + * + *
  3. The Reader/Writer Facility
    + * A RowSet object that implements the RowSetInternal + * interface can call on the RowSetReader object associated with it + * to populate itself with data. It can also call on the RowSetWriter + * object associated with it to write any changes to its rows back to the + * data source from which it originally got the rows. + * A rowset that remains connected to its data source does not need to use a + * reader and writer because it can simply operate on the data source directly. + * + * + *
+ *

+ * The RowSet interface may be implemented in any number of + * ways, and anyone may write an implementation. Developers are encouraged + * to use their imaginations in coming up with new ways to use rowsets. + * + * + *

Package Specification

+ * + * + * + *

Related Documentation

+ *

+ * The Java Series book published by Addison-Wesley Longman provides detailed + * information about the classes and interfaces in the javax.sql + * package: + * + *

+ */ +package javax.sql;