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 com.actuate.schemas 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 Apache Axis 2 client. In the example application, AcAddUsers_Tran.addUsers( ) performs a transaction-based administration operation to add multiple 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.
public class AcAddUsers_Tran {
…
public static void addUsers( ) throws RemoteException {
// set up transaction operation array
TransactionOperation[ ] transactionOperations =
new TransactionOperation[numberOfUsers];
System.out.println("\nAdding users… \n");
In addUsers( ), within a loop, for each user:
Instantiates a com.actuate.schemas.User object, setting the user name, password, home folder, and other options such as view preference, notification, and e-mail.
// begin loop to create a user transaction operation
for (int i = 0; i < numberOfUsers; i++) {
// set User with user name, password, and home folder
com.actuate.schemas.User user = new
com.actuate.schemas.User();
user.setName(userName);
user.setPassword(password);
user.setHomeFolder(homeFolder);
…
Instantiates the CreateUser object, passing the reference to the current User object and setting IgnoreDup.
// create user
com.actuate.schemas.CreateUser createUser =
new com.actuate.schemas.CreateUser( );
createUser.setUser(user);
createUser.setIgnoreDup(ignoreDup);
Instantiates an AdminOperation object, passing the reference to the CreateUser object.
// set Administration operation for current user
com.actuate.schemas.AdminOperation adminOperation =
new com.actuate.schemas.AdminOperation( );
adminOperation.setCreateUser(createUser);
Instantiates a TransactionOperation object, passing the reference to the current User object to complete the set up of the transaction operation.
// set transaction operation for current user
TransactionOperation transactionOperation =
new TransactionOperation( );
transactionOperation.setCreateUser(createUser);
Adds the reference to the current TransactionOperation object to the TransactionOperation array.
transactionOperations[i] = transactionOperation;
}
After the end of loop, instantiates a Transaction object, passing the reference to the TransactionOperation array that contains the details of all the create user operations.
// set up the transaction with the transaction operations
Transaction transaction = new Transaction( );
transaction.setTransactionOperation(transactionOperations);
Instantiates an AdminOperation object, passing the reference to the Transaction object to create the composite administration operation.
// set up Administration operation
AdminOperation adminOperation = new AdminOperation( );
adminOperation.setTransaction(transaction);
Calls ActuateControl.runAdminOperation( ), passing the reference to the composite administration operation, and returning a reference to the AdministrateResponse object that contains the Encyclopedia volume response.
// run Administration operation
if (null == actuateControl.runAdminOperation(adminOperation)) {
Prints an output message, indicating the success or failure of the transaction, depending on whether the reference to the AdministrateResponse object is null or valid.
System.out.println("Create user transaction
failed.\n");
}
else {
System.out.println("Create user transaction succeeded.
\n");
}
}