1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<html>
3<head>
4<!--
5 Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved.
6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7
8This code is free software; you can redistribute it and/or modify it
9under the terms of the GNU General Public License version 2 only, as
10published by the Free Software Foundation.  Oracle designates this
11particular file as subject to the "Classpath" exception as provided
12by Oracle in the LICENSE file that accompanied this code.
13
14This code is distributed in the hope that it will be useful, but WITHOUT
15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
17version 2 for more details (a copy is included in the LICENSE file that
18accompanied this code).
19
20You should have received a copy of the GNU General Public License version
212 along with this work; if not, write to the Free Software Foundation,
22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
23
24Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
25or visit www.oracle.com if you need additional information or have any
26questions.
27-->
28
29</head>
30
31
32
33<body bgcolor="white">
34
35Provides the API for accessing and processing data stored in a 
36data source (usually a relational database) using the 
37Java<sup><font size=-2>TM</font></sup> programming language. 
38This API includes a framework whereby different
39drivers can be installed dynamically to access different data sources.
40Although the JDBC<sup><font size=-2>TM</font></sup> API is mainly geared 
41to passing SQL statements to a database, it provides for reading and
42writing data from any data source with a tabular format.
43The reader/writer facility, available through the 
44<code>javax.sql.RowSet</code> group of interfaces, can be customized to
45use and update data from a spread sheet, flat file, or any other tabular 
46data source.
47<P>
48<h2>What the JDBC<sup><font size=-2>TM</font></sup> 4.1 API Includes</h2>
49The JDBC<sup><font size=-2>TM</font></sup> 4.1 API includes both
50the <code>java.sql</code> package, referred to as the JDBC core API,
51and the <code>javax.sql</code> package, referred to as the JDBC Optional
52Package API. This complete JDBC API
53is included in the Java<sup><font size=-2>TM</font></sup>  
54Standard Edition (Java SE<sup><font size=-2>TM</font></sup>), version 7.
55The <code>javax.sql</code> package extends the functionality of the JDBC API 
56from a client-side API to a server-side API, and it is an essential part
57of the Java<sup><font size=-2>TM</font></sup>  Enterprise Edition
58(Java EE<sup><font size=-2>TM</font></sup>) technology. 
59<P>
60<h2>Versions</h2>
61The JDBC 4.1 API incorporates all of the previous JDBC API versions:
62<UL>
63 <LI> The JDBC 4.0 API
64 <LI> The JDBC 3.0 API
65 <LI> The JDBC 2.1 core API
66 <LI> The JDBC 2.0 Optional Package API<br>
67      (Note that the JDBC 2.1 core API and the JDBC 2.0 Optional Package
68      API together are referred to as the JDBC 2.0 API.)
69 <LI> The JDBC 1.2 API
70 <LI> The JDBC 1.0 API
71</UL>
72<P>
73Classes, interfaces, methods, fields, constructors, and exceptions 
74have the following "since" tags that indicate when they were introduced 
75into the Java platform. When these "since" tags are used in
76Javadoc<sup><font size=-2>TM</font></sup> comments for the JDBC API,
77they indicate the following:
78<UL>
79 <LI>Since 1.7 -- new in the JDBC 4.1 API and part of the Java SE platform,
80     version 7
81<LI>Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform,
82     version 6
83 <LI>Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform, 
84     version 1.4
85 <LI>Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform, 
86     version 1.2
87 <LI>Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of
88      the JDK<sup><font size=-2>TM</font></sup>, version 1.1
89</UL>
90<P>
91<b>NOTE:</b> Many of the new features are optional; consequently, there is 
92some variation in drivers and the features they support. Always 
93check your driver's documentation to see whether it supports a feature before
94you try to use it.
95<P>
96<b>NOTE:</b> The class <code>SQLPermission</code> was added in the
97Java<sup><font size=-2>TM</font></sup> 2 SDK, Standard Edition, 
98version 1.3 release. This class is used to prevent unauthorized
99access to the logging stream associated with the <code>DriverManager</code>,
100which may contain information such as table names, column data, and so on.
101<p>
102
103<h2>What the <code>java.sql</code> Package Contains</h2>
104The <code>java.sql</code> package contains API for the following:
105<UL>
106  <LI>Making a connection with a database via the <code>DriverManager</code> facility
107  <UL>
108	 <LI><code>DriverManager</code> class -- makes a connection with a driver
109	 <LI><code>SQLPermission</code> class -- provides permission when code
110                  running within a Security Manager, such as an applet,
111                  attempts to set up a logging stream through the
112                  <code>DriverManager</code>
113	 <LI><code>Driver</code> interface -- provides the API for registering
114             and connecting drivers based on JDBC technology ("JDBC drivers"); 
115             generally used only by the <code>DriverManager</code> class
116	 <LI><code>DriverPropertyInfo</code> class -- provides properties for a
117             JDBC driver; not used by the general user
118  </UL>
119  <LI>Sending SQL statements to a database
120  <UL>
121	 <LI><code>Statement</code> --  used to send basic SQL statements
122	 <LI><code>PreparedStatement</code> --  used to send prepared statements or 
123              basic SQL statements (derived from <code>Statement</code>)
124	 <LI><code>CallableStatement</code> --  used to call database stored 
125              procedures (derived from <code>PreparedStatement</code>)
126	 <LI><code>Connection</code> interface --  provides methods for creating
127             statements and managing connections and their properties
128	 <LI><code>Savepoint</code> --  provides savepoints in a transaction
129
130  </UL>
131  <LI>Retrieving and updating the results of a query
132  <UL>
133	 <LI><code>ResultSet</code> interface
134  </UL>
135  <LI>Standard mappings for SQL types to classes and interfaces in the 
136      Java programming language
137  <UL>
138	 <LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code> 
139	 <LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code> 
140	 <LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code>
141	 <LI><code>Date</code> class -- mapping for SQL <code>DATE</code> 
142	  <LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code>
143	 <LI><code>Ref</code> interface -- mapping for SQL <code>REF</code> 
144	  <LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code>
145	 <LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code> 
146	  <LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code>
147	 <LI><code>Time</code> class -- mapping for SQL <code>TIME</code> 
148	 <LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code> 
149	 <LI><code>Types</code> class -- provides constants for SQL types
150  </UL>
151  <LI>Custom mapping an SQL user-defined type (UDT) to a class in the
152	  Java programming language
153  <UL>
154	 <LI><code>SQLData</code> interface -- specifies the mapping of
155              a UDT to an instance of this class
156	 <LI><code>SQLInput</code> interface -- provides methods for reading
157              UDT attributes from a stream
158	 <LI><code>SQLOutput</code> interface -- provides methods for writing
159              UDT attributes back to a stream
160  </UL>
161  <LI>Metadata
162  <UL>
163	 <LI><code>DatabaseMetaData</code> interface -- provides information
164              about the database
165	 <LI><code>ResultSetMetaData</code> interface -- provides information
166              about the columns of a <code>ResultSet</code> object
167	 <LI><code>ParameterMetaData</code> interface -- provides information
168              about the parameters to <code>PreparedStatement</code> commands
169  </UL>
170  <LI>Exceptions
171	<UL>
172	  <LI><code>SQLException</code> -- thrown by most methods when there
173		 is a problem accessing data and by some methods for other reasons
174	  <LI><code>SQLWarning</code> -- thrown to indicate a warning
175	  <LI><code>DataTruncation</code> -- thrown to indicate that data may have
176     	  been truncated
177	  <LI><code>BatchUpdateException</code> -- thrown to indicate that not all
178		 commands in a batch update executed successfully
179	</UL>
180</UL>
181<P>
182    <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.1 API</h3>
183<UL>
184    <LI>Allow <code>Connection</code>,
185        <code>ResultSet</code> and <code>Statement</code> objects to be
186        used with the try-with-resources statement</LI>
187    <LI>Supported added to <code>CallableStatement</code> and
188        <code>ResultSet</code> to specify the Java type to convert to via the
189        <code>getObject</code> method</LI>
190    <LI><code>DatabaseMetaData</code> methods to return PseudoColumns and if a
191        generated key is always returned</LI>
192    <LI>Added support to <code>Connection</code> to specify a database schema,
193    abort and timeout a physical connection.</LI>
194    <LI>Added support to close a <code>Statement</code> object when its dependent
195    objects have been closed</LI>
196    <LI>Support for obtaining the parent logger for a <code>Driver</code>,
197     <code>DataSource</code>, <code>ConnectionPoolDataSource</code> and
198     <code>XADataSource</code></LI>
199
200</UL>
201<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.0 API</h3>
202<UL>
203  <LI>auto java.sql.Driver discovery -- no longer need to load a 
204<code>java.sql.Driver</code> class via <code>Class.forName</code>
205 <LI>National Character Set support added
206 <li>Support added for the SQL:2003 XML data type
207 <lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions
208 added for common SQLState class value codes
209 <li>Enhanced Blob/Clob functionality -- Support provided to create and free a Blob/Clob instance
210 as well as additional methods added to improve accessiblity
211 <li>Support added for accessing a SQL ROWID
212 <li>Support added to allow a JDBC application to access an instance of a JDBC resource
213 that has been wrapped by a vendor, usually in an application server or connection 
214 pooling environment.
215 <li>Availability to be notified when a <code>PreparedStatement</code> that is associated
216 with a <code>PooledConnection</code> has been closed or the driver determines is invalid
217 
218 
219</UL>
220<P>
221<P>
222<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 3.0 API</h3>
223<UL>
224  <LI>Pooled statements -- reuse of statements associated with a pooled 
225       connection
226  <LI>Savepoints -- allow a transaction to be rolled back to a designated
227      savepoint
228  <LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify
229      how connections are to be pooled
230  <LI>Metadata for parameters of a <code>PreparedStatement</code> object
231  <LI>Ability to retrieve values from automatically generated columns
232  <LI>Ability to have multiple <code>ResultSet</code> objects 
233       returned from <code>CallableStatement</code> objects open at the
234      same time
235  <LI>Ability to identify parameters to <code>CallableStatement</code>
236      objects by name as well as by index
237  <LI><code>ResultSet</code> holdability -- ability to specify whether cursors
238      should be held open or closed at the end of a transaction
239  <LI>Ability to retrieve and update the SQL structured type instance that a
240      <code>Ref</code> object references
241  <LI>Ability to programmatically update <code>BLOB</code>,
242      <code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values.
243  <LI>Addition of the <code>java.sql.Types.DATALINK</code> data type -- 
244      allows JDBC drivers access to objects stored outside a data source
245  <LI>Addition of metadata for retrieving SQL type hierarchies
246</UL>
247<P>
248<h3><code>java.sql</code> Features Introduced in the JDBC 2.1 Core API</h3>
249<UL>
250  <LI>Scrollable result sets--using new methods in the <code>ResultSet</code>
251	  interface that allow the cursor to be moved to a particular row or to a
252	  position relative to its current position
253  <LI>Batch updates
254  <LI>Programmatic updates--using <code>ResultSet</code> updater methods
255  <LI>New data types--interfaces mapping the SQL3 data types
256  <LI>Custom mapping of user-defined types (UDTs)
257  <LI>Miscellaneous features, including performance hints, the use of character
258	  streams, full precision for <code>java.math.BigDecimal</code> values,
259	  additional security, and
260	  support for time zones in date, time, and timestamp values. 
261</UL>
262<P>
263<h3><code>javax.sql</code> Features Introduced in the JDBC 2.0 Optional
264Package API</h3>
265<UL>
266  <LI>The <code>DataSource</code> interface as a means of making a connection.  The
267      Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>
268      (JNDI) is used for registering a <code>DataSource</code> object with a 
269      naming service and also for  retrieving it.
270  <LI>Pooled connections -- allowing connections to be used and reused
271  <LI>Distributed transactions -- allowing a transaction to span diverse
272      DBMS servers
273  <LI><code>RowSet</code> technology -- providing a convenient means of
274       handling and passing data
275</UL>
276<P>
277<P>
278<h3>Custom Mapping of UDTs</h3>
279A user-defined type (UDT) defined in SQL can be mapped to a class in the Java
280programming language. An SQL structured type or an SQL <code>DISTINCT</code>
281type are the UDTs that may be custom mapped.  The following three
282steps set up a custom mapping:
283<ol>
284  <li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL
285  <li>Defining the class in the Java programming language to which the
286	  SQL UDT will be mapped.  This class must implement the
287	  <code>SQLData</code> interface.
288  <li>Making an entry in a <code>Connection</code> object's type map
289      that contains two things:
290   <ul>
291       <li>the fully-qualified SQL name of the UDT
292       <li>the <code>Class</code> object for the class that implements the 
293           <code>SQLData</code> interface
294   </ul>
295</ol>
296<p>
297When these are in place for a UDT, calling the methods
298<code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code> 
299on that UDT will automatically retrieve the custom mapping for it. Also, the
300<code>PreparedStatement.setObject</code> method will automatically map the
301object back to its SQL type to store it in the data source.
302
303<h2>Package Specification</h2>
304
305<ul>
306  <li><a href="http://java.sun.com/products/jdbc/download.html">Specification 
307      of the JDBC 4.0 API</a>
308</ul>
309
310<h2>Related Documentation</h2>
311
312<ul>
313  <li><a href="{@docRoot}openjdk-redirect.html?v=8&path=/technotes/guides/jdbc/getstart/GettingStartedTOC.fm.html">Getting Started</a>--overviews of the major interfaces
314<P>
315  <li><a href="http://java.sun.com/docs/books/tutorial/jdbc">Chapters on the JDBC 
316     API</a>--from the online version of <i>The Java Tutorial Continued</i>
317<P>
318  <li><a href="http://java.sun.com/docs/books/jdbc">
319<i>JDBC<sup><font size=-2>TM</font></sup>API Tutorial and Reference, 
320Third Edition</i></a>--
321a complete reference and tutorial for the JDBC 3.0 API
322</ul>
323<P>
324@since 1.1
325</body>
326</html>
327