History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/package.html (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/package.html+326−0
@@ -0,0 +1,326 @@
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="../../../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>