ComputerCourse

java.sql Interface PreparedStatement

2009-01-26T23:40:00.000-08:00

public abstract interface PreparedStatement extends Statement

An object that represents a precompiled SQL statement.

A SQL statement is pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: The setXXX methods for setting IN parameter values must specify types that are compatible with the defined SQL type of the input parameter. For instance, if the IN parameter has SQL type Integer, then the method setInt should be used.

If arbitrary parameter type conversions are required, the method setObject should be used with a target SQL type.
Example of setting a parameter; con is an active connection

PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES
SET SALARY = ? WHERE ID = ?");
pstmt.setBigDecimal(1, 153833.00)
pstmt.setInt(2, 110592)

See Also:
Connection.prepareStatement(java.lang.String), ResultSet

Method Detail

executeQuery

public ResultSet executeQuery() throws SQLException

Executes the SQL query in this PreparedStatement object and returns the result set generated by the query.

Returns:
a ResultSet that contains the data produced by the query; never null
Throws:
SQLException - if a database access error occurs

executeUpdate

public int executeUpdate() throws SQLException

Executes the SQL INSERT, UPDATE or DELETE statement in this PreparedStatement object. In addition, SQL statements that return nothing, such as SQL DDL statements, can be executed.

Returns:
either the row count for INSERT, UPDATE or DELETE statements; or 0 for SQL statements that return nothing
Throws:
SQLException - if a database access error occurs

setNull

public void setNull(int parameterIndex,int sqlType) throws SQLException

Sets the designated parameter to SQL NULL.

Note: You must specify the parameter's SQL type.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
sqlType - the SQL type code defined in java.sql.Types
Throws:
SQLException - if a database access error occurs

setBoolean

public void setBoolean(int parameterIndex,boolean x) throws SQLException

Sets the designated parameter to a Java boolean value. The driver converts this to an SQL BIT value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setByte

public void setByte(int parameterIndex,byte x) throws SQLException

Sets the designated parameter to a Java byte value. The driver converts this to an SQL TINYINT value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setShort

public void setShort(int parameterIndex,short x) throws SQLException

Sets the designated parameter to a Java short value. The driver converts this to an SQL SMALLINT value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setInt

public void setInt(int parameterIndex,int x) throws SQLException

Sets the designated parameter to a Java int value. The driver converts this to an SQL INTEGER value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setLong

public void setLong(int parameterIndex,long x) throws SQLException

Sets the designated parameter to a Java long value. The driver converts this to an SQL BIGINT value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setFloat

public void setFloat(int parameterIndex,float x) throws SQLException

Sets the designated parameter to a Java float value. The driver converts this to an SQL FLOAT value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setDouble

public void setDouble(int parameterIndex,double x) throws SQLException

Sets the designated parameter to a Java double value. The driver converts this to an SQL DOUBLE value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setBigDecimal

public void setBigDecimal(int parameterIndex,BigDecimal x) throws SQLException

Sets the designated parameter to a java.lang.BigDecimal value. The driver converts this to an SQL NUMERIC value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setString

public void setString(int parameterIndex,String x) throws SQLException

Sets the designated parameter to a Java String value. The driver converts this to an SQL VARCHAR or LONGVARCHAR value (depending on the argument's size relative to the driver's limits on VARCHARs) when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setBytes

public void setBytes(int parameterIndex,byte[] x) throws SQLException

Sets the designated parameter to a Java array of bytes. The driver converts this to an SQL VARBINARY or LONGVARBINARY (depending on the argument's size relative to the driver's limits on VARBINARYs) when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setDate

public void setDate(int parameterIndex,Date x) throws SQLException

Sets the designated parameter to a java.sql.Date value. The driver converts this to an SQL DATE value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setTime

public void setTime(int parameterIndex,Time x) throws SQLException

Sets the designated parameter to a java.sql.Time value. The driver converts this to an SQL TIME value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setTimestamp

public void setTimestamp(int parameterIndex,Timestamp x) throws SQLException

Sets the designated parameter to a java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setAsciiStream

public void setAsciiStream(int parameterIndex,InputStream x,int length) throws SQLException

Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the Java input stream that contains the ASCII parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs

setUnicodeStream

public void setUnicodeStream(int parameterIndex,InputStream x,int length)throws SQLException

Deprecated.
Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format. The byte format of the Unicode stream must be Java UTF-8, as defined in the Java Virtual Machine Specification.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java input stream which contains the UNICODE parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs

setBinaryStream

public void setBinaryStream(int parameterIndex,InputStream x,int length) throws SQLException

Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java input stream which contains the binary parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs

clearParameters

public void clearParameters() throws SQLException

Clears the current parameter values immediately.

In general, parameter values remain in force for repeated use of a Statement. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values; this can be done by calling clearParameters.

Throws:
SQLException - if a database access error occurs

setObject

public void setObject(int parameterIndex,Object x,int targetSqlType,int scale)
throws SQLException

Sets the value of a parameter using an object. The second argument must be an object type; for integral values, the java.lang equivalent objects should be used.

The given Java object will be converted to the targetSqlType before being sent to the database. If the object has a custom mapping (is of a class implementing SQLData), the JDBC driver should call its method writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

Note that this method may be used to pass datatabase- specific abstract data types.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
scale - for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, this is the number of digits after the decimal point. For all other types, this value will be ignored.
Throws:
SQLException - if a database access error occurs
See Also:
Types

setObject

public void setObject(int parameterIndex,Object x,int targetSqlType) throws SQLException

Sets the value of the designated parameter with the given object. This method is like setObject above, except that it assumes a scale of zero.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database
Throws:
SQLException - if a database access error occurs

setObject

public void setObject(int parameterIndex,Object x) throws SQLException

Sets the value of a parameter using an object; use the java.lang equivalent objects for integral values.

The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument java object will be converted to the corresponding SQL type before being sent to the database.

Note that this method may be used to pass datatabase- specific abstract data types, by using a Driver-specific Java type. If the object is of a class implementing SQLData, the JDBC driver should call its method writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, then the driver should pass it to the database as a value of the corresponding SQL type. This method throws an exception if there is an ambiguity, for example, if the object is of a class implementing more than one of those interfaces.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the object containing the input parameter value
Throws:
SQLException - if a database access error occurs

execute

public boolean execute() throws SQLException

Executes any kind of SQL statement. Some prepared statements return multiple results; the execute method handles these complex statements as well as the simpler form of statements handled by executeQuery and executeUpdate.

Throws:
SQLException - if a database access error occurs
See Also:
Statement.execute(java.lang.String)

addBatch

public void addBatch() throws SQLException

JDBC 2.0 Adds a set of parameters to the batch.

Throws:
SQLException - if a database access error occurs
See Also:
Statement.addBatch(java.lang.String)

setCharacterStream

public void setCharacterStream(int parameterIndex,Reader reader,int length) throws SQLException

JDBC 2.0 Sets the designated parameter to the given Reader object, which is the given number of characters long. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java reader which contains the UNICODE data
length - the number of characters in the stream
Throws:
SQLException - if a database access error occurs

setRef

public void setRef(int i,Ref x) throws SQLException

JDBC 2.0 Sets a REF() parameter.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing data of an SQL REF Type
Throws:
SQLException - if a database access error occurs

setBlob

public void setBlob(int i,Blob x) throws SQLException

JDBC 2.0 Sets a BLOB parameter.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing a BLOB
Throws:
SQLException - if a database access error occurs

setClob

public void setClob(int i,Clob x) throws SQLException

JDBC 2.0 Sets a CLOB parameter.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing a CLOB
Throws:
SQLException - if a database access error occurs

setArray

public void setArray(int i,Array x) throws SQLException

JDBC 2.0 Sets an Array parameter.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing an SQL array
Throws:
SQLException - if a database access error occurs

getMetaData

public ResultSetMetaData getMetaData() throws SQLException

JDBC 2.0 Gets the number, types and properties of a ResultSet's columns.

Returns:
the description of a ResultSet's columns
Throws:
SQLException - if a database access error occurs

setDate

public void setDate(int parameterIndex,Date x,Calendar cal) throws SQLException

JDBC 2.0 Sets the designated parameter to a java.sql.Date value, using the given Calendar object. The driver uses the Calendar object to construct an SQL DATE, which the driver then sends to the database. With a a Calendar object, the driver can calculate the date taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the Calendar object the driver will use to construct the date
Throws:
SQLException - if a database access error occurs

setTime

public void setTime(int parameterIndex,Time x,Calendar cal) throws SQLException

JDBC 2.0 Sets the designated parameter to a java.sql.Time value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIME, which the driver then sends to the database. With a a Calendar object, the driver can calculate the time taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the Calendar object the driver will use to construct the time
Throws:
SQLException - if a database access error occurs

setTimestamp

public void setTimestamp(int parameterIndex,Timestamp x,Calendar cal) throws SQLException

JDBC 2.0 Sets the designated parameter to a java.sql.Timestamp value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIMESTAMP, which the driver then sends to the database. With a a Calendar object, the driver can calculate the timestamp taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the Calendar object the driver will use to construct the timestamp
Throws:
SQLException - if a database access error occurs

setNull

public void setNull(int paramIndex,int sqlType,String typeName) throws SQLException

JDBC 2.0 Sets the designated parameter to SQL NULL. This version of setNull should be used for user-named types and REF type parameters. Examples of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and named array types.

Note: To be portable, applications must give the SQL type code and the fully-qualified SQL type name when specifying a NULL user-defined or REF parameter. In the case of a user-named type the name is the type name of the parameter itself. For a REF parameter the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information, it may ignore it. Although it is intended for user-named and Ref parameters, this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-named or REF type, the given typeName is ignored.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
sqlType - a value from java.sql.Types
typeName - the fully-qualified name of an SQL user-named type, ignored if the parameter is not a user-named type or REF
Throws:
SQLException - if a database access error occurs

javax.servlet - Interface ServletRequest

2009-01-26T06:13:00.000-08:00

Method Detail

getAttribute

public Object getAttribute(String name)

Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.

Attributes can be set two ways. The servlet container may set attributes to make available custom information about a request. For example, for requests made using HTTPS, the attribute javax.servlet.request.X509Certificate can be used to retrieve information on the certificate of the client. Attributes can also be set programatically using setAttribute(java.lang.String, java.lang.Object). This allows information to be embedded into a request before a RequestDispatcher call.

Attribute names should follow the same conventions as package names. This specification reserves names matching java.*, javax.*, and sun.*.

Parameters:
name - a String specifying the name of the attribute
Returns:
an Object containing the value of the attribute, or null if the attribute does not exist

getAttributeNames

public Enumeration getAttributeNames()

Returns an Enumeration containing the names of the attributes available to this request. This method returns an empty Enumeration if the request has no attributes available to it.

Returns:
an Enumeration of strings containing the names of the request's attributes

getCharacterEncoding

public String getCharacterEncoding()

Returns the name of the character encoding used in the body of this request. This method returns null if the request does not specify a character encoding

Returns:
a String containing the name of the chararacter encoding, or null if the request does not specify a character encoding

setCharacterEncoding

public void setCharacterEncoding(String env)
throws UnsupportedEncodingException

Overrides the name of the character encoding used in the body of this request. This method must be called prior to reading request parameters or reading input using getReader().

Parameters:
env - a String containing the name of the chararacter encoding.
Throws:
UnsupportedEncodingException - if this is not a valid encoding

getContentLength

public int getContentLength()

Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.

Returns:
an integer containing the length of the request body or -1 if the length is not known

getContentType

public String getContentType()

Returns the MIME type of the body of the request, or null if the type is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_TYPE.

Returns:
a String containing the name of the MIME type of the request, or null if the type is not known

getInputStream

public ServletInputStream getInputStream()
throws IOException

Retrieves the body of the request as binary data using a ServletInputStream. Either this method or getReader() may be called to read the body, not both.

Returns:
a ServletInputStream object containing the body of the request
Throws:
IllegalStateException - if the getReader() method has already been called for this request
IOException - if an input or output exception occurred

getParameter

public String getParameter(String name)

Returns the value of a request parameter as a String, or null if the parameter does not exist. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getParameterValues(java.lang.String).

If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterValues.

If the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getInputStream() or getReader() can interfere with the execution of this method.

Parameters:
name - a String specifying the name of the parameter
Returns:
a String representing the single value of the parameter
See Also:
getParameterValues(java.lang.String)

getParameterNames

public Enumeration getParameterNames()

Returns an Enumeration of String objects containing the names of the parameters contained in this request. If the request has no parameters, the method returns an empty Enumeration.

Returns:
an Enumeration of String objects, each String containing the name of a request parameter; or an empty Enumeration if the request has no parameters

getParameterValues

public String[] getParameterValues(String name)

Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.

If the parameter has a single value, the array has a length of 1.

Parameters:
name - a String containing the name of the parameter whose value is requested
Returns:
an array of String objects containing the parameter's values
See Also:
getParameter(java.lang.String)

getParameterMap

public Map getParameterMap()

Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

Returns:
an immutable java.util.Map containing parameter names as keys and parameter values as map values. The keys in the parameter map are of type String. The values in the parameter map are of type String array.

getProtocol

public String getProtocol()

Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1. For HTTP servlets, the value returned is the same as the value of the CGI variable SERVER_PROTOCOL.

Returns:
a String containing the protocol name and version number

getScheme

public String getScheme()

Returns the name of the scheme used to make this request, for example, http, https, or ftp. Different schemes have different rules for constructing URLs, as noted in RFC 1738.

Returns:
a String containing the name of the scheme used to make this request

getServerName

public String getServerName()

Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the Host header, if any, or the resolved server name, or the server IP address.

Returns:
a String containing the name of the server

getServerPort

public int getServerPort()

Returns the port number to which the request was sent. It is the value of the part after ":" in the Host header, if any, or the server port where the client connection was accepted on.

Returns:
an integer specifying the port number

getReader

public BufferedReader getReader()
throws IOException

Retrieves the body of the request as character data using a BufferedReader. The reader translates the character data according to the character encoding used on the body. Either this method or getInputStream() may be called to read the body, not both.

Returns:
a BufferedReader containing the body of the request
Throws:
UnsupportedEncodingException - if the character set encoding used is not supported and the text cannot be decoded
IllegalStateException - if getInputStream() method has been called on this request
IOException - if an input or output exception occurred
See Also:
getInputStream()

getRemoteAddr

public String getRemoteAddr()

Returns the Internet Protocol (IP) address of the client or last proxy that sent the request. For HTTP servlets, same as the value of the CGI variable REMOTE_ADDR.

Returns:
a String containing the IP address of the client that sent the request

getRemoteHost

public String getRemoteHost()

Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address. For HTTP servlets, same as the value of the CGI variable REMOTE_HOST.

Returns:
a String containing the fully qualified name of the client

setAttribute

public void setAttribute(String name,Object o)

Stores an attribute in this request. Attributes are reset between requests. This method is most often used in conjunction with RequestDispatcher.

Attribute names should follow the same conventions as package names. Names beginning with java.*, javax.*, and com.sun.*, are reserved for use by Sun Microsystems.
If the object passed in is null, the effect is the same as calling removeAttribute(java.lang.String).

Parameters:
name - a String specifying the name of the attribute
o - the Object to be stored

removeAttribute

public void removeAttribute(String name)

Removes an attribute from this request. This method is not generally needed as attributes only persist as long as the request is being handled.

Attribute names should follow the same conventions as package names. Names beginning with java.*, javax.*, and com.sun.*, are reserved for use by Sun Microsystems.

Parameters:
name - a String specifying the name of the attribute to remove

getLocale

public Locale getLocale()

Returns the preferred Locale that the client will accept content in, based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.

Returns:
the preferred Locale for the client

getLocales

public Enumeration getLocales()

Returns an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns an Enumeration containing one Locale, the default locale for the server.

Returns:
an Enumeration of preferred Locale objects for the client

isSecure

public boolean isSecure()

Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.

Returns:
a boolean indicating if the request was made using a secure channel

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(String path)

Returns a RequestDispatcher object that acts as a wrapper for the resource located at the given path. A RequestDispatcher object can be used to forward a request to the resource or to include the resource in a response. The resource can be dynamic or static.

The pathname specified may be relative, although it cannot extend outside the current servlet context. If the path begins with a "/" it is interpreted as relative to the current context root. This method returns null if the servlet container cannot return a RequestDispatcher.

The difference between this method and ServletContext.getRequestDispatcher(java.lang.String) is that this method can take a relative path.

Parameters:
path - a String specifying the pathname to the resource. If it is relative, it must be relative against the current servlet.
Returns:
a RequestDispatcher object that acts as a wrapper for the resource at the specified path, or null if the servlet container cannot return a RequestDispatcher
See Also:
RequestDispatcher, ServletContext.getRequestDispatcher(java.lang.String)

getRealPath

public String getRealPath(String path)

Deprecated. As of Version 2.1 of the Java Servlet API, use ServletContext.getRealPath(java.lang.String) instead.

getRemotePort

public int getRemotePort()

Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.

Since:
2.4

getLocalName

public String getLocalName()

Returns the host name of the Internet Protocol (IP) interface on which the request was received.

Returns:
a String containing the host name of the IP on which the request was received.
Since:
2.4

getLocalAddr

public String getLocalAddr()

Returns the Internet Protocol (IP) address of the interface on which the request was received.

Returns:
a String containing the IP address on which the request was received.
Since:
2.4

getLocalPort

public int getLocalPort()

Returns the Internet Protocol (IP) port number of the interface on which the request was received.

Returns:
an integer specifying the port number
Since:
2.4

Input-Stream Figure

2008-12-17T04:24:00.000-08:00

API of Frame Class

2008-11-27T10:08:00.000-08:00

java.awt
Class Frame

java.lang.Object
 java.awt.Component
     java.awt.Container
         java.awt.Window
             java.awt.Frame

All Implemented Interfaces:: ImageObserver, MenuContainer, Serializable, Accessible

Direct Known Subclasses:: JFrame

public class Frame
extends Window
implements MenuContainer
extends Window
implements MenuContainer

A Frame is a top-level window with a title and a border.

The size of the frame includes any area designated for the border. The dimensions of the border area may be obtained using the getInsets method, however, since these dimensions are platform-dependent, a valid insets value cannot be obtained until the frame is made displayable by either calling pack or show. Since the border area is included in the overall size of the frame, the border effectively obscures a portion of the frame, constraining the area available for rendering and/or displaying subcomponents to the rectangle which has an upper-left corner location of (insets.left, insets.top), and has a size of width - (insets.left + insets.right) by height - (insets.top + insets.bottom).

The default layout for a frame is BorderLayout.

A frame may have its native decorations (i.e. Frame and Titlebar) turned off with setUndecorated. This can only be done while the frame is not displayable.

In a multi-screen environment, you can create a Frame on a different screen device by constructing the Frame with Frame(GraphicsConfiguration) or Frame(String title, GraphicsConfiguration). The GraphicsConfiguration object is one of the GraphicsConfiguration objects of the target screen device.

In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, the bounds of all configurations are relative to the virtual-coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device, negative coordinates are possible, as shown in the following figure.

In such an environment, when calling setLocation, you must pass a virtual coordinate to this method. Similarly, calling getLocationOnScreen on a Frame returns virtual device coordinates. Call the getBounds method of a GraphicsConfiguration to find its origin in the virtual coordinate system.

The following code sets the location of the Frame at (10, 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration. If the bounds of the GraphicsConfiguration is not taken into account, the Frame location would be set at (10, 10) relative to the virtual-coordinate system and would appear on the primary physical screen, which might be different from the physical screen of the specified GraphicsConfiguration.

      Frame f = new Frame(GraphicsConfiguration gc);
     Rectangle bounds = gc.getBounds();
     f.setLocation(10 + bounds.x, 10 + bounds.y);

Frames are capable of generating the following types of WindowEvents:

WINDOW_OPENED
WINDOW_CLOSING:
If the program doesn't explicitly hide or dispose the window while processing this event, the window close operation is canceled.
WINDOW_CLOSED
WINDOW_ICONIFIED
WINDOW_DEICONIFIED
WINDOW_ACTIVATED
WINDOW_DEACTIVATED
WINDOW_GAINED_FOCUS
WINDOW_LOST_FOCUS
WINDOW_STATE_CHANGED

Since:: JDK1.0
See Also:: WindowEvent, Window.addWindowListener(java.awt.event.WindowListener), Serialized Form

Nested Class Summary
`protected class`	`Frame.AccessibleAWTFrame` This class implements accessibility support for the `Frame` class.

Nested classes/interfaces inherited from class java.awt.Window
`Window.AccessibleAWTWindow`

Nested classes/interfaces inherited from class java.awt.Container
`Container.AccessibleAWTContainer`

Nested classes/interfaces inherited from class java.awt.Component
`Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy`

Field Summary
`static int`	`CROSSHAIR_CURSOR` Deprecated. replaced by `Cursor.CROSSHAIR_CURSOR`.
`static int`	`DEFAULT_CURSOR` Deprecated. replaced by `Cursor.DEFAULT_CURSOR`.
`static int`	`E_RESIZE_CURSOR` Deprecated. replaced by `Cursor.E_RESIZE_CURSOR`.
`static int`	`HAND_CURSOR` Deprecated. replaced by `Cursor.HAND_CURSOR`.
`static int`	`ICONIFIED` This state bit indicates that frame is iconified.
`static int`	`MAXIMIZED_BOTH` This state bit mask indicates that frame is fully maximized (that is both horizontally and vertically).
`static int`	`MAXIMIZED_HORIZ` This state bit indicates that frame is maximized in the horizontal direction.
`static int`	`MAXIMIZED_VERT` This state bit indicates that frame is maximized in the vertical direction.
`static int`	`MOVE_CURSOR` Deprecated. replaced by `Cursor.MOVE_CURSOR`.
`static int`	`N_RESIZE_CURSOR` Deprecated. replaced by `Cursor.N_RESIZE_CURSOR`.
`static int`	`NE_RESIZE_CURSOR` Deprecated. replaced by `Cursor.NE_RESIZE_CURSOR`.
`static int`	`NORMAL` Frame is in the "normal" state.
`static int`	`NW_RESIZE_CURSOR` Deprecated. replaced by `Cursor.NW_RESIZE_CURSOR`.
`static int`	`S_RESIZE_CURSOR` Deprecated. replaced by `Cursor.S_RESIZE_CURSOR`.
`static int`	`SE_RESIZE_CURSOR` Deprecated. replaced by `Cursor.SE_RESIZE_CURSOR`.
`static int`	`SW_RESIZE_CURSOR` Deprecated. replaced by `Cursor.SW_RESIZE_CURSOR`.
`static int`	`TEXT_CURSOR` Deprecated. replaced by `Cursor.TEXT_CURSOR`.
`static int`	`W_RESIZE_CURSOR` Deprecated. replaced by `Cursor.W_RESIZE_CURSOR`.
`static int`	`WAIT_CURSOR` Deprecated. replaced by `Cursor.WAIT_CURSOR`.

Fields inherited from class java.awt.Component
`BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

Fields inherited from interface java.awt.image.ImageObserver
`ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

Constructor Summary
`Frame()` Constructs a new instance of `Frame` that is initially invisible.
`Frame(GraphicsConfiguration gc)` Create a `Frame` with the specified `GraphicsConfiguration` of a screen device.
`Frame(String title)` Constructs a new, initially invisible `Frame` object with the specified title.
`Frame(String title, GraphicsConfiguration gc)` Constructs a new, initially invisible `Frame` object with the specified title and a `GraphicsConfiguration`.

Method Summary
`void`	`addNotify()` Makes this Frame displayable by connecting it to a native screen resource.
`protected void`	`finalize()` Disposes of the input methods and context, and removes this Frame from the AppContext.
`AccessibleContext`	`getAccessibleContext()` Gets the AccessibleContext associated with this Frame.
`int`	`getCursorType()` Deprecated. As of JDK version 1.1, replaced by `Component.getCursor()`.
`int`	`getExtendedState()` Gets the state of this frame.
`static Frame[]`	`getFrames()` Returns an array containing all Frames created by the application.
`Image`	`getIconImage()` Gets the image to be displayed in the minimized icon for this frame.
`Rectangle`	`getMaximizedBounds()` Gets maximized bounds for this frame.
`MenuBar`	`getMenuBar()` Gets the menu bar for this frame.
`int`	`getState()` Gets the state of this frame (obsolete).
`String`	`getTitle()` Gets the title of the frame.
`boolean`	`isResizable()` Indicates whether this frame is resizable by the user.
`boolean`	`isUndecorated()` Indicates whether this frame is undecorated.
`protected String`	`paramString()` Returns a string representing the state of this `Frame`.
`void`	`remove(MenuComponent m)` Removes the specified menu bar from this frame.
`void`	`removeNotify()` Makes this Frame undisplayable by removing its connection to its native screen resource.
`void`	`setCursor(int cursorType)` Deprecated. As of JDK version 1.1, replaced by `Component.setCursor(Cursor)`.
`void`	`setExtendedState(int state)` Sets the state of this frame.
`void`	`setIconImage(Image image)` Sets the image to be displayed in the minimized icon for this frame.
`void`	`setMaximizedBounds(Rectangle bounds)` Sets the maximized bounds for this frame.
`void`	`setMenuBar(MenuBar mb)` Sets the menu bar for this frame to the specified menu bar.
`void`	`setResizable(boolean resizable)` Sets whether this frame is resizable by the user.
`void`	`setState(int state)` Sets the state of this frame (obsolete).
`void`	`setTitle(String title)` Sets the title for this frame to the specified string.
`void`	`setUndecorated(boolean undecorated)` Disables or enables decorations for this frame.

Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getInputContext, getListeners, getLocale, getMostRecentFocusOwner, getOwnedWindows, getOwner, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, setAlwaysOnTop, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setLocationByPlatform, setLocationRelativeTo, show, toBack, toFront

Methods inherited from class java.awt.Window

addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getInputContext, getListeners, getLocale, getMostRecentFocusOwner, getOwnedWindows, getOwner, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, setAlwaysOnTop, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setLocationByPlatform, setLocationRelativeTo, show, toBack, toFront

Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree

Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.awt.MenuContainer
`getFont, postEvent`

Field Detail

DEFAULT_CURSOR

@Deprecated
public static final int DEFAULT_CURSOR

Deprecated. replaced by Cursor.DEFAULT_CURSOR.

See Also:: Constant Field Values

CROSSHAIR_CURSOR

@Deprecated
public static final int CROSSHAIR_CURSOR

Deprecated. replaced by Cursor.CROSSHAIR_CURSOR.

See Also:: Constant Field Values

TEXT_CURSOR

@Deprecated
public static final int TEXT_CURSOR

Deprecated. replaced by Cursor.TEXT_CURSOR.

See Also:: Constant Field Values

WAIT_CURSOR

@Deprecated
public static final int WAIT_CURSOR

Deprecated. replaced by Cursor.WAIT_CURSOR.

See Also:: Constant Field Values

SW_RESIZE_CURSOR

@Deprecated
public static final int SW_RESIZE_CURSOR

Deprecated. replaced by Cursor.SW_RESIZE_CURSOR.

See Also:: Constant Field Values

SE_RESIZE_CURSOR

@Deprecated
public static final int SE_RESIZE_CURSOR

Deprecated. replaced by Cursor.SE_RESIZE_CURSOR.

See Also:: Constant Field Values

NW_RESIZE_CURSOR

@Deprecated
public static final int NW_RESIZE_CURSOR

Deprecated. replaced by Cursor.NW_RESIZE_CURSOR.

See Also:: Constant Field Values

NE_RESIZE_CURSOR

@Deprecated
public static final int NE_RESIZE_CURSOR

Deprecated. replaced by Cursor.NE_RESIZE_CURSOR.

See Also:: Constant Field Values

N_RESIZE_CURSOR

@Deprecated
public static final int N_RESIZE_CURSOR

Deprecated. replaced by Cursor.N_RESIZE_CURSOR.

See Also:: Constant Field Values

S_RESIZE_CURSOR

@Deprecated
public static final int S_RESIZE_CURSOR

Deprecated. replaced by Cursor.S_RESIZE_CURSOR.

See Also:: Constant Field Values

W_RESIZE_CURSOR

@Deprecated
public static final int W_RESIZE_CURSOR

Deprecated. replaced by Cursor.W_RESIZE_CURSOR.

See Also:: Constant Field Values

E_RESIZE_CURSOR

@Deprecated
public static final int E_RESIZE_CURSOR

Deprecated. replaced by Cursor.E_RESIZE_CURSOR.

See Also:: Constant Field Values

HAND_CURSOR

@Deprecated
public static final int HAND_CURSOR

Deprecated. replaced by Cursor.HAND_CURSOR.

See Also:: Constant Field Values

MOVE_CURSOR

@Deprecated
public static final int MOVE_CURSOR

Deprecated. replaced by Cursor.MOVE_CURSOR.

See Also:: Constant Field Values

NORMAL

public static final int NORMAL

Frame is in the "normal" state. This symbolic constant names a frame state with all state bits cleared.

See Also:: setExtendedState(int), getExtendedState(), Constant Field Values

ICONIFIED

public static final int ICONIFIED

This state bit indicates that frame is iconified.

See Also:: setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_HORIZ

public static final int MAXIMIZED_HORIZ

This state bit indicates that frame is maximized in the horizontal direction.

Since:: 1.4
See Also:: setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_VERT

public static final int MAXIMIZED_VERT

This state bit indicates that frame is maximized in the vertical direction.

Since:: 1.4
See Also:: setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_BOTH

public static final int MAXIMIZED_BOTH

This state bit mask indicates that frame is fully maximized (that is both horizontally and vertically). It is just a convenience alias for MAXIMIZED_VERT | MAXIMIZED_HORIZ.

Note that the correct test for frame being fully maximized is

     (state & Frame.MAXIMIZED_BOTH) == Frame.MAXIMIZED_BOTH

To test is frame is maximized in some direction use

     (state & Frame.MAXIMIZED_BOTH) != 0

Since:: 1.4
See Also:: setExtendedState(int), getExtendedState(), Constant Field Values

Constructor Detail

Frame

public Frame()
     throws HeadlessException

Constructs a new instance of Frame that is initially invisible. The title of the Frame is empty.

Throws:: HeadlessException - when GraphicsEnvironment.isHeadless() returns true
See Also:: GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean)

Frame

public Frame(GraphicsConfiguration gc)

Create a Frame with the specified GraphicsConfiguration of a screen device.

Parameters:: gc - the GraphicsConfiguration of the target screen device. If gc is null, the system default GraphicsConfiguration is assumed.
Throws:: IllegalArgumentException - if gc is not from a screen device. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
Since:: 1.3
See Also:: GraphicsEnvironment.isHeadless()

Frame

public Frame(String title)
     throws HeadlessException

Constructs a new, initially invisible Frame object with the specified title.

Parameters:: title - the title to be displayed in the frame's border. A null value is treated as an empty string, "".
Throws:: HeadlessException - when GraphicsEnvironment.isHeadless() returns true
See Also:: GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean), GraphicsConfiguration.getBounds()

Frame

public Frame(String title,
            GraphicsConfiguration gc)

Constructs a new, initially invisible Frame object with the specified title and a GraphicsConfiguration.

Parameters:: title - the title to be displayed in the frame's border. A null value is treated as an empty string, "".; gc - the GraphicsConfiguration of the target screen device. If gc is null, the system default GraphicsConfiguration is assumed.
Throws:: IllegalArgumentException - if gc is not from a screen device. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
See Also:: GraphicsEnvironment.isHeadless(), Component.setSize(int, int), Component.setVisible(boolean), GraphicsConfiguration.getBounds()

Method Detail

finalize

protected void finalize()
                throws Throwable

Disposes of the input methods and context, and removes this Frame from the AppContext. Subclasses that override this method should call super.finalize().

Overrides:: finalize in class Window

Throws:: Throwable - the Exception raised by this method

addNotify

public void addNotify()

Makes this Frame displayable by connecting it to a native screen resource. Making a frame displayable will cause any of its children to be made displayable. This method is called internally by the toolkit and should not be called directly by programs.

Overrides:: addNotify in class Window

See Also:: Component.isDisplayable(), removeNotify()

getTitle

public String getTitle()

Gets the title of the frame. The title is displayed in the frame's border.

Returns:: the title of this frame, or an empty string ("") if this frame doesn't have a title.
See Also:: setTitle(String)

setTitle

public void setTitle(String title)

Sets the title for this frame to the specified string.

Parameters:: title - the title to be displayed in the frame's border. A null value is treated as an empty string, "".
See Also:: getTitle()

getIconImage

public Image getIconImage()

Gets the image to be displayed in the minimized icon for this frame.

Returns:: the icon image for this frame, or null if this frame doesn't have an icon image.
See Also:: setIconImage(Image)

setIconImage

public void setIconImage(Image image)

Sets the image to be displayed in the minimized icon for this frame. Not all platforms support the concept of minimizing a window.

Parameters:: image - the icon image to be displayed. If this parameter is null then the icon image is set to the default image, which may vary with platform.
See Also:: getIconImage()

getMenuBar

public MenuBar getMenuBar()

Gets the menu bar for this frame.

Returns:: the menu bar for this frame, or null if this frame doesn't have a menu bar.
See Also:: setMenuBar(MenuBar)

setMenuBar

public void setMenuBar(MenuBar mb)

Sets the menu bar for this frame to the specified menu bar.

Parameters:: mb - the menu bar being set. If this parameter is null then any existing menu bar on this frame is removed.
See Also:: getMenuBar()

isResizable

public boolean isResizable()

Indicates whether this frame is resizable by the user. By default, all frames are initially resizable.

Returns:: true if the user can resize this frame; false otherwise.
See Also:: setResizable(boolean)

setResizable

public void setResizable(boolean resizable)

Sets whether this frame is resizable by the user.

Parameters:: resizable - true if this frame is resizable; false otherwise.
See Also:: isResizable()

setState

public void setState(int state)

Sets the state of this frame (obsolete).

In older versions of JDK a frame state could only be NORMAL or ICONIFIED. Since JDK 1.4 set of supported frame states is expanded and frame state is represented as a bitwise mask.

For compatibility with old programs this method still accepts Frame.NORMAL and Frame.ICONIFIED but it only changes the iconic state of the frame, other aspects of frame state are not affected by this method.

Parameters:: state - either Frame.NORMAL or Frame.ICONIFIED.
See Also:: getState(), setExtendedState(int)

setExtendedState

public void setExtendedState(int state)

Sets the state of this frame. The state is represented as a bitwise mask.

NORMAL
Indicates that no state bits are set.
ICONIFIED
MAXIMIZED_HORIZ
MAXIMIZED_VERT
MAXIMIZED_BOTH
Concatenates MAXIMIZED_HORIZ and MAXIMIZED_VERT.

Note that if the state is not supported on a given platform, nothing will happen. The application may determine if a specific state is available via the java.awt.Toolkit#isFrameStateSupported(int state) method.

Parameters:: state - a bitwise mask of frame state constants
Since:: 1.4
See Also:: getExtendedState(), Toolkit.isFrameStateSupported(int)

getState

public int getState()

Gets the state of this frame (obsolete).

In older versions of JDK a frame state could only be NORMAL or ICONIFIED. Since JDK 1.4 set of supported frame states is expanded and frame state is represented as a bitwise mask.

For compatibility with old programs this method still returns Frame.NORMAL and Frame.ICONIFIED but it only reports the iconic state of the frame, other aspects of frame state are not reported by this method.

Returns:: Frame.NORMAL or Frame.ICONIFIED.
See Also:: setState(int), getExtendedState()

getExtendedState

public int getExtendedState()

Gets the state of this frame. The state is represented as a bitwise mask.

NORMAL
Indicates that no state bits are set.
ICONIFIED
MAXIMIZED_HORIZ
MAXIMIZED_VERT
MAXIMIZED_BOTH
Concatenates MAXIMIZED_HORIZ and MAXIMIZED_VERT.

Returns:: a bitwise mask of frame state constants
Since:: 1.4
See Also:: setExtendedState(int)

setMaximizedBounds

public void setMaximizedBounds(Rectangle bounds)

Sets the maximized bounds for this frame.

When a frame is in maximized state the system supplies some defaults bounds. This method allows some or all of those system supplied values to be overridden.

If bounds is null, accept bounds supplied by the system. If non-null you can override some of the system supplied values while accepting others by setting those fields you want to accept from system to Integer.MAX_VALUE.

On some systems only the size portion of the bounds is taken into account.

Parameters:: bounds - bounds for the maximized state
Since:: 1.4
See Also:: getMaximizedBounds()

getMaximizedBounds

public Rectangle getMaximizedBounds()

Gets maximized bounds for this frame. Some fields may contain Integer.MAX_VALUE to indicate that system supplied values for this field must be used.

Returns:: maximized bounds for this frame; may be null
Since:: 1.4
See Also:: setMaximizedBounds(Rectangle)

setUndecorated

public void setUndecorated(boolean undecorated)

Disables or enables decorations for this frame. This method can only be called while the frame is not displayable.

Parameters:: undecorated - true if no frame decorations are to be enabled; false if frame decorations are to be enabled.
Throws:: IllegalComponentStateException - if the frame is displayable.
Since:: 1.4
See Also:: isUndecorated(), Component.isDisplayable(), JFrame.setDefaultLookAndFeelDecorated(boolean)

isUndecorated

public boolean isUndecorated()

Indicates whether this frame is undecorated. By default, all frames are initially decorated.

Returns:: true if frame is undecorated; false otherwise.
Since:: 1.4
See Also:: setUndecorated(boolean)

remove

public void remove(MenuComponent m)

Removes the specified menu bar from this frame.

Specified by:: remove in interface MenuContainer
Overrides:: remove in class Component

Parameters:: m - the menu component to remove. If m is null, then no action is taken
See Also:: Component.add(PopupMenu)

removeNotify

public void removeNotify()

Makes this Frame undisplayable by removing its connection to its native screen resource. Making a Frame undisplayable will cause any of its children to be made undisplayable. This method is called by the toolkit internally and should not be called directly by programs.

Overrides:: removeNotify in class Container

See Also:: Component.isDisplayable(), addNotify()

paramString

protected String paramString()

Returns a string representing the state of this Frame. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:: paramString in class Container

Returns:: the parameter string of this frame

setCursor

@Deprecated
public void setCursor(int cursorType)

Deprecated. As of JDK version 1.1, replaced by Component.setCursor(Cursor).

getCursorType

@Deprecated
public int getCursorType()

Deprecated. As of JDK version 1.1, replaced by Component.getCursor().

getFrames

public static Frame[] getFrames()

Returns an array containing all Frames created by the application. If called from an applet, the array will only include the Frames accessible by that applet.

Since:: 1.2

getAccessibleContext

public AccessibleContext getAccessibleContext()

Gets the AccessibleContext associated with this Frame. For frames, the AccessibleContext takes the form of an AccessibleAWTFrame. A new AccessibleAWTFrame instance is created if necessary.

Specified by:: getAccessibleContext in interface Accessible
Overrides:: getAccessibleContext in class Window

Returns:: an AccessibleAWTFrame that serves as the AccessibleContext of this Frame

Session Pattern Examples in Java

2008-09-08T11:36:00.001-07:00

Session Pattern in Java

//[C] 2002 Sun Microsystems, Inc.----

import java.io.IOException;
import java.io.Serializable;
import java.net.MalformedURLException;
import java.rmi.Naming;
import java.rmi.NotBoundException;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.rmi.server.UnicastRemoteObject;
import java.util.ArrayList;
import java.util.HashMap;

public class RunSessionPattern {
public static void main(String[] arguments) {
System.out.println("Example for the Session pattern");
System.out
.println("This demonstration will show how a Session can be used");
System.out
.println(" to organize a series of actions between a client and");
System.out.println(" server.");
System.out
.println("In this case, clients will use sessions to coordinate");
System.out.println(" edits of Contact addresses.");
System.out.println();

System.out.println("Running the RMI compiler (rmic)");
System.out.println();
try {
Process p1 = Runtime.getRuntime().exec("rmic SessionServerImpl");
p1.waitFor();
} catch (IOException exc) {
System.err
.println("Unable to run rmic utility. Exiting application.");
System.exit(1);
} catch (InterruptedException exc) {
System.err
.println("Threading problems encountered while using the rmic utility.");
}

System.out.println("Starting the rmiregistry");
System.out.println();
Process rmiProcess = null;
try {
rmiProcess = Runtime.getRuntime().exec("rmiregistry");
Thread.sleep(15000);
} catch (IOException exc) {
System.err
.println("Unable to start the rmiregistry. Exiting application.");
System.exit(1);
} catch (InterruptedException exc) {
System.err
.println("Threading problems encountered when starting the rmiregistry.");
}

System.out
.println("Creating the SessionServer and two SessionClient objects");
System.out.println();
SessionServer serverObject = new SessionServerImpl();
SessionClient clientOne = new SessionClient();
SessionClient clientTwo = new SessionClient();

System.out.println("Creating sample Contacts and Addresses");
System.out.println();
Contact firstContact = new ContactImpl("First", "Contact", "primo",
"OOI", null);
Contact secondContact = new ContactImpl("Second", "Contact", "secondo",
"OOI", null);
Address workAddress = new AddressImpl("Work address", "5440 Division",
"Fargo", "ND", "54321");
Address homeAddress = new AddressImpl("Home address", "40 Planar Way",
"Paris", "TX", "84301");

System.out
.println("Adding a contact. Both clients will attempt to edit");
System.out
.println(" the same contact at first, which will result in a");
System.out.println(" SessionException.");
try {
clientOne.addContact(firstContact);
clientTwo.addContact(firstContact);
} catch (SessionException exc) {
System.err.println("Exception encountered:");
System.err.println(exc);
}
try {
System.out
.println("Adding a different contact to the second client");
clientTwo.addContact(secondContact);
System.out
.println("Adding addresses to the first and second clients");
clientTwo.addAddress(workAddress);
clientOne.addAddress(homeAddress);
clientTwo.addAddress(workAddress);
clientTwo.addAddress(homeAddress);
System.out.println("Removing address from a client");
clientTwo.removeAddress(homeAddress);
System.out.println("Finalizing the edits to the contacts");
clientOne.commitChanges();
clientTwo.commitChanges();
System.out.println("Changes finalized");
clientTwo.addContact(firstContact);
} catch (SessionException exc) {
System.err.println("Exception encountered:");
System.err.println(exc);
}
System.out.println("The following lines will show the state");
System.out.println(" of the server-side delegate, which in this");
System.out.println(" example represents a persistent data store.");
System.out.println();
System.out.println("Contact list:");
System.out.println(SessionServerDelegate.getContacts());
System.out.println("Address list:");
System.out.println(SessionServerDelegate.getAddresses());
System.out.println("Edit contacts:");
System.out.println(SessionServerDelegate.getEditContacts());
}
}

--------------------------------------------------------------------------------

interface Address extends Serializable {
public static final String EOL_STRING = System
.getProperty("line.separator");

public static final String SPACE = " ";

public static final String COMMA = ",";

public String getType();

public String getDescription();

public String getStreet();

public String getCity();

public String getState();

public String getZipCode();

public void setType(String newType);

public void setDescription(String newDescription);

public void setStreet(String newStreet);

public void setCity(String newCity);

public void setState(String newState);

public void setZipCode(String newZip);
}

--------------------------------------------------------------------------------

class AddressImpl implements Address {
private String type;

private String description;

private String street;

private String city;

private String state;

private String zipCode;

public AddressImpl() {
}

public AddressImpl(String newDescription, String newStreet, String newCity,
String newState, String newZipCode) {
description = newDescription;
street = newStreet;
city = newCity;
state = newState;
zipCode = newZipCode;
}

public String getType() {
return type;
}

public String getDescription() {
return description;
}

public String getStreet() {
return street;
}

public String getCity() {
return city;
}

public String getState() {
return state;
}

public String getZipCode() {
return zipCode;
}

public void setType(String newType) {
type = newType;
}

public void setDescription(String newDescription) {
description = newDescription;
}

public void setStreet(String newStreet) {
street = newStreet;
}

public void setCity(String newCity) {
city = newCity;
}

public void setState(String newState) {
state = newState;
}

public void setZipCode(String newZip) {
zipCode = newZip;
}

public boolean equals(Object o) {
if (!(o instanceof AddressImpl)) {
return false;
} else {
AddressImpl address = (AddressImpl) o;
if (street.equals(address.street) && city.equals(address.city)
&& state.equals(address.state)
&& zipCode.equals(address.zipCode)) {
return true;
}
return false;
}
}

public String toString() {
return street + EOL_STRING + city + COMMA + SPACE + state + SPACE
+ zipCode + EOL_STRING;
}
}

------------------------------------------------------------------------------

class SessionServerImpl implements SessionServer {
private static final String SESSION_SERVER_SERVICE_NAME = "sessionServer";

public SessionServerImpl() {
try {
UnicastRemoteObject.exportObject(this);
Naming.rebind(SESSION_SERVER_SERVICE_NAME, this);
} catch (Exception exc) {
System.err
.println("Error using RMI to register the SessionServerImpl "
+ exc);
}
}

public long addContact(Contact contact, long sessionID)
throws SessionException {
return SessionServerDelegate.addContact(contact, sessionID);
}

public long addAddress(Address address, long sessionID)
throws SessionException {
return SessionServerDelegate.addAddress(address, sessionID);
}

public long removeAddress(Address address, long sessionID)
throws SessionException {
return SessionServerDelegate.removeAddress(address, sessionID);
}

public long finalizeContact(long sessionID) throws SessionException {
return SessionServerDelegate.finalizeContact(sessionID);
}
}

interface SessionServer extends Remote {
public long addContact(Contact contact, long sessionID)
throws RemoteException, SessionException;

public long addAddress(Address address, long sessionID)
throws RemoteException, SessionException;

public long removeAddress(Address address, long sessionID)
throws RemoteException, SessionException;

public long finalizeContact(long sessionID) throws RemoteException,
SessionException;
}

class SessionServerDelegate {
private static final long NO_SESSION_ID = 0;

private static long nextSessionID = 1;

private static ArrayList contacts = new ArrayList();

private static ArrayList addresses = new ArrayList();

private static HashMap editContacts = new HashMap();

public static long addContact(Contact contact, long sessionID)
throws SessionException {
if (sessionID <= NO_SESSION_ID) {
sessionID = getSessionID();
}
if (contacts.indexOf(contact) != -1) {
if (!editContacts.containsValue(contact)) {
editContacts.put(new Long(sessionID), contact);
} else {
throw new SessionException(
"This contact is currently being edited by another user.",
SessionException.CONTACT_BEING_EDITED);
}
} else {
contacts.add(contact);
editContacts.put(new Long(sessionID), contact);
}
return sessionID;
}

public static long addAddress(Address address, long sessionID)
throws SessionException {
if (sessionID <= NO_SESSION_ID) {
throw new SessionException(
"A valid session ID is required to add an address",
SessionException.SESSION_ID_REQUIRED);
}
Contact contact = (Contact) editContacts.get(new Long(sessionID));
if (contact == null) {
throw new SessionException(
"You must select a contact before adding an address",
SessionException.CONTACT_SELECT_REQUIRED);
}
if (addresses.indexOf(address) == -1) {
addresses.add(address);
}
contact.addAddress(address);
return sessionID;
}

public static long removeAddress(Address address, long sessionID)
throws SessionException {
if (sessionID <= NO_SESSION_ID) {
throw new SessionException(
"A valid session ID is required to remove an address",
SessionException.SESSION_ID_REQUIRED);
}
Contact contact = (Contact) editContacts.get(new Long(sessionID));
if (contact == null) {
throw new SessionException(
"You must select a contact before removing an address",
SessionException.CONTACT_SELECT_REQUIRED);
}
if (addresses.indexOf(address) == -1) {
throw new SessionException("There is no record of this address",
SessionException.ADDRESS_DOES_NOT_EXIST);
}
contact.removeAddress(address);
return sessionID;
}

public static long finalizeContact(long sessionID) throws SessionException {
if (sessionID <= NO_SESSION_ID) {
throw new SessionException(
"A valid session ID is required to finalize a contact",
SessionException.SESSION_ID_REQUIRED);
}
Contact contact = (Contact) editContacts.get(new Long(sessionID));
if (contact == null) {
throw new SessionException(
"You must select and edit a contact before committing changes",
SessionException.CONTACT_SELECT_REQUIRED);
}
editContacts.remove(new Long(sessionID));
return NO_SESSION_ID;
}

private static long getSessionID() {
return nextSessionID++;
}

public static ArrayList getContacts() {
return contacts;
}

public static ArrayList getAddresses() {
return addresses;
}

public static ArrayList getEditContacts() {
return new ArrayList(editContacts.values());
}
}

interface Contact extends Serializable {
public static final String SPACE = " ";

public static final String EOL_STRING = System
.getProperty("line.separator");

public String getFirstName();

public String getLastName();

public String getTitle();

public String getOrganization();

public ArrayList getAddresses();

public void setFirstName(String newFirstName);

public void setLastName(String newLastName);

public void setTitle(String newTitle);

public void setOrganization(String newOrganization);

public void addAddress(Address address);

public void removeAddress(Address address);
}

---------------------------------------------------------------------------------

class ContactImpl implements Contact {
private String firstName;

private String lastName;

private String title;

private String organization;

private ArrayList addresses = new ArrayList();

public ContactImpl() {
}

public ContactImpl(String newFirstName, String newLastName,
String newTitle, String newOrganization, ArrayList newAddresses) {
firstName = newFirstName;
lastName = newLastName;
title = newTitle;
organization = newOrganization;
if (newAddresses != null) {
addresses = newAddresses;
}
}

public String getFirstName() {
return firstName;
}

public String getLastName() {
return lastName;
}

public String getTitle() {
return title;
}

public String getOrganization() {
return organization;
}

public ArrayList getAddresses() {
return addresses;
}

public void setFirstName(String newFirstName) {
firstName = newFirstName;
}

public void setLastName(String newLastName) {
lastName = newLastName;
}

public void setTitle(String newTitle) {
title = newTitle;
}

public void setOrganization(String newOrganization) {
organization = newOrganization;
}

public void addAddress(Address address) {
if (!addresses.contains(address)) {
addresses.add(address);
}
}

public void removeAddress(Address address) {
addresses.remove(address);
}

public boolean equals(Object o) {
if (!(o instanceof ContactImpl)) {
return false;
} else {
ContactImpl contact = (ContactImpl) o;
if (firstName.equals(contact.firstName)
&& lastName.equals(contact.lastName)
&& organization.equals(contact.organization)
&& title.equals(contact.title)) {
return true;
}
return false;
}
}

public String toString() {
return firstName + SPACE + lastName + EOL_STRING + addresses;
}
}

class SessionClient {
private static final String SESSION_SERVER_SERVICE_NAME = "sessionServer";

private static final String SESSION_SERVER_MACHINE_NAME = "localhost";

private long sessionID;

private SessionServer sessionServer;

public SessionClient() {
try {
String url = "//" + SESSION_SERVER_MACHINE_NAME + "/"
+ SESSION_SERVER_SERVICE_NAME;
sessionServer = (SessionServer) Naming.lookup(url);
} catch (RemoteException exc) {
} catch (NotBoundException exc) {
} catch (MalformedURLException exc) {
} catch (ClassCastException exc) {
}
}

public void addContact(Contact contact) throws SessionException {
try {
sessionID = sessionServer.addContact(contact, 0);
} catch (RemoteException exc) {
}
}

public void addAddress(Address address) throws SessionException {
try {
sessionServer.addAddress(address, sessionID);
} catch (RemoteException exc) {
}
}

public void removeAddress(Address address) throws SessionException {
try {
sessionServer.removeAddress(address, sessionID);
} catch (RemoteException exc) {
}
}

public void commitChanges() throws SessionException {
try {
sessionID = sessionServer.finalizeContact(sessionID);
} catch (RemoteException exc) {
}
}
}

class SessionException extends Exception {
public static final int CONTACT_BEING_EDITED = 1;

public static final int SESSION_ID_REQUIRED = 2;

public static final int CONTACT_SELECT_REQUIRED = 3;

public static final int ADDRESS_DOES_NOT_EXIST = 4;

private int errorCode;

public SessionException(String cause, int newErrorCode) {
super(cause);
errorCode = newErrorCode;
}

public SessionException(String cause) {
super(cause);
}

public int getErrorCode() {
return errorCode;
}
}

What is Cookie

2008-09-07T04:09:00.000-07:00

cookie

(1) A small amount of data sent back to the requesting party by the recipient. Also called a "magic cookie," it provides information about the transaction, such as an ID or session number, which may be required later either by the recipient or a third party. This is the same concept as definition #2 below, but not specific to the Web.

(2) A small data file created by a Web server that is stored on your computer either temporarily for that session only or permanently on the hard disk (persistent cookie). Cookies provide a way for the Web site to recognize you and keep track of your preferences.

Cookies Are Beneficial
Cookies are commonly used to "maintain the state" of the session as a user browses around the site. The shopping cart is an example. You can place an item in the cart, switch to another page or even another site, and when you come back, the site knows who you are, and you can continue with the order. Without cookies, the site would not be able to identify you automatically because the Internet is "stateless." See state and stateless.

Cookies contain a range of URLs (addresses) for which they are valid. When the Web browser or other HTTP application sends a request to a Web server with those URLs again, it also sends along the related cookies. For example, if your user ID and password are stored in a cookie, it saves you from typing in the same information all over again when accessing that service the next time. By retaining user history, cookies allow the Web site to tailor the pages and create a custom experience for that individual.

Your Cookies Know You
Quite a bit of personal data may reside in the cookie files in your computer. As a result, this storehouse of private information is sometimes the object of attack (see cookie poisoning.)

First-Party Cookies
The default settings in your Web browser typically allow "first-party" cookies, but not "third-party" cookies. First-party cookies are created by the Web site you are visiting and are necessary to keep track of your preferences and the current session as explained above.

Third-Party Tracking Cookies
Third-party cookies are created by a Web site other than the one you are currently visiting; for example, by a third-party advertiser on that site. The purpose of such cookies is usually to track your surfing habits, which is why third-party cookies are considered an invasion of privacy and riskier than first-party cookies.

Configuring Settings
A Web browser can be configured so that only first-party cookies coming from the originating sites are maintained. It can also be set to prevent all cookies from being stored in your computer, but that severely limits the Web surfing experience. To change settings, look for the cookie options in your browser in the Options or Preferences menu. See Web bug, cookie file and state.

Indicator variables and stored procedures

2008-08-27T10:33:00.000-07:00

variables and stored procedures

Indicator variables can be used with the CALL statement, provided host variables are used for the parameters, to pass additional information to and from the procedure. Indicator variables are the SQL standard means of denoting that the associated host variable should be interpreted as containing the null value, and this is their primary use.

To indicate that an associated host variable contains the null value, the indicator variable, which is a two-byte integer, is set to a negative value. A CALL statement with indicator variables is processed as follows:

* If the indicator variable is negative, this denotes the null value. A default value is passed for the associated host variable on the CALL and the indicator variable is passed unchanged.
* If the indicator variable is not negative, this denotes that the host variable contains a non-null value. In this case, the host variable and the indicator variable are passed unchanged.

These rules of processing are the same for input parameters to the procedure as well as output parameters returned from the procedure. When indicator variables are used with stored procedures, the correct method of coding their handling is to check the value of the indicator variable first before using the associated host variable.

The following example illustrates the handling of indicator variables in CALL statements. Notice that the logic checks the value of the indicator variable before using the associated variable. Also note the method that the indicator variables are passed into procedure PROC1 (as a third argument consisting of an array of two-byte values).

Assume a procedure was defined as follows:

CREATE PROCEDURE PROC1
(INOUT DECIMALOUT DECIMAL(7,2), INOUT DECOUT2 DECIMAL(7,2))
EXTERNAL NAME LIB1.PROC1 LANGUAGE RPGLE
GENERAL WITH NULLS)

Figure 5. Handling of Indicator Variables in CALL Statements

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Program CRPG
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
D INOUT1 S 7P 2
D INOUT1IND S 4B 0
D INOUT2 S 7P 2
D INOUT2IND S 4B 0
C EVAL INOUT1 = 1
C EVAL INOUT1IND = 0
C EVAL INOUT2 = 1
C EVAL INOUT2IND = -2
C/EXEC SQL CALL PROC1 (:INOUT1 :INOUT1IND , :INOUT2
C+ :INOUT2IND)
C/END-EXEC
C EVAL INOUT1 = 1
C EVAL INOUT1IND = 0
C EVAL INOUT2 = 1
C EVAL INOUT2IND = -2
C/EXEC SQL CALL PROC1 (:INOUT1 :INOUT1IND , :INOUT2
C+ :INOUT2IND)
C/END-EXEC
C INOUT1IND IFLT 0
C* :
C* HANDLE NULL INDICATOR
C* :
C ELSE
C* :
C* INOUT1 CONTAINS VALID DATA
C* :
C ENDIF
C* :
C* HANDLE ALL OTHER PARAMETERS
C* IN A SIMILAR FASHION
C* :
C RETURN
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
End of PROGRAM CRPG
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Program PROC1
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
D INOUTP S 7P 2
D INOUTP2 S 7P 2
D NULLARRAY S 4B 0 DIM(2)
C *ENTRY PLIST
C PARM INOUTP
C PARM INOUTP2
C PARM NULLARRAY
C NULLARRAY(1) IFLT 0
C* :
C* INOUTP DOES NOT CONTAIN MEANINGFUL DATA
C*
C ELSE
C* :
C* INOUTP CONTAINS MEANINGFUL DATA
C* :
C ENDIF
C* PROCESS ALL REMAINING VARIABLES
C*
C* BEFORE RETURNING, SET OUTPUT VALUE FOR FIRST
C* PARAMETER AND SET THE INDICATOR TO A NON-NEGATIV
C* VALUE SO THAT THE DATA IS RETURNED TO THE CALLING
C* PROGRAM
C*
C EVAL INOUTP2 = 20.5
C EVAL NULLARRAY(2) = 0
C*
C* INDICATE THAT THE SECOND PARAMETER IS TO CONTAIN
C* THE NULL VALUE UPON RETURN. THERE IS NO POINT
C* IN SETTING THE VALUE IN INOUTP SINCE IT WON'T BE
C* PASSED BACK TO THE CALLER.
C EVAL NULLARRAY(1) = -5
C RETURN
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
End of PROGRAM PROC1
+++++++++++++++++++++++++++++++++++++++++++++++++++

Returning Result Sets from Stored Procedures

2008-08-27T10:32:00.000-07:00

Result Sets from Stored Procedures

In addition to returning output parameters, stored procedures have a feature by which a result table associated with a cursor opened in the stored procedure (called a result set) can be returned to the application issuing the CALL statement. That application can then issue fetch requests to read the rows of the result set cursor. Whether a result set gets returned depends on the returnability attribute of the cursor. The cursor's returnability attribute can be explicitly given in the DECLARE CURSOR statement or it can be defaulted. The SET RESULT SETS statement also allows for an indication of where the result sets should be returned (see Example 2: Call a stored procedure which returns a result set from a nested procedure). By default, cursors which are opened in a stored procedure are defined to have a returnability attribute of RETURN TO CALLER. To return the result set associated with the cursor to the application which called the outermost procedure in the call stack, the returnability attribute of RETURN TO CLIENT is specified on the DECLARE CURSOR statement. This will allow inner procedures to return result sets when the application calls nested procedures. For cursors whose result sets are never to be returned to caller or client, the returnability attribute of WITHOUT RETURN is specified on the DECLARE CURSOR statement.

There are many cases where opening the cursor in a stored procedure and returning its result set provides advantages over opening the cursor directly in the application. For instance, security to the tables referenced in the query can be adopted from the stored procedure so that users of the application do not need to be granted direct authority to the tables. Instead, they are given authority to call the stored procedure, which is compiled with adequate authority to access the tables. Another advantage to opening the cursors in the stored procedure is that multiple result sets can be returned from a single call to the stored procedure, which can be more efficient that opening the cursors separately from the calling application. Additionally, each call to the same stored procedure may return a different number of result sets, providing some application versatility.

The interfaces that can work with stored procedure result sets include JDBC, CLI, and ODBC. An example on how to use these API interfaces for working with stored procedure result sets is included in the following examples:

* Example 1: Call a stored procedure which returns a single result set
* Example 2: Call a stored procedure which returns a result set from a nested procedure

Note:
See Code disclaimer information for information pertaining to code examples.

Invoking a Stored Procedure

2008-08-27T10:30:00.000-07:00

Invoking a stored procedure

The SQL CALL statement calls a stored procedure. On the CALL statement, the name of the stored procedure and any arguments are specified. Arguments may be constants, special registers, or host variables. The external stored procedure specified in the CALL statement does not need to have a corresponding CREATE PROCEDURE statement. Programs created by SQL procedures can only be called by invoking the procedure name specified on the CREATE PROCEDURE statement.

Although procedures are system program objects, using the CALL CL command will not typically work to call a procedure. The CALL CL command does not use the procedure definition to map the input and output parameters, nor does it pass parameters to the program using the procedure's parameter style.

There are three types of CALL statements which need to be addressed since DB2® SQL for iSeries has different rules for each type. They are:

* Embedded or dynamic CALL statement where a procedure definition exists
* Embedded CALL statement where no procedure definition exists
* Dynamic CALL statement where no CREATE PROCEDURE exists

Note:
Dynamic here refers to:

* A dynamically prepared and executed CALL statement
* A CALL statement issued in an interactive environment (for example, through STRSQL or Query Manager)
* A CALL statement executed in an EXECUTE IMMEDIATE statement.

Following is a discussion of each type.

* Using CALL statement where procedure definition exists
* Using embedded CALL statement where no procedure definition exists
* Using Embedded CALL statement with an SQLDA
* Using dynamic CALL statement where no CREATE PROCEDURE exists

Additionally, you can find more examples at Examples of CALL statements.

Defining an External Procedure

2008-08-27T10:28:00.000-07:00

External Procedure

The CREATE PROCEDURE statement for an external procedure:

* Names the procedure
* Defines the parameters and their attributes
* Gives other information about the procedure which the system uses when it calls the procedure.

Consider the following example:

    CREATE PROCEDURE P1
     (INOUT PARM1 CHAR(10))
     EXTERNAL NAME MYLIB.PROC1
     LANGUAGE C
     GENERAL WITH NULLS

This CREATE PROCEDURE statement:

* Names the procedure P1
* Defines one parameter which is used both as an input parameter and an output parameter. The parameter is a character field of length ten. Parameters can be defined to be type IN, OUT, or INOUT. The parameter type determines when the values for the parameters get passed to and from the procedure.
* Defines the name of the program which corresponds to the procedure, which is PROC1 in MYLIB. MYLIB.PROC1 is the program which is called when the procedure is called on a CALL statement.
* Indicates that the procedure P1 (program MYLIB.PROC1) is written in C. The language is important since it impacts the types of parameters that can be passed. It also affects how the parameters are passed to the procedure (for example, for ILE C procedures, a NUL-terminator is passed on character, graphic, date, time, and timestamp parameters).
* Defines the CALL type to be GENERAL WITH NULLS. This indicates that the parameter for the procedure can possibly contain the NULL value, and therefore will like an additional argument passed to the procedure on the CALL statement. The additional argument is an array of N short integers, where N is the number of parameters that are declared in the CREATE PROCEDURE statement. In this example, the array contains only one element since there is only parameter.

It is important to note that it is not necessary to define a procedure in order to call it. However, if no procedure definition is found, either from a prior CREATE PROCEDURE or from a DECLARE PROCEDURE in this program, certain restrictions and assumptions are made when the procedure is called on the CALL statement. For example, the NULL indicator argument cannot be passed. See Using embedded CALL statement where no procedure definition exists for an example of a CALL statement without a corresponding procedure definition.

A cursor is a work area for a SQL statement that returns one or more rows. It allows you to fetch rows from the result set one by one. Cursors aren't particularly difficult to use, but to return a result set from a PL/SQL stored procedure, you must use a cursor variable. Cursor variables are basically pointers to cursors, and you use them to pass around references to cursors, such as a parameter to a stored procedure. The PL/SQL type of a cursor variable is REF CURSOR.

To use cursor variables, you must define a REF CURSOR type. This type can be strong or weak. Strong types are tied to a specific set of a table's columns. This means a strong REF CURSOR type can only be used with queries (i.e. cursors) returning those columns. Weak types can refer to any cursor, and so are much more flexible. They do, however, sacrifice type safety.

The easiest way forward is to define a weakly typed REF CURSOR in a PL/SQL package. Packages are used in PL/SQL for partitioning functionality. Below, a weak REF CURSOR type called REF_CURSOR is defined in a PL/SQL package called types.

CREATE OR REPLACE PACKAGE types
AS
TYPE ref_cursor IS REF CURSOR;
END;

This definition can now be used in all stored procedures to declare a variable of type REF CURSOR.

We can now write a stored procedure that returns a REF CURSOR, that in JDBC we can process as a result set.

Assume we start from a table defined as below.

     CREATE TABLE STOCK_PRICES(
     RIC VARCHAR(6) PRIMARY KEY,
     PRICE NUMBER(7,2),
     UPDATED DATE )

Here we have a table of stock prices, with the RIC (Reuters Instrument Code) as the primary key. We define a PL/SQL function that simply declares a cursor that returns all columns for stocks below a certain price.

    CREATE OR REPLACE FUNCTION sp_get_stocks(v_price IN NUMBER)
     RETURN types.ref_cursor
     AS
     stock_cursor types.ref_cursor;
     BEGIN
     OPEN stock_cursor FOR
     SELECT ric,price,updated FROM stock_prices
     WHERE price < v_price;

     RETURN stock_cursor;
    END;

These can all be created via the sqlplus command-line tool. Download the SQL script, and start up sqlplus.

C:\>sqlplus username/password

Once in sqlplus, run the script. If you start up sqlplus in the directory the SQL script is in, you can run it using the @ command:

SQL>@stock_prices

You should get an encouraging list of messages such as "1 row created", "Package created", "Function created". If instead you get error messages such as "insufficient privileges", your user must be given additional database privileges. The predefined Oracle roles CONNECT and RESOURCE should be what you need. Login as the system user and run the below:

SQL>GRANT CONNECT, RESOURCE TO username;

Testing the stored procedure

To test the stored procedure, we can either execute it from within an environment that allows you to execute stored procedures and supply their parameters, such as SQL Navigator or Toad, or we can run it from within sqlplus.

Executing a stored procedure from within sqlplus is straightforward once you know how.

Firstly, start up sqlplus and declare a sqlplus variable of type refcursor. This declares a sqlplus variable of type refcursor (a sqlplus type), called "results":

SQL> var results refcursor

Next, execute the procedure, supplying a number as a parameter, and assigning the result into our variable, "results". Note the unusual syntax.

SQL> exec :results := sp_get_stocks(20.0)

PL/SQL procedure successfully completed.

Finally, use the sqlplus print statement to print out the result set

SQL> print results

RIC PRICE UPDATED
------ --------- ---------
AMZN 15.5 21-OCT-01
SUNW 16.25 21-OCT-01
ORCL 14.5 21-OCT-01

If this works successfully, similar to the above, the stored procedure (well, function) is working correctly.
Calling the stored procedure from Java

There are some Oracle-specific tricks to calling the above stored procedure from Java.

The query string can be in the Oracle format or the standard JDBC callable statement syntax. If you are using the Oracle syntax, the query string is:

begin ? := sp_get_stocks(?); end;

If you are using the JDBC syntax, the query string is:

{ call ? := sp_get_stocks(?) }

In each case the spacing is important - the query will not work otherwise.

Secondly, the out parameter must be registered to be of type OracleTypes.CURSOR.

And finally, use getObject() to retrieve the result set.

The code (without error handling) is illustrated below. A more complete code sample can be downloaded from here.

     String query = "begin ? := sp_get_stocks(?); end;";

     CallableStatement stmt = conn.prepareCall(query);

   // register the type of the out param - an Oracle specific type
     stmt.registerOutParameter(1, OracleTypes.CURSOR);

     // set the in param
     stmt.setFloat(2, price);

     // execute and retrieve the result set
     stmt.execute();
     ResultSet rs = (ResultSet)stmt.getObject(1);

     // print the results
     while (rs.next()) {
     System.out.println(rs.getString(1) + "\t" +
     rs.getFloat(2) + "\t" +
     rs.getDate(3).toString());
     }

Hopefully, this code will be all you need to get started on calling your own Oracle stored procedures via JDBC.

Defining an SQL Procedure

2008-08-27T10:09:00.000-07:00

SQL Procedure

The CREATE PROCEDURE statement for SQL procedures:

* Names the procedure
* Defines the parameters and their attributes
* Provides other information about the procedure which will be used when the procedure is called
* Defines the procedure body. The procedure body is the executable part of the procedure and is a single SQL statement.

Consider the following simple example that takes as input an employee number and a rate and updates the employee's salary:

    CREATE PROCEDURE UPDATE_SALARY_1
    (IN EMPLOYEE_NUMBER CHAR(10),
    IN RATE DECIMAL(6,2))
    LANGUAGE SQL MODIFIES SQL DATA
    UPDATE CORPDATA.EMPLOYEE
    SET SALARY = SALARY * RATE
    WHERE EMPNO = EMPLOYEE_NUMBER

This CREATE PROCEDURE statement:

* Names the procedure UPDATE_SALARY_1.
* Defines parameter EMPLOYEE_NUMBER which is an input parameter and is a character data type of length 6 and parameter RATE which is an input parameter and is a decimal data type.
* Indicates the procedure is an SQL procedure that modifies SQL data.
* Defines the procedure body as a single UPDATE statement. When the procedure is called, the UPDATE statement is executed using the values passed for EMPLOYEE_NUMBER and RATE.

Instead of a single UPDATE statement, logic can be added to the SQL procedure using SQL control statements. SQL control statements consist of the following:

* an assignment statement
* a CALL statement
* a CASE statement
* a compound statement
* a FOR statement
* a GET DIAGNOSTICS statement
* a GOTO statement
* an IF statement
* an ITERATE statement
* a LEAVE statement
* a LOOP statement
* a REPEAT statement
* a RESIGNAL statement
* a RETURN statement
* a SIGNAL statement
* a WHILE statement

The following example takes as input the employee number and a rating that was received on the last evaluation. The procedure uses a CASE statement to determine the appropriate increase and bonus for the update:

     CREATE PROCEDURE UPDATE_SALARY_2
     (IN EMPLOYEE_NUMBER CHAR(6),
     IN RATING INT)
     LANGUAGE SQL MODIFIES SQL DATA
     CASE RATING
     WHEN 1 THEN
     UPDATE CORPDATA.EMPLOYEE
     SET SALARY = SALARY * 1.10,
     BONUS = 1000
     WHERE EMPNO = EMPLOYEE_NUMBER;
     WHEN 2 THEN
     UPDATE CORPDATA.EMPLOYEE
     SET SALARY = SALARY * 1.05,
     BONUS = 500
     WHERE EMPNO = EMPLOYEE_NUMBER;
     ELSE
     UPDATE CORPDATA.EMPLOYEE
     SET SALARY = SALARY * 1.03,
     BONUS = 0
     WHERE EMPNO = EMPLOYEE_NUMBER;
     END CASE

This CREATE PROCEDURE statement:

* Names the procedure UPDATE_SALARY_2.
* Defines parameter EMPLOYEE_NUMBER which is an input parameter and is a character data type of length 6 and parameter RATING which is an input parameter and is an integer data type.
* Indicates the procedure is an SQL procedure that modifies SQL data.
* Defines the procedure body. When the procedure is called, input parameter RATING is checked and the appropriate update statement is executed.

Multiple statements can be added to a procedure body by adding a compound statement. Within a compound statement, any number of SQL statements can be specified. In addition, SQL variables, cursors, and handlers can be declared.

The following example takes as input the department number. It returns the total salary of all the employees in that department and the number of employees in that department who get a bonus.

    CREATE PROCEDURE RETURN_DEPT_SALARY
     (IN DEPT_NUMBER CHAR(3),
     OUT DEPT_SALARY DECIMAL(15,2),
     OUT DEPT_BONUS_CNT INT)
     LANGUAGE SQL READS SQL DATA
     P1: BEGIN
     DECLARE EMPLOYEE_SALARY DECIMAL(9,2);
     DECLARE EMPLOYEE_BONUS DECIMAL(9,2);
     DECLARE TOTAL_SALARY DECIMAL(15,2)DEFAULT 0;
     DECLARE BONUS_CNT INT DEFAULT 0;
     DECLARE END_TABLE INT DEFAULT 0;
     DECLARE C1 CURSOR FOR
     SELECT SALARY, BONUS FROM CORPDATA.EMPLOYEE
     WHERE WORKDEPT = DEPT_NUMBER;
     DECLARE CONTINUE HANDLER FOR NOT FOUND
     SET END_TABLE = 1;
     DECLARE EXIT HANDLER FOR SQLEXCEPTION
    SET DEPT_SALARY = NULL;
    OPEN C1;
     FETCH C1 INTO EMPLOYEE_SALARY, EMPLOYEE_BONUS;
     WHILE END_TABLE = 0 DO
     SET TOTAL_SALARY = TOTAL_SALARY + EMPLOYEE_SALARY + EMPLOYEE_BONUS;
     IF EMPLOYEE_BONUS > 0 THEN
     SET BONUS_CNT = BONUS_CNT + 1;
     END IF;
     FETCH C1 INTO EMPLOYEE_SALARY, EMPLOYEE_BONUS;
     END WHILE;
     CLOSE C1;
     SET DEPT_SALARY = TOTAL_SALARY;
     SET DEPT_BONUS_CNT = BONUS_CNT;
     END P1

This CREATE PROCEDURE statement:

* Names the procedure RETURN_DEPT_SALARY.
* Defines parameter DEPT_NUMBER which is an input parameter and is a character data type of length 3, parameter DEPT_SALARY which is an output parameter and is a decimal data type, and parameter DEPT_BONUS_CNT which is an output parameter and is an integer data type.
* Indicates the procedure is an SQL procedure that reads SQL data
* Defines the procedure body.
o Declares SQL variables EMPLOYEE_SALARY and TOTAL_SALARY as decimal fields.
o Declares SQL variables BONUS_CNT and END_TABLE which are integers and are initialized to 0.
o Declares cursor C1 that selects the columns from the employee table.
o Declares a continue handler for NOT FOUND, which, when called sets variable END_TABLE to 1. This handler is called when the FETCH has no more rows to return. When the handler is called, SQLCODE and SQLSTATE are reinitialized to 0.
o Declares an exit handler for SQLEXCEPTION. If called, DEPT_SALARY is set to NULL and the processing of the compound statement is terminated. This handler is called if any errors occur, that is, the SQLSTATE class is not '00', '01' or '02'. Since indicators are always passed to SQL procedures, the indicator value for DEPT_SALARY is -1 when the procedure returns. If this handler is called, SQLCODE and SQLSTATE are reinitialized to 0.

If the handler for SQLEXCEPTION is not specified and an error occurs that is not handled in another handler, execution of the compound statement is terminated and the error is returned in the SQLCA. Similar to indicators, the SQLCA is always returned from SQL procedures.
o Includes an OPEN, FETCH, and CLOSE of cursor C1. If a CLOSE of the cursor is not specified, the cursor is closed at the end of the compound statement since SET RESULT SETS is not specified in the CREATE PROCEDURE statement.
o Includes a WHILE statement which loops until the last record is fetched. For each row retrieved, the TOTAL_SALARY is incremented and, if the employee's bonus is more than 0, the BONUS_CNT is incremented.
o Returns DEPT_SALARY and DEPT_BONUS_CNT as output parameters.

Compound statements can be made atomic so if an error occurs that is not expected, the statements within the atomic statement are rolled back. The atomic compound statements are implemented using SAVEPOINTS. If the compound statement is successful, the transaction is committed. For more information about using SAVEPOINTS, see Savepoints.

The following example takes as input the department number. It ensures the EMPLOYEE_BONUS table exists, and inserts the name of all employees in the department who get a bonus. The procedure returns the total count of all employees who get a bonus.

    CREATE PROCEDURE CREATE_BONUS_TABLE
     (IN DEPT_NUMBER CHAR(3),
     INOUT CNT INT)
     LANGUAGE SQL MODIFIES SQL DATA
     CS1: BEGIN ATOMIC
     DECLARE NAME VARCHAR(30) DEFAULT NULL;
     DECLARE CONTINUE HANDLER FOR SQLSTATE '42710'
     SELECT COUNT(*) INTO CNT
     FROM DATALIB.EMPLOYEE_BONUS;
     DECLARE CONTINUE HANDLER FOR SQLSTATE '23505'
     SET CNT = CNT - 1;
     DECLARE UNDO HANDLER FOR SQLEXCEPTION
     SET CNT = NULL;
     IF DEPT_NUMBER IS NOT NULL THEN
     CREATE TABLE DATALIB.EMPLOYEE_BONUS
     (FULLNAME VARCHAR(30),
     BONUS DECIMAL(10,2),
     PRIMARY KEY (FULLNAME));
     FOR_1:FOR V1 AS C1 CURSOR FOR
     SELECT FIRSTNME, MIDINIT, LASTNAME, BONUS
     FROM CORPDATA.EMPLOYEE
     WHERE WORKDEPT = CREATE_BONUS_TABLE.DEPT_NUMBER
     DO
     IF BONUS > 0 THEN
     SET NAME = FIRSTNME CONCAT ' ' CONCAT
     MIDINIT CONCAT ' 'CONCAT LASTNAME;
     INSERT INTO DATALIB.EMPLOYEE_BONUS
     VALUES(CS1.NAME, FOR_1.BONUS);
     SET CNT = CNT + 1;
     END IF;
     END FOR FOR_1;
     END IF;
     END CS1

This CREATE PROCEDURE statement:

* Names the procedure CREATE_BONUS_TABLE.
* Defines parameter DEPT_NUMBER which is an input parameter and is a character data type of length 3 and parameter CNT which is an input/output parameter and is an integer data type.
* Indicates the procedure is an SQL procedure that modifies SQL data
* Defines the procedure body.
o Declares SQL variable NAME as varying character.
o Declares a continue handler for SQLSTATE 42710, table already exists. If the EMPLOYEE_BONUS table already exists, the handler is called and retrieves the number of records in the table. The SQLCODE and SQLSTATE are reset to 0 and processing continues with the FOR statement.
o Declares a continue handler for SQLSTATE 23505, duplicate key. If the procedure attempts to insert a name that already exists in the table, the handler is called and decrements CNT. Processing continues on the SET statement following the INSERT statement.
o Declares an UNDO handler for SQLEXCEPTION. If called, the previous statements are rolled back, CNT is set to 0, and processing continues after the compound statement. In this case, since there is no statement following the compound statement, the procedure returns.
o Uses the FOR statement to declare cursor C1 to read the records from the EMPLOYEE table. Within the FOR statement, the column names from the select list are used as SQL variables that contain the data from the row fetched. For each row, data from columns FIRSTNME, MIDINIT, and LASTNAME are concatenated together with a blank in between and the result is put in SQL variable NAME. SQL variables NAME and BONUS are inserted into the EMPLOYEE_BONUS table. Because the data type of the select list items must be known when the procedure is created, the table specified in the FOR statement must exist when the procedure is created.

An SQL variable name can be qualified with the label name of the FOR statement or compound statement in which it is defined. In the example, FOR_1.BONUS refers to the SQL variable that contains the value of column BONUS for each row selected. CS1.NAME is the variable NAME defined in the compound statement with the beginning label CS1. Parameter names can also be qualified with the procedure name. CREATE_BONUS_TABLE.DEPT_NUMBER is the DEPT_NUMBER parameter for the procedure CREATE_BONUS_TABLE. If unqualified SQL variable names are used in SQL statements where column names are also allowed, and the variable name is the same as a column name, the name will be used to refer to the column.

You can also use dynamic SQL in an SQL procedure. The following example creates a table that contains all employees in a specific department. The department number is passed as input to the procedure and is concatenated to the table name.

    CREATE PROCEDURE CREATE_DEPT_TABLE (IN P_DEPT CHAR(3))
     LANGUAGE SQL
     BEGIN
     DECLARE STMT CHAR(1000);
     DECLARE MESSAGE CHAR(20);
     DECLARE TABLE_NAME CHAR(30);
     DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
     SET MESSAGE = 'ok';
     SET TABLE_NAME = 'CORPDATA.DEPT_' CONCAT P_DEPT CONCAT '_T';
     SET STMT = 'DROP TABLE ' CONCAT TABLE_NAME;
     PREPARE S1 FROM STMT;
     EXECUTE S1;
     SET STMT = 'CREATE TABLE ' CONCAT TABLE_NAME CONCAT
     '(EMPNO CHAR(6) NOT NULL,
     FIRSTNME VARCHAR(12) NOT NULL,
     MIDINIT CHAR(1) NOT NULL,
     LASTNAME CHAR(15) NOT NULL,
     SALARY DECIMAL(9,2))';
     PREPARE S2 FROM STMT;
     EXECUTE S2;
     SET STMT = 'INSERT INTO ' CONCAT TABLE_NAME CONCAT
     'SELECT EMPNO, FIRSTNME, MIDINIT, LASTNAME, SALARY
     FROM CORPDATA.EMPLOYEE
     WHERE WORKDEPT = ?';
     PREPARE S3 FROM STMT;
     EXECUTE S3 USING P_DEPT;
     END

This CREATE PROCEDURE statement:

* Names the procedure CREATE_DEPT_TABLE
* Defines parameter P_DEPT which is an input parameter and is a character data type of length 3.
* Indicates the procedure is an SQL procedure.
* Defines the procedure body.
o Declares SQL variable STMT and an SQL variable TABLE_NAME as character.
o Declares a CONTINUE handler. The procedure attempts to DROP the table in case it already exists. If the table does not exist, the first EXECUTE fails. With the handler, processing will continue.
o Sets variable TABLE_NAME to 'DEPT_' followed by the characters passed in parameter P_DEPT, followed by '_T'.
o Sets variable STMT to the DROP statement, and prepares and executes the statement.
o Sets variable STMT to the CREATE statement, and prepares and executes the statement.
o Sets variable STMT to the INSERT statement, and prepares and executes the statement. A parameter marker is specified in the where clause. When the statement is executed, the variable P_DEPT is passed on the USING clause.

If the procedure is called passing value 'D21' for the department, table DEPT_D21_T is created and the table is initialized with all the employees that are in department 'D21'.

Define Stored Procedure

2008-08-27T10:04:00.000-07:00

Introduction

Stored procedures are precompiled database queries that improve the security, efficiency and usability of database client/server applications. Developers specify a stored procedure in terms of input and output variables. They then compile the code on the database platform and make it available to aplication developers for use in other environments, such as web applications.

All of the major database platforms, including Oracle, SQL Server and MySQL support stored procedures. The major benefits of this technology are the substantial performance gains from precompiled execution, the reduction of client/server traffic, development efficiency gains from code reuse and abstraction and the security controls inherent in granting users permissions on specific stored procedures instead of the underlying database tables.

You would think that returning a JDBC result set from an Oracle PL/SQL stored procedure would be quite straightforward. Unfortunately, it's not as easy as it sounds. But reading this article should tell you all you need to know. Any contributions or corrections welcome - please post on our discussion forum. Sorry, but we can't reply to individual emails.

There are three basic steps. First, you have to write the stored procedure - which in Oracle is a bit tricky if you're not familiar with PL/SQL. Testing it using the Oracle command-line tool sqlplus is also quirky. And calling it via JDBC isn't exactly standard either.
Writing the stored procedure

If you are used to Sybase or SQLServer, returning a result set from a stored procedure is easy. Just finish the procedure with a "select x,y,z from my_table", selecting whatever columns you wish to return.

JVM (Java Virtual Machine)

2008-08-25T09:45:00.000-07:00

Acronym for Java Virtual Machine. An abstract computing machine, or virtual machine, JVM is a platform-independent execution environment that converts Java bytecode into machine language and executes it. Most programming languages compile source code directly into machine code that is designed to run on a specific microprocessor architecture or operating system, such as Windows or UNIX. A JVM -- a machine within a machine -- mimics a real Java processor, enabling Java bytecode to be executed as actions or operating system calls on any processor regardless of the operating system. For example, establishing a socket connection from a workstation to a remote machine involves an operating system call. Since different operating systems handle sockets in different ways, the JVM translates the programming code so that the two machines that may be on different platforms are able to connect.

JVMs are not the only virtual machines being used today.

Defining JVM(Java Virtual Machine)

2008-08-25T09:07:00.000-07:00

NAME

Java::JVM::Classfile - Parse JVM Classfiles

SYNOPSIS

use Java::JVM::Classfile;

my $c = Java::JVM::Classfile->new("HelloWorld.class");
print "Class: " . $c->class . "\n";
print "Methods: " . scalar(@{$c->methods}) . "\n";

DESCRIPTION

The Java Virtual Machine (JVM) is an abstract machine which processes JVM classfiles. Such classfiles contain, broadly speaking, representations of the Java methods and member fields forming the definition of a single class, information to support the exception mechanism and a system for representing additional class attributes. The JVM itself exists primarily to load and link classfiles into the running machine on demand (performed by the Class Loader), represent those classes internally by means of a number of runtime data structures and facilitate execution (a role shared between the Execution Engine (which is responsible for execution of JVM instructions) and the Native Method Interface which allows a Java program to execute non-Java code, generally ANSI C/C++.

This Perl module reveals the information in a highly-compressed JVM classfile by representing the information as a series of objects. It is hoped that this module will eventually lead to a JVM implementation in Perl (or Parrot), or possibly a way-ahead-of-time (WAT) to Perl (or Parrot) compiler for Java.

It is important to remember that the Java classfile is highly-compressed. Classfiles are intended to be as small as possible as they are often sent across the network. This may explain the slightly odd object tree. One of the most important things to consider is the idea of a constant pool. All constants (constant strings, method names and signatures etc.) are clustered in the constant pool at the start of the classfile, and sprinkled throughout the file are references to the constant pool. The module attempts to hide this optimisation as much as possible from the user, however.

It is probably important to at least have briefly read "The JavaTM Virtual Machine Specification", http://java.sun.com/docs/books/vmspec/

METHODS

new
This is the constructor, it takes the filename of the classfile to parse and returns an object:

my $c = Java::JVM::Classfile->new("HelloWorld.class");

magic

This method returns the magic number for the classfile. All valid classfiles should have the magic number 0xCAFEBABE:

my $magic = $c->magic;

version

This method returns the version of the classfile. The version consists of a major number and a minor number. For example, "45.3" has major number 45 and minor number 3:

my $version = $c->version;

class

This method returns the name of the class that this classfile corresponds to:

my $class = $c->class;

superclass

This method returns the name of the superclass of the class that this classfile corresponds to:

my $superclass = $c->superclass;

constant_pool

This method returns the constant pool entries as an array reference. Each entry is an object. Currently undocumented.

my $constant_pool = $c->constant_pool;

access_flags

This method returns the access flags for the class as an array reference. Possible flags are:

abstract

Declared abstract; may not be instantiated
final

Declared final; no subclasses allowed
interface

Is an interface, not a class
public

Declared public; may be accessed from outside its package
super

Treat superclass methods specially when invoked by the invokespecial instruction

print "Flags: " . join(", ", @{$c->access_flags}) . "\n";

interfaces

This method returns an array reference of the interfaces defined in the classfile. Currently unimplemented:

my $interfaces = $c->interfaces;

fields

This method returns an array reference of the fields defined in the classfile. Currently unimplemented:

my $fields = $c->fields;

methods

This method returns an array reference of the methods defined in the classfile:

my $methods = $c->methods;

Each Java method is represented by an object which has the following methods: name, descriptor, access_flags and attributes. name and descriptor return the method name and descriptor. Possible access flags are:

abstract

Declared abstract; no implementation is provided
final

Declared final; may not be overridden
native

Declared native; implemented in a language other than Java
private

Declared private; accessible only within the defining class
protected

Declared protected; may be accessed within subclasses
public

Declared public; may be accessed from outside its package
static

Declared static
strict

Declared strictfp; floating-point mode is FP-strict
synchronized

Declared synchronized; invocation is wrapped in a monitor lock

Various attributes are possible, the most common being the Code attribute, where the value holds information about the Java bytecode for the method:

foreach my $method (@{$c->methods}) {
print " " . $method->name . " " . $method->descriptor;
print "\n ";
print "is " . join(", ", @{$method->access_flags});
print "\n ";
print "has attributes: ";
foreach my $att (@{$method->attributes}) {
my $name = $att->name;
my $value = $att->value;
if ($att->name eq 'Code') {
print " $name: ";
print "stack(" . $value->max_stack . ")";
print ", locals(" . $value->max_locals . ")\n";
foreach my $instruction (@{$value->code}) {
print $instruction->label . ':' if defined $instruction->label;
print "\t" . $instruction->op . "\t" . (join ", ", @{$instruction->args}) . "\n";
}
print "\n";
foreach my $att2 (@{$value->attributes}) {
my $name2 = $att2->name;
my $value2 = $att2->value;
if ($name2 eq 'LineNumberTable') {
print "\tLineNumberTable (offset, line)\n";
print "\t" . $_->offset . ", " . $_->line . "\n" foreach (@$value2);
} else {
print "!\t$name2 = $value2\n";
}
}
} else {
print "!\t$name $value\n";
}
}
print "\n";
}

Note that in the case of the Code attribute, the value contains an object which has three main methods: max_stack (the maximum depth of stack needed by the method), max_locals (the number of local variables used by the method), code (returns an arrayref of instruction objects which have op, args and label methods), and attributes. One attribute that Code can have is the LineNumberTable attributes, which has an arrayref of objects as a value. These have offset and line methods, representing a link between bytecode offset and sourcecode line.
attributes

This method returns an array reference of the attributes defined in the classfile. Attributes are common in many places in the classfile - here in particular we have the classfile attributes.

my $attributes = $c->attributes;

Attributes are represented by an object that has name and value methods:

foreach my $attribute (@{$c->attributes}) {
print " " . $attribute->name . " = " . $attribute->value . "\n";
}

Possible attributes include the SourceFile attribute, the value of which is the source file that was compiled into this classfile.

Java theory and practice: Dealing with InterruptedException

2008-08-15T23:52:00.000-07:00

Many Java™ language methods, such as Thread.sleep() and Object.wait(), throw InterruptedException. You can't ignore it because it's a checked exception, but what should you do with it? In this month's Java theory and practice, concurrency expert Brian Goetz explains what InterruptedException means, why it is thrown, and what you should do when you catch one.

This story is probably familiar: You're writing a test program and you need to pause for some amount of time, so you call Thread.sleep(). But then the compiler or IDE balks that you haven't dealt with the checked InterruptedException. What is InterruptedException, and why do you have to deal with it?

The most common response to InterruptedException is to swallow it -- catch it and do nothing (or perhaps log it, which isn't any better) -- as we'll see later in Listing 4. Unfortunately, this approach throws away important information about the fact that an interrupt occurred, which could compromise the application's ability to cancel activities or shut down in a timely manner.

Blocking methods

When a method throws InterruptedException, it is telling you several things in addition to the fact that it can throw a particular checked exception. It is telling you that it is a blocking method and that it will make an attempt to unblock and return early -- if you ask nicely.
A blocking method is different from an ordinary method that just takes a long time to run. The completion of an ordinary method is dependent only on how much work you've asked it to do and whether adequate computing resources (CPU cycles and memory) are available. The completion of a blocking method, on the other hand, is also dependent on some external event, such as timer expiration, I/O completion, or the action of another thread (releasing a lock, setting a flag, or placing a task on a work queue). Ordinary methods complete as soon as their work can be done, but blocking methods are less predictable because they depend on external events. Blocking methods can compromise responsiveness because it can be hard to predict when they will complete.

Because blocking methods can potentially take forever if the event they are waiting for never occurs, it is often useful for blocking operations to be cancelable. (It is often useful for long-running non-blocking methods to be cancelable as well.) A cancelable operation is one that can be externally moved to completion in advance of when it would ordinarily complete on its own. The interruption mechanism provided by Thread and supported by Thread.sleep() and Object.wait() is a cancellation mechanism; it allows one thread to request that another thread stop what it is doing early. When a method throws InterruptedException, it is telling you that if the thread executing the method is interrupted, it will make an attempt to stop what it is doing and return early and indicate its early return by throwing InterruptedException. Well-behaved blocking library methods should be responsive to interruption and throw InterruptedException so they can be used within cancelable activities without compromising responsiveness.

Thread interruption

Every thread has a Boolean property associated with it that represents its interrupted status. The interrupted status is initially false; when a thread is interrupted by some other thread through a call to Thread.interrupt(), one of two things happens. If that thread is executing a low-level interruptible blocking method like Thread.sleep(), Thread.join(), or Object.wait(), it unblocks and throws InterruptedException. Otherwise, interrupt() merely sets the thread's interruption status. Code running in the interrupted thread can later poll the interrupted status to see if it has been requested to stop what it is doing; the interrupted status can be read with Thread.isInterrupted() and can be read and cleared in a single operation with the poorly named Thread.interrupted().

Interruption is a cooperative mechanism. When one thread interrupts another, the interrupted thread does not necessarily stop what it is doing immediately. Instead, interruption is a way of politely asking another thread to stop what it is doing if it wants to, at its convenience. Some methods, like Thread.sleep(), take this request seriously, but methods are not required to pay attention to interruption. Methods that do not block but that still may take a long time to execute can respect requests for interruption by polling the interrupted status and return early if interrupted. You are free to ignore an interruption request, but doing so may compromise responsiveness.

One of the benefits of the cooperative nature of interruption is that it provides more flexibility for safely constructing cancelable activities. We rarely want an activity to stop immediately; program data structures could be left in an inconsistent state if the activity were canceled mid-update. Interruption allows a cancelable activity to clean up any work in progress, restore invariants, notify other activities of the cancellation, and then terminate.

Dealing with InterruptedException

If throwing InterruptedException means that a method is a blocking method, then calling a blocking method means that your method is a blocking method too, and you should have a strategy for dealing with InterruptedException. Often the easiest strategy is to throw InterruptedException yourself, as shown in the putTask() and getTask() methods in Listing 1. Doing so makes your method responsive to interruption as well and often requires nothing more than adding InterruptedException to your throws clause.

Listing 1. Propagating InterruptedException to callers by not catching it

public class TaskQueue {
private static final int MAX_TASKS = 1000;

private BlockingQueue queue
= new LinkedBlockingQueue(MAX_TASKS);

public void putTask(Task r) throws InterruptedException {
queue.put(r);
}

public Task getTask() throws InterruptedException {
return queue.take();
}
}

Sometimes it is necessary to do some amount of cleanup before propagating the exception. In this case, you can catch InterruptedException, perform the cleanup, and then rethrow the exception. Listing 2, a mechanism for matching players in an online game service, illustrates this technique. The matchPlayers() method waits for two players to arrive and then starts a new game. If it is interrupted after one player has arrived but before the second player arrives, it puts that player back on the queue before rethrowing the InterruptedException, so that the player's request to play is not lost.

Listing 2. Performing task-specific cleanup before rethrowing InterruptedException

public class PlayerMatcher {
private PlayerSource players;

public PlayerMatcher(PlayerSource players) {
this.players = players;
}

public void matchPlayers() throws InterruptedException {
Player playerOne, playerTwo;
try {
while (true) {
playerOne = playerTwo = null;
// Wait for two players to arrive and start a new game
playerOne = players.waitForPlayer(); // could throw IE
playerTwo = players.waitForPlayer(); // could throw IE
startNewGame(playerOne, playerTwo);
}
}
catch (InterruptedException e) {
// If we got one player and were interrupted, put that player back
if (playerOne != null)
players.addFirst(playerOne);
// Then propagate the exception
throw e;
}
}
}

Don't swallow interrupts

Sometimes throwing InterruptedException is not an option, such as when a task defined by Runnable calls an interruptible method. In this case, you can't rethrow InterruptedException, but you also do not want to do nothing. When a blocking method detects interruption and throws InterruptedException, it clears the interrupted status. If you catch InterruptedException but cannot rethrow it, you should preserve evidence that the interruption occurred so that code higher up on the call stack can learn of the interruption and respond to it if it wants to. This task is accomplished by calling interrupt() to "reinterrupt" the current thread, as shown in Listing 3. At the very least, whenever you catch InterruptedException and don't rethrow it, reinterrupt the current thread before returning.

Listing 3. Restoring the interrupted status after catching InterruptedException

public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException e) {
// Restore the interrupted status
Thread.currentThread().interrupt();
}
}
}

The worst thing you can do with InterruptedException is swallow it -- catch it and neither rethrow it nor reassert the thread's interrupted status. The standard approach to dealing with an exception you didn't plan for -- catch it and log it -- also counts as swallowing the interruption because code higher up on the call stack won't be able to find out about it. (Logging InterruptedException is also just silly because by the time a human reads the log, it is too late to do anything about it.) Listing 4 shows the all-too-common pattern of swallowing an interrupt:

Listing 4. Swallowing an interrupt -- don't do this

// Don't do this
public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException swallowed) {
/* DON'T DO THIS - RESTORE THE INTERRUPTED STATUS INSTEAD */
}
}
}

If you cannot rethrow InterruptedException, whether or not you plan to act on the interrupt request, you still want to reinterrupt the current thread because a single interruption request may have multiple "recipients." The standard thread pool (ThreadPoolExecutor) worker thread implementation is responsive to interruption, so interrupting a task running in a thread pool may have the effect of both canceling the task and notifying the execution thread that the thread pool is shutting down. If the task were to swallow the interrupt request, the worker thread might not learn that an interrupt was requested, which could delay the application or service shutdown.

Back to top

Implementing cancelable tasks

Nothing in the language specification gives interruption any specific semantics, but in larger programs, it is difficult to maintain any semantics for interruption other than cancellation. Depending on the activity, a user could request cancellation through a GUI or through a network mechanism such as JMX or Web Services. It could also be requested by program logic. For example, a Web crawler might automatically shut itself down if it detects that the disk is full, or a parallel algorithm might start multiple threads to search different regions of the solution space and cancel them once one of them finds a solution.

Just because a task is cancelable does not mean it needs to respond to an interrupt request immediately. For tasks that execute code in a loop, it is common to check for interruption only once per loop iteration. Depending on how long the loop takes to execute, it could take some time before the task code notices the thread has been interrupted (either by polling the interrupted status with Thread.isInterrupted() or by calling a blocking method). If the task needs to be more responsive, it can poll the interrupted status more frequently. Blocking methods usually poll the interrupted status immediately on entry, throwing InterruptedException if it is set to improve responsiveness.

The one time it is acceptable to swallow an interrupt is when you know the thread is about to exit. This scenario only occurs when the class calling the interruptible method is part of a Thread, not a Runnable or general-purpose library code, as illustrated in Listing 5. It creates a thread that enumerates prime numbers until it is interrupted and allows the thread to exit upon interruption. The prime-seeking loop checks for interruption in two places: once by polling the isInterrupted() method in the header of the while loop and once when it calls the blocking BlockingQueue.put() method.

Listing 5. Interrupts can be swallowed if you know the thread is about to exit

public class PrimeProducer extends Thread {
private final BlockingQueue queue;

PrimeProducer(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
BigInteger p = BigInteger.ONE;
while (!Thread.currentThread().isInterrupted())
queue.put(p = p.nextProbablePrime());
} catch (InterruptedException consumed) {
/* Allow thread to exit */
}
}

public void cancel() { interrupt(); }
}

Noninterruptible blocking

Not all blocking methods throw InterruptedException. The input and output stream classes may block waiting for an I/O to complete, but they do not throw InterruptedException, and they do not return early if they are interrupted. However, in the case of socket I/O, if a thread closes the socket, blocking I/O operations on that socket in other threads will complete early with a SocketException. The nonblocking I/O classes in java.nio also do not support interruptible I/O, but blocking operations can similarly be canceled by closing the channel or requesting a wakeup on the Selector. Similarly, attempting to acquire an intrinsic lock (enter a synchronized block) cannot be interrupted, but ReentrantLock supports an interruptible acquisition mode.

Noncancelable tasks

Some tasks simply refuse to be interrupted, making them noncancelable. However, even noncancelable tasks should attempt to preserve the interrupted status in case code higher up on the call stack wants to act on the interruption after the noncancelable task completes. Listing 6 shows a method that waits on a blocking queue until an item is available, regardless of whether it is interrupted. To be a good citizen, it restores the interrupted status in a finally block after it is finished, so as not to deprive callers of the interruption request. (It can't restore the interrupted status earlier, as it would cause an infinite loop -- BlockingQueue.take() could poll the interrupted status immediately on entry and throws InterruptedException if it finds the interrupted status set.)

Listing 6. Noncancelable task that restores interrupted status before returning

public Task getNextTask(BlockingQueue queue) {
boolean interrupted = false;
try {
while (true) {
try {
return queue.take();
} catch (InterruptedException e) {
interrupted = true;
// fall through and retry
}
}
} finally {
if (interrupted)
Thread.currentThread().interrupt();
}
}

Goalsof JAVA-JDBC

2007-11-12T08:25:00.000-08:00

The JDBC API is a mature technology, having first been specified in January 1997. In
its initial release, the JDBC API focused on providing a basic call-level interface to
SQL databases. The JDBC 2.1 specification and the 2.0 Optional Package
specification then broadened the scope of the API to include support for more
advanced applications and for the features required by application servers to
manage use of the JDBC API on behalf of their applications.
The overall goal of the JDBC 3.0 specification is to “round out” the API by filling in
smaller areas of missing functionality. The following list outlines the goals and
design philosophy for the JDBC API in general and the JDBC 3.0 API in particular:
1. Fit into the J2EE and J2SE platforms
The JDBC API is a constituent technology of the Java platform. The JDBC 3.0 API
should be aligned with the overall direction of the Java 2 Enterprise Edition and
Java 2 Standard Edition platforms.
2. Be consistent with SQL99
The JDBC API provides programmatic access from applications written in the
Java programming language to standard SQL. At the time the JDBC 2.0 API was
in development, the SQL99 specification was a moving target. SQL99 is now a
published standard and includes features that are widely supported among
DBMS vendors as well as features that only a few vendors support. The intent of
the JDBC 3.0 API is to provide access to the subset of SQL99 features that are
likely to be widely supported within the next five years.
3. Consolidate predecessor specifications
This document incorporates content from three prior JDBC specifications to
provide a single standalone specification of the JDBC API.
4. Offer vendor-neutral access to common features
The JDBC API strives to provide high-bandwidth access to features commonly
supported across different vendor implementations. The goal is to provide a
degree of feature access comparable to what can be achieved by native
applications. However, the API must be general and flexible enough to allow for
a wide range of implementations.
5. Maintain the focus on SQL
The focus of the JDBC API has always been on accessing relational data from the
Java programming language. This continues to be true with the JDBC 3.0 API. The
JDBC 3.0 API does not preclude interacting with other technologies, including
XML, CORBA, or non-relational data, but the primary target will still be relational
data and SQL.
6. Provide a foundation for tools and higher-level APIs
The JDBC API presents a standard API to access a wide range of underlying data
sources or legacy systems. Implementation differences are made transparent
through JDBC API abstractions, making it a valuable target platform for tools
vendors who want to create portable tools and applications.
Because it is a “call-level” interface from the Java programming language to SQL,
the JDBC API is also suitable as a base layer for higher-level facilities such as EJB
2.0 container-managed persistence and SQLJ.
7. Keep it simple
The JDBC API is intended to be a simple-to-use, straightforward interface upon
which more complex entities can be built. This goal is achieved by defining many
compact, single-purpose methods instead of a smaller number of complex, multipurpose
ones with control flag parameters.
8. Enhance reliability, availability, and scalability
Reliability, availability, and scalability are the themes of the J2EE and J2SE
platforms, as well as the direction for future Java platforms. The JDBC 3.0 API
stays true to these themes by enhancing support in several areas, including
resource management, the reuse of prepared statements across logical
connections, and error handling.
9. Maintain backward compatibility with existing applications and drivers
Existing JDBC technology-enabled drivers (“JDBC drivers”) and the applications
that use them must continue to work in an implementation of the Java virtual
machine that supports the JDBC 3.0 API. Applications that use only features
defined in earlier releases of the JDBC API, excluding those that were deprecated
by JDBC 2.0, will not require changes to continue running. It should be
straightforward for existing applications to migrate to JDBC 3.0 technology.
10. Allow forward compatibility with Connectors
The Connector architecture defines a standard way to package and deploy a
resource adapter that allows a J2EE container to integrate its connection,
transaction, and security management with those of an external resource.
The JDBC 3.0 API provides the migration path for JDBC drivers to the Connector
architecture. It should be possible for vendors whose products use JDBC
technology to move incrementally towards implementing the Connector API. The
expectation is that these implementors will write “resource manager wrappers”
around their existing data source implementations so that they can be reused in a
Connector framework.
11. Specify requirements unambiguously
The requirements for JDBC compliance need to be unambiguous and easy to
identify. The JDBC 3.0 specification and the API documentation (Javadoc) will
clarify which features are required and which are optional.

Overview of JAVA-JDBC

2007-11-12T08:12:00.000-08:00

The JDBC API provides a way for Java programs to access one or more sources of
data. In the majority of cases, the data source is a relational DBMS, and its data is accessed using SQL. However, it is also possible for JDBC technology-enabled drivers to be implemented on top of other data sources, including legacy file systems and object-oriented systems. A primary motivation for the JDBC API is to provide a standard API for applications to access a wide variety of data sources. This chapter introduces some of the key concepts of the JDBC API. In addition, it describes two common environments for JDBC applications, with a discussion of
how different functional roles are implemented in each one. The two-tier and three-tier models are logical configurations that can be implemented on a variety of physical configurations.

Establishing a Connection

The JDBC API defines the Connection interface to represent a connection to an underlying data source. In a typical scenario, a JDBC application will connect to a target data source using
one of two mechanisms:

DriverManager — this fully implemented class was introduced in the original JDBC 1.0 API and requires the application to load a specific driver using a hardcoded URL.

DataSource — this interface was introduced in the JDBC 2.0 Optional Package API. It is preferred over DriverManager because it allows details about the underlying data source to be transparent to the application. A DataSource object’s properties are set so that it represents a particular data source. When its getConnection method is invoked, the DataSource instance will return a connection to that data source. An application can be directed to a different data source by simply changing the DataSource object’s properties; no change in application code is needed. Likewise, a DataSource implementation can be changed without changing the application code that uses it. The JDBC API also defines two important extensions of the DataSource interface tosupport enterprise applications. These extensions are the following two interfaces:

ConnectionPoolDataSource — supports caching and reusing of physical connections, which improves application performance and scalability
XADataSource — provides connections that can participate in a distributed transaction

Executing SQL Statements and

Manipulating Results

Once a connection has been established, an application using the JDBC API can execute queries and updates against the target data source. The JDBC 3.0 API provides access to the most commonly implemented features of SQL99. Because different vendors vary in their level of support for these features, the JDBC API includes the DatabaseMetadata interface. Applications can use this interface to determine whether a particular feature is supported by the data source they are using. The JDBC API also defines escape syntax to allow an application to access non-standard vendor-specific features. The use of escape syntax has the advantage
of giving JDBC applications access to the same feature set as native applications and at the same time maintaining the portability of the application. Applications use methods in the Connection interface to specify transaction attributes and create Statement, PreparedStatement, or CallableStatement objects. These statements are used to execute SQL statements and retrieve results. The ResultSet interface encapsulates the results of an SQL query. Statements may
also be batched, allowing an application to submit multiple updates to a data source
as a single unit of execution. The JDBC API extends the ResultSet interface with the RowSet interface, thereby providing a container for tabular data that is much more versatile than a standard result set. A RowSet object is a JavaBeansTM component, and it may operate without
being connected to its data source. For example, a RowSet implementation can be serializable and therefore sent across a network, which is particularly useful for small-footprint clients that want to operate on tabular data without incurring the overhead of a JDBC driver and data source connection. Another feature of a RowSet implementation is that it can include a custom reader for accessing any data in tabular format, not just data in a relational database. Further, a RowSet object can update its rows while it is disconnected from its data source, and its implementation can include a custom writer that writes those updates back to the underlying data source.

Support for SQL Advanced Data Types

The JDBC API defines standard mappings to convert SQL data types to JDBC data types and back. This includes support for SQL99 advanced data types such as BLOB, CLOB, ARRAY, REF, STRUCT, and DISTINCT. JDBC drivers may also implement one or more customized type mappings for user-defined types (UDTs), in which the UDT is mapped to a class in the Java programming language. The JDBC 3.0 API also adds support for externally managed data, for example, data in a file outside the data source.

Two-tier Model

A two-tier model divides functionality into a client layer and a server layer
The client layer includes the application(s) and one or more JDBC drivers, with the
application handling these areas of responsibility:

Application
data source
JDBC Driver

presentation logic
business logic
transaction management for multiple-statement transactions or distributed transactions
resource management

In this model, the application interacts directly with the JDBC driver(s), including establishing and managing the physical connection(s) and dealing with the details of specific underlying data source implementations. The application may use its knowledge of a specific implementation to take advantage of nonstandard features or do performance tuning.
Some drawbacks of this model include:

mingling presentation and business logic with infrastructure and system-level functions. This presents an obstacle to producing maintainable code with a welldefined architecture.

making applications less portable because they are tuned to a particular database implementation. Applications that require connections to multiple databases must be aware of the differences between the different vendors’ implementations.

limiting scalability. Typically, the application will hold onto one or more physical database connections until it terminates, limiting the number of concurrent applications that can be supported. In this model, issues of performance, scalability and availability are handled by the JDBC driver and the corresponding underlying data source. If an application deals with multiple drivers, it may also need to be aware of the different ways in which each driver/data source pair resolves these issues.

Three-tier Model

The three-tier model introduces a middle-tier server to house business logic and
infrastructure. This architecture is designed to provide improved performance, scalability and
availability for enterprise applications. Functionality is divided among the tiers as follows:

1. Client tier — a thin layer implementing presentation logic for human interaction.
Java programs, web browsers and PDAs are typical client-tier implementations.
The client interacts with the middle-tier application and does not need to include
any knowledge of infrastructure or underlying data source functions.
2. Middle-tier server — a middle tier that includes:
n Applications to interact with the client and implement business logic. If the
application includes interaction with a data source, it will deal with higherlevel
abstractions, such as DataSource objects and logical connections rather
than lower-level driver API.

data source
Web Client
(Browser) Application
Server
transaction
manager
JDBC
Driver
JDBC
Driver
data source
Middle-tier Server
Application Application

An application server to provide supporting infrastructure for a wide range ofapplications. This can include management and pooling of physical connections, transaction management, and the masking of differences between different JDBC drivers. This last point makes it easier to write portable applications. The application server role can be implemented by a J2EE server. Application servers implement the higher-level abstractions used by applications and interact directly with JDBC drivers.

JDBC driver(s) to provide connectivity to the underlying data sources. Each driver implements the standard JDBC API on top of whatever features are supported by its underlying data source. The driver layer may mask differences between standard SQL99 syntax and the native dialect supported by the data source. If the data source is not a relational DBMS, the driver implements the relational layer used by the application server.

3. Underlying data source — the tier where the data resides. It can include
relational DBMSs, legacy file systems, object-oriented DBMSs, data warehouses,
spreadsheets, or other means of packaging and presenting data. The only
requirement is a corresponding driver that supports the JDBC API.

JDBC in the J2EE Platform

J2EE components, such as JavaServerTM Pages, Servlets, and Enterprise Java BeansTM
(EJBTM) components, often require access to relational data and use the JDBC API for this access. When J2EE components use the JDBC API, the container manages their transactions and data sources. This means that J2EE component developers do not directly use the JDBC API’s transaction and datasource management facilities. See the J2EE Platform Specification for further details.

Classes and Interfaces in JAVA-JDBC

2007-11-12T08:06:00.000-08:00

The following classes and interfaces make up the JDBC API.

The java.sql Package

The core JDBC API is contained in the package java.sql. The classes and interfaces
in java.sql are listed below. Classes are bold type; interfaces are in standard type.

java.sql.Array
java.sql.BatchUpdateException
java.sql.Blob
java.sql.CallableStatement
java.sql.Clob
java.sql.Connection
java.sql.DataTruncation
java.sql.DatabaseMetaData
java.sql.Date
java.sql.Driver
java.sql.DriverManager
java.sql.DriverPropertyInfo
java.sql.ParameterMetaData
java.sql.PreparedStatement
java.sql.Ref
java.sql.ResultSet
java.sql.ResultSetMetaData
Chapter 5 Classes and Interfaces 30
java.sql.Savepoint
java.sql.SQLData
java.sql.SQLException
java.sql.SQLInput
java.sql.SQLOutput
java.sql.SQLPermission
java.sql.SQLWarning
java.sql.Statement
java.sql.Struct
java.sql.Time
java.sql.Timestamp
java.sql.Types

The following classes and interfaces are either new or updated in the JDBC 3.0 API.
New classes and interfaces are highlighted in bold.

java.sql.Array
java.sql.Blob
java.sql.CallableStatement
java.sql.Clob
java.sql.Connection
java.sql.DatabaseMetaData
java.sql.ParameterMetaData
java.sql.PreparedStatement
java.sql.Ref
Java.sql.ResultSet
java.sql.Savepoint
java.sql.SQLInput
java.sqlOutput
java.sql.Statement
java.sql.Types

Relationships between major classes and interface in the java.sql package

Connection
Statement
Data types
CallableStatement
ResultSet
PreparedStatement
subclasses
prepareStatement
prepareCall
createStatement
executeQuery
executeQuery
executeQuery
Input to
getXXX
Input/Output of
getMoreResults / getResultSet
subclasses
PreparedStatement
CallableStatement

The javax.sql Package

The following list contains the classes and interfaces that are contained in the
javax.sql package. Classes are highlighted in bold; interfaces are in normal type.

javax.sql.ConnectionEvent
javax.sql.ConnectionEventListener
javax.sql.ConnectionPoolDataSource
javax.sql.DataSource
javax.sql.PooledConnection
javax.sql.RowSet
javax.sql.RowSetEvent
javax.sql.RowSetInternal
javax.sql.RowSetListener
javax.sql.RowSetMetaData
javax.sql.RowSetReader
javax.sql.RowSetWriter
javax.sql.XAConnection
javax.sql.XADataSource

Note – The classes and interfaces in the javax.sql package were first made available as the JDBC 2.0 Optional Package. This optional package was previously separate from the java.sql package, which was part of J2SE 1.2. Both packages (java.sql and javax.sql) are now part of J2SE 1.4.

classes and interfaces in these areas of functionality: DataSource objects, connection pooling, distributed transactions, and rowsets.

Relationship between javax.sql.DataSource and java.sql.Connection
Relationships involved in connection pooling DataSource Connection

java.sql javax.sql
getConnection
Connection PooledConnection
javax.sql java.sql
getConnection
ConnectionPoolDataSource
getConnection
ConnectionEvent
ConnectionEventListener
close or error event

Relationships involved in distributed transaction support

XAConnection
PooledConnection
ConnectionEvent
XAResource
ConnectionEventListener
XADataSource
Connection
java.sql javax.sql javax.transaction.xa
getConnection
getXAConnection
getXAResource
subclasses
close or error event

Compliance in JAVA-JDBC

2007-11-12T07:57:00.000-08:00

This chapter identifies the features that a JDBC API implementation is required to support for each level of compliance. A JDBC API implementation includes a JDBC
technology-enabled driver and its underlying data source. Therefore, compliance is defined in terms of what features are available above the driver layer. Any features not identified here are optional. In general, a driver is not required to implement any feature that its underlying data source does not support.

Definitions

To avoid ambiguity, we will use these terms in our discussion of compliance:

JDBC API implementation — a JDBC technology-enabled driver and its underlying data source. The driver may provide support for features that are not implemented by the underlying data source. It may also provide the mapping between standard syntax/semantics and the native API implemented by the data source.

Relevant specifications — this document, the API specification, and the relevant SQL specification. This is also the order of precedence if a feature is described in more than one of these documents. For the JDBC 1.0 API, the relevant SQL specification is SQL92 and X/Open SQL CLI. For the JDBC 2.0 and 3.0 APIs, it is SQL92 plus the relevant sections of SQL99 and X/Open SQL CLI.
Supported feature — a feature for which the JDBC API implementation supports standard syntax and semantics for that feature as defined in the relevant specifications.
Extension — a feature that is not covered by any of the relevant specifications or a non-standard implementation of a feature that is covered.
Fully implemented — a term applied to an interface that has all of its methods implemented to support the semantics defined in the relevant specifications.

Required interface — an interface that must be included although it might not be fully implemented. Methods that are not implemented should throw an SQLException to indicate that the corresponding feature is not supported.

Guidelines and Requirements
The following guidelines apply to all levels of compliance:

A JDBC API implementation must support Entry Level SQL92 plus the SQL command Drop Table (see note.)

Entry Level SQL92 represents a "floor" for the level of SQL that a JDBC API
implementation must support. Access to features based on SQL99 should be
provided in a way that is compatible with the relevant part of the SQL99
specification.

Drivers must support escape syntax. Escape syntax is described in “Statements”.
Drivers must support transactions. See Chapter 10 “Transactions” for details.
Drivers should provide access to every feature implemented by the underlying data source, including features that extend the JDBC API. When a feature is not supported, the corresponding methods throw an SQLException. The intent is for applications using the JDBC API to have access to the same feature set as native applications.
If a DatabaseMetaData method indicates that a given feature is supported, it must be supported via standard syntax and semantics as described in the relevant specifications. This may require the driver to provide the mapping to the data source’s native API or SQL dialect if it differs from the standard.
If a feature is supported, all of the relevant metadata methods must be implemented. For example, if a JDBC API implementation supports the RowSet interface, it must also implement the RowSetMetaData interface.
If a feature is not supported, the corresponding DatabaseMetaData method must say so. Attempting to access the unsupported feature causes an SQLException to be thrown.

Note – A JDBC API implementation is required to support the DROP TABLE
command as specified by SQL92, Transitional Level. However, support for the
CASCADE and RESTRICT options of DROP TABLE is optional. In addition, the
behaviour of DROP TABLE is implementation-defined when there are views or
integrity constraints defined that reference the table being dropped.

JDBC 1.0 API Compliance

A driver that is compliant with the JDBC 1.0 API must do the following:

Adhere to the preceding guidelines and requirements
Fully implement the following interfaces:
java.sql.Driver
java.sql.DatabaseMetaData (excepting those methods introduced in the JDBC 2.0 API and the JDBC 3.0 API)
java.sql.ResultSetMetaData (excepting those methods introduced in the JDBC 2.0 API and the JDBC 3.0 API)
Include the following required interfaces:
java.sql.CallableStatement
java.sql.Connection
java.sql PreparedStatement
java.sql.ResultSet
java.sql.Statement

JDBC 2.0 API Compliance

A driver that is compliant with the JDBC 2.0 API must do the following:

Comply with the JDBC 1.0 API requirements
Implement the following additional DatabaseMetaData methods:
deletesAreDetected
getConnection
getUDTs
insertsAreDetetced
othersDeletesAreVisible
othersInsertsAreVisible
othersUpdatesAreVisible
ownDeletesAreVisible
ownInsertsAreVisible
ownUpdatesAreVisible
supportsBatchUpdates
supportsResultSetConcurrency
supportsResultSetType
updatesAreDetected
Implement the following additional ResultSetMetaData methods:
getColumnClassName
getColumnType
getColumnTypeName

JDBC 3.0 API Compliance

A driver that is compliant with the JDBC 3.0 API must do the following:

Comply with the JDBC 2.0 API requirements
Include the following required interfaces:
java.sql.ParameterMetaData
java.sql.Savepoint
It must implement the following additional DatabaseMetaData methods:
supportsSavepoints
supportsNamedParameters
supportsMultipleOpenResults
supportsGetGeneratedKeys
getSuperTypes
getSuperTables
getAttributes
getResultSetHoldability
supportsResultSetHoldability
getSQLStateType
getDatabaseMajorVersion
getDatabaseMinorVersion
getJDBCMajorVersion
getJDBCMinorVersion

Determining Compliance Level

The JDBC API is a constituent technology of the Java platform. Compliance with the
JDBC API specification is determined as a subset of evaluating compliance with the
overall platform.
Note – As of this writing, there is no separate evaluation of compliance level for the JDBC API.

Deprecated APIs

Deprecation refers to a class, interface, constructor, method or field that is no longer recommended and may cease to exist in a future version. The following constructors and methods were deprecated in the JDBC 2.0 API:

java.sql.CallableStatement.getBigDecimal(int, int)
java.sql.Date(int, int, int)
java.sql.Date.getHours()
java.sql.Date.getMinutes()
java.sql.Date.getSeconds()
java.sql.Date.setHours(int)
java.sql.Date.setMinutes(int)
java.sql.Date.setSeconds(int)
java.sql.DriverManager.getLogStream()
java.sql.DriverManager.setLogStream(PrintStream)
java.sql.PreparedStatement.setUnicodeStream(int, InputStream,int)
java.sql.ResultSet.getBigDecimal(int, int)
java.sql.ResultSet.getBigDecimal(String, int)
java.sql.ResultSet.getUnicodeStream(int)
java.sql.ResultSet.getUnicodeStream(String)
java.sql.Time(int, int, int)
java.sql.Time.getDate()
java.sql.Time.getDay()
java.sql.Time.getMonth()
java.sql.Time.getYear()
java.sql.Time.setDate(int)
java.sql.Time.setMonth(int)
java.sql.Time.setYear(int)
java.sql.Timestamp(int, int, int, int, int, int, int)

Database Metadata

2007-11-12T07:47:00.000-08:00

The DatabaseMetaData interface is implemented by JDBC drivers to provide
information about their underlying data sources. It is used primarily by application servers and tools to determine how to interact with a given data source. Applications may also use DatabaseMetaData methods to get information about a data source, but this is less typical.
The DatabaseMetaData interface includes over 150 methods, which can be categorized according to the types of information they provide:

general information about the data source
whether or not the data source supports a given feature or capability
data source limits
what SQL objects the data source contains and attributes of those objects
transaction support offered by the data source

The DatabaseMetaData interface also contains over 40 fields, which are constants used as return values for various DatabaseMetaData methods. This chapter presents an overview of the DatabaseMetaData interface, gives examples to illustrate the categories of metadata methods, and introduces some new methods. For a comprehensive listing, however, the reader should consult the JDBC

API specification.

JDBC also defines the ResultSetMetaData interface, which is discussed in “Result Sets”.

Creating a DatabaseMetadata Object

A DatabaseMetaData object is created with the Connection method getMetaData. Once created, it can be used to dynamically discover information about the underlying data source. CODE EXAMPLE creates a DatabaseMetadata object and uses it to determine the maximum number of characters allowed for a table name.

// con is a Connection object
DatabaseMetaData dbmd = con.getMetadata();
int maxLen = dbmd.getMaxTableNameLength();

CODE EXAMPLE Creating and using a DatabaseMetadata object

Retrieving General Information

Some DatabaseMetaData methods are used to dynamically discover general
information about a data source as well as some details about its implementation.
Some of the methods in this category are:

getURL
getUserName
getDatabaseProductVersion, getDriverMajorVersion and getDriverMinorVersion
getSchemaTerm, getCatalogTerm and getProcedureTerm
nullsAreSortedHigh and nullsAreSortedLow
usesLocalFiles and usesLocalFilePerTable
getSQLKeywords

Determining Feature Support

A large group of DatabaseMetaData methods can be used to determine whether a given feature or set of features is supported by the driver or underlying data source. Beyond this, some of the methods describe what level of support is provided. Some of the methods that describe support for individual features are:

supportsAlterTableWithDropColumn
supportsBatchUpdates
supportsTableCorrelationNames
supportsPositionedDelete
supportsFullOuterJoins
supportsStoredProcedures
supportsMixedCaseQuotedIdentifiers

Methods to describe a level of feature support include:

supportsANSI92EntryLevelSQL
supportsCoreSQLGrammar

Data Source Limits

Another group of methods provides the limits imposed by a given data source. Some of the methods in this category are:

getMaxRowSize
getMaxStatementLength
getMaxTablesInSelect
getMaxConnections
getMaxCharLiteralLength
getMaxColumnsInTable

Methods in this group return the limit as an int. A return value of zero means that there is no limit or the limit is unknown.

SQL Objects and Their Attributes

Some DatabaseMetaData methods provide information about the SQL objects that populate a given data source. This group also includes methods to determine the attributes of those objects. Methods in this group return ResultSet objects in which each row describes a particular object. For example, the method getUDTs returns a ResultSet object in which there is a row for each UDT that has been defined in the data source. Examples of this category are:

getSchemas and getCatalogs
getTables
getPrimaryKeys
getProcedures and getProcedureColumns
getUDTs

Transaction Support

A small group of methods provides information about the transaction semantics
supported by the data source. Examples of this category include:

supportsMultipleTransactions
getDefaultTransactionIsolation

New Methods

The JDBC 3.0 API introduces the following new DatabaseMetaData methods:

getSuperTypes — returns a description of the user-defined type hierarchies defined in a given schema in the underlying data source
getSuperTables — returns a description of the table hierarchies defined in a given schema in the underlying data source
getAttributes — returns a description of user-defined type attributes available from a given catalog in the underlying data source
getSQLStateType — returns the type of SQLSTATEs that will be returned by the method SQLException.getSQLState, described in “SQLException”.
supportsSavepoints — returns true if the driver or underlying data source supports savepoints, described in “Savepoints” .
supportsNamedParameters — returns true if the driver or underlying data source supports named parameters for CallableStatement objects, described in “Setting Parameters”.
supportsMultipleOpenResults — returns true if the driver or underlying data source supports multiple open result sets for CallableStatement objects, described in “Returning Unknown or Multiple Results”.
supportsGetGeneratedKeys — returns true if the driver or underlying data source supports the retrieval of automatically generated keys, described in “Retrieving Auto Generated Keys” A complete definition of these methods may be found in the JDBC 3.0 API specification (javadoc).

Modified Methods

The JDBC 3.0 API modifies the definitions of these existing DatabaseMetaData
methods, adding support for type hierarchies:

getTables — returns descriptions of the tables that match the given catalog, schema, table name, and type criteria
getColumns — returns descriptions of the columns that match the given catalog, schema, table name, and column name criteria
getUDTs — returns descriptions of the user-defined types that match the given catalog, schema, type name, and type criteria
getSchemas — now returns catalog for each schema as well as the schemata. The JDBC 3.0 API specification includes updated definitions of these methods.

Exceptions::JAVA-JDBC

2007-11-12T07:41:00.000-08:00

The SQLException class and its subtypes provide information about errors and
warnings that occur while a data source is being accessed.

SQLException

An instance of SQLException is thrown when an error occurs during an interaction
with a data source. The exception contains the following information:

a textual description of the error. The String containing the description can be retrieved by calling the method SQLException.getMessage.

a SQLState. The String containing the SQLState can be retrieved by calling the method SQLException.getSQLState.The value of the SQLState string will depend on the underlying data source setting the value. Both X/Open and SQL99 define SQLState values and the conditions in which they should be set. Although the sets of values overlap, the values defined by SQL99 are not a superset of X/Open.The DatabaseMetaData method getSQLStateType allows an application todetermine if the SQLStates being returned by a data source are X/Open or SQL99.

n an error code. This is an integer value identifying the error that caused the SQLException to be thrown. Its value and meaning are implementation specific and may be the actual error code returned by the underlying data source. The error code can be retrieved using the SQLException.getErrorCode method.

a reference to any "chained" exceptions. If more than one error occurs or the event leading up to the exception being thrown can be described as a chain of events, the exceptions are referenced via this chain. A chained exception can be retrieved by calling the SQLException.getNextException method on the exception that was thrown. If no more exceptions are chained, the getNextException method returns null. SQLWarning, BatchUpdateException and DataTruncation are the three subclasses that extend SQLException. These subclasses are described in the following sections.

SQLWarning

Methods in the following interfaces will generate an SQLWarning object if they cause a database access warning:

Connection
Statement and its subtypes, PreparedStatement and CallableStatement
ResultSet

When a method generates an SQLWarning object, the caller is not informed that a data access warning has occurred. The method getWarnings must be called on the appropriate object to retrieve the SQLWarning object. However, the DataTruncation sub-class of SQLWarning may be thrown in some circumstances, see “DataTruncation” on page 50 for more details.
If multiple data access warnings occur, they are chained to the first one and can be retrieved by calling the SQLWarning.getNextWarning method. If there are no more warnings in the chain, getNextWarning returns null. Subsequent SQLWarning objects continue to be added to the chain until the next statement is executed or, in the case of a ResultSet object, when the cursor is repositioned, at which point all SQLWarning objects in the chain are removed.

DataTruncation

The DataTruncation class, a sub-class of SQLWarning, provides information when data is truncated. When data truncation occurs on a write to the data source, a DataTruncation object is thrown. The data value that has been truncated may have been written to the data source even if a warning has been generated. When data trucation occurs on a read from the data source, a SQLWarning is reported. A DataTruncation object contains the following information:

the descriptive String "Data truncation"
the SQLState "01004"
a boolean to indicated whether a column value or a parameter was truncated. The method DataTruncation.getParameter returns true if a parameter wastruncated and false if a column value was truncated.
an int giving the index of the column or parameter that was truncated. If the index of the column or parameter is unknown, the method DataTruncation.getIndex returns -1. If the index is unknown, the values returned by the methods DataTruncation.getParameter and DataTruncation.getRead are undefined.
a boolean to indicate whether the truncation occurred on a read or a write operation. The method DataTruncation.getRead returns true if the truncation occurred on a read and false if the truncation occurred on a write.
an int indicating the the size of the target field in bytes. The method DataTruncation.getDataSize returns the number of bytes of data that could have been transferred or -1 if the number of bytes is unknown.
an int indicating the actual number of bytes that were transferred. The method DataTruncation.getTransferSize returns the number of bytes actually transferred or -1 if the number of bytes is unknown.

Silent Truncation

The Statement.setMaxFieldSize method allows a maximum size (in bytes) to
be set. This limit applies only to the BINARY, VARBINARY, LONGVARBINARY, CHAR,
VARCHAR and LONGVARCHAR data types.

If a limit has been set using setMaxFieldSize and there is an attempt to read or
write data that exceeds the limit, any truncation that occurs as a result of exceeding
the set limit will not be reported.

BatchUpdateException

A BatchUpdateException object provides information about errors that occur
while a batch of statements is being executed. This exception’s behavior is described
in “Batch Updates”.

Connections::Drivers

2007-11-12T07:33:00.000-08:00

A Connection object represents a connection to a data source via a JDBC technology-enabled driver. The data source can be a DBMS, a legacy file system, or some other source of data with a corresponding JDBC driver. A single application using the JDBC API may maintain multiple connections. These connections may access multiple data sources, or they may all access a single data source. From the JDBC driver perspective, a Connection object represents a client session. It has associated state information such as user ID, a set of SQL statements and result sets being used in that session, and what transaction semantics are in effect.

To obtain a connection, the application may interact with either:

the DriverManager class working with one or more Driver implementations OR
a DataSource implementation

Using a DataSource object is the preferred method because it enhances application portability, it makes code maintenance easier, and it makes it possible for an application to transparently make use of connection pooling and distributed transactions. All J2EE components that establish a connection to a data source use a DataSource object to get a connection. This chapter describes the various types of JDBC drivers and the use of the Driver interface, the DriverManager class, and the basic DataSource interface. DataSource implementations that support connection pooling and distributed transactions are discussed in Chapters “Distributed Transactions”.

Types of Drivers

There are many possible implementations of JDBC drivers. These implementations
are categorized as follows:

Type 1 — drivers that implement the JDBC API as a mapping to another data access API, such as ODBC. Drivers of this type are generally dependent on a native library, which limits their portability. The JDBC-ODBC Bridge driver is an

example of a Type 1 driver.

Type 2 — drivers that are written partly in the Java programming language and partly in native code. These drivers use a native client library specific to the data source to which they connect. Again, because of the native code, their portability is limited.

Type 3 — drivers that use a pure Java client and communicate with a middleware server using a database-independent protocol. The middleware server then communicates the client’s requests to the data source.

Type 4 — drivers that are pure Java and implement the network protocol for a specific data source. The client connects directly to the data source.

The Driver Interface

JDBC drivers must implement the Driver interface, and the implementation must contain a static initializer that will be called when the driver is loaded. This initializer registers a new instance of itself with the DriverManager, as shown in

CODE EXAMPLE 9-1.
public class AcmeJdbcDriver implements java.sql.Driver {
static {
java.sql.DriverManager.registerDriver(new AcmeJdbcDriver());
}
...
}
CODE EXAMPLE Example static initializer for a driver implementing
java.sql.Driver

When an application loads a Driver implementation, which is shown in
CODE EXAMPLE the static initializer will automatically register an instance of the driver.

Class.forName(“com.acme.jdbc.AcmeJdbcDriver”);

CODE EXAMPLE Loading a driver that implements java.sql.Driver To insure that drivers can be loaded using this mechanism, drivers are required to provide a niladic constructor.
The DriverManager class invokes Driver methods when it wishes to interact with a registered driver. The Driver interface also includes the method acceptsURL. The DriverManager can use this method to determine which of its registered drivers it should use for a given URL.
When the DriverManager is trying to establish a connection, it calls that driver’s connect method and passes the driver the URL. If the Driver implementation understands the URL, it will return a Connection object; otherwise it returns null.

The DriverManager Class

The DriverManager class works with the Driver interface to manage the set of drivers available to a JDBC client. When the client requests a connection and provides a URL, the DriverManager is responsible for finding a driver that recognizes the URL and using it to connect to the corresponding data source.
Key DriverManager methods include:

registerDriver — this method adds a driver to the set of available drivers and is invoked implicitly when the driver is loaded. The registerDriver method is typically called by the static initializer provided by each driver.

getConnection — the method the JDBC client invokes to establish a connection. The invocation includes a JDBC URL, which the DriverManager passes to each driver in its list until it finds one whose Driver.connect method recognizes the URL. That driver returns a Connection object to the DriverManager, which in turn passes it to the application.

CODE EXAMPLE illustrates how a JDBC client obtains a connection from the DriverManager.

// Load the driver. This creates an instance of the driver
// and calls the registerDriver method to make acme.db.Driver
// available to clients.
Class.forName(“acme.db.Driver”);
Chapter 9 Connections 56
// Set up arguments for the call to the getConnection method.
// The sub-protocol “odbc” in the driver URL indicates the
// use of the JDBC-ODBC bridge.
String url = “jdbc:odbc:DSN”;
String user = “SomeUser”;
String passwd = “SomePwd”;
// Get a connection from the first driver in the DriverManager
// list that recognizes the URL “jdbc:odbc:DSN”.
Connection con = DriverManager.getConnection(url, user, passwd);

CODE EXAMPLE Loading a driver and getting a connection using the DriverManager The DriverManager class also provides two other getConnection methods:

getConnection(String url) for connecting to data sources that do not use username and passwords.

getConnection(String url, java.util.Properties prop), which allows the client to connect using a set of properties describing the user name and password along with any addition information that may be required. The DriverPropertyInfo class provides information on the properties that the JDBC driver can understand. See the JDBC 3.0 API Specification for more details.

The SQLPermission Class

The SQLPermission class represents a set of permissions that a codebase may be
granted. Currently the only permission defined is setLog. The SecurityManager will check for the setLog permission when an Applet calls one of the DriverManager methods setLogWriter and setLogStream. If the codebase does not have the setLog permission a java.lang.SecurityException exception will be thrown. See the JDBC 3.0 API Specification for more details.

Connections::The DataSource Interface

2007-11-12T07:28:00.000-08:00

The DataSource Interface

The DataSource interface, introduced in JDBC 2.0 Optional Package, is the preferred approach to obtaining data source connections. A JDBC driver that implements the Datasource interface returns connections that implement the same interface, Connection, as those returned by a DriverManager using the Driver interface. Using a Datasource object increases application portability by making it possible for an application to use a logical name for a data source instead
of having to supply information specific to a particular driver. A logical name is mapped to a DataSource object via a naming service that uses the Java Naming and Directory InterfaceTM (JNDI). The DataSource object, represents a physical data source and provides connections to that data source. If the data source or information about it changes, the properties of the DataSource object can simply be modified to reflect the changes; no change in application code is necessary.

The DataSource interface can be implemented so that it transparently provides the
following:

Increased performance and scalability through connection pooling
Support for distributed transactions through the XADataSource interface

The next three sections discuss (1) basic DataSource properties, (2) how logical
naming using the JNDI API improves an applications portability and makes it easier
to maintain, and (3) how to obtain a connection.
Connection pooling and distributed transactions will be discussed in Chapter 11
“Connection Pooling” and Chapter 12 “Distributed Transactions”.

DataSource Properties

The JDBC API defines a set of properties to identify and describe a DataSource implementation. The actual set required for a specific implementation depends on the type of DataSource object, that is, whether it is a basic DataSource object, a ConnectionPoolDataSource object, or an XADataSource object. The only property required for all DataSource implementations is description.

DataSource properties follow the convention specified for properties of
JavaBeansTM components in the JavaBeans 1.01 Specification. DataSource
implementations may augment this set with implementation-specific properties. If
new properties are added, they must be given names that do not conflict with the
standard property names.DataSource implementations must provide “getter” and “setter” methods for eachproperty they support. These properties typically are initialized when the
DataSource object is deployed, as in

CODE EXAMPLE in which a VendorDataSource object implements the DataSource interface.

VendorDataSource vds = new VendorDataSource();
vds.setServerName(“my_database_server”);
String name = vds.getServerName();

CODE EXAMPLE Setting and getting a DataSource property DataSource properties are not intended to be directly accessible by JDBC clients. This design is reinforced by defining the access methods on the implementation class rather than on the public DataSource interface used by applications. Furthermore, the object that the client manipulates can be a wrapper that only implements the DataSource interface. The setter and getter methods for the properties need not be exposed to the client.

Management tools that need to manipulate the properties of a DataSource implementation can access those properties using introspection. The JNDI API and Application Portability
The Java Naming and Directory Interface (JNDI) API provides a uniform way for applications to access remote services over the network. This section describes how it is used to register and access a JDBC DataSource object. See the JNDI specification for a complete description of this interface. Using the JNDI API, applications can access a DataSource object by specifying its
logical name. A naming service using the JNDI API maps this logical name to a corresponding data source. This scheme greatly enhances portability because any of the DataSource properties, such as portNumber or serverName, can be changed without impacting the JDBC client code. In fact, the application can be re-directed to a different underlying data source in a completely transparent fashion. This is particularly useful in the three-tier environment, where an application server hides the details of accessing different data sources.

CODE EXAMPLE illustrates the use of a JNDI-based naming service to deploy a new VendorDataSource object.

// Create a VendorDataSource object and set some properties
VendorDataSource vds = new VendorDataSource();
vds.setServerName(“my_database_server”);
vds.setDatabaseName(“my_database”);
vds.setDescription(“data source for inventory and personnel”);
// Use the JNDI API to register the new VendorDataSource object.
// Reference the root JNDI naming context and then bind the
// logical name “jdbc/AcmeDB” to the new VendorDataSource object.
Context ctx = new InitialContext();
ctx.bind(“jdbc/AcmeDB”, vds);

CODE EXAMPLE Registering a DataSource object with a JNDI-based naming service
Note – J2EE components use a special convention for naming their data sources —
see Chapter 5 "Naming" in the J2EE platform specification for more details.

Getting a Connection with a DataSource Object

Once a DataSource object has been registered with a JNDI-based naming service,
an application can use it to obtain a connection to the physical data source that it
represents, as is done in

CODE EXAMPLE

// Get the initial JNDI naming context
Context ctx = new InitialContext();
// Get the DataSource object associated with the logical name
// “jdbc/AcmeDB” and use it to obtain a database connection
DataSource ds = (DataSource)ctx.lookup(“jdbc/AcmeDB”);
Connection con = ds.getConnection(“user”, “pwd”);

CODE EXAMPLE Getting a Connection object using a DataSource object
The DataSource implementation bound to the name “jdbc/AcmeDB” can be
modified or replaced without affecting the application code.

Transactions::JAVA-JDBC

2007-11-12T07:24:00.000-08:00

Transaction Boundaries and Autocommit

When to start a new transaction is a decision made implicitly by either the JDBC driver or the underlying data source. Although some data sources implement an explicit “begin transaction” statement, there is no JDBC API to do so. Typically, a new transaction is started when the current SQL statement requires one and there is no transaction already in place. Whether or not a given SQL statement requires a transaction is also specified by SQL99.

The Connection attribute auto-commit specifies when to end transactions. Enabling auto-commit causes the JDBC driver to do a transaction commit after each individual SQL statement as soon as it is complete. The point at which a statement is considered to be “complete” depends on the type of SQL statement as well as what the application does after executing it:

For Insert, Update, Delete, and DDL statements, the statement is complete as soon as it has finished executing.
For Select statements, the statement is complete when the associated result set is closed. The result set is closed as soon as one of the following occurs:
all of the rows have been retrieved
the associated Statement object is re-executed
For CallableStatement objects, the statement is complete when all of the associated result sets have been closed.

Disabling Auto-commit Mode

CODE EXAMPLE shows how to disable auto-commit mode.

// Assume con is a Connection object
con.setAutoCommit(false);

CODE EXAMPLE Setting auto-commit off When auto-commit is disabled, each transaction must be explicitly commited by calling the Connection method commit or explicitly rolled back by calling the Connection method rollback, respectively. This is appropriate for cases where transaction management is being done in a layer above the driver, such as:

when the application needs to group multiple SQL statements into a single transaction
when the transaction is being managed by the application server

The default is for auto-commit mode to be enabled when the Connection object is created. If the value of auto-commit is changed in the middle of a transaction, the current transaction is committed. It is an error to enable auto-commit for a connection participating in a distributed transaction, as described in “Distributed Transactions”.

Transactions::Transaction Isolation Levels

2007-11-12T07:20:00.000-08:00

Transaction Isolation Levels

Transaction isolation levels specify what data is “visible” to the statements within a
transaction. They directly impact the level of concurrent access by defining what
interaction, if any, is possible between transactions against the same target data
source. Possible interaction between concurrent transactions is categorized as
follows:

dirty reads occur when transactions are allowed to see uncommitted changes to the data. In other words, changes made inside a transaction are visible outside the transaction before it is commited. If the changes are rolled back instead of being committed, it is possible for other transactions to have done work based on incorrect, transient data.

nonrepeatable reads occur when:

a. Transaction A reads a row
b. Transaction B changes the row
c. Transaction A reads the same row a second time and gets different results

phantom reads occur when:

a. Transaction A reads all rows that satisfy a WHERE condition
b. Transaction B inserts an additional row that satisfies the same condition
c. Transaction A reevaluates the WHERE condition and picks up the additional “phantom” row

JDBC augments the four levels of transaction isolation defined by SQL99, by adding
TRANSACTION_NONE. From least restrictive to most restrictive, the transaction
isolation levels are:

1. TRANSACTION_NONE — indicates that the driver does not support transactions,
which means that it is not a JDBC compliant driver.
2. TRANSACTION_READ_UNCOMMITTED — allows transactions to see uncommitted
changes to the data. This means that dirty reads, nonrepeatable reads, and
phantom reads are possible.
3. TRANSACTION_READ_COMMITTED — means that any changes made inside a
transaction are not visible outside the transaction until the transaction is
committed. This prevents dirty reads, but nonrepeatable reads and phantom
reads are still possible.
4. TRANSACTION_REPEATABLE_READ — disallows dirty reads and nonrepeatable
reads. Phantom read are still possible.
5. TRANSACTION_SERIALIZABLE — specifies that dirty reads, nonrepeatable reads,
and phantom reads are prevented.

Using the setTransactionIsolation Method

The default transaction level for a Connection object is determined by the driver
supplying the connection. Typically, it is the default transaction level supported by
the underlying data source.

The Connection method setTransactionIsolation is provided to allow JDBC clients to change the transaction isolation level for a given Connection object. The new isolation level remains in effect for the remainder of the session or until the next invocation of the setTransactionIsolation method. The result of invoking the method setTransactionIsolation in the middle of a transaction is implementation-defined. The return value of the method getTransactionIsolation should reflect the change in isolation level when it actually occurs. It is recommended that drivers implement the setTransactionIsolation method to change the isolation level
starting with the next transaction. Committing the current transaction to make the effect immediate is also a valid implementation. It is possible for a given JDBC driver to not support all four transaction isolation levels (not counting TRANSACTION_NONE). If a driver does not support the isolation level specified in an invocation of setTransactionIsolation, it is allowed to
substitute a higher, more restrictive transaction isolation level. If a driver is unable to substitute a higher transaction level, it throws an SQLException. The DatabaseMetaData method supportsTransactionIsolationLevel may be used to determine whether or not the driver supports a given level.

Performance Considerations

As the transaction isolation level increases, more locking and other DBMS overhead is required to ensure the correct semantics. This in turn lowers the degree of concurrent access that can be supported. As a result, applications may see decreased performance when they use a higher transaction isolation level. For this reason, the transaction manager, whether it is the application itself or part of the application server, should weigh the need for data consistency against the requirements for performance when determining which transaction isolation level is appropriate.

Transactions::SavePoints

2007-11-12T07:16:00.000-08:00

Savepoints

Savepoints provide finer-grained control of transactions by marking intermediate points within a transaction. Once a savepoint has been set, the transaction can be rolled back to that savepoint without affecting preceding work. The DatabaseMetaData.supportsSavepoints method can be used to determine whether a JDBC driver and DBMS support savepoints.

Setting and Rolling Back to a Savepoint

The JDBC 3.0 API adds the method Connection.setSavepoint, which sets a savepoint within the current transaction. The Connection.rollback method has been overloaded to take a savepoint argument.

CODE EXAMPLE inserts a row into a table, sets the savepoint svpt1, and then inserts a second row. When the transaction is later rolled back to svpt1, the second insertion is undone, but the first insertion remains intact. In other words, when the transaction is committed, only the row containing ’FIRST’ will be added to TAB1.

conn.createStatement();
int rows = stmt.executeUpdate("INSERT INTO TAB1 (COL1) VALUES " +
"(’FIRST’)");
// set savepoint
Savepoint svpt1 = conn.setSavepoint("SAVEPOINT_1");
rows = stmt.executeUpdate("INSERT INTO TAB1 (COL1) " +
"VALUES (’SECOND’)");
...
conn.rollback(svpt1);
...
conn.commit();

CODE EXAMPLE Rolling back a transaction to a savepoint

Releasing a Savepoint

The method Connection.releaseSavepoint takes a Savepoint object as a parameter and removes it from the current transaction. Once a savepoint has been released, attempting to reference it in a rollback operation will cause an SQLException to be thrown. Any savepoints that have been created in a transaction are automatically released and become invalid when the transaction is committed or when the entire transaction is rolled back. Rolling a transaction back to a savepoint automatically releases and makes invalid any other savepoints that were created after the savepoint in question

Connection Pooling2:JAVA-JDBC

2007-11-12T06:36:00.000-08:00

In a basic DataSource implementation, there is a 1:1 correspondence between the
client’s Connection object and the physical database connection. When the Connection object is closed, the physical connection is dropped. Thus, the overhead of opening, initializing, and closing the physical connection is incurred for each client session. A connection pool solves this problem by maintaining a cache of physical database connections that can be reused across client sessions. Connection pooling greatly improves performance and scalability, particularly in a three-tier environment where multiple clients can share a smaller number of physical database connections. In

The algorithm used to manage the connection pool is implementation-specific and varies with application servers. The application server provides its clients with an implementation of the DataSource interface that makes connection pooling transparent to the client. As a result, the client gets better performance and scalability while using the same JNDI and DataSource APIs as before.

This chapter also describes some important differences

Application Server
JDBC
Application
Cache of
PooledConnection objects
JDBC Driver
logical
Connection
object
physical
PooledConnection
object
ConnectionPoolDataSource API
DataSource API

between a basic DataSource object and one that implements connection pooling. In addition, it discusses how a pooled connection can maintain a pool of reusable PrepredStatement objects.
Although much of the discussion in this chapter assumes a three-tier environment, connection pooling is also relevant in a two-tier environment. In a two-tier environment, the JDBC driver implements both the DataSource and ConnectionPoolDataSource interfaces. This implementation allows an application that opens and closes multiple connections to benefit from connection pooling.

ConnectionPoolDataSource and PooledConnection

Typically, a JDBC driver implements the ConnectionPoolDataSource interface, and the application server uses it to obtain PooledConnection objects.
CODE EXAMPLE shows the signatures for the two versions of the getPooledConnection method.

public interface ConnectionPoolDataSource {
PooledConnection getPooledConnection() throws SQLException;
PooledConnection getPooledConnection(String user,
String password) throws SQLException;
...
}

CODE EXAMPLE The ConnectionPoolDataSource interface A PooledConnection object represents a physical connection to a data source. The JDBC driver’s implementation of PooledConnection encapsulates all of the details of maintaining that connection. An application server caches and reuses PooledConnection objects within its implementation of the DataSource interface. When a client calls the method DataSource.getConnection, the application server uses the physical PooledConnection object to obtain a logical Connection object.

CODE EXAMPLE shows the PooledConnection interface definition.

public interface PooledConnection {
Connection getConnection() throws SQLException;
void close() throws SQLException;
void addConnectionEventListener(
ConnectionEventListener listener);
void removeConnectionEventListener(
ConnectionEventListener listener);
}

CODE EXAMPLE The PooledConnection interface When an application is finished using a connection, it closes the logical connection using the method Connection.close. This closes the logical connection but does not close the physical connection. Instead, the physical connection is returned to the pool so that it can be reused. Connection pooling is completely transparent to the client: A client obtains a pooled connection and uses it just the same way it obtains and uses a nonpooled connection.

Connection Events

Recall that when an application calls the method Connection.close, the underlying physical connection—the PooledConnection object—is available for reuse. JavaBeans-style events are used to notify the connection pool manager (the application server) that a PooledConnection object can be recycled. In order to be notified of an event on a PooledConnection object, the connection pool manager must implement the ConnectionEventListener interface and then
be registered as a listener by that PooledConnection object. The ConnectionEventListener interface defines the following two methods, which correspond to the two kinds of events that can occur on a PooledConnection object:

connectionClosed — triggered when the logical Connection object associated with this PooledConnection object is closed, that is, the application called the method Connection.close
connectionErrorOccurred — triggered when a fatal error, such as the server crashing, causes the connection to be lost

A connection pool manager registers itself as a listener for a PooledConnection object using the PooledConnection.addConnectionEventListener method. Typically, a connection pool manager registers itself as a ConnectionEventListener before returning a Connection object to an
application. The driver invokes the ConnectionEventListener methods connectionClosed and connectionErrorOccurred when the corresponding events occur. Both methods take a ConnectionEvent object as a parameter, which can be used to determine which PooledConnection object was closed or had an error. When the JDBC application closes its logical connection, the JDBC driver notifies the connection pool manager (the listener) by calling the listener’s implementation of the method connectionClosed. At this point, the connection pool manager can return the PooledConnection object to the pool for reuse. When an error occurs, the JDBC driver notifies the listener by calling its connectionErrorOccurred method and then throws an SQLException object to the application to notify it of the same error. In the event of a fatal error, the bad PooledConnection object is not returned to the pool. Instead, the connection pool manager calls the PooledConnection.close method on the PooledConnection object to close the physical connection.

Connection Pooling in a Three-tier Environment

The following sequence of steps outlines what happens when a JDBC client requests a connection from a DataSource object that implements connection pooling:

The client calls DataSource.getConnection.
The application server providing the DataSource implementation looks in its

connection pool to see if there is a suitable PooledConnection object— a physical database connection—available. Determining the suitability of a given PooledConnection object may include matching the client’s user authentication information or application type as well as using other implementation-specific criteria. The lookup method and other methods associated with managing the connection pool are specific to the application server.

If there are no suitable PooledConnection objects available, the application server calls the ConnectionPoolDataSource.getPooledConnection method to get a new physical connection. The JDBC driver implementing ConnectionPoolDataSource creates a newPooledConnection object and returns it to the application server.

Regardless of whether the PooledConnection was retrieved from the pool or was newly created, the application server does some internal bookkeeping to indicate that the physical connection is now in use.
The application server calls the method PooledConnection.getConnection to get a logical Connection object. This logical Connection object is actually a “handle” to a physical PooledConnection object, and it is this handle that is returned by the DataSource.getConnection method when connection pooling is in effect.

The application server registers itself as a ConnectionEventListener by calling the method PooledConnection.addConnectionEventListener. This is done so that the application server will be notified when the physical connection is available for reuse.

The logical Connection object is returned to the JDBC client, which uses the same Connection API as in the basic DataSource case. Note that the underlying physical connection cannot be reused until the client calls the method Connection.close. Connection pooling can also be implemented in a two-tier environment where there is no application server. In this case, the JDBC driver provides both the implementation of DataSource which is visible to the client and the underlying ConnectionPoolDataSource implementation.

DataSource Implementations and Connection Pooling

Aside from improved performance and scalability, a JDBC application should not see any difference between accessing a DataSource object that implements connection pooling and one that does not. However, there are some important differences in the application server and driver level implementations. A basic DataSource implementation, that is, one that does not implement connection pooling, is typically provided by a JDBC driver vendor. In a basic
DataSource implementation, the following are true:

The DataSource.getConnection method creates a new Connection object that represents a physical connection and encapsulates all of the work to set up and manage that connection.
The Connection.close method shuts down the physical connection and frees the associated resources. In a DataSource implementation that includes connection pooling, a great deal happens behind the scenes. In such an implementation, the following are true:
The DataSource implementation includes an implementation-specific connection pooling module that manages a cache of PooledConnection objects. The DataSource object is typically implemented by the application server as a layer on top of the driver’s implementations of the ConnectionPoolDataSource and PooledConnection interfaces.
The DataSource.getConnection method calls PooledConnection.getConnection to get a logical handle to an underlying physical connection. The overhead of setting up a new physical connection is incurred only if there are no existing connections available in the connection pool. When a new physical connection is needed, the connection pool manager will call the ConnectionPoolDataSource method getPooledConnection to create one. The work to manage the physical connection is delegated to the PooledConnection object.

The Connection.close method closes the logical handle, but the physical connection is maintained. The connection pool manager is notified that the underlying PooledConnection object is now available for reuse. If the application attempts to reuse the logical handle, the Connection implementation throws an SQLException.

A single physical PooledConnection object may generate many logical Connection objects during its lifetime. For a given PooledConnection object, only the most recently produced logical Connection object will be valid. Any previously existing Connection object is automatically closed when the associated PooledConnection.getConnection method is called. Listeners (connection pool managers) are not notified in this case. This gives the application server a way to take a connection away from a client. This is an unlikely scenario but may be useful if the application server is trying to force an orderly shutdown.

A connection pool manager shuts down a physical connection by calling the method PooledConnection.close. This method is typically called only in certain circumstances: when the application server is undergoing an orderly shutdown, when the connection cache is being reinitialized, or when the application server receives an event indicating that an unrecoverable error has occurred on the connection.

Deployment

Deploying a DataSource object that implements connection pooling requires that both a client-visible DataSource object and an underlying ConnectionPoolDataSource object be registered with a JNDI-based naming service.

The first step is to deploy the ConnectionPoolDataSource implementation, as is
done in CODE EXAMPLE

// ConnectionPoolDS implements the ConnectionPoolDataSource
// interface. Create an instance and set properties.
com.acme.jdbc.ConnectionPoolDS cpds =
new com.acme.jdbc.ConnectionPoolDS();
cpds.setServerName(“bookserver”);
cpds.setDatabaseName(“booklist”);
cpds.setPortNumber(9040);
cpds.setDescription(“Connection pooling for bookserver”);
// Register the ConnectionPoolDS with JNDI, using the logical name
// “jdbc/pool/bookserver_pool”
Context ctx = new InitialContext();
ctx.bind(“jdbc/pool/bookserver_pool”, cpds);
CODE EXAMPLE 11-3 Deploying a ConnectionPoolDataSource object
Once this step is complete, the ConnectionPoolDataSource implementation is
available as a foundation for the client-visible DataSource implementation. The
DataSource implementation is deployed such that it references the
ConnectionPoolDataSource implementation, as shown in CODE EXAMPLE 11-4.
// PooledDataSource implements the DataSource interface.
// Create an instance and set properties.
com.acme.appserver.PooledDataSource ds =
new com.acme.appserver.PooledDataSource();
ds.setDescription(“Datasource with connection pooling”);
// Reference the previously registered ConnectionPoolDataSource
ds.setDataSourceName(“jdbc/pool/bookserver_pool”);
// Register the DataSource implementation with JNDI, using the logical
// name “jdbc/bookserver”.
Context ctx = new InitialContext();
ctx.bind(“jdbc/bookserver”, ds);
CODE EXAMPLE Deploying a DataSource object backed by a
ConnectionPoolDataSource object

Connection Pooling

2007-11-12T06:26:00.000-08:00

Reuse of Statements by Pooled Connections

The JDBC 3.0 specification introduces the feature of statement pooling. This feature, which allows an application to reuse a PreparedStatement object in much the same way it can reuse a connection, is made available through a pooled connection. FIGURE 11-2 provides a logical view of how a pool of PreparedStatement objects can be associated with a PooledConnection object. As with the PooledConnection object itself, the PreparedStatement objects can be reused
by multiple logical connections in a transparent manner.

Using a Pooled Statement

If a pooled connection reuses statements, the reuse must be completely transparent to an application. In other words, from the application’s point of view, using a PreparedStatement object that participates in statement pooling is exactly the

JDBC
Application
JDBC
Application
data source
PooledConnection
PooledConnection
Connection Pool
Application Server
Pool of
PreparedStatement
Objects
Pool of
PreparedStatement
Objects

same as using one that does not. Statements are kept open for reuse entirely under the covers, so there is no change in application code. If an application closes a PreparedStatement object, it must still call Connection.prepareStatement in order to use it again. The only visible effect of statement pooling is a possible improvement in performance. An application may find out whether a data source supports statement pooling by calling the DatabaseMetaData method supportsStatementPooling. If the return value is true, the application can then choose to use PreparedStatement objects knowing that they are being pooled. In many cases, reusing statements is a significant optimization. This is especially true for complex prepared statements. However, it should also be noted that leaving large numbers of statements open may have an adverse impact on the use of resources.

Closing a Pooled Statement

An application closes a pooled statement exactly the same way it closes a nonpooled statement. Whether it is pooled or not, a statement that has been closed is no longer available for use by the application, and an attempt to reuse it will cause an exception to be thrown.

The following methods can close a pooled statement:

Statement.close — called by an application; if the statement is being pooled, closes the logical statement used by the application but does not close the physical statement being pooled
Connection.close — called by an application
Nonpooled connection — closes the physical connection and all statements created by that connection. This is necessary because the garbage collection mechanism is unable to detect when externally managed resources can be released.
Pooled connection — closes the logical connection and the logical statements it returned but leaves open the underlying PooledConnection object and any associated pooled statements
PooledConnection.closeAll — called by the connection pool manager to close all of the physical statements being pooled by the PooledConnection object

An application cannot directly close a physical statement that is being pooled; instead, this is done by the connection pool manager. The method PooledConnection.closeAll closes all of the statements open on a given physical connection, which releases the resources associated with those statements.

An application also has no direct control over how statements are pooled. A pool of statements is associated with a PooledConnection object, whose behaviour is determined by the properties of the ConnectionPoolDataSource object that produced it. “ConnectionPoolDataSource Properties” discusses these properties.

ConnectionPoolDataSource Properties

As with the DataSource interface, the JDBC API defines a set of properties that can used to configure the behaviour of connection pools. These are shown in Connection pool configuration properties follow the convention specified for JavaBeans components in the JavaBeans specification. Connection pool vendors may choose to augment this set with implementation-specific properties. If so, the additional properties must be given names that do not conflict with the standard property names.

Standard Connection Pool Properties

Property Name Type Description maxStatements int The total number of statements that the pool should keep open. 0 (zero) indicates that caching of statements is disabled. initialPoolSize int The number of physical connections the pool should contain when it is created minPoolSize int The number of physical connections the pool should keep available at all times. 0 (zero) indicates that connections should be created as needed. maxPoolSize int The maximum number of physical connections that the pool should contain. 0 (zero) indicates no maximum size.
maxIdleTime int The number of seconds that a physical connection should remain unused in the pool before the connection is closed. 0 (zero) indicates no limit. propertyCycle int The interval, in seconds, that the pool should wait before enforcing the current policy defined by the values of the above connection pool properties

Like DataSource implementations, ConnectionPoolDataSource implementations must provide “getter” and “setter” methods for each property they support. These properties are typically initialized when the ConnectionPoolDataSource object is deployed.

CODE EXAMPLE illustratessetting properties in a vendor’s implementation of the ConnectionPoolDataSource interface.

VendorConnectionPoolDS vcp = new VendorConnectionPoolDS();
vcp.setMaxStatements(25);
vcp.setInitialPoolSize(10);
vcp.setMinPoolSize(1);
vcp.setMaxPoolSize(0);
vcp.setMaxIdleTime(0);
vcp.setPropertyCycle(300);

CODE EXAMPLE Setting connection pool configuration properties The properties set on a ConnectionPoolDataSource object apply to the PooledConnection objects that it creates. An application server managing a pool of PooledConnection objects uses these properties to determine how to manage its pool. ConnectionPoolDataSource configuration properties are not intended to be directly accessible by JDBC clients. Management tools that need to manipulate the properties of a ConnectionPoolDataSource implementation can access those properties using introspection.

Distributed Transactions

2007-11-12T06:24:00.000-08:00

Up to this point, the discussion of transactions has focused on the local case—
transactions involving a single data source. This chapter introduces the distributed
case where a single transaction involves multiple connections to one or more
underlying data sources.

The following discussion includes these topics:

distributed transaction infrastructure
transaction managers and resource managers
the XADataSource, XAConnection, and XAResource interfaces
two-phase commit

Transaction management in the JDBC API is designed to fit with the Java Transaction
APITM (JTATM) . The examples presented here are high-level; the JTA specification
should be consulted for a more substantial discussion.

Infrastructure

Distributed transactions require an infrastructure that provides these roles:

Transaction manager — controls transaction boundaries and manages the twophase commit protocol. This typically will be an implementation of JTA.
JDBC drivers that implement the XADataSource, XAConnection, and XAResource interfaces. These are described in the next section.
An application-visible implementation of DataSource to “sit on top of” each XADataSource object and interact with the transaction manager. The DataSource implementation is typically provided by an application server. Because the XADataSource interface extends the ConnectionPoolDataSource interface, the DataSource implementation will usually include a connection pooling module as well.
Resource manager(s) to manage the underlying data. In the context of the JDBC

API, a resource manager is a DBMS server. The term “resource manager” is borrowed from JTA to emphasize the point that distributed transactions using the JDBC API follow the architecture specified in that document. This infrastructure is most often implemented in a three-tier architecture that includes the following:

1. A client tier
2. A middle tier that includes applications, an EJB server working with an external transaction manager, and a set of JDBC drivers
3. Multiple resource managers

Distributed transactions can also be implemented in two tiers. In a two-tier
architecture, the application itself acts as the transaction manager and interacts
directly with the JDBC drivers’ XADataSource implementations.
The following diagram illustrates the distributed transaction infrastructure:

Distributed Transactions::JAVA-JDBC2

2007-11-12T06:07:00.000-08:00

XADataSource and XAConnection

The XADataSource and XAConnection interfaces, which are defined in the package javax.sql, are implemented by JDBC drivers that support distributed transactions. An XAConnection object is a pooled connection that can participate in a distributed transaction. More precisely, XAConnection extends the PooledConnection interface by adding the method getXAResource. This method produces an XAResource object that can be used by a transaction manager to coordinate the work done on this connection with the other participants in the distributed transaction.

CODE EXAMPLE gives the definition of the XAConnection interface.

public interface XAConnection extends PooledConnection {
javax.transaction.xa.XAResource getXAResource()
throws SQLException;
}

CODE EXAMPLE The XAConnection interface Because they extend the PooledConnection interface, XAConnection objects support all the methods of PooledConnection objects. They are reusable physical connections to an underlying data source and produce logical connection handles that can be passed back to a JDBC application. XAConnection objects are produced by an XADataSource object. There is some similarity between ConnectionPoolDataSource objects and XADataSource objects in that they are both implemented below a DataSource layer that is visible to the JDBC application. This architecture allows JDBC drivers to support distributed transactions in a way that is transparent to the application.

CODE EXAMPLE shows the signatures for the two getXAConnection methods

defined in XADataSource.
public interface XADataSource {
XAConnection getXAConnection() throws SQLException;
XAConnection getXAConnection(String user,
String password) throws SQLException;
...
}

CODE EXAMPLE The XADataSource interface Typically, DataSource implementations built on top of an XADataSource implementation will also include a connection pooling module.
12.2.1 Deploying an XADataSource Object Deploying an XADataSource object is done in exactly the same manner as previously described for ConnectionPoolDataSource objects. The two-step
process includes deploying the XADataSource object and the application-visible DataSource object, as is done in

CODE EXAMPLE

// com.acme.jdbc.XADataSource implements the
// XADataSource interface.
// Create an instance and set properties.
com.acme.jdbc.XADataSource xads = new com.acme.jdbc.XADataSource();
xads.setServerName(“bookstore”);
xads.setDatabaseName(“bookinventory”);
xads.setPortNumber(9040);
xads.setDescription(“XADataSource for inventory”);
// First register xads with a JNDI naming service, using the
// logical name “jdbc/xa/inventory_xa”
Context ctx = new InitialContext();
ctx.bind(“jdbc/xa/inventory_xa”, xads);
// Next register the overlying DataSource object for application
// access. com.acme.appserver.DataSource is an implementation of
// the DataSource interface.
// Create an instance and set properties.
com.acme.appserver.DataSource ds =
new com.acme.appserver.DataSource();
ds.setDescription(“Datasource supporting distributed transactions”);
// Reference the previously registered XADataSource
ds.setDataSourceName(“jdbc/xa/inventory_xa”);
// Register the DataSource implementation with a JNDI naming service,
// using the logical name “jdbc/inventory”.
ctx.bind(“jdbc/inventory”, ds);

CODE EXAMPLE Deploying a DataSource object backed by an XADataSource object

Getting a Connection

As in the connection pooling case, the application call to the method DataSource.getConnection returns a logical handle produced by the physical XAConnection object. The application code to get a logical connection is shown in

CODE EXAMPLE

Context ctx = new InitialContext();
DataSource ds = (DataSource)ctx.lookup(“jdbc/inventory”);
Connection con = ds.getConnection(“myID”,“mypasswd”);

CODE EXAMPLE Application code to get a logical connection
CODE EXAMPLE is an example of code from the middle-tier server’s implementation of the method DataSource.getConnection.

// Assume xads is a driver’s implementation of XADataSource
XADataSource xads = (XADataSource)ctx.lookup(“jdbc/xa/" +
"inventory_xa”);
// xacon implements XAConnection
XAConnection xacon = xads.getXAConnection(“myID”, “mypasswd”);
// Get a logical connection to pass back up to the application
Connection con = xacon.getConnection();

CODE EXAMPLE Getting a logical connection from an XAConnection object

XAResource

The XAResource interface is defined in the JTA specification and is the mapping in the Java programming language of the X/Open Group XA interface. An XAResource object is produced by calling the XAConnection.getXAResource method and is used to associate an XAConnection object with a distributed transaction. A given XAConnection object may be associated with at most one transaction at a time. The JDBC driver maintains a one-to-one correspondence
between an XAResource object and its associated XAConnection object; that is, multiple calls to the getXAResource method must all return the same object. In a typical scenario, the middle-tier application server calls the method XAConnection.getXAResource and passes the returned object to an external transaction manager. The transaction manager uses the XAResource object exclusively—it does not access an XAConnection object directly. The transaction manager coordinates the work of multiple XAResource objects, each of which represents a resource manager participating in the distributed transaction. Note that two XAResource objects may “point” to the same resource manager, that is, they may be associated with XAConnection objects that were produced by the same XADataSource. The following XAResource methods are used by the transaction manager to implement a two-phase commit protocol.

Each method takes an xid parameter that identifies the distributed transaction:

start — tells the resource manager that the subsequent operations are part of the distributed transaction.
end — marks the end of this resource manager’s part of the distributed transaction.
prepare — gets the resource manager’s vote on whether to commit or roll back the distributed transaction.
commit — tells the resource manager to commit its part of the distributed transaction. This method is invoked only if all the participating resource managers voted to commit the transaction.
rollback — tells the resource manager to roll back its part of the distributed transaction. This method is invoked if one or more of the participating resource managers voted to roll back the transaction.

See the JTA specification for a complete description of the XAResouce interface.

Transaction Management

Participation in a distributed transaction is defined as the work done between invocations of the methods XAResource.start and XAResource.end. Outside these boundaries, the transaction mode is local, and a connection behaves exactly like a local connection. With one exception, there is no difference in how an application participating in a distributed transaction is coded. In contrast to the local case, the boundaries of a distributed transaction must be controlled by an external transaction manager that is coordinating the work of multiple connections. For this reason, it is an error for applications to call any of the following Connection methods while they are participating in a distributed transaction:

setAutoCommit(true)
commit
rollback
setSavepoint

Distributed Transactions::JAVA-JDBC3

2007-11-12T06:00:00.000-08:00

Transaction Management

Participation in a distributed transaction is defined as the work done between invocations of the methods XAResource.start and XAResource.end. Outside these boundaries, the transaction mode is local, and a connection behaves exactly like a local connection. With one exception, there is no difference in how an application participating in a distributed transaction is coded. In contrast to the local case, the boundaries of a distributed transaction must be controlled by an external transaction manager that is coordinating the work of multiple connections. For this reason, it is an error for applications to call any of the following Connection methods while they are participating in a distributed transaction:

setAutoCommit(true)
commit
rollback
setSavepoint

The JDBC driver throws an SQLException if one of these operations is attempted on a connection that is participating in a distributed transaction. If the connection is later used for a local transaction, these operations are legal at that point. Applications should also refrain from calling Connection.setTransactionIsolation within the bounds of a distributed transaction. The resulting behavior is implementation-defined. If a connection has auto-commit mode already enabled at the time it joins a global transaction, the attribute will be ignored. The auto-commit behavior will resume when the connection returns to local transaction mode.

Two-phase Commit

The following steps outline how a transaction manager uses XAResource objects to implement the two-phase commit protocol. These steps assume a three-tier architecture where an application server is working with an external transaction manager:

1. The application server gets XAResource objects from two different connections:
// XAConA connects to resource manager A
javax.transaction.xa.XAResource resourceA = XAConA.getXAResource();

// XAConB connects to resource manager B
javax.transaction.xa.XAResource resourceB = XAConB.getXAResource();

CODE EXAMPLE Getting the XAResource object from an XAConnection object

2. The application server passes the XAResource objects to the transaction manager.
The transaction manager does not access the associated XAConnection objects
directly.
3. The transaction manager uses the XAResource objects to assign a piece of the
transaction to each of the associated resource managers. The transaction is
identified by xid, which represents the identifier generated by the transaction
manager when the transaction is created.

// Send work to resource manager A. The TMNOFLAGS argument indicates
// we are starting a new branch of the transaction, not joining or
// resuming an existing branch.
resourceA.start(xid, javax.transaction.xa.TMNOFLAGS);
// do work with resource manager A
...
// tell resource manager A that it’s done, and no errors have occurred
resourceA.end(xid, javax.transaction.xa.TMSUCCESS);
// do work with resource manager B.
resourceB.start(xid, javax.transaction.xa.TMNOFLAGS);
// B’s part of the distributed transaction
...
resourceB.end(xid, javax.transaction.xa.TMSUCCESS);
CODE EXAMPLE Starting and ending transaction branches using the XAResource interface
4. The transaction manager initiates the two-phase commit protocol by asking each participant to vote:

resourceA.prepare(xid);
resourceB.prepare(xid);

CODE EXAMPLE Initiating two-phase commit A participating resource manager can vote to roll back the transaction by throwing a javax.transaction.xa.XAException.

5. If both participants vote to commit, the transaction manager tells each one to commit its piece of the distributed transaction (the second parameter tells the resource manager not to use a one phase commit protocol on behalf of the xid):

resourceA.commit(xid, false);
resourceB.commit(xid, false);

CODE EXAMPLE Committing the distributed transaction

6. If either resource manager votes to roll back, the transaction manager tells each one to roll back its piece of the transaction:

resourceA.rollback(xid);
resourceB.rollback(xid);

CODE EXAMPLE Rolling back the distributed transaction The transaction manager is not required to use the same XAResource object to commit/rollback a transaction branch as was used to execute the branch. If different XAResource objects are used, however, they must be associated with XAConnection objects that connect to the same resource manager.
Note – Steps 1-6 also apply to the case where XAConA and XAConB are two physical
connections to the same resource manager.

Closing the Connection

In a typical distributed transaction environment, the middle-tier server needs to be notified when an application has finished using a connection. As in the earlier discussion of PooledConnection objects, the middle-tier server will add itself as a ConnectionEventListener so that it will be notified when the application calls the method Connection.close. At this point, the server will notify the transaction manager so that it can end the transaction branch for the corresponding XAResource object. If the server’s DataSource implementation includes connection pooling, the connection pooling module will be notified that it can return the physical XAConnection object to the pool.

Note – A distributed transaction may still be active after a participating Connection object is closed. This is not true for local transactions.

Limitations of the XAResource Interface

The javax.transaction.xa.XAResource interface is limited to defining only the set of methods needed to join and participate in global transactions, as defined by the X/Open XA standard. This allows any resource manager that implements the interface to participate with any other resource manager or transaction manager that has the same level of support. Functionality that is not defined in the X/Open standard is correspondingly not defined in the XAResource interface. Resource managers that provide for support of features not defined in the X/Open XA standard, such as setting isolation levels in global transactions, will have to do so in an implementation-defined way. Users who use implementation-defined features should be aware that they will limit the portability of their applications.

Statement::JAVA-JDBC1

2007-11-12T05:52:00.000-08:00

The Statement Interface

The Statement interface defines methods for executing SQL statements that do not
contain parameter markers. The PreparedStatement interface adds methods for
setting input parameters, and the CallableStatement interface adds methods for
retrieving output parameter values returned from stored procedures.

Creating Statements

Statement objects are created by Connection objects, as is done in
CODE EXAMPLE

Connection conn = dataSource.getConnection(user, passwd);
Statement stmt = conn.createStatement()

CODE EXAMPLE Creating a Statement object Each Connection object can create multiple Statement objects that may be usedconcurrently by the program. This is demonstrated in CODE EXAMPLE

// get a connection from the DataSource object ds
Connection conn = ds.getConnection(user, passwd);
// create two instances of Statement
Statement stmt1 = conn.createStatement();
Statement stmt2 = conn.createStatement();

CODE EXAMPLE Creating multiple Statement objects from a single connection'

Setting ResultSet Characteristics

Additional constructors may be used to set the type and concurrency or the type, concurrency, and holdability of any result sets produced by a statement. See

CODE EXAMPLE creates a Statement object that returns result sets that are scrollable, that are insensitive to changes made while the ResultSet object is open, that can be updated, and that do not close the ResultSet objects when commit is called.

Connection conn = ds.getConnection(user, passwd);
Statement stmt = conn.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_UPDATABLE,
ResultSet.HOLD_CURSOR_OVER_COMMIT);

CODE EXAMPLE Creating a scrollable, insensitive, updatable result set that stays open
after the method commit is called

Executing Statement Objects

The method used to execute a Statement object depends on the type of SQL statement being executed. If the Statement object represents an SQL query returning a ResultSet object, the method executeQuery should be used. If the SQL is known to be a DDL statement or a DML statement returning an update count, the method executeUpdate should be used. If the type of the SQL statement is not known, the method execute should be used.

Returning a ResultSet object

CODE EXAMPLE shows the execution of an SQL string returning a ResultSet object.

Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(“select TITLE, AUTHOR, ISBN " +
"from BOOKLIST”);
while (rs.next()){
...
}

CODE EXAMPLE Executing a Statement object that returns a ResultSet object If the SQL string being executed does not return a ResultSet object, the method executeQuery throws an SQLException.

Returning an Update Count

In CODE EXAMPLE the SQL statement being executed returns the number of rows affected by the update.

Statement stmt = conn.createStatement();
int rows = stmt.executeUpdate(“update STOCK set ORDER = ‘Y’ " +
"where SUPPLY = 0”);
if (rows > 0) {
...
}

CODE EXAMPLE Executing a Statement object that returns an update count The method executeUpdate throws an SQLException if the SQL string being executed does not return an update count.

Using the Method execute

The method execute should be used only when the SQL string being executed could return either an update count or a ResultSet object. The execute method returns true if the first result is a ResultSet object and false if it is an update count. Additional methods must be called to retrieve the ResultSet object or update count or to retrieve additional results, if any.

String sql;
...
Statement stmt = conn.createStatement();
boolean b = stmt.execute(sql);
if (b == true) {
// b is true if a ResultSet is returned
ResultSet rs;
rs = stmt.getResultSet();
while (rs.next()) {
...
}
} else {
// b is false if an update count is returned
int rows = stmt.getUpdateCount();
if (rows > 0) {
...
}
}

CODE EXAMPLE Executing a Statement object that may return an update count or a ResultSet object When the SQL string being executed returns a ResultSet object, the method
getUpdateCount returns -1. If the SQL string being executed returns an update
count, the method getResultSet returns null.

Closing Statement Objects

An application calls the method Statement.close to indicate that it has finished processing a statement. All Statement objects will be closed when the connection that created them is closed. However, it is good coding practice for applications to close statements as soon as they have finished processing them. This allows any external resources that the statement is using to be released immediately. Closing a Statement object will close and invalidate any instances of ResultSet produced by that Statement object. The resources held by the ResultSet object
may not be released until garbage collection runs again, so it is a good practice to explicitly close ResultSet objects when they are no longer needed. These comments about closing Statement objects apply to PreparedStatement and CallableStatement objects as well.

ComputerCourse

java.sql Interface PreparedStatement

javax.servlet - Interface ServletRequest

Input-Stream Figure

API of Frame Class

java.awtClass Frame

DEFAULT_CURSOR

CROSSHAIR_CURSOR

TEXT_CURSOR

WAIT_CURSOR

SW_RESIZE_CURSOR

SE_RESIZE_CURSOR

NW_RESIZE_CURSOR

NE_RESIZE_CURSOR

N_RESIZE_CURSOR

S_RESIZE_CURSOR

W_RESIZE_CURSOR

E_RESIZE_CURSOR

HAND_CURSOR

MOVE_CURSOR

NORMAL

ICONIFIED

MAXIMIZED_HORIZ

MAXIMIZED_VERT

MAXIMIZED_BOTH

Frame

Frame

Frame

Frame

finalize

addNotify

getTitle

setTitle

getIconImage

setIconImage

getMenuBar

setMenuBar

isResizable

setResizable

setState

setExtendedState

getState

getExtendedState

setMaximizedBounds

getMaximizedBounds

setUndecorated

isUndecorated

remove

removeNotify

paramString

setCursor

getCursorType

getFrames

getAccessibleContext

Session Pattern Examples in Java

//[C] 2002 Sun Microsystems, Inc.----

--------------------------------------------------------------------------------

--------------------------------------------------------------------------------

------------------------------------------------------------------------------

---------------------------------------------------------------------------------

What is Cookie

Indicator variables and stored procedures

Returning Result Sets from Stored Procedures

Invoking a Stored Procedure

Defining an External Procedure

Defining an SQL Procedure

Define Stored Procedure

JVM (Java Virtual Machine)

Defining JVM(Java Virtual Machine)

Java theory and practice: Dealing with InterruptedException

Goalsof JAVA-JDBC

Overview of JAVA-JDBC

Classes and Interfaces in JAVA-JDBC

Compliance in JAVA-JDBC

Database Metadata

Exceptions::JAVA-JDBC

Connections::Drivers

Connections::The DataSource Interface

Transactions::JAVA-JDBC

Transactions::Transaction Isolation Levels

java.awt
Class Frame