Writing a batch or transaction application
Actuate Information Delivery API supports batch and transaction administration operations. An IDAPI application uses a mixture of developer and API classes to implement a batch or transaction administration operation, including:
Administrate
AdminOperation
Transaction
TransactionOperation
The following sections explain the use of these administration operation classes in detail.
About batch and transaction operations
A batch application submits an array of administration operation requests to an Encyclopedia volume using one composite Administrate message. An Administrate request can contain any number of AdminOperation requests in the batch.
An AdminOperation request can contain any number of Transaction requests.
A Transaction request is a composite message that can contain any number of TransactionOperation requests. A TransactionOperation represents a single unit of work within a Transaction.
The default level of granularity for a transaction is an object. One operation run against one object is atomic. The use of an explicit Transaction tag in a composite Administrate message expands the transaction boundary to include multiple TransactionOperation requests.
To perform an administration operation that contains a set of requests, submit the request as a batch or transaction within one composite Administrate message. If a batch request fails, the operations that complete successfully before the failed operation still take effect. If a transaction operation fails, none of the operations in the transaction take effect. BIRT iHub rolls all the work back, leaving the system in the state it was in just prior to the execution of the transaction operation.
Implementing a transaction-based application
The following application derives from the code in the BIRT iHub Integration Technology example applications for the MS .NET Client. In the example application, AcAddUser_Tran performs a transaction-based administration operation to add multiple Encyclopedia volume users. When the command line includes the optional ignoreDup argument, the program ignores errors if a user already exists.
AcAddUsers_Tran.addUsers( ) performs the following tasks:
Defines a TransactionOperation array, dimensioning the array to the number of new users
namespace Actuate
{
class AcAddUser_Tran
{
…
TransactionOperation[ ] l_transOperation =
new TransactionOperation[numberOfUsers];
Within a loop, for each user:
Instantiates the CreateUser object and sets IgnoreDup
CreateUser l_createUser = new CreateUser( );
l_createUser.IgnoreDup = true;
l_createUser.IgnoreDupSpecified = true;
Instantiates a User object, passing the reference to the CreateUser object, and setting the user name, password, home folder, and other options such as view preference, notification, and e-mail
for (int i = 0; i < numberOfUsers; i++)
{
l_createUser.User = new User( );
l_createUser.User.Name = l_tranUserName;
l_createUser.User.Password = l_tranPassword;
l_createUser.User.HomeFolder = l_tranHomeFolder;
…
Instantiates an AdminOperation object, passing the reference to the CreateUser object
AdminOperation l_createUserOpt = new AdminOperation( );
l_createUserOpt.Item = l_createUser;
Instantiates a TransactionOperation object, passing the reference to the CreateUser object to complete the set up of the transaction operation
l_transOperation[i] = new TransactionOperation( );
l_transOperation[i].Item = l_createUser;
After the end of the loop, instantiates an AdminOperation object, passing the reference to the Transaction object to create the composite administration operation
AdminOperation l_adminOperation = new AdminOperation( );
l_adminOperation.Item = l_transOperation;
Instantiates an AdminOperation array, passing the reference to the AdminOperation object to complete the assembly of the administration operation request
AdminOperation[ ] l_adminRequest = new AdminOperation[1];
l_adminRequest[0] = l_adminOperation;
Makes the administrate proxy call, passing the reference to the administration operation array, handling any Exception that occurs
try
{
l_proxy.administrate(l_adminRequest);
}
catch(Exception e)
{
Console.WriteLine("Create user transaction failed.\n");
PrintExceptionDetails(e);
return;
}
Prints an output message, if the operation succeeds
Console.WriteLine("Create user transaction succeeded.\n");