package-summary.html

API資料大全

<P>
The JDBC 2.0 API includes two packages:
<ul>
  <li><code>java.sql</code> package--the JDBC 2.0 core API
  <ul>
     <li>JDBC API included in the JDK<sup><font size=-3>TM</sup></font> 
         1.1 release (previously called JDBC 1.2).  This API is compatible
         with any driver that uses JDBC technology.
<p>
     <li>JDBC API included in the Java 2 SDK, Standard Edition, version 1.2
         (called the JDBC 2.0 core API). This API includes the JDBC 1.2 API
         and adds many new features.<br>
  </ul>
  <P>
  <li><code>javax.sql</code> package--the JDBC 2.0 Optional Package API.
      This package extends the functionality of the JDBC API from
	  a client-side API to a server-side API, and it is an essential part
	  of Java<sup><font size=-2>TM</font></sup> 2 SDK, Enterprise Edition
	  technology.
	  <p>
	  Being an Optional Package, it is not included in the 
	  Java 2 Platform SDK, Standard Edition, version 1.2, 
	  but it is readily available from various sources.
  <ul>
     <li>Information about the JDBC 2.0 Optional Package API is 
         available from
         the <a href="http://java.sun.com/products/jdbc">JDBC web page</a>.
         The <code>javax.sql</code> package may also be downloaded from
         this web site.
     <li>Driver vendors may include the
         <code>javax.sql</code> package with their products.
     <li>The Java 2 SDK, Enterprise Edition, includes many
         Optional Package APIs, including the JDBC 2.0 Optional Package.
  </ul>
</ul>

<p>
<h2>What the <code>java.sql</code> Package Contains</h2>
The <code>java.sql</code> package contains API for the following:
<UL>
  <LI>Making a connection with a data source
  <UL>
	 <LI><code>DriverManager</code> class
	 <LI><code>Driver</code> interface
	 <LI><code>DriverPropertyInfo</code> class
	 <LI><code>Connection</code> interface
  </UL>
  <LI>Sending SQL statements to a database
  <UL>
	 <LI><code>Statement</code> interface for sending basic SQL
		statements
	 <LI><code>PreparedStatement</code> interface for sending prepared
    	 statements or basic SQL statements (derived from
		 <code>Statement</code>)
	 <LI><code>CallableStatement</code> interface for calling database
		stored procedures (derived from <code>PreparedStatement</code>)
  </UL>
  <LI>Retrieving and updating the results of a query
  <UL>
	 <LI><code>ResultSet</code> interface
  </UL>
  <LI>Mapping an SQL value to the standard mapping in the
     Java programming language
  <UL>
	 <LI><code>Array</code> interface
	 <LI><code>Blob</code> interface
	 <LI><code>Clob</code> interface
	 <LI><code>Date</code> class
	 <LI><code>Ref</code> interface
	 <LI><code>Struct</code> interface
	 <LI><code>Time</code> class
	 <LI><code>Timestamp</code> class
	 <LI><code>Types</code> class
  </UL>
  <LI>Custom mapping an SQL user-defined type to a class in the
	  Java programming language
  <UL>
	 <LI><code>SQLData</code> interface
	 <LI><code>SQLInput</code> interface
	 <LI><code>SQLOutput</code> interface
  </UL>
  <LI>Providing information about the database and the columns of
      a <code>ResultSet</code> object
  <UL>
	 <LI><code>DatabaseMetaData</code> interface
	 <LI><code>ResultSetMetaData</code> interface
  </UL>
  <LI>Throwing exceptions
	<UL>
	  <LI><code>SQLException</code> thrown by most methods when there
		 is a problem accessing data and by some methods for other reasons
	  <LI><code>SQLWarning</code> thrown to indicate a warning
	  <LI><code>DataTruncation</code> thrown to indicate that data may have
     	  been truncated
	  <LI><code>BatchUpdateException</code> thrown to indicate that not all
		 commands in a batch update executed successfully
	</UL>
  <LI>Providing security
  <UL>
	 <LI><code>SQLPermission</code> interface
  </UL>
</UL>

<P>
<h3>New Features in the JDBC 2.0 Core API</h3>
<UL>
  <LI>Scrollable result sets--using new methods in the <code>ResultSet</code>
	  interface that allow the cursor to be moved to a particular row or to a
	  position relative to its current position
  <LI>Batch updates
  <LI>Programmatic updates--using <code>ResultSet.updateXXX</code> methods
  <LI>New data types--interfaces mapping the SQL3 data types
  <LI>Custom mapping of user-defined types (UDTs)
  <LI>Miscellaneous features, including performance hints, the use of character
	  streams, full precision for <code>java.math.BigDecimal</code> values,
	  additional security, and
	  support for time zones in date, time, and timestamp values. 
</UL>
<P>
<h3>Custom Mapping of UDTs</h3>
New features in the JDBC 2.0 core API make it possible to map a
user-defined type (UDT) defined in SQL to a class in the Java
programming language. An SQL structured type or an SQL <code>DISTINCT</code>
 type are the UDTs that may be custom mapped.  The following three
 steps set up a custom mapping:
<ol>
  <li>Defining the SQL structured type or <code>DISTINCT</code> type in SQL
  <li>Defining the class in the Java programming language to which the
	  SQL UDT will be mapped.  This class must implement the
	  <code>SQLData</code> interface.
  <li>Making an entry in a <code>Connection</code> object's type map
      that contains two things:
   <ul>
       <li>the fully-qualified SQL name of the UDT and the
       <li>the <code>Class</code> object for the class to which the UDT is to
      be mapped 
   </ul>
</ol>
<p>
When these are in place for a UDT, calling the methods
<code>ResultSet.getObject</code> or <code>CallableStatement.getObject</code> 
on that UDT will automatically retrieve the custom mapping for it.

<h4>Type Maps</h4>
A newly-created JDBC 2.0 <code>Connection</code> object has an 
initially-empty type map associated with it. A user may enter a
custom mapping for a UDT in this type map. 
When a UDT is retrieved from a data source with the
method <code>ResultSet.getObject</code>, the <code>getObject</code> method
will check the connection's type map to see if there is an entry for that
UDT.  If so, the <code>getObject</code> method will map the UDT to the
class indicated.  If there is no entry, the UDT will be mapped using the
standard mapping.
<p>
A user may create a new type map, which is a <A HREF="../../java/util/Map.html"><CODE>Map</CODE></A>
 object, make an entry in it, and pass it to the <code>java.sql</code>
 methods that can perform custom mapping.  In this case, the method
 will use the given type map instead of the one associated with
 the connection.
</ol>
<p>

For example, the following code fragment specifies that the SQL
type <code>ATHLETES</code> will be mapped to the class
<code>Athletes</code> in the Java programming language.
The code fragment retrieves the type map for the <code>Connection
</code> object <code>con</code>, inserts the entry into it, and then sets
the type map with the new entry as the connection's type map.

<pre>
	java.util.Map map = con.getTypeMap();
	map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
	con.setTypeMap(map);

</pre>

<h4>Classes Used for Custom Mapping</h4>
The class to which an SQL UDT is mapped in a custom mapping must
implement the <CODE>SQLData</CODE> interface.  Typically, this class
will define a field for each attribute of an SQL structured type or a
single field for an SQL <code>DISTINCT</code> type. When the UDT is
retrieved from a data source with the <code>ResultSet.getObject</code>
method, it will be mapped as an instance of this class.  A programmer 
can operate on this class instance just as on any other object in the
Java programming language and then store any changes made to it by 
calling the <code>PreparedStatement.setObject</code> method, 
which will map it back to the SQL type.
<p>
It is expected that the implementation of the class for a custom
mapping will be done by a tool.  In a typical implementation, the 
programmer would simply supply the name of the SQL UDT, the name of
the class to which it is being mapped, and the names of the fields to
which each of the attributes of the UDT is to be mapped.  The tool will use
this information to implement the <code>SQLData.readSQL</code> and
<code>SQLData.writeSQL</code> methods.  The <code>readSQL</code> method
calls the appropriate <code>SQLInput.readXXX</code> methods to read
each attribute from an <code>SQLInput</code> object, and the 
<code>writeSQL</code> method calls <code>SQLOutput.writeXXX</code> methods
to write each attribute back to the data source via an
<code>SQLOutput</code> object.
<P>
An application programmer will not normally call <code>SQLData</code> methods
directly, and the <code>SQLInput</code> and <code>SQLOutput</code> methods
are called internally by <code>SQLData</code> methods, not by application code.

<h2>Package Specification</h2>

<ul>
  <li><a href="../../../guide/jdbc/spec/jdbc-spec.frame.html">Specification of the JDBC 2.0 Core API</a>
</ul>

<h2>Related Documentation</h2>

For overviews of the basic interfaces and a tutorial, please see:
<ul>
  <li><a href="../../../guide/jdbc/getstart/GettingStartedTOC.fm.html">Getting Started--overviews of the major interfaces</a>
  <li><a href="http://java.sun.com/docs/books/tutorial/jdbc">Chapters on the JDBC API from
  the online version of <i>The Java Tutorial Continued</i></a>
</ul>
<P>
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<b>Java<sup><font size=-2>TM</font></sup>&nbsp;2&nbsp;Platform<br>Std.&nbsp;Ed. v1.3</b></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../java/security/spec/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../java/text/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a bug or feature</a><br>For further API reference and developer documentation, see <a href="http://java.sun.com/products/jdk/1.3/devdocs-vs-specs.html">Java 2 SDK SE Developer Documentation</a>. That documentation  contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples. <p>Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road<br>Palo Alto, California, 94303, U.S.A.  All Rights Reserved.</font>
</BODY>
</HTML>