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