jdk-sandbox: jdk/src/java.sql.rowset/share/classes/com/sun/rowset/providers/package.html@f1c04490ded1 (annotated)

2 90ce3da70b43 Initial load duke parents: diff changeset	1	<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
90ce3da70b43 Initial load duke parents: diff changeset	2	<html>
90ce3da70b43 Initial load duke parents: diff changeset	3	<head>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	4
2 90ce3da70b43 Initial load duke parents: diff changeset	5	<meta http-equiv="Content-Type"
90ce3da70b43 Initial load duke parents: diff changeset	6	content="text/html; charset=iso-8859-1">
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	7
2 90ce3da70b43 Initial load duke parents: diff changeset	8	<meta name="GENERATOR"
90ce3da70b43 Initial load duke parents: diff changeset	9	content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
90ce3da70b43 Initial load duke parents: diff changeset	10	<!--
90ce3da70b43 Initial load duke parents: diff changeset	11
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	12	Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
2 90ce3da70b43 Initial load duke parents: diff changeset	13	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load duke parents: diff changeset	14
90ce3da70b43 Initial load duke parents: diff changeset	15	This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load duke parents: diff changeset	16	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	17	published by the Free Software Foundation. Oracle designates this
2 90ce3da70b43 Initial load duke parents: diff changeset	18	particular file as subject to the "Classpath" exception as provided
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	19	by Oracle in the LICENSE file that accompanied this code.
2 90ce3da70b43 Initial load duke parents: diff changeset	20
90ce3da70b43 Initial load duke parents: diff changeset	21	This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load duke parents: diff changeset	22	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load duke parents: diff changeset	23	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
90ce3da70b43 Initial load duke parents: diff changeset	24	version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load duke parents: diff changeset	25	accompanied this code).
90ce3da70b43 Initial load duke parents: diff changeset	26
90ce3da70b43 Initial load duke parents: diff changeset	27	You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load duke parents: diff changeset	28	2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load duke parents: diff changeset	29	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load duke parents: diff changeset	30
5551 327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc. ohair parents: 5506 diff changeset	31	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	32	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	33	questions.
2 90ce3da70b43 Initial load duke parents: diff changeset	34	-->
90ce3da70b43 Initial load duke parents: diff changeset	35	<title>javax.sql.rowset.providers Package</title>
90ce3da70b43 Initial load duke parents: diff changeset	36	</head>
90ce3da70b43 Initial load duke parents: diff changeset	37	<body bgcolor="#ffffff">
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	38	Repository for the <code>RowSet</code> reference implementations of the
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	39	<code>SyncProvider</code> abstract class. These implementations provide a
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	40	disconnected <code>RowSet</code>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	41	object with the ability to synchronize the data in the underlying data
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	42	source with its data. These implementations are provided as
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	43	the default <code>SyncProvider</code> implementations and are accessible via the
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	44	<code>SyncProvider</code> SPI managed by the <code>SyncFactory</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	45
90ce3da70b43 Initial load duke parents: diff changeset	46	<h3>1.0 <code>SyncProvider</code> Reference Implementations</h3>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	47	The main job of a <code>SyncProvider</code> implementation is to manage
2 90ce3da70b43 Initial load duke parents: diff changeset	48	the reader and writer mechanisms.
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	49	The <code>SyncProvider</code> SPI, as specified in the <code>javax.sql.rowset.spi</code>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	50	package, provides a pluggable mechanism by which <code>javax.sql.RowSetReader</code>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	51	and <code>javax.sql.RowSetWriter</code> implementations can be supplied to a disconnected
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	52	<code>RowSet</code> object.
2 90ce3da70b43 Initial load duke parents: diff changeset	53	<P>
90ce3da70b43 Initial load duke parents: diff changeset	54	A reader, a <code>javax.sql.RowSetReader</code>
90ce3da70b43 Initial load duke parents: diff changeset	55	object, does the work necessary to populate a <code>RowSet</code> object with data.
90ce3da70b43 Initial load duke parents: diff changeset	56	A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for
90ce3da70b43 Initial load duke parents: diff changeset	57	synchronizing a <code>RowSet</code> object's data with the data in the originating
90ce3da70b43 Initial load duke parents: diff changeset	58	source of data. Put another way, a writer writes a <code>RowSet</code>
90ce3da70b43 Initial load duke parents: diff changeset	59	object's data back to the data source.
90ce3da70b43 Initial load duke parents: diff changeset	60	<P>
90ce3da70b43 Initial load duke parents: diff changeset	61	Generally speaking, the course of events is this. The reader makes a connection to
90ce3da70b43 Initial load duke parents: diff changeset	62	the data source and reads the data from a <code>ResultSet</code> object into its
90ce3da70b43 Initial load duke parents: diff changeset	63	<code>RowSet</code> object. Then it closes the connection. While
90ce3da70b43 Initial load duke parents: diff changeset	64	the <code>RowSet</code> object is disconnected, an application makes some modifications
90ce3da70b43 Initial load duke parents: diff changeset	65	to the data and calls the method <code>acceptChanges</code>. At this point, the
90ce3da70b43 Initial load duke parents: diff changeset	66	writer is called to write the changes back to the database table or view
90ce3da70b43 Initial load duke parents: diff changeset	67	from which the original data came. This is called <i>synchronization</i>.
90ce3da70b43 Initial load duke parents: diff changeset	68	<P>
90ce3da70b43 Initial load duke parents: diff changeset	69	If the data in the originating data source has not changed, there is no problem
90ce3da70b43 Initial load duke parents: diff changeset	70	with just writing the <code>RowSet</code> object's new data to the data source.
90ce3da70b43 Initial load duke parents: diff changeset	71	If it has changed, however, there is a conflict that needs to be resolved. One
90ce3da70b43 Initial load duke parents: diff changeset	72	way to solve the problem is not to let the data in the data source be changed in
90ce3da70b43 Initial load duke parents: diff changeset	73	the first place, which can be done by setting locks on a row, a table, or the
90ce3da70b43 Initial load duke parents: diff changeset	74	whole data source. Setting locks is a way to avoid conflicts, but it can be
90ce3da70b43 Initial load duke parents: diff changeset	75	very expensive. Another approach, which is at the other end of the spectrum,
90ce3da70b43 Initial load duke parents: diff changeset	76	is simply to assume that no conflicts will occur and thus do nothing to avoid
90ce3da70b43 Initial load duke parents: diff changeset	77	conflicts.
90ce3da70b43 Initial load duke parents: diff changeset	78	Different <code>SyncProvider</code> implementations may handle synchronization in
90ce3da70b43 Initial load duke parents: diff changeset	79	any of these ways, varying from doing no checking for
90ce3da70b43 Initial load duke parents: diff changeset	80	conflicts, to doing various levels of checking, to guaranteeing that there are no
90ce3da70b43 Initial load duke parents: diff changeset	81	conflicts.
90ce3da70b43 Initial load duke parents: diff changeset	82	<P>
90ce3da70b43 Initial load duke parents: diff changeset	83	The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code>
90ce3da70b43 Initial load duke parents: diff changeset	84	object discover and manage how a provider handles synchronization.
90ce3da70b43 Initial load duke parents: diff changeset	85	The method <code>getProviderGrade</code> returns the
90ce3da70b43 Initial load duke parents: diff changeset	86	grade of synchronization a provider offers. An application can
90ce3da70b43 Initial load duke parents: diff changeset	87	direct the provider to use a particular level of locking by calling
90ce3da70b43 Initial load duke parents: diff changeset	88	the method <code>setDataSourceLock</code> and specifying the level of locking desired.
90ce3da70b43 Initial load duke parents: diff changeset	89	If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an
90ce3da70b43 Initial load duke parents: diff changeset	90	application may call the method <code>supportsUpdatableView</code> to
90ce3da70b43 Initial load duke parents: diff changeset	91	find out whether the <code>VIEW</code> can be updated.
90ce3da70b43 Initial load duke parents: diff changeset	92	<P>
90ce3da70b43 Initial load duke parents: diff changeset	93	Synchronization is done completely behind the scenes, so it is third party vendors of
90ce3da70b43 Initial load duke parents: diff changeset	94	synchronization provider implementations who have to take care of this complex task.
90ce3da70b43 Initial load duke parents: diff changeset	95	Application programmers can decide which provider to use and the level of locking to
90ce3da70b43 Initial load duke parents: diff changeset	96	be done, but they are free from having to worry about the implementation details.
90ce3da70b43 Initial load duke parents: diff changeset	97	<P>
90ce3da70b43 Initial load duke parents: diff changeset	98	The JDBC <code>RowSet</code> Implementations reference implementation provides two
90ce3da70b43 Initial load duke parents: diff changeset	99	implementations of the <code>SyncProvider</code> class:
90ce3da70b43 Initial load duke parents: diff changeset	100
90ce3da70b43 Initial load duke parents: diff changeset	101	<UL>
90ce3da70b43 Initial load duke parents: diff changeset	102	<LI>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	103	<b><code>RIOptimisticProvider</code></b> - provides the <code>javax.sql.RowSetReader</code>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	104	and <code>javax.sql.RowSetWriter</code> interface implementations and provides
2 90ce3da70b43 Initial load duke parents: diff changeset	105	an optimistic concurrency model for synchronization. This model assumes that there
90ce3da70b43 Initial load duke parents: diff changeset	106	will be few conflicts and therefore uses a relatively low grade of synchronization.
90ce3da70b43 Initial load duke parents: diff changeset	107	If no other provider is available, this is the default provider that the
90ce3da70b43 Initial load duke parents: diff changeset	108	<code>SyncFactory</code> will supply to a <code>RowSet</code> object.
90ce3da70b43 Initial load duke parents: diff changeset	109	<br>
90ce3da70b43 Initial load duke parents: diff changeset	110	<LI>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	111	<b><code>RIXMLProvider</code></b> - provides the <code>XmlReader</code> (an extension
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	112	of the <code>javax.sql.RowSetReader</code> interface) and the <code>XmlWriter</code>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	113	(an extension of the <code>javax.sql.RowSetWriter</code> interface) to enable
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	114	<code>WebRowSet</code> objects to write their state to a
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	115	well formed XML document according to the <code>WebRowSet</code> XML schema
2 90ce3da70b43 Initial load duke parents: diff changeset	116	definition.<br>
90ce3da70b43 Initial load duke parents: diff changeset	117	</UL>
90ce3da70b43 Initial load duke parents: diff changeset	118
90ce3da70b43 Initial load duke parents: diff changeset	119	<h3>2.0 Basics in RowSet Population & Synchronization</h3>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	120	A rowset's first task is to populate itself with rows of column values.
2 90ce3da70b43 Initial load duke parents: diff changeset	121	Generally, these rows will come from a relational database, so a rowset
90ce3da70b43 Initial load duke parents: diff changeset	122	has properties that supply what is necessary for making a connection to
90ce3da70b43 Initial load duke parents: diff changeset	123	a database and executing a query. A rowset that does not need to establish
90ce3da70b43 Initial load duke parents: diff changeset	124	a connection and execute a command, such as one that gets its data from
90ce3da70b43 Initial load duke parents: diff changeset	125	a tabular file instead of a relational database, does not need to have these
90ce3da70b43 Initial load duke parents: diff changeset	126	properties set. The vast majority of RowSets, however, do need to set these
90ce3da70b43 Initial load duke parents: diff changeset	127	properties. The general rule is that a RowSet is required to set only the
90ce3da70b43 Initial load duke parents: diff changeset	128	properties that it uses.<br>
90ce3da70b43 Initial load duke parents: diff changeset	129	<br>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	130	The <code>command</code> property contains the query that determines what
2 90ce3da70b43 Initial load duke parents: diff changeset	131	data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's
90ce3da70b43 Initial load duke parents: diff changeset	132	parameter(s), which means that a query can be executed multiple times with
90ce3da70b43 Initial load duke parents: diff changeset	133	different parameters to produce different result sets. Or the query can be
90ce3da70b43 Initial load duke parents: diff changeset	134	changed to something completely new to get a new result set.
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	135	<p>Once a rowset contains the rows from a <code>ResultSet</code> object or some
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	136	other data source, its column values can be updated, and its rows can be
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	137	inserted or deleted. Any method that causes a change in the rowset's values
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	138	or cursor position also notifies any object that has been registered as
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	139	a listener with the rowset. So, for example, a table that displays the rowset's
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	140	data in an applet can be notified of changes and make updates as they
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	141	occur.<br>
2 90ce3da70b43 Initial load duke parents: diff changeset	142	<br>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	143	The changes made to a rowset can be propagated back to the original data
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	144	source to keep the rowset and its data source synchronized. Although this
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	145	involves many operations behind the scenes, it is completely transparent
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	146	to the application programmer and remains the concern of the RowSet provider
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	147	developer. All an application has to do is invoke the method <code>acceptChanges</code>,
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	148	and the data source backing the rowset will be updated to match the current
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	149	values in the rowset. </p>
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	150
958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	151	<p>A disconnected rowset, such as a <code>CachedRowSet</code> or <code>WebRowSet</code>
2 90ce3da70b43 Initial load duke parents: diff changeset	152	object, establishes a connection to populate itself with data from a database
90ce3da70b43 Initial load duke parents: diff changeset	153	and then closes the connection. The <code>RowSet</code> object will remain
90ce3da70b43 Initial load duke parents: diff changeset	154	disconnected until it wants to propagate changes back to its database table,
90ce3da70b43 Initial load duke parents: diff changeset	155	which is optional. To write its changes back to the database (synchronize with
90ce3da70b43 Initial load duke parents: diff changeset	156	the database), the rowset establishes a connection, write the changes, and then
90ce3da70b43 Initial load duke parents: diff changeset	157	once again disconnects itself.<br>
90ce3da70b43 Initial load duke parents: diff changeset	158	</p>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	159
2 90ce3da70b43 Initial load duke parents: diff changeset	160	<h3> 3.0 Other Possible Implementations</h3>
32210 958d823579c3 8133480: replace some <tt> tags (obsolete in html5) in core-libs docs avstepan parents: 28059 diff changeset	161	There are many other possible implementations of the <code>SyncProvider</code> abstract
2 90ce3da70b43 Initial load duke parents: diff changeset	162	class. One possibility is to employ a more robust synchronization model, which
90ce3da70b43 Initial load duke parents: diff changeset	163	would give a <code>RowSet</code> object increased trust in the provider's
90ce3da70b43 Initial load duke parents: diff changeset	164	ability to get any updates back to the original data source. Another possibility
90ce3da70b43 Initial load duke parents: diff changeset	165	is a more formal synchronization mechanism such as SyncML
90ce3da70b43 Initial load duke parents: diff changeset	166	(<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br>
90ce3da70b43 Initial load duke parents: diff changeset	167	<br>
90ce3da70b43 Initial load duke parents: diff changeset	168	<br>
90ce3da70b43 Initial load duke parents: diff changeset	169	</body>
90ce3da70b43 Initial load duke parents: diff changeset	170	</html>

author	coleenp
	Wed, 28 Jun 2017 19:12:58 -0400
changeset 46589	f1c04490ded1
parent 32210	958d823579c3
permissions	-rw-r--r--