|
1 | 1 | /* |
2 | | - * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. |
| 2 | + * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. |
3 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 | 4 | * |
5 | 5 | * This code is free software; you can redistribute it and/or modify it |
|
25 | 25 |
|
26 | 26 | /** |
27 | 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> |
| 28 | + * Repository for the {@code RowSet} reference implementations of the |
| 29 | + * {@code SyncProvider} abstract class. These implementations provide a |
| 30 | + * disconnected {@code RowSet} |
31 | 31 | * object with the ability to synchronize the data in the underlying data |
32 | 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>. |
| 33 | + * the default {@code SyncProvider} implementations and are accessible via the |
| 34 | + * {@code SyncProvider} SPI managed by the {@code SyncFactory}. |
35 | 35 | * |
36 | | - * <h2>1.0 <code>SyncProvider</code> Reference Implementations</h2> |
37 | | - * The main job of a <code>SyncProvider</code> implementation is to manage |
| 36 | + * <h2>1.0 {@code SyncProvider} Reference Implementations</h2> |
| 37 | + * The main job of a {@code SyncProvider} implementation is to manage |
38 | 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. |
| 39 | + * The {@code SyncProvider} SPI, as specified in the {@code javax.sql.rowset.spi} |
| 40 | + * package, provides a pluggable mechanism by which {@code javax.sql.RowSetReader} |
| 41 | + * and {@code javax.sql.RowSetWriter} implementations can be supplied to a disconnected |
| 42 | + * {@code RowSet} object. |
43 | 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> |
| 44 | + * A reader, a {@code javax.sql.RowSetReader} |
| 45 | + * object, does the work necessary to populate a {@code RowSet} object with data. |
| 46 | + * A writer, a {@code javax.sql.RowSetWriter} object, does the work necessary for |
| 47 | + * synchronizing a {@code RowSet} object's data with the data in the originating |
| 48 | + * source of data. Put another way, a writer writes a {@code RowSet} |
49 | 49 | * object's data back to the data source. |
50 | 50 | * <P> |
51 | 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 |
| 52 | + * the data source and reads the data from a {@code ResultSet} object into its |
| 53 | + * {@code RowSet} object. Then it closes the connection. While |
| 54 | + * the {@code RowSet} object is disconnected, an application makes some modifications |
| 55 | + * to the data and calls the method {@code acceptChanges}. At this point, the |
56 | 56 | * writer is called to write the changes back to the database table or view |
57 | 57 | * from which the original data came. This is called <i>synchronization</i>. |
58 | 58 | * <P> |
59 | 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. |
| 60 | + * with just writing the {@code RowSet} object's new data to the data source. |
61 | 61 | * If it has changed, however, there is a conflict that needs to be resolved. One |
62 | 62 | * way to solve the problem is not to let the data in the data source be changed in |
63 | 63 | * the first place, which can be done by setting locks on a row, a table, or the |
64 | 64 | * whole data source. Setting locks is a way to avoid conflicts, but it can be |
65 | 65 | * very expensive. Another approach, which is at the other end of the spectrum, |
66 | 66 | * is simply to assume that no conflicts will occur and thus do nothing to avoid |
67 | 67 | * conflicts. |
68 | | - * Different <code>SyncProvider</code> implementations may handle synchronization in |
| 68 | + * Different {@code SyncProvider} implementations may handle synchronization in |
69 | 69 | * any of these ways, varying from doing no checking for |
70 | 70 | * conflicts, to doing various levels of checking, to guaranteeing that there are no |
71 | 71 | * conflicts. |
72 | 72 | * <P> |
73 | | - * The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code> |
| 73 | + * The {@code SyncProvider} class offers methods to help a {@code RowSet} |
74 | 74 | * object discover and manage how a provider handles synchronization. |
75 | | - * The method <code>getProviderGrade</code> returns the |
| 75 | + * The method {@code getProviderGrade} returns the |
76 | 76 | * grade of synchronization a provider offers. An application can |
77 | 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. |
| 78 | + * the method {@code setDataSourceLock} and specifying the level of locking desired. |
| 79 | + * If a {@code RowSet} object's data came from an SQL {@code VIEW}, an |
| 80 | + * application may call the method {@code supportsUpdatableView} to |
| 81 | + * find out whether the {@code VIEW} can be updated. |
82 | 82 | * <P> |
83 | 83 | * Synchronization is done completely behind the scenes, so it is third party vendors of |
84 | 84 | * synchronization provider implementations who have to take care of this complex task. |
85 | 85 | * Application programmers can decide which provider to use and the level of locking to |
86 | 86 | * be done, but they are free from having to worry about the implementation details. |
87 | 87 | * <P> |
88 | | - * The JDBC <code>RowSet</code> Implementations reference implementation provides two |
89 | | - * implementations of the <code>SyncProvider</code> class: |
| 88 | + * The JDBC {@code RowSet} Implementations reference implementation provides two |
| 89 | + * implementations of the {@code SyncProvider} class: |
90 | 90 | * |
91 | 91 | * <UL> |
92 | 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 |
| 93 | + * <b>{@code RIOptimisticProvider}</b> - provides the {@code javax.sql.RowSetReader} |
| 94 | + * and {@code javax.sql.RowSetWriter} interface implementations and provides |
95 | 95 | * an optimistic concurrency model for synchronization. This model assumes that there |
96 | 96 | * will be few conflicts and therefore uses a relatively low grade of synchronization. |
97 | 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. |
| 98 | + * {@code SyncFactory} will supply to a {@code RowSet} object. |
99 | 99 | * <br> |
100 | 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 |
| 101 | + * <b>{@code RIXMLProvider}</b> - provides the {@code XmlReader} (an extension |
| 102 | + * of the {@code javax.sql.RowSetReader} interface) and the {@code XmlWriter} |
| 103 | + * (an extension of the {@code javax.sql.RowSetWriter} interface) to enable |
| 104 | + * {@code WebRowSet} objects to write their state to a |
| 105 | + * well formed XML document according to the {@code WebRowSet} XML schema |
106 | 106 | * definition.<br> |
107 | 107 | * </UL> |
108 | 108 | * |
|
117 | 117 | * properties. The general rule is that a RowSet is required to set only the |
118 | 118 | * properties that it uses.<br> |
119 | 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 |
| 120 | + * The {@code command} property contains the query that determines what |
| 121 | + * data a {@code RowSet} will contain. Rowsets have methods for setting a query's |
122 | 122 | * parameter(s), which means that a query can be executed multiple times with |
123 | 123 | * different parameters to produce different result sets. Or the query can be |
124 | 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 |
| 125 | + * <p>Once a rowset contains the rows from a {@code ResultSet} object or some |
126 | 126 | * other data source, its column values can be updated, and its rows can be |
127 | 127 | * inserted or deleted. Any method that causes a change in the rowset's values |
128 | 128 | * or cursor position also notifies any object that has been registered as |
|
134 | 134 | * source to keep the rowset and its data source synchronized. Although this |
135 | 135 | * involves many operations behind the scenes, it is completely transparent |
136 | 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>, |
| 137 | + * developer. All an application has to do is invoke the method {@code acceptChanges}, |
138 | 138 | * and the data source backing the rowset will be updated to match the current |
139 | 139 | * values in the rowset. </p> |
140 | 140 | * |
141 | | - * <p>A disconnected rowset, such as a <code>CachedRowSet</code> or <code>WebRowSet</code> |
| 141 | + * <p>A disconnected rowset, such as a {@code CachedRowSet} or {@code WebRowSet} |
142 | 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 |
| 143 | + * and then closes the connection. The {@code RowSet} object will remain |
144 | 144 | * disconnected until it wants to propagate changes back to its database table, |
145 | 145 | * which is optional. To write its changes back to the database (synchronize with |
146 | 146 | * the database), the rowset establishes a connection, write the changes, and then |
147 | 147 | * once again disconnects itself.<br> |
148 | 148 | * </p> |
149 | 149 | * |
150 | 150 | * <h2> 3.0 Other Possible Implementations</h2> |
151 | | - * There are many other possible implementations of the <code>SyncProvider</code> abstract |
| 151 | + * There are many other possible implementations of the {@code SyncProvider} abstract |
152 | 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 |
| 153 | + * would give a {@code RowSet} object increased trust in the provider's |
154 | 154 | * ability to get any updates back to the original data source. Another possibility |
155 | 155 | * is a more formal synchronization mechanism such as SyncML |
156 | 156 | * (<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br> |
|
0 commit comments