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