IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Developing client applications for BPEL processes and tasks > Developing EJB client applications > Access the EJB APIs

Access the local interface of the session bean

An EJB client application for BPEL processes or human tasks accesses the local interface of the session bean through the local home interface of the bean.

The session bean can be either the BusinessFlowManager session bean for process applications or the HumanTaskManager session bean for human task applications.

Procedure

1. Add a reference to the local interface of the session bean to the application deployment descriptor. Add the reference to one of the following files:

   • The application-client.xml file, for a Java™ Platform, Enterprise Edition (Java EE) client application

   • The web.xml file, for a web application

   • The ejb-jar.xml file, for an Enterprise JavaBeans (EJB) application

   The reference to the local home interface for process applications is shown in the following example:

   <ejb-local-ref>
   	<ejb-ref-name>ejb/LocalBusinessFlowManagerHome</ejb-ref-name>
   	<ejb-ref-type>Session</ejb-ref-type>
   	<local-home>com.ibm.bpe.api.LocalBusinessFlowManagerHome</local-home>
   	<local>com.ibm.bpe.api.LocalBusinessFlowManager</local>
   </ejb-local-ref>

   The reference to the local home interface for task applications is shown in the following example:

   <ejb-local-ref>
   	<ejb-ref-name>ejb/LocalHumanTaskManagerHome</ejb-ref-name>
   	<ejb-ref-type>Session</ejb-ref-type>
   	<local-home>com.ibm.task.api.LocalHumanTaskManagerHome</local-home>
   	<local>com.ibm.task.api.LocalHumanTaskManager</local>
   </ejb-local-ref>

   If you use IBM Integration Designer to add the EJB reference to the deployment descriptor, the binding for the EJB reference is automatically created when the application is deployed. For more information on adding EJB references, refer to the Integration Designer documentation.

2. Locate the local home interface of the session bean through the Java Naming and Directory Interface (JNDI).

   The following example shows this step for a process application:

   // Obtain the default initial JNDI context
   InitialContext initialContext = new InitialContext();
   
   // Lookup the local home interface of the BusinessFlowManager bean
    
    LocalBusinessFlowManagerHome processHome = 
         (LocalBusinessFlowManagerHome)initialContext.lookup
         ("java:comp/env/ejb/LocalBusinessFlowManagerHome");

   The local home interface of the session bean contains a create method for EJB objects. The method returns the local interface of the session bean.

3. Access the local interface of the session bean.

   The following example shows this step for a process application:

   LocalBusinessFlowManager process = processHome.create();

   Access to the session bean does not guarantee that the caller can perform all of the actions provided by the bean; the caller must also be authorized for these actions. When an instance of the session bean is created, a context is associated with the instance of the session bean. The context contains the caller's principal ID, group membership list, and indicates whether the caller has one of the Business Process Choreographer Java EE roles. The context is used to check the caller's authorization for each call, even when administrative security is not set. If administrative security is not set, the caller's principal ID has the value UNAUTHENTICATED.

4. Call the business functions exposed by the service interface.

   The following example shows this step for a process application:

   process.initiate("MyProcessModel",input);

   Calls from applications are run as transactions. A transaction is established and ended in one of the following ways:

   • Automatically by WebSphere Application Server (the deployment descriptor specifies TX_REQUIRED).
   • Explicitly by the application. You can bundle application calls into one transaction:

     // Obtain user transaction interface UserTransaction transaction= 
            (UserTransaction)initialContext.lookup("java:comp/UserTransaction");
     
     // Begin a transaction transaction.begin();
     
     // Applications calls ...
     
     // On successful return, commit the transaction transaction.commit();

   Tip: To prevent database deadlocks, avoid running statements similar to the following in parallel:

   // Obtain user transaction interface UserTransaction transaction= 
          (UserTransaction)initialContext.lookup("java:comp/UserTransaction");
   
   transaction.begin();
   
   //read the activity instance 
   process.getActivityInstance(aiid);     
   //claim the activity instance process.claim(aiid);               
        
   transaction.commit();

   The getActivityInstance method and other read operations set a read lock. In this example, a read lock on the activity instance is upgraded to an update lock on the activity instance. This can result in a database deadlock when these transactions are run in parallel

Example

Here is an example of how steps 2 through 4 might look for a task application.

//Obtain the default initial JNDI context
InitialContext initialContext = new InitialContext();

//Lookup the local home interface of the HumanTaskManager bean
LocalHumanTaskManagerHome taskHome = 
        (LocalHumanTaskManagerHome)initialContext.lookup
        ("java:comp/env/ejb/LocalHumanTaskManagerHome");

...
//Access the local interface of the session bean
LocalHumanTaskManager task = taskHome.create();

...
//Call the business functions exposed by the service interface task.callTask(tkiid,input);

Access the EJB APIs

Related concepts:
Authorization roles for BPEL processes
Authorization roles for human tasks