Note that a conflict is a situation where the RowSet object's original
values for a row do not match the values in the data source, which indicates that
the data source row has been modified since the last synchronization. Note also that
a RowSet object's original values are the values it had just prior to the
the last synchronization, which are not necessarily its initial values.
SyncResolver ObjectSyncResolver object is a specialized RowSet object
that implements the SyncResolver interface.
It may operate as either a connected RowSet object (an
implementation of the JdbcRowSet interface) or a connected
RowSet object (an implementation of the
CachedRowSet interface or one of its subinterfaces). For information
on the subinterfaces, see the
javax.sql.rowset package
description. The reference implementation for SyncResolver implements
the CachedRowSet interface, but other implementations
may choose to implement the JdbcRowSet interface to satisfy
particular needs.
After an application has attempted to synchronize a RowSet object with
the data source (by calling the CachedRowSet
method acceptChanges), and one or more conflicts have been found,
a rowset's SyncProvider object creates an instance of
SyncResolver. This new SyncResolver object has
the same number of rows and columns as the
RowSet object that was attempting the synchronization. The
SyncResolver object contains the values from the data source that caused
the conflict(s) and null for all other values.
In addition, it contains information about each conflict.
SyncResolver ObjectacceptChanges encounters conflicts, the
SyncProvider object creates a SyncProviderException
object and sets it with the new SyncResolver object. The method
acceptChanges will throw this exception, which
the application can then catch and use to retrieve the
SyncResolver object it contains. The following code snippet uses the
SyncProviderException method getSyncResolver to get
the SyncResolver object resolver.
} catch (SyncProviderException spe) {
SyncResolver resolver = spe.getSyncResolver();
...
}
With resolver in hand, an application can use it to get the information
it contains about the conflict or conflicts. A SyncResolver object
such as resolver keeps
track of the conflicts for each row in which there is a conflict. It also places a
lock on the table or tables affected by the rowset's command so that no more
conflicts can occur while the current conflicts are being resolved.
The following kinds of information can be obtained from a SyncResolver
object:
SyncProvider interface defines four constants
describing states that may occur. Three
constants describe the type of operation (update, delete, or insert) that a
RowSet object was attempting to perform when a conflict was discovered,
and the fourth indicates that there is no conflict.
These constants are the possible return values when a SyncResolver object
calls the method getStatus.
int operation = resolver.getStatus();
RowSet object has changed
and is attempting to write to the data source
has also been changed in the data source since the last synchronization. An
application can call the SyncResolver method
getConflictValue to retrieve the
value in the data source that is the cause of the conflict because the values in a
SyncResolver object are the conflict values from the data source.
java.lang.Object conflictValue = resolver.getConflictValue(2);
Note that the column in resolver can be designated by the column number,
as is done in the preceding line of code, or by the column name.
With the information retrieved from the methods getStatus and
getConflictValue, the application may make a determination as to
which value should be persisted in the data source. The application then calls the
SyncResolver method setResolvedValue, which sets the value
to be persisted in the RowSet object and also in the data source.
resolver.setResolvedValue("DEPT", 8390426);
In the preceding line of code,
the column name designates the column in the RowSet object
that is to be set with the given value. The column number can also be used to
designate the column.
An application calls the method setResolvedValue after it has
resolved all of the conflicts in the current conflict row and repeats this process
for each conflict row in the SyncResolver object.
SyncResolver ObjectSyncResolver object is a RowSet object, an
application can use all of the RowSet methods for moving the cursor
to navigate a SyncResolver object. For example, an application can
use the RowSet method next to get to each row and then
call the SyncResolver method getStatus to see if the row
contains a conflict. In a row with one or more conflicts, the application can
iterate through the columns to find any non-null values, which will be the values
from the data source that are in conflict.
To make it easier to navigate a SyncResolver object, especially when
there are large numbers of rows with no conflicts, the SyncResolver
interface defines the methods nextConflict and
previousConflict, which move only to rows
that contain at least one conflict value. Then an application can call the
SyncResolver method getConflictValue, supplying it
with the column number, to get the conflict value itself. The code fragment in the
next section gives an example.
RowSet
object crs might attempt to synchronize itself with the
underlying data source and then resolve the conflicts. In the try
block, crs calls the method acceptChanges, passing it the
Connection object con. If there are no conflicts, the
changes in crs are simply written to the data source. However, if there
is a conflict, the method acceptChanges throws a
SyncProviderException object, and the
catch block takes effect. In this example, which
illustrates one of the many ways a SyncResolver object can be used,
the SyncResolver method nextConflict is used in a
while loop. The loop will end when nextConflict returns
false, which will occur when there are no more conflict rows in the
SyncResolver object resolver. In This particular code fragment,
resolver looks for rows that have update conflicts (rows with the status
SyncResolver.UPDATE_ROW_CONFLICT), and the rest of this code fragment
executes only for rows where conflicts occurred because crs was attempting an
update.
After the cursor for resolver has moved to the next conflict row that
has an update conflict, the method getRow indicates the number of the
current row, and
the cursor for the CachedRowSet object crs is moved to
the comparable row in crs. By iterating
through the columns of that row in both resolver and crs, the conflicting
values can be retrieved and compared to decide which one should be persisted. In this
code fragment, the value in crs is the one set as the resolved value, which means
that it will be used to overwrite the conflict value in the data source.
try {
crs.acceptChanges(con);
} catch (SyncProviderException spe) {
SyncResolver resolver = spe.getSyncResolver();
Object crsValue; // value in the RowSet object
Object resolverValue: // value in the SyncResolver object
Object resolvedValue: // value to be persisted
while(resolver.nextConflict()) {
if(resolver.getStatus() == SyncResolver.UPDATE_ROW_CONFLICT) {
int row = resolver.getRow();
crs.absolute(row);
int colCount = crs.getMetaData().getColumnCount();
for(int j = 1; j <= colCount; j++) {
if (resolver.getConflictValue(j) != null) {
crsValue = crs.getObject(j);
resolverValue = resolver.getConflictValue(j);
. . .
// compare crsValue and resolverValue to determine
// which should be the resolved value (the value to persist)
resolvedValue = crsValue;
resolver.setResolvedValue(j, resolvedValue);
}
}
}
}
}
RowSet object was
attempting to delete a row in the data source.
The values in the data source row to be updated differ from the
RowSet object's original values for that row, which means that
the row in the data source has been updated or deleted since the last
synchronization.RowSet object was
attempting to insert a row into the data source. This means that a
row with the same primary key as the row to be inserted has been inserted
into the data source since the last synchronization.RowSet object
was attempting to update, delete or insert a row in the data source. The values in
the SyncResolver will contain null values only as an indication
that no information in pertitent to the conflict resolution in this row.RowSet object was
attempting to update a row in the data source.
The values in the data source row to be updated differ from the
RowSet object's original values for that row, which means that
the row in the data source has been updated or deleted since the last
synchronization.RowSet object.RowSet object's command.
In general, parameter values remain in force for repeated use of a
RowSet object. Setting a parameter value automatically clears its
previous value. However, in some cases it is useful to immediately
release the resources used by the current parameter values, which can
be done by calling the method clearParameters.
RowSet object with data.
The execute method may use the following properties
to create a connection for reading data: url, data source name,
user name, password, transaction isolation, and type map.
The execute method may use the following properties
to create a statement to execute a command:
command, read only, maximum field size,
maximum rows, escape processing, and query timeout.
If the required properties have not been set, an exception is thrown. If this method is successful, the current contents of the rowset are discarded and the rowset's metadata is also (re)set. If there are outstanding updates, they are ignored.
If this RowSet object does not maintain a continuous connection
with its source of data, it may use a reader (a RowSetReader
object) to fill itself with data. In this case, a reader will have been
registered with this RowSet object, and the method
execute will call on the reader's readData
method as part of its implementation.
RowSet object's command property.
The command property contains a command string, which must be an SQL
query, that can be executed to fill the rowset with data.
The default value is null.SyncResolver object, which is the value in the data source
that caused a conflict.SyncResolver object, which is the value in the data source
that caused a conflict.RowSet object. Users should set
either the url property or the data source name property. The rowset will use
the property that was set more recently to get a connection.RowSet object.
If escape scanning is enabled, which is the default, the driver will do
escape substitution before sending an SQL statement to the database.BINARY,
VARBINARY, LONGVARBINARYBINARY, CHAR,
VARCHAR, and LONGVARCHAR columns.
If the limit is exceeded, the excess data is silently discarded.RowSet
object can contain.
If the limit is exceeded, the excess rows are silently dropped.execute. It is not usually part of the serialized state
of a RowSet object.SQLException is thrown.SyncResolver,
which indicates the operation
the RowSet object was attempting when the conflict occurred.RowSet object.Map object associated with this
RowSet object, which specifies the custom mapping
of SQL user-defined types, if any. The default is for the
type map to be empty.RowSet object will use to
create a connection if it uses the DriverManager
instead of a DataSource object to establish the connection.
The default value is null.RowSet object.
The username property is set at run time before calling the method
execute. It is
not usually part of the serialized state of a RowSet object.RowSet object is read-only.
If updates are possible, the default is for a rowset to be
updatable.
Attempts to update a read-only rowset will result in an
SQLException being thrown.
SyncResolver object's
cursor is initially positioned before the first conflict row; the first call to the
method nextConflict makes the first conflict row the current row;
the second call makes the second conflict row the current row, and so on.
A call to the method nextConflict will implicitly close
an input stream if one is open and will clear the SyncResolver
object's warning chain.
SyncResolver object.
A call to the method previousConflict will implicitly close
an input stream if one is open and will clear the SyncResolver
object's warning chain.
RowSet object.RowSet object's command
with the given Array value. The driver will convert this
to the ARRAY value that the Array object
represents before sending it to the database.RowSet object's command
to the given java.io.InputStream value.
It may be more practical to send a very large ASCII value via a
java.io.InputStream rather than as a LONGVARCHAR
parameter. The driver will read the data from the stream
as needed until it reaches end-of-file.
Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.
RowSet object's command
to the given java.math.BigDeciaml value.
The driver converts this to
an SQL NUMERIC value before sending it to the database.RowSet object's command
to the given java.io.InputStream value.
It may be more practical to send a very large binary value via a
java.io.InputStream rather than as a LONGVARBINARY
parameter. The driver will read the data from the stream
as needed until it reaches end-of-file.
Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.
RowSet object's command
with the given Blob value. The driver will convert this
to the BLOB value that the Blob object
represents before sending it to the database.RowSet object's command
to the given Java boolean value. The driver converts this to
an SQL BIT value before sending it to the database.RowSet object's command
to the given Java byte value. The driver converts this to
an SQL TINYINT value before sending it to the database.RowSet object's command
to the given Java array of byte values. Before sending it to the
database, the driver converts this to an SQL VARBINARY or
LONGVARBINARY value, depending on the argument's size relative
to the driver's limits on VARBINARY values.RowSet object's command
to the given java.io.Reader value.
It may be more practical to send a very large UNICODE value via a
java.io.Reader rather than as a LONGVARCHAR
parameter. The driver will read the data from the stream
as needed until it reaches end-of-file.
Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.
RowSet object's command
with the given Clob value. The driver will convert this
to the CLOB value that the Clob object
represents before sending it to the database.RowSet object's command property to the given
SQL query.
This property is optional
when a rowset gets its data from a data source that does not support
commands, such as a spreadsheet.RowSet object to the given
concurrency level. This method is used to change the concurrency level
of a rowset, which is by default ResultSet.CONCUR_READ_ONLYRowSet object to the
given String.
The value of the data source name property can be used to do a lookup of
a DataSource object that has been registered with a naming
service. After being retrieved, the DataSource object can be
used to create a connection to the data source that it represents.
RowSet object's command
to the given java.sql.Date value. The driver converts this to
an SQL DATE value before sending it to the database, using the
default java.util.Calendar to calculate the date.RowSet object's command
with the given java.sql.Date value. The driver will convert this
to an SQL DATE value, using the given java.util.Calendar
object to calculate the date.RowSet object's command
to the given Java double value. The driver converts this to
an SQL DOUBLE value before sending it to the database.RowSet object on or
off. If escape scanning is on (the default), the driver will do
escape substitution before sending an SQL statement to the database.RowSet object's command
to the given Java float value. The driver converts this to
an SQL REAL value before sending it to the database.RowSet object's command
to the given Java int value. The driver converts this to
an SQL INTEGER value before sending it to the database.RowSet object's command
to the given Java long value. The driver converts this to
an SQL BIGINT value before sending it to the database.BINARY,
VARBINARY, LONGVARBINARYBINARY, CHAR,
VARCHAR, and LONGVARCHAR columns.
If the limit is exceeded, the excess data is silently discarded.
For maximum portability, use values greater than 256.RowSet
object can contain to the specified number.
If the limit is exceeded, the excess rows are silently dropped.RowSet object's SQL
command to SQL NULL.
Note: You must specify the parameter's SQL type.
RowSet object's SQL
command to SQL NULL. This version of the method setNull
should be used for SQL user-defined types (UDTs) and REF type
parameters. Examples of UDTs include: STRUCT, DISTINCT,
JAVA_OBJECT, and named array types.
Note: To be portable, applications must give the
SQL type code and the fully qualified SQL type name when specifying
a NULL UDT or REF parameter. In the case of a UDT,
the name is the type name of the parameter itself. For a REF
parameter, the name is the type name of the referenced type. If
a JDBC driver does not need the type code or type name information,
it may ignore it.
Although it is intended for UDT and REF parameters,
this method may be used to set a null parameter of any JDBC type.
If the parameter does not have a user-defined or REF type,
the typeName parameter is ignored.
RowSet object's command
with a Java Object. For integral values, the
java.lang equivalent objects should be used.
The JDBC specification provides a standard mapping from Java Object types to SQL types. The driver will convert the given Java object to its standard SQL mapping before sending it to the database.
Note that this method may be used to pass datatabase-specific
abstract data types by using a driver-specific Java type.
If the object is of a class implementing SQLData,
the rowset should call the method SQLData.writeSQL
to write the object to an SQLOutput data stream.
If the object is an instance of a class implementing the Ref,
Struct, Array, Blob,
or Clob interfaces,
the driver uses the default mapping to the corresponding SQL type.
An exception is thrown if there is an ambiguity, for example, if the object is of a class implementing more than one of these interfaces.
RowSet object's command
with a Java Object. For integral values, the
java.lang equivalent objects should be used.
This method is like setObject above, but the scale used is the scale
of the second parameter. Scalar values have a scale of zero. Literal
values have the scale present in the literal.
Even though it is supported, it is not recommended that this method be called with floating point input values.
RowSet object's command
with the given Java Object. For integral values, the
java.lang equivalent objects should be used (for example,
an instance of the class Integer for an int).
The given Java object will be converted to the targetSqlType before being sent to the database.
If the object is of a class implementing SQLData,
the rowset should call the method SQLData.writeSQL
to write the object to an SQLOutput data stream.
If the object is an instance of a class implementing the Ref,
Struct, Array, Blob,
or Clob interfaces,
the driver uses the default mapping to the corresponding SQL type.
Note that this method may be used to pass datatabase-specific abstract data types.
RowSet object to
the given String.SQLException is thrown.RowSet object is read-only to the
given boolean.RowSet object's command
with the given Ref value. The driver will convert this
to the appropriate REF(<structured-type>) value.RowSet object that is being synchronized. obj
is set as the value in the data source internally.RowSet object that is being synchronized. obj
is set as the value in the data source internally.RowSet object's command
to the given Java short value. The driver converts this to
an SQL SMALLINT value before sending it to the database.RowSet object's command
to the given Java String value. Before sending it to the
database, the driver converts this to an SQL VARCHAR or
LONGVARCHAR value, depending on the argument's size relative
to the driver's limits on VARCHAR values.RowSet object's command
to the given java.sql.Time value. The driver converts this to
an SQL TIME value before sending it to the database, using the
default java.util.Calendar to calculate it.RowSet object's command
with the given java.sql.Time value. The driver will convert this
to an SQL TIME value, using the given java.util.Calendar
object to calculate it, before sending it to the database.RowSet object's command
to the given java.sql.Timestamp value. The driver converts this to
an SQL TIMESTAMP value before sending it to the database, using the
default java.util.Calendar to calculate it.RowSet object's command
with the given java.sql.Timestamp value. The driver will
convert this to an SQL TIMESTAMP value, using the given
java.util.Calendar object to calculate it, before sending it to the
database.RowSet obejct.RowSet object to the given type.
This method is used to change the type of a rowset, which is by
default read-only and non-scrollable.java.util.Map object as the default
type map for this RowSet object. This type map will be
used unless another type map is supplied as a method parameter.RowSet object will use when it uses the
DriverManager to create a connection.
Setting this property is optional. If a URL is used, a JDBC driver
that accepts the URL must be loaded by the application before the
rowset is used to connect to a database. The rowset will use the URL
internally to create a database connection when reading or writing
data. Either a URL or a data source name is used to create a
connection, whichever was specified most recently.RowSet object to the
given String.