java.sql

Home
Java Source Code / Java Documentation
1.6.0 JDK Core
2.6.0 JDK Modules
3.6.0 JDK Modules com.sun
4.6.0 JDK Modules com.sun.java
5.6.0 JDK Modules sun
6.6.0 JDK Platform
7.Ajax
8.Apache Harmony Java SE
9.Aspect oriented
10.Authentication Authorization
11.Blogger System
12.Build
13.Byte Code
14.Cache
15.Chart
16.Chat
17.Code Analyzer
18.Collaboration
19.Content Management System
20.Database Client
21.Database DBMS
22.Database JDBC Connection Pool
23.Database ORM
24.Development
25.EJB Server
26.ERP CRM Financial
27.ESB
28.Forum
29.Game
30.GIS
31.Graphic 3D
32.Graphic Library
33.Groupware
34.HTML Parser
35.IDE
36.IDE Eclipse
37.IDE Netbeans
38.Installer
39.Internationalization Localization
40.Inversion of Control
41.Issue Tracking
42.J2EE
43.J2ME
44.JBoss
45.JMS
46.JMX
47.Library
48.Mail Clients
49.Music
50.Net
51.Parser
52.PDF
53.Portal
54.Profiler
55.Project Management
56.Report
57.RSS RDF
58.Rule Engine
59.Science
60.Scripting
61.Search Engine
62.Security
63.Sevlet Container
64.Source Control
65.Swing Library
66.Template Engine
67.Test Coverage
68.Testing
69.UML
70.Web Crawler
71.Web Framework
72.Web Mail
73.Web Server
74.Web Services
75.Web Services apache cxf 2.2.6
76.Web Services AXIS2
77.Wiki Engine
78.Workflow Engines
79.XML
80.XML UI
Java Source Code / Java Documentation » 6.0 JDK Core » sql » java.sql 
java.sql
Provides the API for accessing and processing data stored in a data source (usually a relational database) using the JavaTM programming language. This API includes a framework whereby different drivers can be installed dynamically to access different data sources. Although the JDBCTM API is mainly geared to passing SQL statements to a database, it provides for reading and writing data from any data source with a tabular format. The reader/writer facility, available through the javax.sql.RowSet group of interfaces, can be customized to use and update data from a spread sheet, flat file, or any other tabular data source.

What the JDBCTM 4.0 API Includes

The JDBCTM 4.0 API includes both the java.sql package, referred to as the JDBC core API, and the javax.sql package, referred to as the JDBC Optional Package API. This complete JDBC API is included in the JavaTM Standard Edition (Java SETM), version 6. The javax.sql package extends the functionality of the JDBC API from a client-side API to a server-side API, and it is an essential part of the JavaTM Enterprise Edition (Java EETM) technology.

Versions

The JDBC 4.0 API incorporates all of the previous JDBC API versions:
  • The JDBC 3.0 API
  • The JDBC 2.1 core API
  • The JDBC 2.0 Optional Package API
    (Note that the JDBC 2.1 core API and the JDBC 2.0 Optional Package API together are referred to as the JDBC 2.0 API.)
  • The JDBC 1.2 API
  • The JDBC 1.0 API

Classes, interfaces, methods, fields, constructors, and exceptions have the following "since" tags that indicate when they were introduced into the Java platform. When these "since" tags are used in JavadocTM comments for the JDBC API, they indicate the following:

  • Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform, version 6
  • Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform, version 1.4
  • Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform, version 1.2
  • Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of the JDKTM, version 1.1

NOTE: Many of the new features are optional; consequently, there is some variation in drivers and the features they support. Always check your driver's documentation to see whether it supports a feature before you try to use it.

NOTE: The class SQLPermission was added in the JavaTM 2 SDK, Standard Edition, version 1.3 release. This class is used to prevent unauthorized access to the logging stream associated with the DriverManager, which may contain information such as table names, column data, and so on.

What the java.sql Package Contains

The java.sql package contains API for the following:
  • Making a connection with a database via the DriverManager facility
    • DriverManager class -- makes a connection with a driver
    • SQLPermission class -- provides permission when code running within a Security Manager, such as an applet, attempts to set up a logging stream through the DriverManager
    • Driver interface -- provides the API for registering and connecting drivers based on JDBC technology ("JDBC drivers"); generally used only by the DriverManager class
    • DriverPropertyInfo class -- provides properties for a JDBC driver; not used by the general user
  • Sending SQL statements to a database
    • Statement -- used to send basic SQL statements
    • PreparedStatement -- used to send prepared statements or basic SQL statements (derived from Statement)
    • CallableStatement -- used to call database stored procedures (derived from PreparedStatement)
    • Connection interface -- provides methods for creating statements and managing connections and their properties
    • Savepoint -- provides savepoints in a transaction
  • Retrieving and updating the results of a query
    • ResultSet interface
  • Standard mappings for SQL types to classes and interfaces in the Java programming language
    • Array interface -- mapping for SQL ARRAY
    • Blob interface -- mapping for SQL BLOB
    • Clob interface -- mapping for SQL CLOB
    • Date class -- mapping for SQL DATE
    • NClob interface -- mapping for SQL NCLOB
    • Ref interface -- mapping for SQL REF
    • RowId interface -- mapping for SQL ROWID
    • Struct interface -- mapping for SQL STRUCT
    • SQLXML interface -- mapping for SQL XML
    • Time class -- mapping for SQL TIME
    • Timestamp class -- mapping for SQL TIMESTAMP
    • Types class -- provides constants for SQL types
  • Custom mapping an SQL user-defined type (UDT) to a class in the Java programming language
    • SQLData interface -- specifies the mapping of a UDT to an instance of this class
    • SQLInput interface -- provides methods for reading UDT attributes from a stream
    • SQLOutput interface -- provides methods for writing UDT attributes back to a stream
  • Metadata
    • DatabaseMetaData interface -- provides information about the database
    • ResultSetMetaData interface -- provides information about the columns of a ResultSet object
    • ParameterMetaData interface -- provides information about the parameters to PreparedStatement commands
  • Exceptions
    • SQLException -- thrown by most methods when there is a problem accessing data and by some methods for other reasons
    • SQLWarning -- thrown to indicate a warning
    • DataTruncation -- thrown to indicate that data may have been truncated
    • BatchUpdateException -- thrown to indicate that not all commands in a batch update executed successfully

java.sql and javax.sql Features Introduced in the JDBC 4.0 API

  • auto java.sql.Driver discovery -- no longer need to load a java.sql.Driver class via Class.forName
  • National Character Set support added
  • Support added for the SQL:2003 XML data type
  • SQLException enhancements -- Added support for cause chaining; New SQLExceptions added for common SQLState class value codes
  • Enhanced Blob/Clob functionality -- Support provided to create and free a Blob/Clob instance as well as additional methods added to improve accessiblity
  • Support added for accessing a SQL ROWID
  • Support added to allow a JDBC application to access an instance of a JDBC resource that has been wrapped by a vendor, usually in an application server or connection pooling environment.
  • Availability to be notfied when a PreparedStatement that is associated with a PooledConnection has been closed or the driver determines is invalid

java.sql and javax.sql Features Introduced in the JDBC 3.0 API

  • Pooled statements -- reuse of statements associated with a pooled connection
  • Savepoints -- allow a transaction to be rolled back to a designated savepoint
  • Properties defined for ConnectionPoolDataSource -- specify how connections are to be pooled
  • Metadata for parameters of a PreparedStatement object
  • Ability to retrieve values from automatically generated columns
  • Ability to have multiple ResultSet objects returned from CallableStatement objects open at the same time
  • Ability to identify parameters to CallableStatement objects by name as well as by index
  • ResultSet holdability -- ability to specify whether cursors should be held open or closed at the end of a transaction
  • Ability to retrieve and update the SQL structured type instance that a Ref object references
  • Ability to programmatically update BLOB, CLOB, ARRAY, and REF values.
  • Addition of the java.sql.Types.DATALINK data type -- allows JDBC drivers access to objects stored outside a data source
  • Addition of metadata for retrieving SQL type hierarchies

java.sql Features Introduced in the JDBC 2.1 Core API

  • Scrollable result sets--using new methods in the ResultSet interface that allow the cursor to be moved to a particular row or to a position relative to its current position
  • Batch updates
  • Programmatic updates--using ResultSet updater methods
  • New data types--interfaces mapping the SQL3 data types
  • Custom mapping of user-defined types (UDTs)
  • Miscellaneous features, including performance hints, the use of character streams, full precision for java.math.BigDecimal values, additional security, and support for time zones in date, time, and timestamp values.

javax.sql Features Introduced in the JDBC 2.0 Optional Package API

  • The DataSource interface as a means of making a connection. The Java Naming and Directory InterfaceTM (JNDI) is used for registering a DataSource object with a naming service and also for retrieving it.
  • Pooled connections -- allowing connections to be used and reused
  • Distributed transactions -- allowing a transaction to span diverse DBMS servers
  • RowSet technology -- providing a convenient means of handling and passing data

Custom Mapping of UDTs

A user-defined type (UDT) defined in SQL can be mapped to a class in the Java programming language. An SQL structured type or an SQL DISTINCT type are the UDTs that may be custom mapped. The following three steps set up a custom mapping:
  1. Defining the SQL structured type or DISTINCT type in SQL
  2. Defining the class in the Java programming language to which the SQL UDT will be mapped. This class must implement the SQLData interface.
  3. Making an entry in a Connection object's type map that contains two things:
    • the fully-qualified SQL name of the UDT
    • the Class object for the class that implements the SQLData interface

When these are in place for a UDT, calling the methods ResultSet.getObject or CallableStatement.getObject on that UDT will automatically retrieve the custom mapping for it. Also, the PreparedStatement.setObject method will automatically map the object back to its SQL type to store it in the data source.

Package Specification

Related Documentation

@since 1.1

Java Source File NameTypeComment
Array.javaInterface The mapping in the Java programming language for the SQL type ARRAY. By default, an Array value is a transaction-duration reference to an SQL ARRAY value.
BatchUpdateException.javaClass The subclass of SQLException thrown when an error occurs during a batch update operation.
Blob.javaInterface The representation (mapping) in the JavaTM programming language of an SQL BLOB value.
CallableStatement.javaInterface The interface used to execute SQL stored procedures.
ClientInfoStatus.javaenum
Clob.javaInterface The mapping in the JavaTM programming language for the SQL CLOB type. An SQL CLOB is a built-in type that stores a Character Large Object as a column value in a row of a database table. By default drivers implement a Clob object using an SQL locator(CLOB), which means that a Clob object contains a logical pointer to the SQL CLOB data rather than the data itself.
Connection.javaInterface

A connection (session) with a specific database.

DatabaseMetaData.javaInterface Comprehensive information about the database as a whole.

This interface is implemented by driver vendors to let users know the capabilities of a Database Management System (DBMS) in combination with the driver based on JDBCTM technology ("JDBC driver") that is used with it.

DataTruncation.javaClass An exception thrown as a DataTruncation exception (on writes) or reported as a DataTruncation warning (on reads) when a data values is unexpectedly truncated for reasons other than its having execeeded MaxFieldSize.
Date.javaClass

A thin wrapper around a millisecond value that allows JDBC to identify this as an SQL DATE value.

Driver.javaInterface The interface that every driver class must implement.

The Java SQL framework allows for multiple database drivers.

Each driver should supply a class that implements the Driver interface.

The DriverManager will try to load as many drivers as it can find and then for any given connection request, it will ask each driver in turn to try to connect to the target URL.

It is strongly recommended that each Driver class should be small and standalone so that the Driver class can be loaded and queried without bringing in vast quantities of supporting code.

When a Driver class is loaded, it should create an instance of itself and register it with the DriverManager.

DriverManager.javaClass

The basic service for managing a set of JDBC drivers.
NOTE: The DataSource interface, new in the JDBC 2.0 API, provides another way to connect to a data source. The use of a DataSource object is the preferred means of connecting to a data source.

DriverPropertyInfo.javaClass

Driver properties for making a connection.

NClob.javaInterface The mapping in the JavaTM programming language for the SQL NCLOB type. An SQL NCLOB is a built-in type that stores a Character Large Object using the National Character Set as a column value in a row of a database table.

The NClob interface extends the Clob interface which provides provides methods for getting the length of an SQL NCLOB value, for materializing a NCLOB value on the client, and for searching for a substring or NCLOB object within a NCLOB value.

ParameterMetaData.javaInterface An object that can be used to get information about the types and properties for each parameter marker in a PreparedStatement object.
PreparedStatement.javaInterface An object that represents a precompiled SQL statement.

A SQL statement is precompiled and stored in a PreparedStatement object.

Ref.javaInterface The mapping in the Java programming language of an SQL REF value, which is a reference to an SQL structured type value in the database.

SQL REF values are stored in a table that contains instances of a referenceable SQL structured type, and each REF value is a unique identifier for one instance in that table.

ResultSet.javaInterface A table of data representing a database result set, which is usually generated by executing a statement that queries the database.
ResultSetMetaData.javaInterface An object that can be used to get information about the types and properties of the columns in a ResultSet object.
RowId.javaInterface The representation (mapping) in the Java programming language of an SQL ROWID value.
RowIdLifetime.javaenum Enumeration for RowId life-time values.
Savepoint.javaInterface The representation of a savepoint, which is a point within the current transaction that can be referenced from the Connection.rollback method.
SQLClientInfoException.javaClass The subclass of SQLException is thrown when one or more client info properties could not be set on a Connection.
SQLData.javaInterface The interface used for the custom mapping of an SQL user-defined type (UDT) to a class in the Java programming language.
SQLDataException.javaClass The subclass of SQLException thrown when the SQLState class value is '22'.
SQLException.javaClass

An exception that provides information on a database access error or other errors.

Each SQLException provides several kinds of information:

  • a string describing the error.
SQLFeatureNotSupportedException.javaClass The subclass of SQLException thrown when the SQLState class value is '0A' ( the value is 'zero' A).
SQLInput.javaInterface An input stream that contains a stream of values representing an instance of an SQL structured type or an SQL distinct type. This interface, used only for custom mapping, is used by the driver behind the scenes, and a programmer never directly invokes SQLInput methods.
SQLIntegrityConstraintViolationException.javaClass The subclass of SQLException thrown when the SQLState class value is '23'.
SQLInvalidAuthorizationSpecException.javaClass The subclass of SQLException thrown when the SQLState class value is '28'.
SQLNonTransientConnectionException.javaClass

The subclass of SQLException thrown for the SQLState class value '08', representing that the connection operation that failed will not succeed when the operation is retried without the cause of the failure being corrected.

SQLNonTransientException.javaClass The subclass of SQLException thrown when an instance where a retry of the same operation would fail unless the cause of the SQLException is corrected.
SQLOutput.javaInterface The output stream for writing the attributes of a user-defined type back to the database.
SQLPermission.javaClass The permission for which the SecurityManager will check when code that is running in an applet calls the DriverManager.setLogWriter method or the DriverManager.setLogStream (deprecated) method. If there is no SQLPermission object, these methods throw a java.lang.SecurityException as a runtime exception.

A SQLPermission object contains a name (also referred to as a "target name") but no actions list; there is either a named permission or there is not. The target name is the name of the permission (see below).

SQLRecoverableException.javaClass The subclass of SQLException thrown in situations where a previously failed operation might be able to succeed if the application performs some recovery steps and retries the entire transaction or in the case of a distributed transaction, the transaction branch.
SQLSyntaxErrorException.javaClass The subclass of SQLException thrown when the SQLState class value is '42'.
SQLTimeoutException.javaClass

The subclass of SQLException thrown when the timeout specified by Statement has expired.

SQLTransactionRollbackException.javaClass The subclass of SQLException thrown when the SQLState class value is '40'.
SQLTransientConnectionException.javaClass The subclass of SQLException for the SQLState class value '08', representing that the connection operation that failed might be able to succeed when the operation is retried without any application-level changes.
SQLTransientException.javaClass The subclass of SQLException is thrown in situations where a previoulsy failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality.
SQLWarning.javaClass

An exception that provides information on database access warnings.

SQLXML.javaInterface The mapping in the JavaTM programming language for the SQL XML type.
Statement.javaInterface

The object used for executing a static SQL statement and returning the results it produces.

By default, only one ResultSet object per Statement object can be open at the same time.

Struct.javaInterface

The standard mapping in the Java programming language for an SQL structured type.

Time.javaClass

A thin wrapper around the java.util.Date class that allows the JDBC API to identify this as an SQL TIME value.

Timestamp.javaClass

A thin wrapper around java.util.Date that allows the JDBC API to identify this as an SQL TIMESTAMP value. It adds the ability to hold the SQL TIMESTAMP fractional seconds value, by allowing the specification of fractional seconds to a precision of nanoseconds. A Timestamp also provides formatting and parsing operations to support the JDBC escape syntax for timestamp values.

The precision of a Timestamp object is calculated to be either:

  • 19 , which is the number of characters in yyyy-mm-dd hh:mm:ss
  • 20 + s , which is the number of characters in the yyyy-mm-dd hh:mm:ss.[fff...] and s represents the scale of the given Timestamp, its fractional seconds precision.

Note: This type is a composite of a java.util.Date and a separate nanoseconds value.

Types.javaClass

The class that defines the constants that are used to identify generic SQL types, called JDBC types.

Wrapper.javaInterface Interface for JDBC classes which provide the ability to retrieve the delegate instance when the instance in question is in fact a proxy class.

The wrapper pattern is employed by many JDBC driver implementations to provide extensions beyond the traditional JDBC API that are specific to a data source.

www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.