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