Progress
Open Client
Developer’s Guide
Updating SDOResultSet Objects
To update an SDOResultSet, you must complete two general steps:
CAUTION: If you move the cursor from a row where you have updated columns (for example, usingnext()
) but before you have committed the column updates to the database, your column updates to that row will be lost.Transactions and Concurrency Control
By default, all updates that change the database occur in a transaction managed by the remote SmartDataObject. Typically, any method that updates or deletes an existing row, or that inserts a new row causes the SmartDataObject to complete a transaction for that row. Note that updating column values does not, in itself, change the database. Only row operations can actually cause a transaction to occur.
You can also extend a transaction to include modifications to multiple rows by using an SDOResultSet in Batch mode or by remotely controlling an automatic transaction, if one is available on the AppServer. For more information on Batch mode, see the "Using Batch Mode [Extension]" section, and on automatic transactions, see the "Using Extended Transactions" section.
SmartDataObjects use optimistic concurrency control, which means that records are read without a lock. Locks are acquired only for the short duration of the transaction when modifications are actually performed. Before updating or deleting a row, the remote SmartDataObject implementation compares the original values of the columns to their values in the database to determine if the columns where modified by another user. If one of the columns was modified, the modification does not succeed and the transaction is rolled back. A failed update then throws an
SDOModificationException
. If the SmartDataObject implementation tries to modify or delete a row that is already locked, it also throws anSDOModificationException
. For more information onSDOModificationException
, see the "Errors and Exceptions" section.Updating Column Values
These methods modify a column in an SDOResultSet according to the specified data type. All column access methods in SDOResultSet use the flat model (see "Programming Concepts"). The column is specified by name (columnName) or number (columnIndex) and is set to the specified value (value):
void updateNull(String
columnName)
void updateBoolean(String
columnName, boolean value)void updateInt(String
columnName, int
value)
void updateLong(String
columnName,long
value)
void updateDouble(String
columnName, double
value)
void updateBigDecimal(String
columnName, BigDecimal
value)void updateString(String
columnName, String
value)
void updateBytes(String
columnName, byte
x[])
void updateDate(String
columnName, java.sql.Date
value)
void updateObject(String
columnName, Object
value)
void updateObject(int
columnIndex, Object
value)
void updateNull(int
columnIndex)
void updateBoolean(int
columnIndex, boolean
value)
void updateInt(int
columnIndex, int
value)
void updateLong(int
columnIndex, long
value)
void updateDouble(int
columnIndex, double
value)void updateBigDecimal(int
columnIndex, BigDecimal
value)
void updateString(int
columnIndex, String
value)
void updateBytes(int
columnIndex, byte
x[])
void updateDate(int
columnIndex, java.sql.Date
value)
Some
java.util.Date
andjava.sql.Date
methods are being deprecated by JavaSoft in favor of using the more robustjava.util.GregorianCalendar
. These are the methods that update column values with instances of this class:For more information on the mapping between 4GL and Java data types, see the sections on Progress/Java data type mapping for TEMP–TABLE fields and passing INPUT TEMP–TABLE parameters in Programming Java Clients."
Inserting, Deleting, and Updating Rows
These methods manage operations on rows in the SDOResultSet:
Moves the cursor to a staging position for creating a new row.
Moves the cursor from the insert row back to the current position.
Sends the newly created row to the AppServer.
Deletes the row in the current position and sends the delete request to the AppServer.
Sends the updates for the current row to the AppServer.
Cancels
the updates by rolling back the effects of all method calls that updated column values. To cancel these updates, you must invoke this method before any call to
updateRow()
orinsertRow()
.
Returns
true
if the cursor is positioned on an inserted row position and the row is not yet sent to the AppServer.
Returns
NOTE: The only time the row is not also physically deleted on the AppServer is if you are using a batch update. For more information, see the "Using Batch Mode [Extension]" section.true
if the cursor is positioned on a deleted row, whether or not the deletion is sent to the AppServer because it does not make sense to allow the user to manipulate a row that is logically deleted.
Returns
true
if the cursor is positioned on a row that is modified but not yet sent to the AppServer.Using Extended Transactions
As described earlier in this section, by default, each row modification (row update, insertion, and deletion method) executes as a single transaction in the SmartDataObject. You can extend a transaction to include multiple rows using
Batch
mode, where asendBatch()
method applies a set of row updates as a single transaction (see the "Using Batch Mode [Extension]" section). You can also explicitly manage a larger transaction on the AppServer remotely using an automatic transaction.An automatic transaction allows you to remotely create a larger transaction within which all SmartDataObject transactions become nested as subtransactions. Using an automatic transaction, the Open Client application can start, commit, and roll back a single transaction by executing methods on a special ProcObject defined in the same AppObject that provides access to the corresponding SmartDataObject. The persistent procedure that underlies this ProcObject supports specific functionality and must be available for execution on the AppServer to make an automatic transaction possible. Such a transaction can encompass the entire life of the SDOResultSet. For more information on automatic transactions, see the Building Distributed Applications Using the Progress AppServer manual.
NOTE: You should callreOpenQuery()
after an explicit transaction roll-back in order to maintain a cache that is consistent with the database. ThereOpenQuery()
method can also be desirable after committing a transaction containing inserted rows so that these rows are visible within the result set. For more information on row visibility, see the "Visibility of Updates" section.Using Batch Mode [Extension]
Batch
mode allows an Open Client to group together several updates and send them to the AppServer in one transaction. This might be a better update strategy than generating a transaction for each update method, depending on your application requirements. Thus:
- If your application requires user feedback for each update method applied, you generally must complete a transaction for each update method and
Batch
mode is not appropriate.- If your application requires that a group of updates be applied and succeed together, you must group the updates into a single large transaction. You can do this by using an automatic transaction or by using
Batch
mode. For information on automatic transactions, see the Building Distributed Applications Using the Progress AppServer manual.- If your application has the option of applying several updates individually or as a group, you can generally increase performance dramatically by grouping the updates into a single large transaction using
Batch
mode.- If your SDOResultSet is in
Stateless
mode, you can only apply modifications underBatch
mode.These are the SDOResultSet methods that support
Batch
mode:
Starts a batch session. All the modifications (column updates, deletions and insertions) are maintained locally. Calling this method if you have already called it and have not called
sendBatch()
orcancelBatch()
throws an Exception.
Sends the current batch to the AppServer.
Sends the current batch to the AppServer, then reopens the result set. In
Stateless
mode, this method is more efficient than separately callingsendBatch()
andreOpenQuery()
. For more information, see the "Visibility of Updates" section.
Undoes all the modifications of the current batch.
Returns
NOTE: A row that is updated or deleted intrue
if the SDOResultSet object is inBatch
mode (that is, you have calledstartBatch()
and have not yet calledsendBatch()
orsendBatchandReopen()
).Batch
mode, and has not yet been sent to the AppServer (usingsendBatch()
), cannot be refreshed usingrefreshRow()
. Also, to save your changes locally in batch mode, you must still call the row update methods (for example,insertRow()
orupdateRow()
) even though, in this mode, your changes are not sent to the AppServer.Visibility of Updates
The visibility, from within the Open Client, of an update to the SDOResultSet object depends on whether the update is applied by:
The following rules determine the visibility of updates initiated by the Open Client:
Updates by external applications can typically occur on the data source that feeds the SDOResultSet. You can make any such updates visible to the Open Client application by calling
reOpenQuery()
, which refreshes all the data in the SDOResultSet. However, if you do not callreOpenQuery()
, the following rules determine the visibility of updates from external applications:
- Column Updates — The modification of a column by another application can be made visible by calling the
refreshRow()
method.- Row Inserts — Row inserts are not visible in
PREFETCH
mode. In other scrolling modes, the visibility is determined by a combination of the underlying implementation of SmartDataObject and the 4GL query. The guideline is that the application should not make any assumptions unless it makes an explicit call toreOpenQuery()
.- Row Deletion — Row deletions are not visible in
PREFETCH
scrolling mode. In other scrolling modes, the visibility is determined by a combination of the underlying implementation of the SmartDataObject and the 4GL query. The guideline is that the application should not make any assumptions unless it makes an explicit call torefreshRow()
orreOpenQuery()
. In these cases, the specific row deletion or all the row deletions become visible, respectively.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |