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