/** * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * 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 {@code java.sql} * package and, as of the version 1.4 release, is included in the * Java Platform, Standard Edition (Java SE). * It remains an essential part of the Java Platform, Enterprise Edition * (Java EE). *
* The {@code javax.sql} package provides for the following: *
* Applications use the {@code DataSource} and {@code RowSet} * APIs directly, but the connection pooling and distributed transaction * APIs are used internally by the middle-tier infrastructure. * *
* The {@code javax.sql} package provides the preferred * way to make a connection with a data source. The {@code DriverManager} * class, the original mechanism, is still valid, and code using it will * continue to run. However, the newer {@code DataSource} mechanism * is preferred because it offers many advantages over the * {@code DriverManager} mechanism. *
* These are the main advantages of using a {@code DataSource} object to * make a connection: *
* Driver vendors provide {@code DataSource} implementations. A * particular {@code DataSource} object represents a particular * physical data source, and each connection the {@code DataSource} object * creates is a connection to that physical data source. *
* A logical name for the data source is registered with a naming service that * uses the Java Naming and Directory Interface * (JNDI) API, usually by a system administrator or someone performing the * duties of a system administrator. An application can retrieve the * {@code DataSource} object it wants by doing a lookup on the logical * name that has been registered for it. The application can then use the * {@code DataSource} object to create a connection to the physical data * source it represents. *
* A {@code DataSource} object can be implemented to work with the * middle tier infrastructure so that the connections it produces will be * pooled for reuse. An application that uses such a {@code DataSource} * implementation will automatically get a connection that participates in * connection pooling. * A {@code DataSource} object can also be implemented to work with the * middle tier infrastructure so that the connections it produces can be * used for distributed transactions without any special coding. * *
* Connections made via a {@code DataSource} * object that is implemented to work with a middle tier connection pool manager * will participate in connection pooling. This can improve performance * dramatically because creating new connections is very expensive. * 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 {@code DataSource.getConnection} method to get the pooled * connection and uses it the same way it uses any {@code Connection} * object. *
* The classes and interfaces used for connection pooling are: *
* If the connection pool manager supports {@code Statement} pooling, for * {@code PreparedStatements}, which can be determined by invoking the method * {@code DatabaseMetaData.supportsStatementPooling}, the * connection pool manager will register as a {@code StatementEventListener} * object with the new {@code PooledConnection} object. When the * {@code PreparedStatement} is closed or there is an error, the connection * pool manager (being a listener) * gets a notification that includes a {@code StatementEvent} object. * *
* As with pooled connections, connections made via a {@code DataSource} * object that is implemented to work with the middle tier infrastructure * may participate in distributed transactions. This gives an application * the ability to involve data sources on multiple servers in a single * transaction. *
* The classes and interfaces used for distributed transactions are: *
* The {@code XAConnection} interface is derived from the * {@code PooledConnection} interface, so what applies to a pooled connection * also applies to a connection that is part of a distributed transaction. * A transaction manager in the middle tier handles everything transparently. * The only change in application code is that an application cannot do anything * that would interfere with the transaction manager's handling of the transaction. * Specifically, an application cannot call the methods {@code Connection.commit} * or {@code Connection.rollback}, and it cannot set the connection to be in * auto-commit mode (that is, it cannot call * {@code Connection.setAutoCommit(true)}). *
* An application does not need to do anything special to participate in a * distributed transaction. * It simply creates connections to the data sources it wants to use via * the {@code DataSource.getConnection} method, just as it normally does. * The transaction manager manages the transaction behind the scenes. The * {@code XADataSource} interface creates {@code XAConnection} objects, and * each {@code XAConnection} object creates an {@code XAResource} object * that the transaction manager uses to manage the connection. * * *
* When the {@code RowSet} object changes one of its rows, changes all of * it rows, or moves its cursor, it also notifies each listener that is registered * with it. The listener reacts by carrying out its implementation of the * notification method called on it. *
* The {@code RowSetMetaData} interface provides methods for * setting the information about columns, but an application would not * normally use these methods. When an application calls the {@code RowSet} * method {@code execute}, the {@code RowSet} object will contain * a new set of rows, and its {@code RowSetMetaData} object will have been * internally updated to contain information about the new columns. *
* The {@code RowSet} interface may be implemented in any number of * ways, and anyone may write an implementation. Developers are encouraged * to use their imaginations in coming up with new ways to use rowsets. * * *
* The Java Series book published by Addison-Wesley Longman provides detailed * information about the classes and interfaces in the {@code javax.sql} * package: * *