org.omus.db
Class DbTransaction

java.lang.Object
  |
  +--org.omus.db.DbTransaction

All Implemented Interfaces:

java.io.Serializable

public class DbTransaction

extends java.lang.Object

implements java.io.Serializable

Represents a transaction; contains one or more DbWriter or DbReader objects to execute custom SQL statements. The statements must be configured in the dbCustom.xml file on the server. This approach may seem a bit cumbersome at first sight. But it is very versatile once you get used to it.

The following example illustrates how you can use the DbTransaction object to read a user ID from one table and use that ID to change a value in another table. By the way: It is the same example used to illustrate the use of the client-side DbTransaction object in the user manual. Most of the classes in org.omus.db have their twins in the client API.

The corresponding entries in dbCustom.xml might look as follows (see the Configuration chapter in the manual for more details):

     <dbReader configID="readUserID" rollbackOnError="true"
         rollbackOnFailure="true">
         <in name="username" />
         <out name="userID" />
         <statement>
             SELECT userID FROM reginfo WHERE username = ?
         </statement>
     </dbReader>

     <dbWriter configID="updateAddress" rollbackOnError="true"
         rollbackOnFailure="true">
         <in name="street" />
         <in name="city" />
         <in name="phone" />
         <in name="userID" />
         <statement>
             UPDATE address SET street = ?, city = ?, phone = ?
             WHERE userID = ?
         </statement>
     </dbWriter>
 

You can write Java code to execute those statements as follows:

     DbTransaction ta = new org.omus.DbTransaction();
     ta.add(new org.omus.DbReader("readUserID"));
     ta.add(new org.omus.DbWriter("updateAddress","address"));
     ta.setParam(new StringField("username","Thomas"));
     ta.setParam(new StringField("street","217 Mulholland Drive"));
     ta.setParam(new StringField("city","Los Angeles"));
     ta.setParam(new StringField("phone","27 27 55 55"));
     DbResult res = null;
     try {
         res = ta.execute();
         int afRows = res.getAffectedRows("address");
         // should be 1
     } catch (DbException dbe) {
         // handle Exception
     }
 

Please note that the second statement has 4 <in> nodes. Three of them (street, city and phone) will be set by your Java code. The last one (userID) will be set automatically because it is configured as an <out>-value in the first statement which will be available to all subsequent statements. The attribute rollbackOnFailure is set to "true" in the first statement so that execution of the transaction will be aborted if the result is empty, because the second statement would fail anyway, if no user with the specified name exists.

See Also:

Serialized Form

Constructor Summary

DbTransaction()
Creates a new DbTransaction object.

Method Summary

void	add(DbTransactionPart tap) Adds a DbWriter or DbReader object to this transaction.
DbResult	execute() Executes this transaction and returns the result.
void	setAllParams(DataRow dr) Adds all DataFields contained in the specified DataRow as a parameter to this DbTransaction.
void	setParam(DataField df) Adds the specified DataField as a parameter to this DbTransaction.
int	size() Returns the number of DbWriter and DbReader objects that have been added to this transaction.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DbTransaction

public DbTransaction()

Creates a new DbTransaction object.

Method Detail

size

public int size()

Returns the number of DbWriter and DbReader objects that have been added to this transaction.

add

public void add(DbTransactionPart tap)

Adds a DbWriter or DbReader object to this transaction.

setParam

public void setParam(DataField df)

Adds the specified DataField as a parameter to this DbTransaction. The name of the DataField must match the name attribute of one of the <in> nodes you specified in the dbCustom.xml file. If you set a parameter in the DbTransaction object it is available to all the DbWriter or DbReader parts you add to this transaction. If you want to set parameters that can only be read by one particular DbWriter or DbReader object, you must use the setParam method of those objects.

setAllParams

public void setAllParams(DataRow dr)

Adds all DataFields contained in the specified DataRow as a parameter to this DbTransaction. The name of each DataField must have a matching name attribute in one of the <in> nodes you specified in the dbCustom.xml file. If you set parameters in the DbTransaction object, they are available to all the DbWriter or DbReader parts you add to this transaction. If you want to set parameters that can only be read by one particular DbWriter or DbReader object, you must use the setParam method of those objects.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

execute

public DbResult execute()
                 throws DbException

Executes this transaction and returns the result.