1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2 <html> 3 <head> 4 <!-- 5 Copyright (c) 1998, 2017, 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™ 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™ 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™ 4.3 API Includes</h2> 49 The JDBC™ 4.3 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™ Standard Edition (Java SE™), version 7. 54 The <code>javax.sql</code> package extends the functionality of the JDBC API 55 from a client-side API to a server-side API, and it is an essential part 56 of the Java™ Enterprise Edition 57 (Java EE™) technology. 58 59 <h2>Versions</h2> 60 The JDBC 4.3 API incorporates all of the previous JDBC API versions: 61 <UL> 62 <LI> The JDBC 4.2 API</li> 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™ comments for the JDBC API, 78 they indicate the following: 79 <UL> 80 <LI>Since 9 -- new in the JDBC 4.3 API and part of the Java SE platform, 81 version 9</li> 82 <LI>Since 1.8 -- new in the JDBC 4.2 API and part of the Java SE platform, 83 version 8</li> 84 <LI>Since 1.7 -- new in the JDBC 4.1 API and part of the Java SE platform, 85 version 7</li> 86 <LI>Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform, 87 version 6</li> 88 <LI>Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform, 89 version 1.4</li> 90 <LI>Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform, 91 version 1.2</li> 92 <LI>Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of 93 the JDK™, version 1.1</li> 94 </UL> 95 <P> 96 <b>NOTE:</b> Many of the new features are optional; consequently, there is 97 some variation in drivers and the features they support. Always 98 check your driver's documentation to see whether it supports a feature before 99 you try to use it. 100 <P> 101 <b>NOTE:</b> The class <code>SQLPermission</code> was added in the 102 Java™ 2 SDK, Standard Edition, 103 version 1.3 release. This class is used to prevent unauthorized 104 access to the logging stream associated with the <code>DriverManager</code>, 105 which may contain information such as table names, column data, and so on. 106 107 <h2>What the <code>java.sql</code> Package Contains</h2> 108 The <code>java.sql</code> package contains API for the following: 109 <UL> 110 <LI>Making a connection with a database via the <code>DriverManager</code> facility 111 <UL> 112 <LI><code>DriverManager</code> class -- makes a connection with a driver 113 <LI><code>SQLPermission</code> class -- provides permission when code 114 running within a Security Manager, such as an applet, 115 attempts to set up a logging stream through the 116 <code>DriverManager</code> 117 <LI><code>Driver</code> interface -- provides the API for registering 118 and connecting drivers based on JDBC technology ("JDBC drivers"); 119 generally used only by the <code>DriverManager</code> class 120 <LI><code>DriverPropertyInfo</code> class -- provides properties for a 121 JDBC driver; not used by the general user 122 </UL> 123 <LI>Sending SQL statements to a database 124 <UL> 125 <LI><code>Statement</code> -- used to send basic SQL statements 126 <LI><code>PreparedStatement</code> -- used to send prepared statements or 127 basic SQL statements (derived from <code>Statement</code>) 128 <LI><code>CallableStatement</code> -- used to call database stored 129 procedures (derived from <code>PreparedStatement</code>) 130 <LI><code>Connection</code> interface -- provides methods for creating 131 statements and managing connections and their properties 132 <LI><code>Savepoint</code> -- provides savepoints in a transaction 133 134 </UL> 135 <LI>Retrieving and updating the results of a query 136 <UL> 137 <LI><code>ResultSet</code> interface 138 </UL> 139 <LI>Standard mappings for SQL types to classes and interfaces in the 140 Java programming language 141 <UL> 142 <LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code> 143 <LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code> 144 <LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code> 145 <LI><code>Date</code> class -- mapping for SQL <code>DATE</code> 146 <LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code> 147 <LI><code>Ref</code> interface -- mapping for SQL <code>REF</code> 148 <LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code> 149 <LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code> 150 <LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code> 151 <LI><code>Time</code> class -- mapping for SQL <code>TIME</code> 152 <LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code> 153 <LI><code>Types</code> class -- provides constants for SQL types 154 </UL> 155 <LI>Custom mapping an SQL user-defined type (UDT) to a class in the 156 Java programming language 157 <UL> 158 <LI><code>SQLData</code> interface -- specifies the mapping of 159 a UDT to an instance of this class 160 <LI><code>SQLInput</code> interface -- provides methods for reading 161 UDT attributes from a stream 162 <LI><code>SQLOutput</code> interface -- provides methods for writing 163 UDT attributes back to a stream 164 </UL> 165 <LI>Metadata 166 <UL> 167 <LI><code>DatabaseMetaData</code> interface -- provides information 168 about the database 169 <LI><code>ResultSetMetaData</code> interface -- provides information 170 about the columns of a <code>ResultSet</code> object 171 <LI><code>ParameterMetaData</code> interface -- provides information 172 about the parameters to <code>PreparedStatement</code> commands 173 </UL> 174 <LI>Exceptions 175 <UL> 176 <LI><code>SQLException</code> -- thrown by most methods when there 177 is a problem accessing data and by some methods for other reasons 178 <LI><code>SQLWarning</code> -- thrown to indicate a warning 179 <LI><code>DataTruncation</code> -- thrown to indicate that data may have 180 been truncated 181 <LI><code>BatchUpdateException</code> -- thrown to indicate that not all 182 commands in a batch update executed successfully 183 </UL> 184 </UL> 185 186 <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.3 API</h3> 187 <UL> 188 <LI>Added <code>Sharding</code> support</LI> 189 <LI>Enhanced <code>Connection</code> to be able to provide hints 190 to the driver that a request, an independent unit of work, 191 is beginning or ending</LI> 192 <LI>Enhanced <code>DatabaseMetaData</code> to determine if Sharding is 193 supported</LI> 194 <LI>Added the method <code>drivers</code> to <code>DriverManager</code> 195 to return a Stream of the currently loaded and 196 available JDBC drivers</LI> 197 <LI>Added support to <code>Statement</code> for enquoting literals 198 and simple identifiers</LI> 199 <LI>Clarified the Java SE version that methods were deprecated</LI> 200 </UL> 201 202 <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.2 API</h3> 203 <UL> 204 <LI>Added <code>JDBCType</code> enum and <code>SQLType</code> interface</li> 205 <LI>Support for <code>REF CURSORS</code> in <code>CallableStatement</code> 206 </LI> 207 <LI><code>DatabaseMetaData</code> methods to return maximum Logical LOB size 208 and if Ref Cursors are supported</LI> 209 <LI>Added support for large update counts</LI> 210 211 </UL> 212 213 <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.1 API</h3> 214 <UL> 215 <LI>Allow <code>Connection</code>, 216 <code>ResultSet</code> and <code>Statement</code> objects to be 217 used with the try-with-resources statement</LI> 218 <LI>Support added to <code>CallableStatement</code> and 219 <code>ResultSet</code> to specify the Java type to convert to via the 220 <code>getObject</code> method</LI> 221 <LI><code>DatabaseMetaData</code> methods to return PseudoColumns and if a 222 generated key is always returned</LI> 223 <LI>Added support to <code>Connection</code> to specify a database schema, 224 abort and timeout a physical connection.</LI> 225 <LI>Added support to close a <code>Statement</code> object when its dependent 226 objects have been closed</LI> 227 <LI>Support for obtaining the parent logger for a <code>Driver</code>, 228 <code>DataSource</code>, <code>ConnectionPoolDataSource</code> and 229 <code>XADataSource</code></LI> 230 231 </UL> 232 <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.0 API</h3> 233 <UL> 234 <LI>auto java.sql.Driver discovery -- no longer need to load a 235 <code>java.sql.Driver</code> class via <code>Class.forName</code> 236 <LI>National Character Set support added 237 <li>Support added for the SQL:2003 XML data type 238 <lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions 239 added for common SQLState class value codes 240 <li>Enhanced Blob/Clob functionality -- Support provided to create and free a Blob/Clob instance 241 as well as additional methods added to improve accessibility 242 <li>Support added for accessing a SQL ROWID 243 <li>Support added to allow a JDBC application to access an instance of a JDBC resource 244 that has been wrapped by a vendor, usually in an application server or connection 245 pooling environment. 246 <li>Availability to be notified when a <code>PreparedStatement</code> that is associated 247 with a <code>PooledConnection</code> has been closed or the driver determines is invalid 248 249 250 </UL> 251 252 253 <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 3.0 API</h3> 254 <UL> 255 <LI>Pooled statements -- reuse of statements associated with a pooled 256 connection 257 <LI>Savepoints -- allow a transaction to be rolled back to a designated 258 savepoint 259 <LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify 260 how connections are to be pooled 261 <LI>Metadata for parameters of a <code>PreparedStatement</code> object 262 <LI>Ability to retrieve values from automatically generated columns 263 <LI>Ability to have multiple <code>ResultSet</code> objects 264 returned from <code>CallableStatement</code> objects open at the 265 same time 266 <LI>Ability to identify parameters to <code>CallableStatement</code> 267 objects by name as well as by index 268 <LI><code>ResultSet</code> holdability -- ability to specify whether cursors 269 should be held open or closed at the end of a transaction 270 <LI>Ability to retrieve and update the SQL structured type instance that a 271 <code>Ref</code> object references 272 <LI>Ability to programmatically update <code>BLOB</code>, 273 <code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values. 274 <LI>Addition of the <code>java.sql.Types.DATALINK</code> data type -- 275 allows JDBC drivers access to objects stored outside a data source 276 <LI>Addition of metadata for retrieving SQL type hierarchies 277 </UL> 278 279 <h3><code>java.sql</code> Features Introduced in the JDBC 2.1 Core API</h3> 280 <UL> 281 <LI>Scrollable result sets--using new methods in the <code>ResultSet</code> 282 interface that allow the cursor to be moved to a particular row or to a 283 position relative to its current position 284 <LI>Batch updates 285 <LI>Programmatic updates--using <code>ResultSet</code> updater methods 286 <LI>New data types--interfaces mapping the SQL3 data types 287 <LI>Custom mapping of user-defined types (UDTs) 288 <LI>Miscellaneous features, including performance hints, the use of character 289 streams, full precision for <code>java.math.BigDecimal</code> values, 290 additional security, and 291 support for time zones in date, time, and timestamp values. 292 </UL> 293 294 <h3><code>javax.sql</code> Features Introduced in the JDBC 2.0 Optional 295 Package API</h3> 296 <UL> 297 <LI>The <code>DataSource</code> interface as a means of making a connection. The 298 Java Naming and Directory Interface™ 299 (JNDI) is used for registering a <code>DataSource</code> object with a 300 naming service and also for retrieving it. 301 <LI>Pooled connections -- allowing connections to be used and reused 302 <LI>Distributed transactions -- allowing a transaction to span diverse 303 DBMS servers 304 <LI><code>RowSet</code> technology -- providing a convenient means of 305 handling and passing data 306 </UL> 307 308 309 <h3>Custom Mapping of UDTs</h3> 310 A user-defined type (UDT) defined in SQL can be mapped to a class in the Java 311 programming language. An SQL structured type or an SQL <code>DISTINCT</code> 312 type are the UDTs that may be custom mapped. The following three 313 steps set up a custom mapping: 314 <ol> 315 <li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL 316 <li>Defining the class in the Java programming language to which the 317 SQL UDT will be mapped. This class must implement the 318 <code>SQLData</code> interface. 319 <li>Making an entry in a <code>Connection</code> object's type map 320 that contains two things: 321 <ul> 322 <li>the fully-qualified SQL name of the UDT 323 <li>the <code>Class</code> object for the class that implements the 324 <code>SQLData</code> interface 325 </ul> 326 </ol> 327 <p> 328 When these are in place for a UDT, calling the methods 329 <code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code> 330 on that UDT will automatically retrieve the custom mapping for it. Also, the 331 <code>PreparedStatement.setObject</code> method will automatically map the 332 object back to its SQL type to store it in the data source. 333 334 <h2>Package Specification</h2> 335 336 <ul> 337 <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a> 338 </ul> 339 340 <h2>Related Documentation</h2> 341 342 <ul> 343 <li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/index.html"> 344 Lesson:JDBC Basics(The Javaxx Tutorials > JDBC™ Database Access)</a> 345 346 <li><a href="http://www.oracle.com/technetwork/java/index-142838.html"> 347 <i>JDBC™ API Tutorial and Reference, Third Edition</i></a> 348 </ul> 349 350 </body> 351 </html>