com.sssw.rt.util
Class AgoDataUpdateRow

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

public abstract class AgoDataUpdateRow

extends Object

This is an abstract base class for holding rows to be updated against a "database" or other data source. It's intended to be used as a base class for the use of updatable customer-written data source objects.

The AgoDataUpdateRow holds the AgiDataRow containing the row values as sent from the client, plus additional information including the data source, the kind of update, and the "row factory" to be used in creating a return row with server-modified data.

An updatable data source object can be written that will subclass this class, implementing the checkStatement() and prepareAndExecuteUpdate() methods to actually perform the data update requested by this row.

Protected class variables

This class includes the following fields to be used as parameters with class methods: AgoDataUpdateRow.m_operation, {link #m_mainRow}, and AgoDataUpdateRow.m_updateRow, AgoDataUpdateRow.m_rowFactory, and AgoDataUpdateRow.m_dataSource.

See Also:

AgoDataUpdateRequest

Field Summary

protected AgiDataSource	m_dataSource The data source of this row.
protected AgiDataRow	m_mainRow The data row containing the modified data.
protected char	m_operation The kind of operation (insert, delete, update, or makePrimary) From CommandCodes.
protected AgiDataRowFactory	m_rowFactory The row factory to be used for creating the row to be returned from prepareAndExecuteUpdates() -- this row contains server-modified data, if necessary.
protected AgiDataRow	m_updateRow For an update request only, the data row containing the new values.

Constructor Summary

AgoDataUpdateRow(char operation, AgiDataSource dataSource, AgiDataRowFactory rowFactory, AgiDataRow row)
The constructor for insert, delete, or make-primary operations.

AgoDataUpdateRow(char operation, AgiDataSource dataSource, AgiDataRowFactory rowFactory, AgiDataRow oldRow, AgiDataRow newRow)
The constructor for update operations.

Method Summary

abstract void	checkStatement() Check the update request for validity.
abstract AgiDataRow	prepareAndExecuteUpdate(AgiTransactionHandle transactionHandle) Prepare and execute the statement.

Methods inherited from class java.lang.Object

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

Field Detail

m_operation

protected char m_operation

The kind of operation (insert, delete, update, or makePrimary) From CommandCodes.

m_mainRow

protected AgiDataRow m_mainRow

The data row containing the modified data. For an update request, this is the "old row" containing the pre-modification values.

m_updateRow

protected AgiDataRow m_updateRow

For an update request only, the data row containing the new values. This row is "sparse" -- only the modified columns are present.

See Also:

AgiDataRow.isColumnPresent(int colid)

m_rowFactory

protected AgiDataRowFactory m_rowFactory

The row factory to be used for creating the row to be returned from prepareAndExecuteUpdates() -- this row contains server-modified data, if necessary.

m_dataSource

protected AgiDataSource m_dataSource

The data source of this row.

Constructor Detail

AgoDataUpdateRow

public AgoDataUpdateRow(char operation,
                        AgiDataSource dataSource,
                        AgiDataRowFactory rowFactory,
                        AgiDataRow row)
                 throws AgoApiException

The constructor for insert, delete, or make-primary operations.

Parameters:

operation - update operation (insert, delete, make primary)

dataSource - the source of the row

row - the row itself

Throws:

AgoApiException - on error

Usage:

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

AgoDataUpdateRow

public AgoDataUpdateRow(char operation,
                        AgiDataSource dataSource,
                        AgiDataRowFactory rowFactory,
                        AgiDataRow oldRow,
                        AgiDataRow newRow)
                 throws AgoApiException

The constructor for update operations.

Parameters:

kind - Update operation (always update)

dataSource - the source of the row

oldRow - the old row

newRow - the new row

Throws:

AgoApiException - on error

Usage:

For more information about the parameters, see Protected class variables

Method Detail

checkStatement

public abstract void checkStatement()
                             throws AgoApiException

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

Throws:

AgoApiException - if a statement check fails

Example:

For our example, we verify that no attempt is made to modify the contents of the primary key field in the row.

 public void checkStatement() throws AgoApiException
 {
 if (m_operation == CommandCodes.CCUPDATE && m_updateRow.isColumnPresent(0))
     throw new AgoInvalidDataException("Illegal attempt to modify the primary key for row " + m_mainRow.getRowKey());
 }
 

prepareAndExecuteUpdate

public abstract AgiDataRow prepareAndExecuteUpdate(AgiTransactionHandle transactionHandle)
                                            throws AgoApiException

Prepare and execute the statement. Return the server-modified row, if any (null if none).

Parameters:

transactionHandle - the transaction handle for this update

Returns:

a server-modified row created with the specified row factory, or null if there were no server modifications

Throws:

AgoApiException - if a statement check fails

Example:

This is a fairly elaborate example, but the idea is simple: figure out the kind of operation being performed, and execute the SQL statements needed to do it.

 public AgiDataRow prepareAndExecuteUpdate(AgiTransactionHandle transactionHandle) throws AgoApiException
 {
 MyTransactionHandle hand = (MyTransactionHandle)agiTransactionHandle0;
 Connection conn = hand.getConnection();
 PreparedStatement ps = null;
 try {

     switch (m_operation) {
       case CommandCodes.CCINSERT:
         ps = conn.prepareStatement("insert into Names (ID, Name) values (?, ?)");
         ps.setInt(1, ((Integer)m_mainRow.getData(0)).intValue());
         ps.setString(2, (String)m_mainRow.getData(1));
         break;
       case CommandCodes.CCUPDATE:
         ps = conn.prepareStatement("update Names set Name=? where ID=? and Name=?");
         ps.setString(1, (String)m_updateRow.getData(1));
         ps.setInt(2, ((Integer)m_mainRow.getData(0)).intValue());
         ps.setString(3, (String)m_mainRow.getData(1));
         break;
       case CommandCodes.CCDELETE:
         ps = conn.prepareStatement("delete from Names where ID=? and Name=?");

         ps.setInt(1, ((Integer)m_mainRow.getData(0)).intValue());
         ps.setString(2, (String)m_mainRow.getData(1));
         break;
       default:
         throw new AgoUnrecoverableSystemException("Unsupported update type " + m_operation + " on row " + m_mainRow.getRowKey());
     }
     if (ps.executeUpdate() != 1)
         throw new AgoDataConcurrencyException("Row " + m_mainRow.getRowKey() + " must have been modified");
 } catch (SQLException ex) {
     throw new AgoSystemDatabaseException(ex, "Exception during update of row " + m_mainRow.getRowKey());
 } finally {
     if (ps != null)
       try { ps.close(); } catch (Exception ex) {}
 }
 return null;   // no server-modified rows here
 }