Chapter 27. The javax.sql Package

The javax.sql package contains the JDBC 2.0 Standard Extension API. The classes and interfaces in this package provide new functionality, such as connection pooling, that do not fall under the scope of the original JDBC API and can therefore be safely packaged separately. The DataSource interface serves as a factory for Connectionobjects; DataSource objects can be registered with a JNDI server, making it possible to get the name of a database from a name service. PooledConnectionsupports connection pooling, which allows an application to handle multiple database connections in a fairly transparent manner. RowSet extends the ResultSetinterface to a JavaBeans component that can be manipulated at design time and used with non-SQL data sources. Figure 27-1 shows the class hierarchy of the javax.sql package.

Figure 27-1. The javax.sql package

ConnectionEvent

JDBC 2.0 Extension

javax.sql

serializable event

Provides information about a pooled connection when an event occurs on the connection. If the event is an error event, ConnectionEvent includes the SQLException that is about to be thrown to the application.

public class ConnectionEvent extends java.util.EventObject {
//	Public Constructors
	public ConnectionEvent (PooledConnection con);
	public ConnectionEvent (PooledConnection con, java.sql.SQLException ex);
//	Public Instance Methods
	public java.sql.SQLException getSQLException ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->ConnectionEvent

Passed To: ConnectionEventListener.{connectionClosed(), connectionErrorOccurred()}

ConnectionEventListener

JDBC 2.0 Extension

javax.sql

event listener

An object that implements ConnectionEventListener registers to receive event notifications from PooledConnection objects. The connectionClosed() method is called when the close() method of the PooledConnection object is called, while the connectionErrorOccurred() method is called immediately before an SQLException is thrown to indicate a fatal error condition (one that renders the connection unusable in the future).

public abstract interface ConnectionEventListener extends java.util.EventListener {
//	Public Instance Methods
	public abstract void connectionClosed (ConnectionEvent event);
	public abstract void connectionErrorOccurred (ConnectionEvent event);
}

Hierarchy: (ConnectionEventListener(java.util.EventListener))

Passed To: PooledConnection.{addConnectionEventListener(), removeConnectionEventListener()}

ConnectionPoolDataSource

JDBC 2.0 Extension

javax.sql

A factory for PooledConnection objects. Can be registered with a JNDI service or used standalone (for example, in a servlet).

public abstract interface ConnectionPoolDataSource {
//	Public Instance Methods
	public abstract int getLoginTimeout () throws java.sql.SQLException;
	public abstract PrintWriter getLogWriter () throws java.sql.SQLException;
	public abstract PooledConnection getPooledConnection () throws java.sql.SQLException;
	public abstract PooledConnection getPooledConnection (String user, String password) throws java.sql.SQLException;
	public abstract void setLoginTimeout (int seconds) throws java.sql.SQLException;
	public abstract void setLogWriter (PrintWriter out) throws java.sql.SQLException;
}

DataSource

JDBC 2.0 Extension

javax.sql

A factory for java.sql.Connection objects. Can be registered with a JNDI service, so that an application can get the name of a database from a name service.

public abstract interface DataSource {
//	Public Instance Methods
	public abstract java.sql.Connection getConnection () throws java.sql.SQLException;
	public abstract java.sql.Connection getConnection (String username, String password) throws java.sql.SQLException;
	public abstract int getLoginTimeout () throws java.sql.SQLException;
	public abstract PrintWriter getLogWriter () throws java.sql.SQLException;
	public abstract void setLoginTimeout (int seconds) throws java.sql.SQLException;
	public abstract void setLogWriter (PrintWriter out) throws java.sql.SQLException;
}

PooledConnection

JDBC 2.0 Extension

javax.sql

PooledConnection provides an application-level hook into the JDBC Standard Extension's connection pooling functionality. Call getConnection() to retrieve a standard java.sql.Connection object for database access from the connection pool. Use close() to return this connection to the pool.

public abstract interface PooledConnection {
//	Event Registration Methods (by event name)
	public abstract void addConnectionEventListener (ConnectionEventListener listener);
	public abstract void removeConnectionEventListener (ConnectionEventListener listener);
//	Public Instance Methods
	public abstract void close () throws java.sql.SQLException;
	public abstract java.sql.Connection getConnection () throws java.sql.SQLException;
}

Implementations: javax.sql.XAConnection

Passed To: ConnectionEvent.ConnectionEvent()

Returned By: ConnectionPoolDataSource.getPooledConnection()

RowSet

JDBC 2.0 Extension

javax.sql

RowSet extends the java.sql.ResultSet interface so that RowSet objects are JavaBeans components and can be manipulated by visual programming tools. A RowSet can be implemented on top of any JDBC-compliant ResultSet. The setCommand() method specifies what data the row set should contain (for a database generated set, this might be an SQL statement).

public abstract interface RowSet extends java.sql.ResultSet {
//	Event Registration Methods (by event name)
	public abstract void addRowSetListener (RowSetListener listener);
	public abstract void removeRowSetListener (RowSetListener listener);
//	Public Instance Methods
	public abstract void clearParameters () throws java.sql.SQLException;
	public abstract void execute () throws java.sql.SQLException;
	public abstract String getCommand ();
	public abstract String getDataSourceName ();
	public abstract boolean getEscapeProcessing () throws java.sql.SQLException;
	public abstract int getMaxFieldSize () throws java.sql.SQLException;
	public abstract int getMaxRows () throws java.sql.SQLException;
	public abstract String getPassword ();
	public abstract int getQueryTimeout () throws java.sql.SQLException;
	public abstract int getTransactionIsolation ();
	public abstract java.util.Map getTypeMap () throws java.sql.SQLException;
	public abstract String getUrl () throws java.sql.SQLException;
	public abstract String getUsername ();
	public abstract boolean isReadOnly ();
	public abstract void setArray (int i, java.sql.Array x) throws java.sql.SQLException;
	public abstract void setAsciiStream (int parameterIndex, java.io.InputStream x, int length) throws java.sql.SQLException;
	public abstract void setBigDecimal (int parameterIndex, java.math.BigDecimal x) throws java.sql.SQLException;
	public abstract void setBinaryStream (int parameterIndex, java.io.InputStream x, int length) throws java.sql.SQLException;
	public abstract void setBlob (int i, java.sql.Blob x) throws java.sql.SQLException;
	public abstract void setBoolean (int parameterIndex, boolean x) throws java.sql.SQLException;
	public abstract void setByte (int parameterIndex, byte x) throws java.sql.SQLException;
	public abstract void setBytes (int parameterIndex, byte[ ] x) throws java.sql.SQLException;
	public abstract void setCharacterStream (int parameterIndex, Reader reader, int length) throws java.sql.SQLException;
	public abstract void setClob (int i, java.sql.Clob x) throws java.sql.SQLException;
	public abstract void setCommand (String cmd) throws java.sql.SQLException;
	public abstract void setConcurrency (int concurrency) throws java.sql.SQLException;
	public abstract void setDataSourceName (String name) throws java.sql.SQLException;
	public abstract void setDate (int parameterIndex, java.sql.Date x) throws java.sql.SQLException;
	public abstract void setDate (int parameterIndex, java.sql.Date x, java.util.Calendar cal) throws java.sql.SQLException;
	public abstract void setDouble (int parameterIndex, double x) throws java.sql.SQLException;
	public abstract void setEscapeProcessing (boolean enable) throws java.sql.SQLException;
	public abstract void setFloat (int parameterIndex, float x) throws java.sql.SQLException;
	public abstract void setInt (int parameterIndex, int x) throws java.sql.SQLException;
	public abstract void setLong (int parameterIndex, long x) throws java.sql.SQLException;
	public abstract void setMaxFieldSize (int max) throws java.sql.SQLException;
	public abstract void setMaxRows (int max) throws java.sql.SQLException;
	public abstract void setNull (int parameterIndex, int sqlType) throws java.sql.SQLException;
	public abstract void setNull (int paramIndex, int sqlType, String typeName) throws java.sql.SQLException;
	public abstract void setObject (int parameterIndex, Object x) throws java.sql.SQLException;
	public abstract void setObject (int parameterIndex, Object x, int targetSqlType) throws java.sql.SQLException;
	public abstract void setObject (int parameterIndex, Object x, int targetSqlType, int scale) throws java.sql.SQLException;
	public abstract void setPassword (String password) throws java.sql.SQLException;
	public abstract void setQueryTimeout (int seconds) throws java.sql.SQLException;
	public abstract void setReadOnly (boolean value) throws java.sql.SQLException;
	public abstract void setRef (int i, java.sql.Ref x) throws java.sql.SQLException;
	public abstract void setShort (int parameterIndex, short x) throws java.sql.SQLException;
	public abstract void setString (int parameterIndex, String x) throws java.sql.SQLException;
	public abstract void setTime (int parameterIndex, java.sql.Time x) throws java.sql.SQLException;
	public abstract void setTime (int parameterIndex, java.sql.Time x, java.util.Calendar cal) throws java.sql.SQLException;
	public abstract void setTimestamp (int parameterIndex, java.sql.Timestamp x) throws java.sql.SQLException;
	public abstract void setTimestamp (int parameterIndex, java.sql.Timestamp x, java.util.Calendar cal) throws java.sql.SQLException;
	public abstract void setTransactionIsolation (int level) throws java.sql.SQLException;
	public abstract void setType (int type) throws java.sql.SQLException;
	public abstract void setTypeMap (java.util.Map map) throws java.sql.SQLException;
	public abstract void setUrl (String url) throws java.sql.SQLException;
	public abstract void setUsername (String name) throws java.sql.SQLException;
}

Hierarchy: (RowSet(java.sql.ResultSet))

Passed To: RowSetEvent.RowSetEvent()

RowSetEvent

JDBC 2.0 Extension

javax.sql

serializable event

Generated when an important event, such as a change in a column's value, occurs within a RowSet.

public class RowSetEvent extends java.util.EventObject {
//	Public Constructors
	public RowSetEvent (RowSet source);
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->RowSetEvent

Passed To: RowSetListener.{cursorMoved(), rowChanged(), rowSetChanged()}

RowSetInternal

JDBC 2.0 Extension

javax.sql

Implemented by a RowSet object that wishes to support the reader/writer row-loading paradigm. Contains additional methods used by RowSetReader and RowSetWriter.

public abstract interface RowSetInternal {
//	Public Instance Methods
	public abstract java.sql.Connection getConnection () throws java.sql.SQLException;
	public abstract java.sql.ResultSet getOriginal () throws java.sql.SQLException;
	public abstract java.sql.ResultSet getOriginalRow () throws java.sql.SQLException;
	public abstract Object[ ] getParams () throws java.sql.SQLException;
	public abstract void setMetaData (RowSetMetaData md) throws java.sql.SQLException;
}

Passed To: RowSetReader.readData(), RowSetWriter.writeData()

RowSetListener

JDBC 2.0 Extension

javax.sql

event listener

Implemented by an object that wishes to be informed of events generated by a RowSet.

public abstract interface RowSetListener extends java.util.EventListener {
//	Public Instance Methods
	public abstract void cursorMoved (RowSetEvent event);
	public abstract void rowChanged (RowSetEvent event);
	public abstract void rowSetChanged (RowSetEvent event);
}

Hierarchy: (RowSetListener(java.util.EventListener))

Passed To: RowSet.{addRowSetListener(), removeRowSetListener()}

RowSetMetaData

JDBC 2.0 Extension

javax.sql

Extends java.sql.ResultSetMetaData to support the functionality of RowSet objects.

public abstract interface RowSetMetaData extends java.sql.ResultSetMetaData {
//	Public Instance Methods
	public abstract void setAutoIncrement (int columnIndex, boolean property) throws java.sql.SQLException;
	public abstract void setCaseSensitive (int columnIndex, boolean property) throws java.sql.SQLException;
	public abstract void setCatalogName (int columnIndex, String catalogName) throws java.sql.SQLException;
	public abstract void setColumnCount (int columnCount) throws java.sql.SQLException;
	public abstract void setColumnDisplaySize (int columnIndex, int size) throws java.sql.SQLException;
	public abstract void setColumnLabel (int columnIndex, String label) throws java.sql.SQLException;
	public abstract void setColumnName (int columnIndex, String columnName) throws java.sql.SQLException;
	public abstract void setColumnType (int columnIndex, int SQLType) throws java.sql.SQLException;
	public abstract void setColumnTypeName (int columnIndex, String typeName) throws java.sql.SQLException;
	public abstract void setCurrency (int columnIndex, boolean property) throws java.sql.SQLException;
	public abstract void setNullable (int columnIndex, int property) throws java.sql.SQLException;
	public abstract void setPrecision (int columnIndex, int precision) throws java.sql.SQLException;
	public abstract void setScale (int columnIndex, int scale) throws java.sql.SQLException;
	public abstract void setSchemaName (int columnIndex, String schemaName) throws java.sql.SQLException;
	public abstract void setSearchable (int columnIndex, boolean property) throws java.sql.SQLException;
	public abstract void setSigned (int columnIndex, boolean property) throws java.sql.SQLException;
	public abstract void setTableName (int columnIndex, String tableName) throws java.sql.SQLException;
}

Hierarchy: (RowSetMetaData(java.sql.ResultSetMetaData))

Passed To: RowSetInternal.setMetaData()

RowSetReader

JDBC 2.0 Extension

javax.sql

Loads data into a RowSet that implements RowSetInternal. The extensions to ResultSet introduced in JDBC 2.0 insert data.

public abstract interface RowSetReader {
//	Public Instance Methods
	public abstract void readData (RowSetInternal caller) throws java.sql.SQLException;
}

RowSetWriter

JDBC 2.0 Extension

javax.sql

Writes data from a RowSet that implements RowSetInternal. The data from the RowSet can be written back to a data source (not necessarily a database).

public abstract interface RowSetWriter {
//	Public Instance Methods
	public abstract boolean writeData (RowSetInternal caller) throws java.sql.SQLException;
}

XAConnection

JDBC 2.0 Extension

javax.sql

An extended version of PooledConnection that can be used in a distributed transaction environment, using the Java Transaction API (in the javax.transaction package).

public abstract interface XAConnection extends PooledConnection {
//	Public Instance Methods
	public abstract javax.transaction.xa.XAResource getXAResource () throws java.sql.SQLException;
}

Hierarchy: (XAConnection(PooledConnection))

Returned By: XADataSource.getXAConnection()

XADataSource

JDBC 2.0 Extension

javax.sql

A factory for XAConnection objects.

public abstract interface XADataSource {
//	Public Instance Methods
	public abstract int getLoginTimeout () throws java.sql.SQLException;
	public abstract PrintWriter getLogWriter () throws java.sql.SQLException;
	public abstract javax.sql.XAConnection getXAConnection () throws java.sql.SQLException;
	public abstract javax.sql.XAConnection getXAConnection (String user, String password) throws java.sql.SQLException;
	public abstract void setLoginTimeout (int seconds) throws java.sql.SQLException;
	public abstract void setLogWriter (PrintWriter out) throws java.sql.SQLException;
}