archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-19 10:34:38 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8187443: Forest Consolidation: Move files to unified layout

Browse source 
Reviewed-by: darcy, ihse
This commit is contained in:
Erik Joelsson 2017-09-12 19:03:39 +02:00
parent 270fe13182
commit 3789983e89
56923 changed files with 3 additions and 15727 deletions
Download patch file Download diff file Expand all files Collapse all files

143
src/java.sql/share/classes/javax/sql/CommonDataSource.java Normal file
View file

@ -0,0 +1,143 @@
/*
* Copyright (c) 2005, 2016, 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.
*/
package javax.sql;
import java.sql.SQLException;
import java.sql.SQLFeatureNotSupportedException;
import java.sql.ShardingKeyBuilder;
import java.util.logging.Logger;
/**
* Interface that defines the methods which are common between <code>DataSource</code>,
* <code>XADataSource</code> and <code>ConnectionPoolDataSource</code>.
*
* @since 1.6
*/
public interface CommonDataSource {
/**
* <p>Retrieves the log writer for this <code>DataSource</code>
* object.
*
* <p>The log writer is a character output stream to which all logging
* and tracing messages for this data source will be
* printed. This includes messages printed by the methods of this
* object, messages printed by methods of other objects manufactured
* by this object, and so on. Messages printed to a data source
* specific log writer are not printed to the log writer associated
* with the <code>java.sql.DriverManager</code> class. When a
* <code>DataSource</code> object is
* created, the log writer is initially null; in other words, the
* default is for logging to be disabled.
*
* @return the log writer for this data source or null if
* logging is disabled
* @exception java.sql.SQLException if a database access error occurs
* @see #setLogWriter
*/
java.io.PrintWriter getLogWriter() throws SQLException;
/**
* <p>Sets the log writer for this <code>DataSource</code>
* object to the given <code>java.io.PrintWriter</code> object.
*
* <p>The log writer is a character output stream to which all logging
* and tracing messages for this data source will be
* printed. This includes messages printed by the methods of this
* object, messages printed by methods of other objects manufactured
* by this object, and so on. Messages printed to a data source-
* specific log writer are not printed to the log writer associated
* with the <code>java.sql.DriverManager</code> class. When a
* <code>DataSource</code> object is created the log writer is
* initially null; in other words, the default is for logging to be
* disabled.
*
* @param out the new log writer; to disable logging, set to null
* @exception SQLException if a database access error occurs
* @see #getLogWriter
*/
void setLogWriter(java.io.PrintWriter out) throws SQLException;
/**
* <p>Sets the maximum time in seconds that this data source will wait
* while attempting to connect to a database. A value of zero
* specifies that the timeout is the default system timeout
* if there is one; otherwise, it specifies that there is no timeout.
* When a <code>DataSource</code> object is created, the login timeout is
* initially zero.
*
* @param seconds the data source login time limit
* @exception SQLException if a database access error occurs.
* @see #getLoginTimeout
*/
void setLoginTimeout(int seconds) throws SQLException;
/**
* Gets the maximum time in seconds that this data source can wait
* while attempting to connect to a database. A value of zero
* means that the timeout is the default system timeout
* if there is one; otherwise, it means that there is no timeout.
* When a <code>DataSource</code> object is created, the login timeout is
* initially zero.
*
* @return the data source login time limit
* @exception SQLException if a database access error occurs.
* @see #setLoginTimeout
*/
int getLoginTimeout() throws SQLException;
//------------------------- JDBC 4.1 -----------------------------------
/**
* Return the parent Logger of all the Loggers used by this data source. This
* should be the Logger farthest from the root Logger that is
* still an ancestor of all of the Loggers used by this data source. Configuring
* this Logger will affect all of the log messages generated by the data source.
* In the worst case, this may be the root Logger.
*
* @return the parent Logger for this data source
* @throws SQLFeatureNotSupportedException if the data source does not use
* {@code java.util.logging}
* @since 1.7
*/
public Logger getParentLogger() throws SQLFeatureNotSupportedException;
//------------------------- JDBC 4.3 -----------------------------------
/**
* Creates a new {@code ShardingKeyBuilder} instance
* @implSpec
* The default implementation will throw a {@code SQLFeatureNotSupportedException}.
* @return The ShardingKeyBuilder instance that was created
* @throws SQLException if an error occurs creating the builder
* @throws SQLFeatureNotSupportedException if the driver does not support this method
* @since 9
* @see ShardingKeyBuilder
*/
default ShardingKeyBuilder createShardingKeyBuilder() throws SQLException {
throw new SQLFeatureNotSupportedException("createShardingKeyBuilder not implemented");
};
}

95
src/java.sql/share/classes/javax/sql/ConnectionEvent.java Normal file
View file

@ -0,0 +1,95 @@
/*
* Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sql;
import java.sql.SQLException;
/**
* <P>An <code>Event</code> object that provides information about the
* source of a connection-related event. <code>ConnectionEvent</code>
* objects are generated when an application closes a pooled connection
* and when an error occurs. The <code>ConnectionEvent</code> object
* contains two kinds of information:
* <UL>
* <LI>The pooled connection closed by the application
* <LI>In the case of an error event, the <code>SQLException</code>
* about to be thrown to the application
* </UL>
*
* @since 1.4
*/
public class ConnectionEvent extends java.util.EventObject {
/**
* <P>Constructs a <code>ConnectionEvent</code> object initialized with
* the given <code>PooledConnection</code> object. <code>SQLException</code>
* defaults to <code>null</code>.
*
* @param con the pooled connection that is the source of the event
* @throws IllegalArgumentException if <code>con</code> is null.
*/
public ConnectionEvent(PooledConnection con) {
super(con);
}
/**
* <P>Constructs a <code>ConnectionEvent</code> object initialized with
* the given <code>PooledConnection</code> object and
* <code>SQLException</code> object.
*
* @param con the pooled connection that is the source of the event
* @param ex the SQLException about to be thrown to the application
* @throws IllegalArgumentException if <code>con</code> is null.
*/
public ConnectionEvent(PooledConnection con, SQLException ex) {
super(con);
this.ex = ex;
}
/**
* <P>Retrieves the <code>SQLException</code> for this
* <code>ConnectionEvent</code> object. May be <code>null</code>.
*
* @return the SQLException about to be thrown or <code>null</code>
*/
public SQLException getSQLException() { return ex; }
/**
* The <code>SQLException</code> that the driver will throw to the
* application when an error occurs and the pooled connection is no
* longer usable.
* @serial
*/
private SQLException ex = null;
/**
* Private serial version unique ID to ensure serialization
* compatibility.
*/
static final long serialVersionUID = -4843217645290030002L;
}

76
src/java.sql/share/classes/javax/sql/ConnectionEventListener.java Normal file
View file

@ -0,0 +1,76 @@
/*
* Copyright (c) 2000, 2001, 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.
*/
package javax.sql;
/**
* <P>
* An object that registers to be notified of events generated by a
* <code>PooledConnection</code> object.
* <P>
* The <code>ConnectionEventListener</code> interface is implemented by a
* connection pooling component. A connection pooling component will
* usually be provided by a JDBC driver vendor or another system software
* vendor. A JDBC driver notifies a <code>ConnectionEventListener</code>
* object when an application is finished using a pooled connection with
* which the listener has registered. The notification
* occurs after the application calls the method <code>close</code> on
* its representation of a <code>PooledConnection</code> object. A
* <code>ConnectionEventListener</code> is also notified when a
* connection error occurs due to the fact that the <code>PooledConnection</code>
* is unfit for future use---the server has crashed, for example.
* The listener is notified by the JDBC driver just before the driver throws an
* <code>SQLException</code> to the application using the
* <code>PooledConnection</code> object.
*
* @since 1.4
*/
public interface ConnectionEventListener extends java.util.EventListener {
/**
* Notifies this <code>ConnectionEventListener</code> that
* the application has called the method <code>close</code> on its
* representation of a pooled connection.
*
* @param event an event object describing the source of
* the event
*/
void connectionClosed(ConnectionEvent event);
/**
* Notifies this <code>ConnectionEventListener</code> that
* a fatal error has occurred and the pooled connection can
* no longer be used. The driver makes this notification just
* before it throws the application the <code>SQLException</code>
* contained in the given <code>ConnectionEvent</code> object.
*
* @param event an event object describing the source of
* the event and containing the <code>SQLException</code> that the
* driver is about to throw
*/
void connectionErrorOccurred(ConnectionEvent event);
}

118
src/java.sql/share/classes/javax/sql/ConnectionPoolDataSource.java Normal file
View file

@ -0,0 +1,118 @@
/*
* Copyright (c) 2000, 2016, 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.
*/
package javax.sql;
import java.sql.SQLException;
import java.sql.SQLFeatureNotSupportedException;
/**
* A factory for <code>PooledConnection</code>
* objects. An object that implements this interface will typically be
* registered with a naming service that is based on the
* Java&trade; Naming and Directory Interface
* (JNDI).
*
* @since 1.4
*/
public interface ConnectionPoolDataSource extends CommonDataSource {
/**
* Attempts to establish a physical database connection that can
* be used as a pooled connection.
*
* @return a <code>PooledConnection</code> object that is a physical
* connection to the database that this
* <code>ConnectionPoolDataSource</code> object represents
* @exception SQLException if a database access error occurs
* @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.4
*/
PooledConnection getPooledConnection() throws SQLException;
/**
* Attempts to establish a physical database connection that can
* be used as a pooled connection.
*
* @param user the database user on whose behalf the connection is being made
* @param password the user's password
* @return a <code>PooledConnection</code> object that is a physical
* connection to the database that this
* <code>ConnectionPoolDataSource</code> object represents
* @exception SQLException if a database access error occurs
* @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.4
*/
PooledConnection getPooledConnection(String user, String password)
throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
java.io.PrintWriter getLogWriter() throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLogWriter(java.io.PrintWriter out) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLoginTimeout(int seconds) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
int getLoginTimeout() throws SQLException;
//------------------------- JDBC 4.3 -----------------------------------
/**
* Creates a new {@code PooledConnectionBuilder} instance
* @implSpec
* The default implementation will throw a {@code SQLFeatureNotSupportedException}.
* @return The ConnectionBuilder instance that was created
* @throws SQLException if an error occurs creating the builder
* @throws SQLFeatureNotSupportedException if the driver does not support sharding
* @since 9
* @see PooledConnectionBuilder
*/
default PooledConnectionBuilder createPooledConnectionBuilder() throws SQLException {
throw new SQLFeatureNotSupportedException("createPooledConnectionBuilder not implemented");
};
}

156
src/java.sql/share/classes/javax/sql/DataSource.java Normal file
View file

@ -0,0 +1,156 @@
/*
* Copyright (c) 2000, 2016, 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.
*/
package javax.sql;
import java.sql.Connection;
import java.sql.ConnectionBuilder;
import java.sql.SQLException;
import java.sql.SQLFeatureNotSupportedException;
import java.sql.Wrapper;
/**
* <p>A factory for connections to the physical data source that this
* {@code DataSource} object represents. An alternative to the
* {@code DriverManager} facility, a {@code DataSource} object
* is the preferred means of getting a connection. An object that implements
* the {@code DataSource} interface will typically be
* registered with a naming service based on the
* Java&trade; Naming and Directory (JNDI) API.
* <P>
* The {@code DataSource} interface is implemented by a driver vendor.
* There are three types of implementations:
* <OL>
* <LI>Basic implementation -- produces a standard {@code Connection}
* object
* <LI>Connection pooling implementation -- produces a {@code Connection}
* object that will automatically participate in connection pooling. This
* implementation works with a middle-tier connection pooling manager.
* <LI>Distributed transaction implementation -- produces a
* {@code Connection} object that may be used for distributed
* transactions and almost always participates in connection pooling.
* This implementation works with a middle-tier
* transaction manager and almost always with a connection
* pooling manager.
* </OL>
* <P>
* A {@code DataSource} object has properties that can be modified
* when necessary. For example, if the data source is moved to a different
* server, the property for the server can be changed. The benefit is that
* because the data source's properties can be changed, any code accessing
* that data source does not need to be changed.
* <P>
* A driver that is accessed via a {@code DataSource} object does not
* register itself with the {@code DriverManager}. Rather, a
* {@code DataSource} object is retrieved through a lookup operation
* and then used to create a {@code Connection} object. With a basic
* implementation, the connection obtained through a {@code DataSource}
* object is identical to a connection obtained through the
* {@code DriverManager} facility.
* <p>
* An implementation of {@code DataSource} must include a public no-arg
* constructor.
*
* @since 1.4
*/
public interface DataSource extends CommonDataSource, Wrapper {
/**
* <p>Attempts to establish a connection with the data source that
* this {@code DataSource} object represents.
*
* @return a connection to the data source
* @exception SQLException if a database access error occurs
* @throws java.sql.SQLTimeoutException when the driver has determined that the
* timeout value specified by the {@code setLoginTimeout} method
* has been exceeded and has at least tried to cancel the
* current database connection attempt
*/
Connection getConnection() throws SQLException;
/**
* <p>Attempts to establish a connection with the data source that
* this {@code DataSource} object represents.
*
* @param username the database user on whose behalf the connection is
* being made
* @param password the user's password
* @return a connection to the data source
* @exception SQLException if a database access error occurs
* @throws java.sql.SQLTimeoutException when the driver has determined that the
* timeout value specified by the {@code setLoginTimeout} method
* has been exceeded and has at least tried to cancel the
* current database connection attempt
* @since 1.4
*/
Connection getConnection(String username, String password)
throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
java.io.PrintWriter getLogWriter() throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLogWriter(java.io.PrintWriter out) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLoginTimeout(int seconds) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
int getLoginTimeout() throws SQLException;
// JDBC 4.3
/**
* Create a new {@code ConnectionBuilder} instance
* @implSpec
* The default implementation will throw a {@code SQLFeatureNotSupportedException}
* @return The ConnectionBuilder instance that was created
* @throws SQLException if an error occurs creating the builder
* @throws SQLFeatureNotSupportedException if the driver does not support sharding
* @since 9
* @see ConnectionBuilder
*/
default ConnectionBuilder createConnectionBuilder() throws SQLException {
throw new SQLFeatureNotSupportedException("createConnectionBuilder not implemented");
};
}

187
src/java.sql/share/classes/javax/sql/PooledConnection.java Normal file
View file

@ -0,0 +1,187 @@
/*
* Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sql;
import java.sql.Connection;
import java.sql.SQLException;
/**
* An object that provides hooks for connection pool management.
* A <code>PooledConnection</code> object
* represents a physical connection to a data source. The connection
* can be recycled rather than being closed when an application is
* finished with it, thus reducing the number of connections that
* need to be made.
* <P>
* An application programmer does not use the <code>PooledConnection</code>
* interface directly; rather, it is used by a middle tier infrastructure
* that manages the pooling of connections.
* <P>
* When an application calls the method <code>DataSource.getConnection</code>,
* it gets back a <code>Connection</code> object. If connection pooling is
* being done, that <code>Connection</code> object is actually a handle to
* a <code>PooledConnection</code> object, which is a physical connection.
* <P>
* The connection pool manager, typically the application server, maintains
* a pool of <code>PooledConnection</code> objects. If there is a
* <code>PooledConnection</code> object available in the pool, the
* connection pool manager returns a <code>Connection</code> object that
* is a handle to that physical connection.
* If no <code>PooledConnection</code> object is available, the
* connection pool manager calls the <code>ConnectionPoolDataSource</code>
* method <code>getPoolConnection</code> to create a new physical connection. The
* JDBC driver implementing <code>ConnectionPoolDataSource</code> creates a
* new <code>PooledConnection</code> object and returns a handle to it.
* <P>
* When an application closes a connection, it calls the <code>Connection</code>
* method <code>close</code>. When connection pooling is being done,
* the connection pool manager is notified because it has registered itself as
* a <code>ConnectionEventListener</code> object using the
* <code>ConnectionPool</code> method <code>addConnectionEventListener</code>.
* The connection pool manager deactivates the handle to
* the <code>PooledConnection</code> object and returns the
* <code>PooledConnection</code> object to the pool of connections so that
* it can be used again. Thus, when an application closes its connection,
* the underlying physical connection is recycled rather than being closed.
* <p>
* If the connection pool manager wraps or provides a proxy to the logical
* handle returned from a call to {@code PoolConnection.getConnection}, the pool
* manager must do one of the following when the connection pool manager
* closes or returns the {@code PooledConnection} to the pool in response to
* the application calling {@code Connection.close}:
* <ul>
* <li>call {@code endRequest} on the logical {@code Connection} handle
* <li>call {@code close} on the logical {@code Connection} handle
* </ul>
* <p>
* The physical connection is not closed until the connection pool manager
* calls the <code>PooledConnection</code> method <code>close</code>.
* This method is generally called to have an orderly shutdown of the server or
* if a fatal error has made the connection unusable.
*
* <p>
* A connection pool manager is often also a statement pool manager, maintaining
* a pool of <code>PreparedStatement</code> objects.
* When an application closes a prepared statement, it calls the
* <code>PreparedStatement</code>
* method <code>close</code>. When <code>Statement</code> pooling is being done,
* the pool manager is notified because it has registered itself as
* a <code>StatementEventListener</code> object using the
* <code>ConnectionPool</code> method <code>addStatementEventListener</code>.
* Thus, when an application closes its <code>PreparedStatement</code>,
* the underlying prepared statement is recycled rather than being closed.
*
* @since 1.4
*/
public interface PooledConnection {
/**
* Creates and returns a <code>Connection</code> object that is a handle
* for the physical connection that
* this <code>PooledConnection</code> object represents.
* The connection pool manager calls this method when an application has
* called the method <code>DataSource.getConnection</code> and there are
* no <code>PooledConnection</code> objects available. See the
* {@link PooledConnection interface description} for more information.
*
* @return a <code>Connection</code> object that is a handle to
* this <code>PooledConnection</code> object
* @exception SQLException if a database access error occurs
* @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.4
*/
Connection getConnection() throws SQLException;
/**
* Closes the physical connection that this <code>PooledConnection</code>
* object represents. An application never calls this method directly;
* it is called by the connection pool module, or manager.
* <P>
* See the {@link PooledConnection interface description} for more
* information.
*
* @exception SQLException if a database access error occurs
* @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.4
*/
void close() throws SQLException;
/**
* Registers the given event listener so that it will be notified
* when an event occurs on this <code>PooledConnection</code> object.
*
* @param listener a component, usually the connection pool manager,
* that has implemented the
* <code>ConnectionEventListener</code> interface and wants to be
* notified when the connection is closed or has an error
* @see #removeConnectionEventListener
*/
void addConnectionEventListener(ConnectionEventListener listener);
/**
* Removes the given event listener from the list of components that
* will be notified when an event occurs on this
* <code>PooledConnection</code> object.
*
* @param listener a component, usually the connection pool manager,
* that has implemented the
* <code>ConnectionEventListener</code> interface and
* been registered with this <code>PooledConnection</code> object as
* a listener
* @see #addConnectionEventListener
*/
void removeConnectionEventListener(ConnectionEventListener listener);
/**
* Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object. Components that
* wish to be notified when <code>PreparedStatement</code>s created by the
* connection are closed or are detected to be invalid may use this method
* to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.
*
* @param listener an component which implements the <code>StatementEventListener</code>
* interface that is to be registered with this <code>PooledConnection</code> object
*
* @since 1.6
*/
public void addStatementEventListener(StatementEventListener listener);
/**
* Removes the specified <code>StatementEventListener</code> from the list of
* components that will be notified when the driver detects that a
* <code>PreparedStatement</code> has been closed or is invalid.
*
* @param listener the component which implements the
* <code>StatementEventListener</code> interface that was previously
* registered with this <code>PooledConnection</code> object
*
* @since 1.6
*/
public void removeStatementEventListener(StatementEventListener listener);
}

105
src/java.sql/share/classes/javax/sql/PooledConnectionBuilder.java Normal file
View file

@ -0,0 +1,105 @@
/*
* Copyright (c) 2016, 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.
*/
package javax.sql;
import java.sql.SQLException;
import java.sql.ShardingKey;
/**
* A builder created from a {@code ConnectionPoolDataSource} object,
* used to establish a connection to the database that the
* {@code data source} object represents. The connection
* properties that were specified for the {@code data source} are used as the
* default values by the {@code PooledConnectionBuilder}.
* <p>The following example illustrates the use of {@code PooledConnectionBuilder}
* to create a {@link XAConnection}:
*
* <pre>{@code
* ConnectionPoolDataSource ds = new MyConnectionPoolDataSource();
* ShardingKey superShardingKey = ds.createShardingKeyBuilder()
* .subkey("EASTERN_REGION", JDBCType.VARCHAR)
* .build();
* ShardingKey shardingKey = ds.createShardingKeyBuilder()
* .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
* .build();
* PooledConnection con = ds.createPooledConnectionBuilder()
* .user("rafa")
* .password("tennis")
* .setShardingKey(shardingKey)
* .setSuperShardingKey(superShardingKey)
* .build();
* }</pre>
*
* @since 9
*
*/
public interface PooledConnectionBuilder {
/**
* Specifies the username to be used when creating a connection
*
* @param username the database user on whose behalf the connection is being
* made
* @return the same {@code PooledConnectionBuilder} instance
*/
PooledConnectionBuilder user(String username);
/**
* Specifies the password to be used when creating a connection
*
* @param password the password to use for this connection. May be {@code null}
* @return the same {@code PooledConnectionBuilder} instance
*/
PooledConnectionBuilder password(String password);
/**
* Specifies a {@code shardingKey} to be used when creating a connection
*
* @param shardingKey the ShardingKey. May be {@code null}
* @return the same {@code PooledConnectionBuilder} instance
* @see java.sql.ShardingKey
* @see java.sql.ShardingKeyBuilder
*/
PooledConnectionBuilder shardingKey(ShardingKey shardingKey);
/**
* Specifies a {@code superShardingKey} to be used when creating a connection
*
* @param superShardingKey the SuperShardingKey. May be {@code null}
* @return the same {@code PooledConnectionBuilder} instance
* @see java.sql.ShardingKey
* @see java.sql.ShardingKeyBuilder
*/
PooledConnectionBuilder superShardingKey(ShardingKey superShardingKey);
/**
* Returns an instance of the object defined by this builder.
*
* @return The built object
* @throws java.sql.SQLException If an error occurs building the object
*/
PooledConnection build() throws SQLException;
}

2193
src/java.sql/share/classes/javax/sql/RowSet.java Normal file
View file

File diff suppressed because it is too large Load diff

62
src/java.sql/share/classes/javax/sql/RowSetEvent.java Normal file
View file

@ -0,0 +1,62 @@
/*
* Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sql;
/**
* An <code>Event</code> object generated when an event occurs to a
* <code>RowSet</code> object. A <code>RowSetEvent</code> object is
* generated when a single row in a rowset is changed, the whole rowset
* is changed, or the rowset cursor moves.
* <P>
* When an event occurs on a <code>RowSet</code> object, one of the
* <code>RowSetListener</code> methods will be sent to all registered
* listeners to notify them of the event. An <code>Event</code> object
* is supplied to the <code>RowSetListener</code> method so that the
* listener can use it to find out which <code>RowSet</code> object is
* the source of the event.
*
* @since 1.4
*/
public class RowSetEvent extends java.util.EventObject {
/**
* Constructs a <code>RowSetEvent</code> object initialized with the
* given <code>RowSet</code> object.
*
* @param source the <code>RowSet</code> object whose data has changed or
* whose cursor has moved
* @throws IllegalArgumentException if <code>source</code> is null.
*/
public RowSetEvent(RowSet source)
{ super(source); }
/**
* Private serial version unique ID to ensure serialization
* compatibility.
*/
static final long serialVersionUID = -1875450876546332005L;
}

103
src/java.sql/share/classes/javax/sql/RowSetInternal.java Normal file
View file

@ -0,0 +1,103 @@
/*
* Copyright (c) 2000, 2001, 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.
*/
package javax.sql;
import java.sql.*;
/**
* The interface that a <code>RowSet</code> object implements in order to
* present itself to a <code>RowSetReader</code> or <code>RowSetWriter</code>
* object. The <code>RowSetInternal</code> interface contains
* methods that let the reader or writer access and modify the internal
* state of the rowset.
*
* @since 1.4
*/
public interface RowSetInternal {
/**
* Retrieves the parameters that have been set for this
* <code>RowSet</code> object's command.
*
* @return an array of the current parameter values for this <code>RowSet</code>
* object's command
* @exception SQLException if a database access error occurs
*/
Object[] getParams() throws SQLException;
/**
* Retrieves the <code>Connection</code> object that was passed to this
* <code>RowSet</code> object.
*
* @return the <code>Connection</code> object passed to the rowset
* or <code>null</code> if none was passed
* @exception SQLException if a database access error occurs
*/
Connection getConnection() throws SQLException;
/**
* Sets the given <code>RowSetMetaData</code> object as the
* <code>RowSetMetaData</code> object for this <code>RowSet</code>
* object. The <code>RowSetReader</code> object associated with the rowset
* will use <code>RowSetMetaData</code> methods to set the values giving
* information about the rowset's columns.
*
* @param md the <code>RowSetMetaData</code> object that will be set with
* information about the rowset's columns
*
* @exception SQLException if a database access error occurs
*/
void setMetaData(RowSetMetaData md) throws SQLException;
/**
* Retrieves a <code>ResultSet</code> object containing the original
* value of this <code>RowSet</code> object.
* <P>
* The cursor is positioned before the first row in the result set.
* Only rows contained in the result set returned by the method
* <code>getOriginal</code> are said to have an original value.
*
* @return the original value of the rowset
* @exception SQLException if a database access error occurs
*/
public ResultSet getOriginal() throws SQLException;
/**
* Retrieves a <code>ResultSet</code> object containing the original value
* of the current row only. If the current row has no original value,
* an empty result set is returned. If there is no current row,
* an exception is thrown.
*
* @return the original value of the current row as a <code>ResultSet</code>
* object
* @exception SQLException if a database access error occurs or this method
* is called while the cursor is on the insert row, before the
* first row, or after the last row
*/
public ResultSet getOriginalRow() throws SQLException;
}

77
src/java.sql/share/classes/javax/sql/RowSetListener.java Normal file
View file

@ -0,0 +1,77 @@
/*
* Copyright (c) 2000, 2001, 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.
*/
package javax.sql;
/**
* An interface that must be implemented by a
* component that wants to be notified when a significant
* event happens in the life of a <code>RowSet</code> object.
* A component becomes a listener by being registered with a
* <code>RowSet</code> object via the method <code>RowSet.addRowSetListener</code>.
* How a registered component implements this interface determines what it does
* when it is notified of an event.
*
* @since 1.4
*/
public interface RowSetListener extends java.util.EventListener {
/**
* Notifies registered listeners that a <code>RowSet</code> object
* in the given <code>RowSetEvent</code> object has changed its entire contents.
* <P>
* The source of the event can be retrieved with the method
* <code>event.getSource</code>.
*
* @param event a <code>RowSetEvent</code> object that contains
* the <code>RowSet</code> object that is the source of the event
*/
void rowSetChanged(RowSetEvent event);
/**
* Notifies registered listeners that a <code>RowSet</code> object
* has had a change in one of its rows.
* <P>
* The source of the event can be retrieved with the method
* <code>event.getSource</code>.
*
* @param event a <code>RowSetEvent</code> object that contains
* the <code>RowSet</code> object that is the source of the event
*/
void rowChanged(RowSetEvent event);
/**
* Notifies registered listeners that a <code>RowSet</code> object's
* cursor has moved.
* <P>
* The source of the event can be retrieved with the method
* <code>event.getSource</code>.
*
* @param event a <code>RowSetEvent</code> object that contains
* the <code>RowSet</code> object that is the source of the event
*/
void cursorMoved(RowSetEvent event);
}

235
src/java.sql/share/classes/javax/sql/RowSetMetaData.java Normal file
View file

@ -0,0 +1,235 @@
/*
* Copyright (c) 2000, 2005, 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.
*/
package javax.sql;
import java.sql.*;
/**
* An object that contains information about the columns in a
* <code>RowSet</code> object. This interface is
* an extension of the <code>ResultSetMetaData</code> interface with
* methods for setting the values in a <code>RowSetMetaData</code> object.
* When a <code>RowSetReader</code> object reads data into a <code>RowSet</code>
* object, it creates a <code>RowSetMetaData</code> object and initializes it
* using the methods in the <code>RowSetMetaData</code> interface. Then the
* reader passes the <code>RowSetMetaData</code> object to the rowset.
* <P>
* The methods in this interface are invoked internally when an application
* calls the method <code>RowSet.execute</code>; an application
* programmer would not use them directly.
*
* @since 1.4
*/
public interface RowSetMetaData extends ResultSetMetaData {
/**
* Sets the number of columns in the <code>RowSet</code> object to
* the given number.
*
* @param columnCount the number of columns in the <code>RowSet</code> object
* @exception SQLException if a database access error occurs
*/
void setColumnCount(int columnCount) throws SQLException;
/**
* Sets whether the designated column is automatically numbered,
* The default is for a <code>RowSet</code> object's
* columns not to be automatically numbered.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property <code>true</code> if the column is automatically
* numbered; <code>false</code> if it is not
*
* @exception SQLException if a database access error occurs
*/
void setAutoIncrement(int columnIndex, boolean property) throws SQLException;
/**
* Sets whether the designated column is case sensitive.
* The default is <code>false</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property <code>true</code> if the column is case sensitive;
* <code>false</code> if it is not
*
* @exception SQLException if a database access error occurs
*/
void setCaseSensitive(int columnIndex, boolean property) throws SQLException;
/**
* Sets whether the designated column can be used in a where clause.
* The default is <code>false</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property <code>true</code> if the column can be used in a
* <code>WHERE</code> clause; <code>false</code> if it cannot
*
* @exception SQLException if a database access error occurs
*/
void setSearchable(int columnIndex, boolean property) throws SQLException;
/**
* Sets whether the designated column is a cash value.
* The default is <code>false</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property <code>true</code> if the column is a cash value;
* <code>false</code> if it is not
*
* @exception SQLException if a database access error occurs
*/
void setCurrency(int columnIndex, boolean property) throws SQLException;
/**
* Sets whether the designated column's value can be set to
* <code>NULL</code>.
* The default is <code>ResultSetMetaData.columnNullableUnknown</code>
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property one of the following constants:
* <code>ResultSetMetaData.columnNoNulls</code>,
* <code>ResultSetMetaData.columnNullable</code>, or
* <code>ResultSetMetaData.columnNullableUnknown</code>
*
* @exception SQLException if a database access error occurs
*/
void setNullable(int columnIndex, int property) throws SQLException;
/**
* Sets whether the designated column is a signed number.
* The default is <code>false</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param property <code>true</code> if the column is a signed number;
* <code>false</code> if it is not
*
* @exception SQLException if a database access error occurs
*/
void setSigned(int columnIndex, boolean property) throws SQLException;
/**
* Sets the designated column's normal maximum width in chars to the
* given <code>int</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param size the normal maximum number of characters for
* the designated column
*
* @exception SQLException if a database access error occurs
*/
void setColumnDisplaySize(int columnIndex, int size) throws SQLException;
/**
* Sets the suggested column title for use in printouts and
* displays, if any, to the given <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param label the column title
* @exception SQLException if a database access error occurs
*/
void setColumnLabel(int columnIndex, String label) throws SQLException;
/**
* Sets the name of the designated column to the given <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param columnName the designated column's name
* @exception SQLException if a database access error occurs
*/
void setColumnName(int columnIndex, String columnName) throws SQLException;
/**
* Sets the name of the designated column's table's schema, if any, to
* the given <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param schemaName the schema name
* @exception SQLException if a database access error occurs
*/
void setSchemaName(int columnIndex, String schemaName) throws SQLException;
/**
* Sets the designated column's number of decimal digits to the
* given <code>int</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param precision the total number of decimal digits
* @exception SQLException if a database access error occurs
*/
void setPrecision(int columnIndex, int precision) throws SQLException;
/**
* Sets the designated column's number of digits to the
* right of the decimal point to the given <code>int</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param scale the number of digits to right of decimal point
* @exception SQLException if a database access error occurs
*/
void setScale(int columnIndex, int scale) throws SQLException;
/**
* Sets the designated column's table name, if any, to the given
* <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param tableName the column's table name
* @exception SQLException if a database access error occurs
*/
void setTableName(int columnIndex, String tableName) throws SQLException;
/**
* Sets the designated column's table's catalog name, if any, to the given
* <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param catalogName the column's catalog name
* @exception SQLException if a database access error occurs
*/
void setCatalogName(int columnIndex, String catalogName) throws SQLException;
/**
* Sets the designated column's SQL type to the one given.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param SQLType the column's SQL type
* @exception SQLException if a database access error occurs
* @see Types
*/
void setColumnType(int columnIndex, int SQLType) throws SQLException;
/**
* Sets the designated column's type name that is specific to the
* data source, if any, to the given <code>String</code>.
*
* @param columnIndex the first column is 1, the second is 2, ...
* @param typeName data source specific type name.
* @exception SQLException if a database access error occurs
*/
void setColumnTypeName(int columnIndex, String typeName) throws SQLException;
}

73
src/java.sql/share/classes/javax/sql/RowSetReader.java Normal file
View file

@ -0,0 +1,73 @@
/*
* Copyright (c) 2000, 2001, 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.
*/
package javax.sql;
import java.sql.*;
/**
* The facility that a disconnected <code>RowSet</code> object calls on
* to populate itself with rows of data. A reader (an object implementing the
* <code>RowSetReader</code> interface) may be registered with
* a <code>RowSet</code> object that supports the reader/writer paradigm.
* When the <code>RowSet</code> object's <code>execute</code> method is
* called, it in turn calls the reader's <code>readData</code> method.
*
* @since 1.4
*/
public interface RowSetReader {
/**
* Reads the new contents of the calling <code>RowSet</code> object.
* In order to call this method, a <code>RowSet</code>
* object must have implemented the <code>RowSetInternal</code> interface
* and registered this <code>RowSetReader</code> object as its reader.
* The <code>readData</code> method is invoked internally
* by the <code>RowSet.execute</code> method for rowsets that support the
* reader/writer paradigm.
*
* <P>The <code>readData</code> method adds rows to the caller.
* It can be implemented in a wide variety of ways and can even
* populate the caller with rows from a nonrelational data source.
* In general, a reader may invoke any of the rowset's methods,
* with one exception. Calling the method <code>execute</code> will
* cause an <code>SQLException</code> to be thrown
* because <code>execute</code> may not be called recursively. Also,
* when a reader invokes <code>RowSet</code> methods, no listeners
* are notified; that is, no <code>RowSetEvent</code> objects are
* generated and no <code>RowSetListener</code> methods are invoked.
* This is true because listeners are already being notified by the method
* <code>execute</code>.
*
* @param caller the <code>RowSet</code> object (1) that has implemented the
* <code>RowSetInternal</code> interface, (2) with which this reader is
* registered, and (3) whose <code>execute</code> method called this reader
* @exception SQLException if a database access error occurs or this method
* invokes the <code>RowSet.execute</code> method
*/
void readData(RowSetInternal caller) throws SQLException;
}

64
src/java.sql/share/classes/javax/sql/RowSetWriter.java Normal file
View file

@ -0,0 +1,64 @@
/*
* Copyright (c) 2000, 2001, 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.
*/
package javax.sql;
import java.sql.*;
/**
* An object that implements the <code>RowSetWriter</code> interface,
* called a <i>writer</i>. A writer may be registered with a <code>RowSet</code>
* object that supports the reader/writer paradigm.
* <P>
* If a disconnected <code>RowSet</code> object modifies some of its data,
* and it has a writer associated with it, it may be implemented so that it
* calls on the writer's <code>writeData</code> method internally
* to write the updates back to the data source. In order to do this, the writer
* must first establish a connection with the rowset's data source.
* <P>
* If the data to be updated has already been changed in the data source, there
* is a conflict, in which case the writer will not write
* the changes to the data source. The algorithm the writer uses for preventing
* or limiting conflicts depends entirely on its implementation.
*
* @since 1.4
*/
public interface RowSetWriter {
/**
* Writes the changes in this <code>RowSetWriter</code> object's
* rowset back to the data source from which it got its data.
*
* @param caller the <code>RowSet</code> object (1) that has implemented the
* <code>RowSetInternal</code> interface, (2) with which this writer is
* registered, and (3) that called this method internally
* @return <code>true</code> if the modified data was written; <code>false</code>
* if not, which will be the case if there is a conflict
* @exception SQLException if a database access error occurs
*/
boolean writeData(RowSetInternal caller) throws SQLException;
}

118
src/java.sql/share/classes/javax/sql/StatementEvent.java Normal file
View file

@ -0,0 +1,118 @@
/*
* Copyright (c) 2005, 2014, 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.
*/
/*
* Created on Apr 28, 2005
*/
package javax.sql;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.util.EventObject;
/**
* A <code>StatementEvent</code> is sent to all <code>StatementEventListener</code>s which were
* registered with a <code>PooledConnection</code>. This occurs when the driver determines that a
* <code>PreparedStatement</code> that is associated with the <code>PooledConnection</code> has been closed or the driver determines
* is invalid.
*
* @since 1.6
*/
public class StatementEvent extends EventObject {
static final long serialVersionUID = -8089573731826608315L;
private SQLException exception;
private PreparedStatement statement;
/**
* Constructs a <code>StatementEvent</code> with the specified <code>PooledConnection</code> and
* <code>PreparedStatement</code>. The <code>SQLException</code> contained in the event defaults to
* null.
*
* @param con The <code>PooledConnection</code> that the closed or invalid
* <code>PreparedStatement</code>is associated with.
* @param statement The <code>PreparedStatement</code> that is being closed or is invalid
*
* @throws IllegalArgumentException if <code>con</code> is null.
*
* @since 1.6
*/
public StatementEvent(PooledConnection con,
PreparedStatement statement) {
super(con);
this.statement = statement;
this.exception = null;
}
/**
* Constructs a <code>StatementEvent</code> with the specified <code>PooledConnection</code>,
* <code>PreparedStatement</code> and <code>SQLException</code>
*
* @param con The <code>PooledConnection</code> that the closed or invalid <code>PreparedStatement</code>
* is associated with.
* @param statement The <code>PreparedStatement</code> that is being closed or is invalid
* @param exception The <code>SQLException </code>the driver is about to throw to
* the application
*
* @throws IllegalArgumentException if <code>con</code> is null.
*
* @since 1.6
*/
public StatementEvent(PooledConnection con,
PreparedStatement statement,
SQLException exception) {
super(con);
this.statement = statement;
this.exception = exception;
}
/**
* Returns the <code>PreparedStatement</code> that is being closed or is invalid
*
* @return The <code>PreparedStatement</code> that is being closed or is invalid
*
* @since 1.6
*/
public PreparedStatement getStatement() {
return this.statement;
}
/**
* Returns the <code>SQLException</code> the driver is about to throw
*
* @return The <code>SQLException</code> the driver is about to throw
*
* @since 1.6
*/
public SQLException getSQLException() {
return this.exception;
}
}

86
src/java.sql/share/classes/javax/sql/StatementEventListener.java Normal file
View file

@ -0,0 +1,86 @@
/*
* Copyright (c) 2005, 2014, 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.
*/
/*
* Created on Apr 28, 2005
*/
package javax.sql;
/**
* An object that registers to be notified of events that occur on PreparedStatements
* that are in the Statement pool.
* <p>
* The JDBC 3.0 specification added the maxStatements
* <code>ConnectionPooledDataSource</code> property to provide a standard mechanism for
* enabling the pooling of <code>PreparedStatements</code>
* and to specify the size of the statement
* pool. However, there was no way for a driver to notify an external
* statement pool when a <code>PreparedStatement</code> becomes invalid. For some databases, a
* statement becomes invalid if a DDL operation is performed that affects the
* table. For example an application may create a temporary table to do some work
* on the table and then destroy it. It may later recreate the same table when
* it is needed again. Some databases will invalidate any prepared statements
* that reference the temporary table when the table is dropped.
* <p>
* Similar to the methods defined in the <code>ConnectionEventListener</code> interface,
* the driver will call the <code>StatementEventListener.statementErrorOccurred</code>
* method prior to throwing any exceptions when it detects a statement is invalid.
* The driver will also call the <code>StatementEventListener.statementClosed</code>
* method when a <code>PreparedStatement</code> is closed.
* <p>
* Methods which allow a component to register a StatementEventListener with a
* <code>PooledConnection</code> have been added to the <code>PooledConnection</code> interface.
*
* @since 1.6
*/
public interface StatementEventListener extends java.util.EventListener{
/**
* The driver calls this method on all <code>StatementEventListener</code>s registered on the connection when it detects that a
* <code>PreparedStatement</code> is closed.
*
* @param event an event object describing the source of
* the event and that the <code>PreparedStatement</code> was closed.
* @since 1.6
*/
void statementClosed(StatementEvent event);
/**
* The driver calls this method on all <code>StatementEventListener</code>s
* registered on the connection when it detects that a
* <code>PreparedStatement</code> is invalid. The driver calls this method
* just before it throws the <code>SQLException</code>,
* contained in the given event, to the application.
*
* @param event an event object describing the source of the event,
* the statement that is invalid and the exception the
* driver is about to throw. The source of the event is
* the <code>PooledConnection</code> which the invalid <code>PreparedStatement</code>
* is associated with.
*
* @since 1.6
*/
void statementErrorOccurred(StatementEvent event);
}

55
src/java.sql/share/classes/javax/sql/XAConnection.java Normal file
View file

@ -0,0 +1,55 @@
/*
* Copyright (c) 2000, 2016, 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.
*/
package javax.sql;
import java.sql.*;
/**
* An object that provides support for distributed transactions. An
* {@code XAConnection} object may be enlisted in a distributed transaction
* by means of an {@code XAResource} object. A transaction manager, usually
* part of a middle tier server, manages an {@code XAConnection} object
* through the {@code XAResource} object.
* <P>
* An application programmer does not use this interface directly; rather, it is
* used by a transaction manager working in the middle tier server.
*
* @since 1.4
*/
public interface XAConnection extends PooledConnection {
/**
* Retrieves an {@code XAResource} object that the transaction manager
* will use to manage this {@code XAConnection} object's participation
* in a distributed transaction.
*
* @return the {@code XAResource} object
* @exception SQLException if a database access error occurs
* @exception SQLFeatureNotSupportedException if the JDBC driver does not
* support this method
* @since 1.4
*/
javax.transaction.xa.XAResource getXAResource() throws SQLException;
}

105
src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java Normal file
View file

@ -0,0 +1,105 @@
/*
* Copyright (c) 2016, 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.
*/
package javax.sql;
import java.sql.SQLException;
import java.sql.ShardingKey;
/**
* A builder created from a {@code XADataSource} object,
* used to establish a connection to the database that the
* {@code data source} object represents. The connection
* properties that were specified for the {@code data source} are used as the
* default values by the {@code XAConnectionBuilder}.
* <p>The following example illustrates the use of {@code XAConnectionBuilder}
* to create a {@link XAConnection}:
*
* <pre>{@code
* XADataSource ds = new MyXADataSource();
* ShardingKey superShardingKey = ds.createShardingKeyBuilder()
* .subkey("EASTERN_REGION", JDBCType.VARCHAR)
* .build();
* ShardingKey shardingKey = ds.createShardingKeyBuilder()
* .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
* .build();
* XAConnection con = ds.createXAConnectionBuilder()
* .user("rafa")
* .password("tennis")
* .setShardingKey(shardingKey)
* .setSuperShardingKey(superShardingKey)
* .build();
* }</pre>
*
* @since 9
*
*/
public interface XAConnectionBuilder {
/**
* Specifies the username to be used when creating a connection
*
* @param username the database user on whose behalf the connection is being
* made
* @return the same {@code XAConnectionBuilder} instance
*/
XAConnectionBuilder user(String username);
/**
* Specifies the password to be used when creating a connection
*
* @param password the password to use for this connection. May be {@code null}
* @return the same {@code XAConnectionBuilder} instance
*/
XAConnectionBuilder password(String password);
/**
* Specifies a {@code shardingKey} to be used when creating a connection
*
* @param shardingKey the ShardingKey. May be {@code null}
* @return the same {@code XAConnectionBuilder} instance
* @see java.sql.ShardingKey
* @see java.sql.ShardingKeyBuilder
*/
XAConnectionBuilder shardingKey(ShardingKey shardingKey);
/**
* Specifies a {@code superShardingKey} to be used when creating a connection
*
* @param superShardingKey the SuperShardingKey. May be {@code null}
* @return the same {@code XAConnectionBuilder} instance
* @see java.sql.ShardingKey
* @see java.sql.ShardingKeyBuilder
*/
XAConnectionBuilder superShardingKey(ShardingKey superShardingKey);
/**
* Returns an instance of the object defined by this builder.
*
* @return The built object
* @throws java.sql.SQLException If an error occurs building the object
*/
XAConnection build() throws SQLException;
}

128
src/java.sql/share/classes/javax/sql/XADataSource.java Normal file
View file

@ -0,0 +1,128 @@
/*
* Copyright (c) 2000, 2016, 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.
*/
package javax.sql;
import java.sql.*;
/**
* A factory for {@code XAConnection} objects that is used internally.
* An object that implements the {@code XADataSource} interface is
* typically registered with a naming service that uses the
* Java Naming and Directory Interface&trade;
* (JNDI).
* <p>
* An implementation of {@code XADataSource} must include a public no-arg
* constructor.
* @since 1.4
*/
public interface XADataSource extends CommonDataSource {
/**
* Attempts to establish a physical database connection that can be
* used in a distributed transaction.
*
* @return an {@code XAConnection} object, which represents a
* physical connection to a data source, that can be used in
* a distributed transaction
* @exception SQLException if a database access error occurs
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @throws SQLTimeoutException when the driver has determined that the
* timeout value specified by the {@code setLoginTimeout} method
* has been exceeded and has at least tried to cancel the
* current database connection attempt
* @since 1.4
*/
XAConnection getXAConnection() throws SQLException;
/**
* Attempts to establish a physical database connection, using the given
* user name and password. The connection that is returned is one that
* can be used in a distributed transaction.
*
* @param user the database user on whose behalf the connection is being made
* @param password the user's password
* @return an {@code XAConnection} object, which represents a
* physical connection to a data source, that can be used in
* a distributed transaction
* @exception SQLException if a database access error occurs
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @throws SQLTimeoutException when the driver has determined that the
* timeout value specified by the {@code setLoginTimeout} method
* has been exceeded and has at least tried to cancel the
* current database connection attempt
* @since 1.4
*/
XAConnection getXAConnection(String user, String password)
throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
java.io.PrintWriter getLogWriter() throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLogWriter(java.io.PrintWriter out) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
void setLoginTimeout(int seconds) throws SQLException;
/**
* {@inheritDoc}
* @since 1.4
*/
@Override
int getLoginTimeout() throws SQLException;
// JDBC 4.3
/**
* Creates a new {@code XAConnectionBuilder} instance
* @implSpec
* The default implementation will throw a {@code SQLFeatureNotSupportedException}.
* @return The XAConnectionBuilder instance that was created
* @throws SQLException if an error occurs creating the builder
* @throws SQLFeatureNotSupportedException if the driver does not support sharding
* @since 9
* @see XAConnectionBuilder
*/
default XAConnectionBuilder createXAConnectionBuilder() throws SQLException {
throw new SQLFeatureNotSupportedException("createXAConnectionBuilder not implemented");
};
}

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

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