Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / java / sql / package.html
blob: 9d737976fcf0663da4e6410cd3819551f894547f [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<html>
3<head>
4<!--
5Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
11particular file as subject to the "Classpath" exception as provided
12by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
25CA 95054 USA or visit www.sun.com if you need additional information or
26have any questions.
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.0 API Includes</h2>
49The JDBC<sup><font size=-2>TM</font></sup> 4.0 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 6.
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.0 API incorporates all of the previous JDBC API versions:
62<UL>
63 <LI> The JDBC 3.0 API
64 <LI> The JDBC 2.1 core API
65 <LI> The JDBC 2.0 Optional Package API<br>
66 (Note that the JDBC 2.1 core API and the JDBC 2.0 Optional Package
67 API together are referred to as the JDBC 2.0 API.)
68 <LI> The JDBC 1.2 API
69 <LI> The JDBC 1.0 API
70</UL>
71<P>
72Classes, interfaces, methods, fields, constructors, and exceptions
73have the following "since" tags that indicate when they were introduced
74into the Java platform. When these "since" tags are used in
75Javadoc<sup><font size=-2>TM</font></sup> comments for the JDBC API,
76they indicate the following:
77<UL>
78 <LI>Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform,
79 version 6
80 <LI>Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform,
81 version 1.4
82 <LI>Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform,
83 version 1.2
84 <LI>Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of
85 the JDK<sup><font size=-2>TM</font></sup>, version 1.1
86</UL>
87<P>
88<b>NOTE:</b> Many of the new features are optional; consequently, there is
89some variation in drivers and the features they support. Always
90check your driver's documentation to see whether it supports a feature before
91you try to use it.
92<P>
93<b>NOTE:</b> The class <code>SQLPermission</code> was added in the
94Java<sup><font size=-2>TM</font></sup> 2 SDK, Standard Edition,
95version 1.3 release. This class is used to prevent unauthorized
96access to the logging stream associated with the <code>DriverManager</code>,
97which may contain information such as table names, column data, and so on.
98<p>
99
100<h2>What the <code>java.sql</code> Package Contains</h2>
101The <code>java.sql</code> package contains API for the following:
102<UL>
103 <LI>Making a connection with a database via the <code>DriverManager</code> facility
104 <UL>
105 <LI><code>DriverManager</code> class -- makes a connection with a driver
106 <LI><code>SQLPermission</code> class -- provides permission when code
107 running within a Security Manager, such as an applet,
108 attempts to set up a logging stream through the
109 <code>DriverManager</code>
110 <LI><code>Driver</code> interface -- provides the API for registering
111 and connecting drivers based on JDBC technology ("JDBC drivers");
112 generally used only by the <code>DriverManager</code> class
113 <LI><code>DriverPropertyInfo</code> class -- provides properties for a
114 JDBC driver; not used by the general user
115 </UL>
116 <LI>Sending SQL statements to a database
117 <UL>
118 <LI><code>Statement</code> -- used to send basic SQL statements
119 <LI><code>PreparedStatement</code> -- used to send prepared statements or
120 basic SQL statements (derived from <code>Statement</code>)
121 <LI><code>CallableStatement</code> -- used to call database stored
122 procedures (derived from <code>PreparedStatement</code>)
123 <LI><code>Connection</code> interface -- provides methods for creating
124 statements and managing connections and their properties
125 <LI><code>Savepoint</code> -- provides savepoints in a transaction
126
127 </UL>
128 <LI>Retrieving and updating the results of a query
129 <UL>
130 <LI><code>ResultSet</code> interface
131 </UL>
132 <LI>Standard mappings for SQL types to classes and interfaces in the
133 Java programming language
134 <UL>
135 <LI><code>Array</code> interface -- mapping for SQL <code>ARRAY</code>
136 <LI><code>Blob</code> interface -- mapping for SQL <code>BLOB</code>
137 <LI><code>Clob</code> interface -- mapping for SQL <code>CLOB</code>
138 <LI><code>Date</code> class -- mapping for SQL <code>DATE</code>
139 <LI><code>NClob</code> interface -- mapping for SQL <code>NCLOB</code>
140 <LI><code>Ref</code> interface -- mapping for SQL <code>REF</code>
141 <LI><code>RowId</code> interface -- mapping for SQL <code>ROWID</code>
142 <LI><code>Struct</code> interface -- mapping for SQL <code>STRUCT</code>
143 <LI><code>SQLXML</code> interface -- mapping for SQL <code>XML</code>
144 <LI><code>Time</code> class -- mapping for SQL <code>TIME</code>
145 <LI><code>Timestamp</code> class -- mapping for SQL <code>TIMESTAMP</code>
146 <LI><code>Types</code> class -- provides constants for SQL types
147 </UL>
148 <LI>Custom mapping an SQL user-defined type (UDT) to a class in the
149 Java programming language
150 <UL>
151 <LI><code>SQLData</code> interface -- specifies the mapping of
152 a UDT to an instance of this class
153 <LI><code>SQLInput</code> interface -- provides methods for reading
154 UDT attributes from a stream
155 <LI><code>SQLOutput</code> interface -- provides methods for writing
156 UDT attributes back to a stream
157 </UL>
158 <LI>Metadata
159 <UL>
160 <LI><code>DatabaseMetaData</code> interface -- provides information
161 about the database
162 <LI><code>ResultSetMetaData</code> interface -- provides information
163 about the columns of a <code>ResultSet</code> object
164 <LI><code>ParameterMetaData</code> interface -- provides information
165 about the parameters to <code>PreparedStatement</code> commands
166 </UL>
167 <LI>Exceptions
168 <UL>
169 <LI><code>SQLException</code> -- thrown by most methods when there
170 is a problem accessing data and by some methods for other reasons
171 <LI><code>SQLWarning</code> -- thrown to indicate a warning
172 <LI><code>DataTruncation</code> -- thrown to indicate that data may have
173 been truncated
174 <LI><code>BatchUpdateException</code> -- thrown to indicate that not all
175 commands in a batch update executed successfully
176 </UL>
177</UL>
178<P>
179<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.0 API</h3>
180<UL>
181 <LI>auto java.sql.Driver discovery -- no longer need to load a
182<code>java.sql.Driver</code> class via <code>Class.forName</code>
183 <LI>National Character Set support added
184 <li>Support added for the SQL:2003 XML data type
185 <lI>SQLException enhancements -- Added support for cause chaining; New SQLExceptions
186 added for common SQLState class value codes
187 <li>Enhanced Blob/Clob functionality -- Support provided to create and free a Blob/Clob instance
188 as well as additional methods added to improve accessiblity
189 <li>Support added for accessing a SQL ROWID
190 <li>Support added to allow a JDBC application to access an instance of a JDBC resource
191 that has been wrapped by a vendor, usually in an application server or connection
192 pooling environment.
193 <li>Availability to be notfied when a <code>PreparedStatement</code> that is associated
194 with a <code>PooledConnection</code> has been closed or the driver determines is invalid
195
196
197</UL>
198<P>
199<P>
200<h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 3.0 API</h3>
201<UL>
202 <LI>Pooled statements -- reuse of statements associated with a pooled
203 connection
204 <LI>Savepoints -- allow a transaction to be rolled back to a designated
205 savepoint
206 <LI>Properties defined for <code>ConnectionPoolDataSource</code> -- specify
207 how connections are to be pooled
208 <LI>Metadata for parameters of a <code>PreparedStatement</code> object
209 <LI>Ability to retrieve values from automatically generated columns
210 <LI>Ability to have multiple <code>ResultSet</code> objects
211 returned from <code>CallableStatement</code> objects open at the
212 same time
213 <LI>Ability to identify parameters to <code>CallableStatement</code>
214 objects by name as well as by index
215 <LI><code>ResultSet</code> holdability -- ability to specify whether cursors
216 should be held open or closed at the end of a transaction
217 <LI>Ability to retrieve and update the SQL structured type instance that a
218 <code>Ref</code> object references
219 <LI>Ability to programmatically update <code>BLOB</code>,
220 <code>CLOB</code>, <code>ARRAY</code>, and <code>REF</code> values.
221 <LI>Addition of the <code>java.sql.Types.DATALINK</code> data type --
222 allows JDBC drivers access to objects stored outside a data source
223 <LI>Addition of metadata for retrieving SQL type hierarchies
224</UL>
225<P>
226<h3><code>java.sql</code> Features Introduced in the JDBC 2.1 Core API</h3>
227<UL>
228 <LI>Scrollable result sets--using new methods in the <code>ResultSet</code>
229 interface that allow the cursor to be moved to a particular row or to a
230 position relative to its current position
231 <LI>Batch updates
232 <LI>Programmatic updates--using <code>ResultSet</code> updater methods
233 <LI>New data types--interfaces mapping the SQL3 data types
234 <LI>Custom mapping of user-defined types (UDTs)
235 <LI>Miscellaneous features, including performance hints, the use of character
236 streams, full precision for <code>java.math.BigDecimal</code> values,
237 additional security, and
238 support for time zones in date, time, and timestamp values.
239</UL>
240<P>
241<h3><code>javax.sql</code> Features Introduced in the JDBC 2.0 Optional
242Package API</h3>
243<UL>
244 <LI>The <code>DataSource</code> interface as a means of making a connection. The
245 Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>
246 (JNDI) is used for registering a <code>DataSource</code> object with a
247 naming service and also for retrieving it.
248 <LI>Pooled connections -- allowing connections to be used and reused
249 <LI>Distributed transactions -- allowing a transaction to span diverse
250 DBMS servers
251 <LI><code>RowSet</code> technology -- providing a convenient means of
252 handling and passing data
253</UL>
254<P>
255<P>
256<h3>Custom Mapping of UDTs</h3>
257A user-defined type (UDT) defined in SQL can be mapped to a class in the Java
258programming language. An SQL structured type or an SQL <code>DISTINCT</code>
259type are the UDTs that may be custom mapped. The following three
260steps set up a custom mapping:
261<ol>
262 <li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL
263 <li>Defining the class in the Java programming language to which the
264 SQL UDT will be mapped. This class must implement the
265 <code>SQLData</code> interface.
266 <li>Making an entry in a <code>Connection</code> object's type map
267 that contains two things:
268 <ul>
269 <li>the fully-qualified SQL name of the UDT
270 <li>the <code>Class</code> object for the class that implements the
271 <code>SQLData</code> interface
272 </ul>
273</ol>
274<p>
275When these are in place for a UDT, calling the methods
276<code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code>
277on that UDT will automatically retrieve the custom mapping for it. Also, the
278<code>PreparedStatement.setObject</code> method will automatically map the
279object back to its SQL type to store it in the data source.
280
281<h2>Package Specification</h2>
282
283<ul>
284 <li><a href="http://java.sun.com/products/jdbc/download.html">Specification
285 of the JDBC 4.0 API</a>
286</ul>
287
288<h2>Related Documentation</h2>
289
290<ul>
291 <li><a href="../../../guide/jdbc/getstart/GettingStartedTOC.fm.html">Getting Started</a>--overviews of the major interfaces
292<P>
293 <li><a href="http://java.sun.com/docs/books/tutorial/jdbc">Chapters on the JDBC
294 API</a>--from the online version of <i>The Java Tutorial Continued</i>
295<P>
296 <li><a href="http://java.sun.com/docs/books/jdbc">
297<i>JDBC<sup><font size=-2>TM</font></sup>API Tutorial and Reference,
298Third Edition</i></a>--
299a complete reference and tutorial for the JDBC 3.0 API
300</ul>
301<P>
302@since 1.1
303</body>
304</html>