jdk/src/share/classes/javax/sql/package.html
author lancea
Wed, 02 Apr 2014 11:03:10 -0400
changeset 23708 fea03b9ae8af
parent 5551 327690766109
child 24197 a5c2cff81e25
permissions -rw-r--r--
8039088: Fix broken URLs in package.html Reviewed-by: chegar
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
<html>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
<head>
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
<!--
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     5
Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    10
published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    12
by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
5551
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    24
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    25
or visit www.oracle.com if you need additional information or have any
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents: 5506
diff changeset
    26
questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
-->
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
</head>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
<body bgcolor="white">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
Provides the API for server side data source access and processing from
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
the Java<sup><font size=-2>TM</font></sup> programming language.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
This package supplements the <code>java.sql</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
package and, as of the version 1.4 release, is included in the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
Java Platform, Standard Edition
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
(Java SE<sup><font size=-2>TM</sup></font>).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
It remains an essential part of the Java Platform, Enterprise Edition
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
(Java EE<sup><font size=-2>TM</sup></font>).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
The <code>javax.sql</code> package provides for the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
<OL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
  <LI>The <code>DataSource</code> interface as an alternative to the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
      <code>DriverManager</code> for establishing a 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
      connection with a data source
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
  <LI>Connection pooling and Statement pooling
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
  <LI>Distributed transactions
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
  <LI>Rowsets
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
</OL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
Applications use the <code>DataSource</code> and <code>RowSet</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
APIs directly, but the connection pooling and distributed transaction
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
APIs are used internally by the middle-tier infrastructure.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
<H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
The <code>javax.sql</code> package provides the preferred
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
way to make a connection with a data source.  The <code>DriverManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
class, the original mechanism, is still valid, and code using it will
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
continue to run.  However, the newer <code>DataSource</code> mechanism
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
is preferred because it offers many advantages over the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
<code>DriverManager</code> mechanism.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
These are the main advantages of using a <code>DataSource</code> object to 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
make a connection:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
  
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
  <LI>Changes can be made to a data source's properties, which means
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
      that it is not necessary to make changes in application code when
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
      something about the data source or driver changes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
  <LI>Connection  and Statement pooling and distributed transactions are available
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
      through a <code>DataSource</code> object that is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      implemented to work with the middle-tier infrastructure.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
      Connections made through the <code>DriverManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
      do not have connection and statement pooling or distributed transaction
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
      capabilities.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
Driver vendors provide <code>DataSource</code> implementations. A
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
particular <code>DataSource</code> object represents a particular
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
physical data source, and each connection the <code>DataSource</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
creates is a connection to that physical data source. 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
A logical name for the data source is registered with a naming service that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
uses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>  
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
(JNDI) API, usually by a system administrator or someone performing the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
duties of a system administrator. An application can retrieve the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
<code>DataSource</code> object it wants by doing a lookup on the logical
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
name that has been registered for it.  The application can then use the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
<code>DataSource</code> object to create a connection to the physical data
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
source it represents.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
A <code>DataSource</code> object can be implemented to work with the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
middle tier infrastructure so that the connections it produces will be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
pooled for reuse. An application that uses such a <code>DataSource</code> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
implementation will automatically get a connection that participates in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
connection pooling.  
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
A <code>DataSource</code> object can also be implemented to work with the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
middle tier infrastructure so that the connections it produces can be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
used for distributed transactions without any special coding.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
<H2>Connection Pooling and Statement Pooling</H2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
Connections made via a <code>DataSource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
object that is implemented to work with a middle tier connection pool manager
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
will participate in connection pooling.  This can improve performance
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
dramatically because creating new connections is very expensive. 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
Connection pooling allows a connection to be used and reused, 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
thus cutting down substantially on the number of new connections 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
that need to be created.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
Connection pooling is totally transparent.  It is done automatically
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
in the middle tier of a Java EE configuration, so from an application's 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
viewpoint, no change in code is required. An application simply uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
the <code>DataSource.getConnection</code> method to get the pooled
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
connection and uses it the same way it uses any <code>Connection</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
The classes and interfaces used for connection pooling are:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
  <LI><code>ConnectionPoolDataSource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
  <LI><code>PooledConnection</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
  <LI><code>ConnectionEvent</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
  <LI><code>ConnectionEventListener</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
   <LI><code>StatementEvent</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
  <LI><code>StatementEventListener</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
The connection pool manager, a facility in the middle tier of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
a three-tier architecture, uses these classes and interfaces
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
behind the scenes.  When a <code>ConnectionPoolDataSource</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
is called on to create a <code>PooledConnection</code> object, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
connection pool manager will register as a <code>ConnectionEventListener</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
object with the new <code>PooledConnection</code> object.  When the connection
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
is closed or there is an error, the connection pool manager (being a listener)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
gets a notification that includes a <code>ConnectionEvent</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
If the connection pool manager supports <code>Statement</code> pooling, for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
<code>PreparedStatements</code>, which can be determined by invoking the method 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
<code>DatabaseMetaData.supportsStatementPooling</code>,  the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
connection pool manager will register as a <code>StatementEventListener</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
object with the new <code>PooledConnection</code> object.  When the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
<code>PreparedStatement</code> is closed or there is an error, the connection 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
pool manager (being a listener)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
gets a notification that includes a <code>StatementEvent</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
<H2>Distributed Transactions</H2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
As with pooled connections, connections made via a <code>DataSource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
object that is implemented to work with the middle tier infrastructure
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
may participate in distributed transactions.  This gives an application
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
the ability to involve data sources on multiple servers in a single
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
transaction.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
The classes and interfaces used for distributed transactions are:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
  <LI><code>XADataSource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
  <LI><code>XAConnection</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
These interfaces are used by the transaction manager; an application does
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
not use them directly.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
The <code>XAConnection</code> interface is derived from the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
<code>PooledConnection</code> interface, so what applies to a pooled connection
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
also applies to a connection that is part of a distributed transaction.  
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
A transaction manager in the middle tier handles everything transparently.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
The only change in application code is that an application cannot do anything
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
that would interfere with the transaction manager's handling of the transaction.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
Specifically, an application cannot call the methods <code>Connection.commit</code> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
or <code>Connection.rollback</code>, and it cannot set the connection to be in 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
auto-commit mode (that is, it cannot call 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
<code>Connection.setAutoCommit(true)</code>).  
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
An application does not need to do anything special to participate in a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
distributed transaction.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
It simply creates connections to the data sources it wants to use via
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
the <code>DataSource.getConnection</code> method, just as it normally does.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
The transaction manager manages the transaction behind the scenes.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
<code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
each <code>XAConnection</code> object creates an <code>XAResource</code> object 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
that the transaction manager uses to manage the connection.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
<H2>Rowsets</H2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
The <code>RowSet</code> interface works with various other classes and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
interfaces behind the scenes. These can be grouped into three categories.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
<OL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
<LI>Event Notification 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
  <LI><code>RowSetListener</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
component because it has properties and participates in the JavaBeans
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
event notification mechanism. The <code>RowSetListener</code> interface 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
is implemented by a component that wants to be notified about events that 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
occur to a particular <code>RowSet</code> object.  Such a component registers
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
method.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
When the <code>RowSet</code> object changes one of its rows, changes all of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
it rows, or moves its cursor, it also notifies each listener that is registered 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
with it.  The listener reacts by carrying out its implementation of the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
notification method called on it.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
  <LI><code>RowSetEvent</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
As part of its internal notification process, a <code>RowSet</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
creates an instance of <code>RowSetEvent</code> and passes it to the listener.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
The listener can use this <code>RowSetEvent</code> object to find out which rowset
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
had the event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
<LI>Metadata 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
  <LI><code>RowSetMetaData</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
This interface, derived from the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
<code>ResultSetMetaData</code> interface, provides information about
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
the columns in a <code>RowSet</code> object.  An application can use
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
<code>RowSetMetaData</code> methods to find out how many columns the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
rowset contains and what kind of data each column can contain.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
The <code>RowSetMetaData</code> interface provides methods for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
setting the information about columns, but an application would not
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
normally use these methods.  When an application calls the <code>RowSet</code> 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
method <code>execute</code>, the <code>RowSet</code> object will contain
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
a new set of rows, and its <code>RowSetMetaData</code> object will have been
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
internally updated to contain information about the new columns.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
<LI>The Reader/Writer Facility<br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
interface can call on the <code>RowSetReader</code> object associated with it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
to populate itself with data.  It can also call on the <code>RowSetWriter</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
object associated with it to write any changes to its rows back to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
data source from which it originally got the rows.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
A rowset that remains connected to its data source does not need to use a 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
reader and writer because it can simply operate on the data source directly.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
  <LI><code>RowSetInternal</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
By implementing the <code>RowSetInternal</code> interface, a 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
<code>RowSet</code> object gets access to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
its internal state and is able to call on its reader and writer. A rowset
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
keeps track of the values in its current rows and of the values that immediately
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
preceded the current ones, referred to as the <i>original</i> values.  A rowset
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
also keeps track of (1) the parameters that have been set for its command and 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
(2) the connection that was passed to it, if any.  A rowset uses the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
<code>RowSetInternal</code> methods behind the scenes to get access to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
this information.  An application does not normally invoke these methods directly.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
  <LI><code>RowSetReader</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
A disconnected <code>RowSet</code> object that has implemented the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
<code>RowSetInternal</code> interface can call on its reader (the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
<code>RowSetReader</code> object associated with it) to populate it with 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
data.  When an application calls the <code>RowSet.execute</code> method, 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
that method calls on the rowset's reader to do much of the work. Implementations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
can vary widely, but generally a reader makes a connection to the data source,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
reads data from the data source and populates the rowset with it, and closes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
the connection. A reader may also update the <code>RowSetMetaData</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
for its rowset.  The rowset's internal state is also updated, either by the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
reader or directly by the method <code>RowSet.execute</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
  <LI><code>RowSetWriter</code><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
A disconnected <code>RowSet</code> object that has implemented the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
<code>RowSetInternal</code> interface can call on its writer (the 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
<code>RowSetWriter</code> object associated with it) to write changes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
back to the underlying data source.  Implementations may vary widely, but
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
generally, a writer will do the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
<UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
  <LI>Make a connection to the data source 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
  <LI>Check to see whether there is a conflict, that is, whether
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
      a value that has been changed in the rowset has also been changed 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
      in the data source
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
  <LI>Write the new values to the data source if there is no conflict 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
  <LI>Close the connection
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
</UL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
</OL>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
The <code>RowSet</code> interface may be implemented in any number of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
ways, and anyone may write an implementation. Developers are encouraged 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
to use their imaginations in coming up with new ways to use rowsets.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
<B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
JDBC technology driver that implements the JDBC 4.0 API.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
You must check your driver documentation to be sure that it implements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
the particular features you want to use.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
<h2>Package Specification</h2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
<ul>
23708
fea03b9ae8af 8039088: Fix broken URLs in package.html
lancea
parents: 5551
diff changeset
   299
  <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.2 Specification</a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
</ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
<h2>Related Documentation</h2>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
The Java Series book published by Addison-Wesley Longman provides detailed
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
information about the classes and interfaces in the <code>javax.sql</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
package: 
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
<ul>
23708
fea03b9ae8af 8039088: Fix broken URLs in package.html
lancea
parents: 5551
diff changeset
   309
  <li><a href="http://www.oracle.com/technetwork/java/index-142838.html">
fea03b9ae8af 8039088: Fix broken URLs in package.html
lancea
parents: 5551
diff changeset
   310
          <i>JDBC&#0153;API Tutorial and Reference, Third Edition</i></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
</ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
</body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
</html>