com.sssw.rt.util
Class AgoDataUpdateRequest

java.lang.Object
 |
 +--com.sssw.rt.util.AgoDataUpdateRequest

All Implemented Interfaces:

AgiDataUpdateRequest

public abstract class AgoDataUpdateRequest

extends Object

implements AgiDataUpdateRequest

This is an abstract base class implementing the AgiDataUpdateRequest interface. It's intended to be used as a base class for the use of updatable customer-written Data Source Objects. The DataUpdateRequest acts as a "basket" for gathering up rows to be updated, and then executing the entire batch as a single database transaction. A customer writing an updatable Data Source Object would actually implement 5 separate classes:

• The Data Source Object class itself, implementing two methods: invokeQuery() and prepareUpdateRequest()
• The object that implements ResultSet; invokeQuery() creates one of these and returns it in the event
• An object that extends AgoDataUpdateRequest and overrides the protected methods defined below; prepareUpdateRequest() creates one of these and returns it
• An object that extends AgoDataUpdateRow and overrides the abstract methods it defines for checking and saving the row; the createUpdateRow() method in the AgoDataUpdateRequest subclass creates one of these
• An object that implements AgiTransactionHandle, to pass any necessary information to the row at save time.

Protected class variables

This class includes two fields to be used as parameters with class methods: AgoDataUpdateRequest.m_rowFactory and AgoDataUpdateRequest.m_updateRows.

See Also:

AgiDataUpdateRequest, AgoDataUpdateRow, AgiDataRow, AgiDataRowFactory, AgiTransactionHandle

Field Summary

protected AgiDataRowFactory	m_rowFactory The factory for creating AgiDataRows; this factory must be used for creating any rows returned in the "server-modified rows" enumeration
protected Vector	m_updateRows The vector of update rows, of type AgoDataUpdateRow.

Constructor Summary

AgoDataUpdateRequest(AgiDataRowFactory rowFactory)
The constructor is normally called only from the business object's prepareUpdateRequest factory method.

Method Summary

protected abstract void	abortTransaction(AgiTransactionHandle transactionHandle) Abort the transaction against the "database" associated with this data update request.
protected abstract AgiTransactionHandle	beginTransaction() Start a transaction against the "database" associated with this data update request.
protected void	checkUpdates() Check the update request(s) for validity.
protected abstract void	commitTransaction(AgiTransactionHandle transactionHandle) Commit the transaction against the "database" associated with this data update request.
protected abstract AgoDataUpdateRow	createUpdateRow(char kind, AgiDataSource dataSource, AgiDataRow row) Create a "row holder" object for the specified row.
protected abstract AgoDataUpdateRow	createUpdateRow(char kind, AgiDataSource dataSource, AgiDataRow oldRow, AgiDataRow newRow) Create a "row holder" object for the specified row.
protected Enumeration	executeUpdatesInTransaction(AgiTransactionHandle transactionHandle) Execute the actual updates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods implemented from interface com.sssw.rt.util.AgiDataUpdateRequest

close, deleteRow, executeAllUpdates, insertRow, makePrimaryRow, updateRow

Field Detail

m_rowFactory

protected AgiDataRowFactory m_rowFactory

The factory for creating AgiDataRows; this factory must be used for creating any rows returned in the "server-modified rows" enumeration

m_updateRows

protected Vector m_updateRows

The vector of update rows, of type AgoDataUpdateRow.

Constructor Detail

AgoDataUpdateRequest

public AgoDataUpdateRequest(AgiDataRowFactory rowFactory)

The constructor is normally called only from the business object's prepareUpdateRequest factory method. It takes 'row factory' that was passed to the business object; this is used to construct new data rows to be returned in the enumeration from executeAllUpdates (containing modified data).

Parameters:

rowFactory - Data row factory for modified rows

For the parameter value, see Protected class variables.

Method Detail

createUpdateRow

protected abstract AgoDataUpdateRow createUpdateRow(char kind,
                                                    AgiDataSource dataSource,
                                                    AgiDataRow row)
                                             throws AgoApiException

Create a "row holder" object for the specified row. The row holder must hold the type of update (insert, delete, or makePrimary) and the row itself. All derived classes will need to implement this method by constructing an appropriate derived class of AgoDataUpdateRow that knows how to update itself.

Parameters:

kind - update kind (insert, delete, modify)

dataSource - the source of the row

row - the row itself

Returns:

a derived class of AgoDataUpdateRow

Throws:

AgoApiException - on error

For more information about the parameters, see Protected class variables.

Example:

 protected AgoDataUpdateRow createUpdateRow(char kind, AgiDataSource dataSource, AgiDataRow row)
 throws AgoApiException
 {
 return new MyDataUpdateRow(kind, dataSource, m_rowFactory, row);
 }
 

createUpdateRow

protected abstract AgoDataUpdateRow createUpdateRow(char kind,
                                                    AgiDataSource dataSource,
                                                    AgiDataRow oldRow,
                                                    AgiDataRow newRow)
                                             throws AgoApiException

Create a "row holder" object for the specified row. The row holder must hold the type of update (always update), the old row, and the new row. All derived classes will need to implement this method by constructing an appropriate derived class of AgoDataUpdateRow that knows how to update itself. class of AgoDataUpdateRow that knows how to update itself.

Parameters:

kind - update kind (always update)

dataSource - the source of the row

oldRow - the old row

newRow - the new row

Returns:

a derived class of AgoDataUpdateRow

Throws:

AgoApiException - On error

For more information about the parameters, see Protected class variables.

Example:

 protected AgoDataUpdateRow createUpdateRow(char kind, AgiDataSource dataSource, AgiDataRow oldRow, AgiDataRow newRow)
 throws AgoApiException
 {
 return new MyDataUpdateRow(kind, dataSource, m_rowFactory, oldRow, newRow);
 }
 

checkUpdates

protected void checkUpdates()
                     throws AgoApiException

Check the update request(s) for validity. This includes setting the values of any server-assigned fields, and running any validation expressions.

Normally, the default implementation of this method in AgoDataUpdateRequest, which calls the checkStatement() method of each row in the update, will suffice, but it is documented here in case the user-written derived class needs to override or augment it.

Throws:

AgoApiException - if a statement check fails

Example:

 protected void checkUpdates() throws AgoApiException
 {
 super.checkUpdates();
 // Perform some specific checks here
 ...
 }
 

beginTransaction

protected abstract AgiTransactionHandle beginTransaction()
                                                  throws AgoApiException

Start a transaction against the "database" associated with this data update request. Throws an exception if an error occurs starting the transaction.

Returns:

a transaction handle identifying this transaction

Throws:

AgoApiException - on error

Example:

 protected AgiTransactionHandle beginTransaction() throws AgoApiException
 {
    try {
     Connection conn = m_db.getConnection(true);
     conn.setAutoCommit(false);
     return new MyTransactionHandle(m_db, conn);
 } catch (SQLException ex) {
     throw new AgoSystemDatabaseException(ex, "Error trying to start transaction");
 }
 }
 

commitTransaction

protected abstract void commitTransaction(AgiTransactionHandle transactionHandle)
                                   throws AgoApiException

Commit the transaction against the "database" associated with this data update request.

Parameters:

transactionHandle - the handle returned from the beginTransaction

Throws:

AgoApiException - on error

Example:

 protected void commitTransaction(AgiTransactionHandle transactionHandle) throws AgoApiException
 {
 try {
     MyTransactionHandle hand = (MyTransactionHandle)transactionHandle;
     Connection conn = hand.getConnection();
     conn.commit();
     hand.releaseConnection();
 } catch (SQLException ex) {
     throw new AgoSystemDatabaseException(ex, "Exception during commit");
 }
 }
 

See Also:

AgoDataUpdateRequest.beginTransaction()

abortTransaction

protected abstract void abortTransaction(AgiTransactionHandle transactionHandle)
                                  throws AgoApiException

Abort the transaction against the "database" associated with this data update request.

Parameters:

transactionHandle - the handle returned from the beginTransaction

Throws:

AgoApiException - on error

Example:

 protected void commitTransaction(AgiTransactionHandle transactionHandle) throws AgoApiException
 {
 try {
     MyTransactionHandle hand = (MyTransactionHandle)transactionHandle;
     Connection conn = hand.getConnection();
     conn.rollback();
     hand.releaseConnection();
 } catch (SQLException ex) {
     throw new AgoSystemDatabaseException(ex, "Exception during abort");
 }
 }
 

See Also:

AgoDataUpdateRequest.beginTransaction()

executeUpdatesInTransaction

protected Enumeration executeUpdatesInTransaction(AgiTransactionHandle transactionHandle)
                                           throws AgoApiException

Execute the actual updates. A transaction has already been started. Return an Enumeration of server-modified rows in the correct client-row format (AgiDataRow).

Most derived classes will NOT need to override this method; instead, they will depend on the prepareAndExecuteUpdate() method in the related subclass of AgoDataUpdateRow.

Parameters:

transactionHandle - the handle returned from the beginTransaction

Throws:

AgoApiException - on error

Example:

 protected Enumeration executeUpdatesInTransaction(AgiTransactionHandle transactionHandle) throws AgoApiException
 {
 Enumeration enum = super.executeUpdatesInTransaction(transactionHandle);
 // Do some additional work here ...
     . . .
 return enum;
 }
 

See Also:

AgoDataUpdateRequest.beginTransaction()