Creating Service Managed Transaction Components

A service implementation is a Plain Old Java Object (POJO) that you develop by creating a Java interface. This interface defines the service’s operations (public methods), input values, and return values. The public methods that are defined within the Java interface become operations that the service exposes. You do not need to implement any Adobe-specific Java libraries when creating a service interface.

The SMT component that is developed exposes an operation named UpdateDatabase that is defined in the component interface. The following Java code example shows the DatabaseTransaction interface.

package com.adobe.sample.database; 
 
public interface DatabaseTransaction{ 
     
    //Create an operation to update the Employee and Contact tables 
    public int UpdateDatabase( 
            String firstName,// common to both tables         
            String lastName, //common to both tables 
            String email, // common to both tables 
            String phone, // common to both tables 
            String title, // required for the employee table 
            String compId,// required for the employee table 
            String address,//required for the contact table 
            String city, //required for the contact table 
            String state, //required for the contact table 
            String zip, //required for the contact table 
            String country, //required for the contact table 
            String notes); //required for the contact table 
    }

The DatabaseTransaction interface belongs to a package named com.adobe.sample.database.

Create a service implementation class that implements DatabaseTransaction. A service implementation conforms to the following restrictions:

• The implementation class must have a public no-argument constructor.

• The service implementation class must be stateless.

• Input parameters, output parameters, and exceptions must be serializable.

The business logic that LiveCycle executes when the operation is invoked must be specified in the corresponding methods. For example, consider the UpdateDatabase method that is defined in the DatabaseTransaction interface. Create business logic within the UpdateDatabase method that updates the HSQLDB database using transactions.

The UpdateDatabase method requires the following string arguments:

• firstName: Specifies the first name of the employee.

• lastName: Specifies the last name of the employee.

• email: Specifies the email address of the employee.

• phone: Specifies the phone number of the employee.

• title: Specifies the job title of the employee.

• compId: Specifies the company identifier value.

• address: Specifies the address of the employee.

• city: Specifies the city in which the employee lives.

• state: Specifies the state in which the employee lives.

• zip: Specifies the zip code of the employee.

• country: Specifies the country in which the employee lives.

• notes: Specifies additional information associated with the employee.

The following Java code shows the Java implementation class named DatabaseTransactionImpl that implements DatabaseTransaction. Notice that this class is located within a Java package named com.adobe.sample.database. The UpdateDatabase method returns the value 1 if the update was successful. If an exception was thrown and a rollback operation occurred, this method returns the value -1.

package com.adobe.sample.database; 
 
import java.sql.DriverManager; 
import java.sql.PreparedStatement; 
import java.sql.Savepoint; 
 
public class DatabaseTransactionImpl implements DatabaseTransaction { 
 
     
public int UpdateDatabase(String firstName, String lastName, String email, 
            String phone, String title, String compId, String address, 
            String city, String state, String zip, String country, String notes) { 
         
        //Declare a Connection and Sharepoint object 
        java.sql.Connection con = null; 
        Savepoint mySavePoint = null; 
         
        //Create a return value that indicates if the operation was successful 
        int returnVal = 0;  
        try{ 
             
            //Perform updates to Contact table and Employee table as a single transaction 
            Class.forName("org.hsqldb.jdbcDriver"); 
             
            // Specify an URL to the HSQLDB database 
            String url = "jdbc:hsqldb:hsql://scottm-xp:9002/flexdemodb"; 
             
            // Create a Connection object 
            con =  DriverManager.getConnection(url); 
             
             //set auto-comment to false - necessary to perform a transaction 
            con.setAutoCommit(false); 
                         
            //Populates data fields required by both the Employee table and Contact table 
            String FIRST_NAME = firstName; // common to both tables 
            String LAST_NAME = lastName;  //common to both tables 
            String EMAIL=email; // common to both tables 
            String PHONE=phone; // common to both tables 
            String TITLE =title; // required for employee table 
            int COMPANY_ID = Integer.parseInt(compId); // required for employee table 
            String ADDRESS = address ; //required for contact table 
            String CITY = city; //required for contact table 
            String STATE = state ; //required for contact table 
            String ZIP = zip ; //required for contact table 
            String COUNTRY = country ; //required for contact table 
            String Notes = notes ; //required for contact table 
             
            // set a savepoint 
            mySavePoint = con.setSavepoint("sp1"); 
 
          //Update the Employee table using a Prepared Statement 
            PreparedStatement psEmployee = con.prepareStatement( 
                       "INSERT INTO employee " + 
                       "(FIRST_NAME, LAST_NAME, EMAIL, PHONE, " + 
                       "TITLE, COMPANY_ID) " + 
                       "VALUES (?,?,?,?,?,?)"); 
 
            //Set the field values 
            psEmployee.setString(1,FIRST_NAME); 
            psEmployee.setString(2,LAST_NAME); 
            psEmployee.setString(3,EMAIL); 
            psEmployee.setString(4,PHONE); 
            psEmployee.setString(5,TITLE); 
            psEmployee.setInt(6,COMPANY_ID); 
     
     
             //Update the Contact table using a Prepared Statement 
          PreparedStatement psContact = con.prepareStatement( 
                       "INSERT INTO contact " + 
                       "(FIRST_NAME, LAST_NAME, EMAIL, PHONE, " + 
                       "ADDRESS, CITY,STATE,ZIP,COUNTRY,Notes) " + 
                       "VALUES (?,?,?,?,?,?, ?,?,?,?)"); 
 
             //Set the field values 
            psContact.setString(1,FIRST_NAME); 
            psContact.setString(2,LAST_NAME); 
            psContact.setString(3,EMAIL); 
            psContact.setString(4,PHONE); 
            psContact.setString(5,ADDRESS); 
            psContact.setString(6,CITY); 
            psContact.setString(7,STATE); 
            psContact.setString(8,ZIP); 
            psContact.setString(9,COUNTRY); 
            psContact.setString(10,Notes); 
             
            // Insert new employee record 
            psEmployee.executeUpdate(); 
             
            // Insert new Contact record 
            psContact.executeUpdate(); 
                 
            //commit these updates to the database 
            con.commit(); 
            con.close(); 
            returnVal = 1;  
            } 
         
        //If an exception is thrown during the update - roll back the transaction 
        catch (Exception ee) 
         { 
            try 
                { 
                    ee.printStackTrace(); 
                     
                    //Rollback the transaction     
                    con.rollback(mySavePoint); 
                    con.close(); 
                    returnVal = -1;  
                    return returnVal;  
                } 
                catch (Exception ex1) 
                { 
                    ex1.printStackTrace(); 
                } 
        } 
    return returnVal; 
    } 
} 

To deploy the SMT component to LiveCycle, package your Eclipse project into a JAR file. Ensure that external JAR files that the component’s business logic depends on, such as hsqldb.jar (applicable to this SMT component), are also included. As well, the component XML file must be present. The component.xml file and external JAR files must be located at the root of the JAR file.

The following illustration shows the Eclipse project’s content, which is packaged into the component’s JAR file.

Grafik in Originalgröße anzeigen

You can use Workbench to deploy the SMT component by performing the following steps:

1. Start Workbench.

2. Log in to Workbench.

3. Select Window,Show Views, Components. This action adds the Components view to Workbench.

4. Right-click the Components icon and select Install Component.

5. Select the JAR file that represents your component by using the file browser and click Open.

   Notice that there is a red square next to the new com.adobe.sample.database.DatabaseTransactionService. Expand com.adobe.sample.database.DatabaseTransactionService.

6. Select Service Descriptors, and then right-click DatabaseTransactionService and select Activate Service.

7. Right-click on the component name and select Start Component.

8. Expand the Active Services and right-click DatabaseTransactionService and select Start Component. A green arrow appears next to the name if it succeeds.

The following illustration shows a process named MyApplication/UpdateHSQLDatabase that updates the Employee and Contact tables by using the SMT component.

Grafik in Originalgröße anzeigen

The following illustration shows the property editor that lets you specify input values that the SMT component requires.

Grafik in Originalgröße anzeigen

Notice that these input values correspond to the parameters that belong to the UpdateDatabase method that is defined in the DatabaseTransaction interface. For information, see Define the DatabaseTransaction interface.

These values are string process variables that you specify when you invoke the process. To create a process that uses the SMT component, perform the following steps in Workbench:

1. Start Workbench.

2. Under the Application tab in Workbench, select MyApplication. Right click and select New > Process.

3. In the New Process dialog box, specify UpdateHSQLDatabase for the process name and click Finish.

4. Using the Activity picker, select the SetValue operation. Create a string process variable for each input parameter defined by the UpdateDatabase operation.

5. Using the Activity picker, select the UpdateDatabase operation that belongs to DatabaseTransactionService.

6. Click the Process Properties tab. Under the Input option, there are default property-editors for each input parameter. Select the process variable that corresponds to the input parameter. Assign a process variable for each input parameter.

7. Create an output process variable to handle the return value of the UpdateDatabase method. Ensure that the data type for the output variable is int. Under the Output option, specify the output process variable in the OutValue field.

8. Under the Application tab in Workbench, select MyApplication. Right click and select Deploy.

9. Invoke the process from within Workbench by selecting MyApplication/UpdateHSQLDatabase. Right click and select invoke.

10. In the Check In Assets dialog box, select Check in all files and click OK.

11. Specify input parameter values for the fields and click OK. If the updates are made, the value 1 is returned. If an exception is thrown and a rollback occurs, the value -1 is returned.

You can programmatically invoke the DatabaseTransactionService (which belongs to the SMT component) by using the Java API. That is, you can invoke the UpdateDatabase operation by using the Java Invocation API. For more information, see Invoking LiveCycle using the Java API.

You can invoke the DatabaseTransactionService defined in the SMT component by performing the following tasks:

1. Include client JAR files, such as the adobe-livecycle-client.jar, in your Java project’s class path. For information about the location of these files, see Including LiveCycle Java library files.

2. Set connection properties that are required to invoke a service. For information, see Setting connection properties.

3. Create a ServiceClientFactory object by invoking the ServiceClientFactory object’s static createInstance method and passing the java.util.Properties object that contains connection properties. A ServiceClientFactory object is a Java singleton responsible for creating a ServiceClient instance and maintaining connection settings.

4. Create a ServiceClient object by invoking the ServiceClientFactory object’s getServiceClient method. A ServiceClient object lets you invoke a service operation. It handles tasks such as locating, dispatching, and routing invocation requests.

5. Create a java.util.HashMap object.

6. Invoke the java.util.HashMap object’s put method for each parameter required to execute the service. You invoke this method 12 times to correspond to the parameters specified in the UpdateDatabase method that is defined in the DatabaseTransaction interface. For information, see Define the DatabaseTransaction interface.

7. Create an InvocationRequest object by invoking the ServiceClientFactory object’s createInvocationRequest method and passing the following values:

   • A string value that specifies DatabaseTransactionService (the name of the service to invoke).

   • A string value that specifies UpdateDatabase (the name of the operation to invoke).

   • The java.util.HashMap object that contains the parameter values that the service operation requires.

   • A Boolean value where the value true creates a synchronous request and the value false creates an asynchronous request. Pass the value true.

8. Send the invocation request to the service by invoking the ServiceClient object’s invoke method and passing the InvocationRequest object.

9. Retrieve the return value of the invoke method. This method returns an instance of com.adobe.idp.dsc.InvocationResponse.

10. Retrieve the return value of the UpdateDatabase operation by invoking the InvocationResponse object’s getParameter method. Pass the string value outValue, which corresponds to the name of the return value as specified in the component XML file. The data type of this value is java.lang.Integer. Ensure that you cast the return value to java.lang.Integer.

The following Java example invokes the UpdateDatabase operation that belongs to the DatabaseTransactionService by using the Java invocation API. If the value 1 is returned, the update to the Employee and Contact tables was successfully performed. If the value -1 was returned, the updates were not made to these tables and a rollback operation was performed.

package com.adobe.update.database; 
 
import com.adobe.idp.dsc.InvocationRequest; 
import com.adobe.idp.dsc.InvocationResponse; 
import com.adobe.idp.dsc.clientsdk.ServiceClientFactory; 
import com.adobe.idp.dsc.clientsdk.ServiceClient; 
import com.adobe.idp.dsc.clientsdk.ServiceClientFactoryProperties; 
import java.util.Properties; 
import java.util.Map; 
import java.util.HashMap; 
 
public class InvokeDatabaseTransactionService { 
     
    public static void main(String[] args) { 
 
        try{ 
            //Set connection properties required to invoke LiveCycle 
            Properties connectionProps = new Properties(); 
            connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://hiro-xp:1099"); 
            connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);           
            connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss"); 
            connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
            connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password"); 
     
            //Create a ServiceClientFactory object 
            ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps); 
         
            //Create a ServiceClient object 
            ServiceClient myServiceClient = myFactory.getServiceClient(); 
         
            //Create a Map object to store the parameter value 
            Map params = new HashMap(); 
             
                //Populate the Map object with parameter values  
            //required to invoke the UpdateDatabase operation 
            params.put("firstName", "Tony"); 
            params.put("lastName", "Blue"); 
            params.put("email","tblue@nomailserver.com"); 
            params.put("phone", "555-555-5555"); 
            params.put("title", "Developer"); 
            params.put("compId", "10"); 
            params.put("address", "1 NoWhere Dr"); 
            params.put("city", "New York"); 
            params.put("state", "NY"); 
            params.put("zip", "55555"); 
            params.put("country", "USA"); 
            params.put("notes", "New Employee"); 
                     
            //Create an InvocationRequest object 
            InvocationRequest request =  myFactory.createInvocationRequest( 
                "DatabaseTransactionService",  //Specify the service name 
                "UpdateDatabase",                 //Specify the operation name     
                params,               //Specify input values 
                true);               //Create a synchronous request  
                 
            //Send the invocation request and get back the response 
            InvocationResponse resp = myServiceClient.invoke(request); 
         
            java.lang.Integer updateStatus = (java.lang.Integer)resp.getOutputParameter("outValue"); 
            int intVal = updateStatus.intValue(); 
         
            if (intVal == 1) 
                System.out.println("The updates were successfully made"); 
            else 
                System.out.println("The updates were not made - a rollback was performed"); 
         
    }catch (Exception e) { 
            e.printStackTrace(); 
    } 
 
    } 
}