JAVA SQL

java sql

The JavaTM programming language can be used to retrieve and handle data stored in a data source, often a relational database, thanks to the package java.sql.

See: Description

• Enum Summary

  Enum	Description
  ClientInfoStatus	Enumeration for status of the reason that a property could not be set via a call to Connection.setClientInfo
  JDBCType	Defines the constants that are used to identify generic SQL types, called JDBC types.
  PseudoColumnUsage	Enumeration for pseudo/hidden column usage.
  RowIdLifetime	Enumeration for RowId life-time values.

• Exception Summary

  Exception	Description
  BatchUpdateException	The subclass of SQLException thrown when an error occurs during a batch update operation.
  DataTruncation	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 exceeded MaxFieldSize.
  SQLClientInfoException	The subclass of SQLException is thrown when one or more client info properties could not be set on a Connection.
  SQLDataException	The subclass of SQLException thrown when the SQLState class value is ‘22‘, or under vendor-specified conditions.
  SQLException	An exception that provides information on a database access error or other errors.
  SQLFeatureNotSupportedException	The subclass of SQLException thrown when the SQLState class value is ‘0A‘ ( the value is ‘zero’ A).
  SQLIntegrityConstraintViolationException	The subclass of SQLException thrown when the SQLState class value is ‘23‘, or under vendor-specified conditions.
  SQLInvalidAuthorizationSpecException	The subclass of SQLException thrown when the SQLState class value is ‘28‘, or under vendor-specified conditions.
  SQLNonTransientConnectionException	The subclass of SQLException thrown for the SQLState class value ‘08‘, or under vendor-specified conditions.
  SQLNonTransientException	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.
  SQLRecoverableException	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	The subclass of SQLException thrown when the SQLState class value is ‘42‘, or under vendor-specified conditions.
  SQLTimeoutException	The subclass of SQLException thrown when the timeout specified by Statement.setQueryTimeout, DriverManager.setLoginTimeout, DataSource.setLoginTimeout,XADataSource.setLoginTimeout has expired.
  SQLTransactionRollbackException	The subclass of SQLException thrown when the SQLState class value is ‘40‘, or under vendor-specified conditions.
  SQLTransientConnectionException	The subclass of SQLException for the SQLState class value ‘08‘, or under vendor-specified conditions.
  SQLTransientException	The subclass of SQLException is thrown in situations where a previously failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality.
  SQLWarning	An exception that provides information on database access warnings.

The java.sql package

The JavaTM programming language is used to provide the API for accessing and processing data stored in a data source, often a relational database. A framework for dynamically installing various drivers to access various data sources is included in this API.

The JDBCTM API allows for reading and writing data from any data source in tabular style, even though its primary purpose is to pass SQL instructions to a database. The javax.sql.RowSet series of interfaces provides the reader/writer capability, which may be tailored to utilize and update data from any tabular data source, including spread sheets and flat files.

Features of the JDBC 4.2 API

The java.sql package, also known as the JDBC core API, and the javax.sql package, also known as the JDBC Optional Package API, are both part of the JDBCTM 4.2 API. Version 7 of the JavaTM Standard Edition (Java SETM) has this whole JDBC API. An integral component of JavaTM Enterprise Edition (Java EETM) technology, the javax.sql package expands the capabilities of the JDBC API from a client-side to a server-side API.

Versions

The JDBC 4.2 API incorporates all of the previous JDBC API versions:

• The JDBC 4.1 API
• The JDBC 4.0 API
• 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 Javadoc^TM comments for the JDBC API, they indicate the following:

• Since 1.8 — new in the JDBC 4.2 API and part of the Java SE platform, version 8
• Since 1.7 — new in the JDBC 4.1 API and part of the Java SE platform, version 7
• 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 JDK^TM, 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 Java^TM 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.2 API

• Added JDBCType enum and SQLType interface
• Support for REF CURSORS in CallableStatement
• DatabaseMetaData methods to return maximum Logical LOB size and if Ref Cursors are supported
• Added support for large update counts

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

• Allow Connection, ResultSet and Statement objects to be used with the try-with-resources statement
• Supported added to CallableStatement and ResultSet to specify the Java type to convert to via the getObject method
• DatabaseMetaData methods to return PseudoColumns and if a generated key is always returned
• Added support to Connection to specify a database schema, abort and timeout a physical connection.
• Added support to close a Statement object when its dependent objects have been closed
• Support for obtaining the parent logger for a Driver, DataSource, ConnectionPoolDataSource and XADataSource

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 accessibility
• 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 notified 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 Interface^TM (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

• Specification of the JDBC 4.0 API

Related Documentation

• Getting Started–overviews of the major interfaces
• Chapters on the JDBC API–from the online version of The Java Tutorial Continued
• JDBC^TMAPI Tutorial and Reference, Third Edition— a complete reference and tutorial for the JDBC 3.0 API