KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sql > rowset > spi > SyncResolver


1 /*
2  * @(#)SyncResolver.java 1.4 04/02/27
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sql.rowset.spi;
9
10 import javax.sql.RowSet JavaDoc;
11 import java.sql.SQLException JavaDoc;
12
13 /**
14  * Defines a framework that allows applications to use a manual decision tree
15  * to decide what should be done when a synchronization conflict occurs.
16  * Although it is not mandatory for
17  * applications to resolve synchronization conflicts manually, this
18  * framework provides the means to delegate to the application when conflicts
19  * arise.
20  * <p>
21  * Note that a conflict is a situation where the <code>RowSet</code> object's original
22  * values for a row do not match the values in the data source, which indicates that
23  * the data source row has been modified since the last synchronization. Note also that
24  * a <code>RowSet</code> object's original values are the values it had just prior to the
25  * the last synchronization, which are not necessarily its initial values.
26  * <p>
27  *
28  * <H2>Description of a <code>SyncResolver</code> Object</H2>
29  *
30  * A <code>SyncResolver</code> object is a specialized <code>RowSet</code> object
31  * that implements the <code>SyncResolver</code> interface.
32  * It <b>may</b> operate as either a connected <code>RowSet</code> object (an
33  * implementation of the <code>JdbcRowSet</code> interface) or a connected
34  * <code>RowSet</code> object (an implementation of the
35  * <code>CachedRowSet</code> interface or one of its subinterfaces). For information
36  * on the subinterfaces, see the
37  * <a HREF="../package-summary.html"><code>javax.sql.rowset</code></a> package
38  * description. The reference implementation for <code>SyncResolver</code> implements
39  * the <code>CachedRowSet</code> interface, but other implementations
40  * may choose to implement the <code>JdbcRowSet</code> interface to satisfy
41  * particular needs.
42  * <P>
43  * After an application has attempted to synchronize a <code>RowSet</code> object with
44  * the data source (by calling the <code>CachedRowSet</code>
45  * method <code>acceptChanges</code>), and one or more conflicts have been found,
46  * a rowset's <code>SyncProvider</code> object creates an instance of
47  * <code>SyncResolver</code>. This new <code>SyncResolver</code> object has
48  * the same number of rows and columns as the
49  * <code>RowSet</code> object that was attempting the synchronization. The
50  * <code>SyncResolver</code> object contains the values from the data source that caused
51  * the conflict(s) and <code>null</code> for all other values.
52  * In addition, it contains information about each conflict.
53  * <P>
54  *
55  * <H2>Getting and Using a <code>SyncResolver</code> Object</H2>
56  *
57  * When the method <code>acceptChanges</code> encounters conflicts, the
58  * <code>SyncProvider</code> object creates a <code>SyncProviderException</code>
59  * object and sets it with the new <code>SyncResolver</code> object. The method
60  * <code>acceptChanges</code> will throw this exception, which
61  * the application can then catch and use to retrieve the
62  * <code>SyncResolver</code> object it contains. The following code snippet uses the
63  * <code>SyncProviderException</code> method <code>getSyncResolver</code> to get
64  * the <code>SyncResolver</code> object <i>resolver</i>.
65  * <PRE>
66  * } catch (SyncProviderException spe) {
67  * SyncResolver resolver = spe.getSyncResolver();
68  * ...
69  * }
70  * </PRE>
71  * <P>
72  * With <i>resolver</i> in hand, an application can use it to get the information
73  * it contains about the conflict or conflicts. A <code>SyncResolver</code> object
74  * such as <i>resolver</i> keeps
75  * track of the conflicts for each row in which there is a conflict. It also places a
76  * lock on the table or tables affected by the rowset's command so that no more
77  * conflicts can occur while the current conflicts are being resolved.
78  * <P>
79  * The following kinds of information can be obtained from a <code>SyncResolver</code>
80  * object:
81  * <P>
82  * <LI>What operation was being attempted when a conflict occurred<BR>
83  * The <code>SyncProvider</code> interface defines four constants
84  * describing states that may occur. Three
85  * constants describe the type of operation (update, delete, or insert) that a
86  * <code>RowSet</code> object was attempting to perform when a conflict was discovered,
87  * and the fourth indicates that there is no conflict.
88  * These constants are the possible return values when a <code>SyncResolver</code> object
89  * calls the method <code>getStatus</code>.
90  * <PRE>
91  * int operation = resolver.getStatus();
92  * </PRE>
93  * <P>
94  * <LI>The value in the data source that caused a conflict<BR>
95  * A conflict exists when a value that a <code>RowSet</code> object has changed
96  * and is attempting to write to the data source
97  * has also been changed in the data source since the last synchronization. An
98  * application can call the <code>SyncResolver</code> method
99  * <code>getConflictValue</code > to retrieve the
100  * value in the data source that is the cause of the conflict because the values in a
101  * <code>SyncResolver</code> object are the conflict values from the data source.
102  * <PRE>
103  * java.lang.Object conflictValue = resolver.getConflictValue(2);
104  * </PRE>
105  * Note that the column in <i>resolver</i> can be designated by the column number,
106  * as is done in the preceding line of code, or by the column name.
107  * </UL>
108  * <P>
109  * With the information retrieved from the methods <code>getStatus</code> and
110  * <code>getConflictValue</code>, the application may make a determination as to
111  * which value should be persisted in the data source. The application then calls the
112  * <code>SyncResolver</code> method <code>setResolvedValue</code>, which sets the value
113  * to be persisted in the <code>RowSet</code> object and also in the data source.
114  * <PRE>
115  * resolver.setResolvedValue("DEPT", 8390426);
116  * </PRE>
117  * In the preceding line of code,
118  * the column name designates the column in the <code>RowSet</code> object
119  * that is to be set with the given value. The column number can also be used to
120  * designate the column.
121  * <P>
122  * An application calls the method <code>setResolvedValue</code> after it has
123  * resolved all of the conflicts in the current conflict row and repeats this process
124  * for each conflict row in the <code>SyncResolver</code> object.
125  * <P>
126  *
127  * <H2>Navigating a <code>SyncResolver</code> Object</H2>
128  *
129  * Because a <code>SyncResolver</code> object is a <code>RowSet</code> object, an
130  * application can use all of the <code>RowSet</code> methods for moving the cursor
131  * to navigate a <code>SyncResolver</code> object. For example, an application can
132  * use the <code>RowSet</code> method <code>next</code> to get to each row and then
133  * call the <code>SyncResolver</code> method <code>getStatus</code> to see if the row
134  * contains a conflict. In a row with one or more conflicts, the application can
135  * iterate through the columns to find any non-null values, which will be the values
136  * from the data source that are in conflict.
137  * <P>
138  * To make it easier to navigate a <code>SyncResolver</code> object, especially when
139  * there are large numbers of rows with no conflicts, the <code>SyncResolver</code>
140  * interface defines the methods <code>nextConflict</code> and
141  * <code>previousConflict</code>, which move only to rows
142  * that contain at least one conflict value. Then an application can call the
143  * <code>SyncResolver</code> method <code>getConflictValue</code>, supplying it
144  * with the column number, to get the conflict value itself. The code fragment in the
145  * next section gives an example.
146  *
147  * <H2>Code Example</H2>
148  *
149  * The following code fragment demonstrates how a disconnected <code>RowSet</code>
150  * object <i>crs</i> might attempt to synchronize itself with the
151  * underlying data source and then resolve the conflicts. In the <code>try</code>
152  * block, <i>crs</i> calls the method <code>acceptChanges</code>, passing it the
153  * <code>Connection</code> object <i>con</i>. If there are no conflicts, the
154  * changes in <i>crs</i> are simply written to the data source. However, if there
155  * is a conflict, the method <code>acceptChanges</code> throws a
156  * <code>SyncProviderException</code> object, and the
157  * <code>catch</code> block takes effect. In this example, which
158  * illustrates one of the many ways a <code>SyncResolver</code> object can be used,
159  * the <code>SyncResolver</code> method <code>nextConflict</code> is used in a
160  * <code>while</code> loop. The loop will end when <code>nextConflict</code> returns
161  * <code>false</code>, which will occur when there are no more conflict rows in the
162  * <code>SyncResolver</code> object <i>resolver</i>. In This particular code fragment,
163  * <i>resolver</i> looks for rows that have update conflicts (rows with the status
164  * <code>SyncResolver.UPDATE_ROW_CONFLICT</code>), and the rest of this code fragment
165  * executes only for rows where conflicts occurred because <i>crs</i> was attempting an
166  * update.
167  * <P>
168  * After the cursor for <i>resolver</i> has moved to the next conflict row that
169  * has an update conflict, the method <code>getRow</code> indicates the number of the
170  * current row, and
171  * the cursor for the <code>CachedRowSet</code> object <i>crs</i> is moved to
172  * the comparable row in <i>crs</i>. By iterating
173  * through the columns of that row in both <i>resolver</i> and <i>crs</i>, the conflicting
174  * values can be retrieved and compared to decide which one should be persisted. In this
175  * code fragment, the value in <i>crs</i> is the one set as the resolved value, which means
176  * that it will be used to overwrite the conflict value in the data source.
177  *
178  * <PRE>
179  * try {
180  *
181  * crs.acceptChanges(con);
182  *
183  * } catch (SyncProviderException spe) {
184  *
185  * SyncResolver resolver = spe.getSyncResolver();
186  *
187  * Object crsValue; // value in the <code>RowSet</code> object
188  * Object resolverValue: // value in the <code>SyncResolver</code> object
189  * Object resolvedValue: // value to be persisted
190  *
191  * while(resolver.nextConflict()) {
192  * if(resolver.getStatus() == SyncResolver.UPDATE_ROW_CONFLICT) {
193  * int row = resolver.getRow();
194  * crs.absolute(row);
195  *
196  * int colCount = crs.getMetaData().getColumnCount();
197  * for(int j = 1; j <= colCount; j++) {
198  * if (resolver.getConflictValue(j) != null) {
199  * crsValue = crs.getObject(j);
200  * resolverValue = resolver.getConflictValue(j);
201  * . . .
202  * // compare crsValue and resolverValue to determine
203  * // which should be the resolved value (the value to persist)
204  * resolvedValue = crsValue;
205  *
206  * resolver.setResolvedValue(j, resolvedValue);
207  * }
208  * }
209  * }
210  * }
211  * }
212  * </PRE>
213  * @author Jonathan Bruce
214  */
215
216 public interface SyncResolver extends RowSet JavaDoc {
217     /**
218      * Indicates that a conflict occurred while the <code>RowSet</code> object was
219      * attempting to update a row in the data source.
220      * The values in the data source row to be updated differ from the
221      * <code>RowSet</code> object's original values for that row, which means that
222      * the row in the data source has been updated or deleted since the last
223      * synchronization.
224      */
225      public static int UPDATE_ROW_CONFLICT = 0;
226
227     /**
228      * Indicates that a conflict occurred while the <code>RowSet</code> object was
229      * attempting to delete a row in the data source.
230      * The values in the data source row to be updated differ from the
231      * <code>RowSet</code> object's original values for that row, which means that
232      * the row in the data source has been updated or deleted since the last
233      * synchronization.
234      */
235     public static int DELETE_ROW_CONFLICT = 1;
236     
237    /**
238     * Indicates that a conflict occurred while the <code>RowSet</code> object was
239     * attempting to insert a row into the data source. This means that a
240     * row with the same primary key as the row to be inserted has been inserted
241     * into the data source since the last synchronization.
242     */
243     public static int INSERT_ROW_CONFLICT = 2;
244     
245     /**
246      * Indicates that <b>no</b> conflict occured while the <code>RowSet</code> object
247      * was attempting to update, delete or insert a row in the data source. The values in
248      * the <code>SyncResolver</code> will contain <code>null</code> values only as an indication
249      * that no information in pertitent to the conflict resolution in this row.
250      */
251     public static int NO_ROW_CONFLICT = 3;
252           
253     /**
254      * Retrieves the conflict status of the current row of this <code>SyncResolver</code>,
255      * which indicates the operation
256      * the <code>RowSet</code> object was attempting when the conflict occurred.
257      *
258      * @return one of the following constants:
259      * <code>SyncResolver.UPDATE_ROW_CONFLICT</code>,
260      * <code>SyncResolver.DELETE_ROW_CONFLICT</code>,
261      * <code>SyncResolver.INSERT_ROW_CONFLICT</code>, or
262      * <code>SyncResolver.NO_ROW_CONFLICT</code>
263      */
264     public int getStatus();
265     
266     /**
267      * Retrieves the value in the designated column in the current row of this
268      * <code>SyncResolver</code> object, which is the value in the data source
269      * that caused a conflict.
270      *
271      * @param index an <code>int</code> designating the column in this row of this
272      * <code>SyncResolver</code> object from which to retrieve the value
273      * causing a conflict
274      * @return the value of the designated column in the current row of this
275      * <code>SyncResolver</code> object
276      * @throws SQLException if a database access error occurs
277      */
278     public Object JavaDoc getConflictValue(int index) throws SQLException JavaDoc;
279     
280     /**
281      * Retrieves the value in the designated column in the current row of this
282      * <code>SyncResolver</code> object, which is the value in the data source
283      * that caused a conflict.
284      *
285      * @param columnName a <code>String</code> object designating the column in this row of this
286      * <code>SyncResolver</code> object from which to retrieve the value
287      * causing a conflict
288      * @return the value of the designated column in the current row of this
289      * <code>SyncResolver</code> object
290      * @throws SQLException if a database access error occurs
291      */
292     public Object JavaDoc getConflictValue(String JavaDoc columnName) throws SQLException JavaDoc;
293     
294     /**
295      * Sets <i>obj</i> as the value in column <i>index</i> in the current row of the
296      * <code>RowSet</code> object that is being synchronized. <i>obj</i>
297      * is set as the value in the data source internally.
298      *
299      * @param index an <code>int</code> giving the number of the column into which to
300      * set the value to be persisted
301      * @param obj an <code>Object</code> that is the value to be set in the
302      * <code>RowSet</code> object and persisted in the data source
303      * @throws SQLException if a database access error occurs
304      */
305     public void setResolvedValue(int index, Object JavaDoc obj) throws SQLException JavaDoc;
306     
307     /**
308      * Sets <i>obj</i> as the value in column <i>columnName</i> in the current row of the
309      * <code>RowSet</code> object that is being synchronized. <i>obj</i>
310      * is set as the value in the data source internally.
311      *
312      * @param columnName a <code>String</code> object giving the name of the column
313      * into which to set the value to be persisted
314      * @param obj an <code>Object</code> that is the value to be set in the
315      * <code>RowSet</code> object and persisted in the data source
316      * @throws SQLException if a database access error occurs
317      */
318     public void setResolvedValue(String JavaDoc columnName, Object JavaDoc obj) throws SQLException JavaDoc;
319     
320     /**
321      * Moves the cursor down from its current position to the next row that contains
322      * a conflict value. A <code>SyncResolver</code> object's
323      * cursor is initially positioned before the first conflict row; the first call to the
324      * method <code>nextConflict</code> makes the first conflict row the current row;
325      * the second call makes the second conflict row the current row, and so on.
326      * <p>
327      * A call to the method <code>nextConflict</code> will implicitly close
328      * an input stream if one is open and will clear the <code>SyncResolver</code>
329      * object's warning chain.
330      *
331      * @return <code>true</code> if the new current row is valid; <code>false</code>
332      * if there are no more rows
333      * @throws SQLException if a database access error occurs or the result set type
334      * is <code>TYPE_FORWARD_ONLY</code>
335      *
336      */
337     public boolean nextConflict() throws SQLException JavaDoc;
338     
339     /**
340      * Moves the cursor up from its current position to the previous conflict
341      * row in this <code>SyncResolver</code> object.
342      * <p>
343      * A call to the method <code>previousConflict</code> will implicitly close
344      * an input stream if one is open and will clear the <code>SyncResolver</code>
345      * object's warning chain.
346      *
347      * @return <code>true</code> if the cursor is on a valid row; <code>false</code>
348      * if it is off the result set
349      * @throws SQLException if a database access error occurs or the result set type
350      * is <code>TYPE_FORWARD_ONLY</code>
351      */
352     public boolean previousConflict() throws SQLException JavaDoc;
353                     
354 }
355
Popular Tags