Accessing the remote session bean

An EJB client application accesses the appropriate remote session bean through the home interface of the bean.

Why and when to perform this task

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

Steps for this task

  1. Add a reference to the remote session bean to the application deployment descriptor. Add the reference to one of the following files:
    • The application-client.xml file, for a Java™ 2 Platform, Enterprise Edition (J2EE) 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 remote home interface for process applications is shown in the following example:
    <ejb-ref>
    	<ejb-ref-name>ejb/BusinessFlowManagerHome</ejb-ref-name>
    	<ejb-ref-type>Session</ejb-ref-type>
    	<home>com.ibm.bpe.api.BusinessFlowManagerHome</home>
    	<remote>com.ibm.bpe.api.BusinessFlowManager</remote>
    </ejb-ref>
    The reference to the remote home interface for task applications is shown in the following example:
    <ejb-ref>
    	<ejb-ref-name>ejb/HumanTaskManagerHome</ejb-ref-name>
    	<ejb-ref-type>Session</ejb-ref-type>
    	<home>com.ibm.task.api.HumanTaskManagerHome</home>
    	<remote>com.ibm.task.api.HumanTaskManager</remote>
    </ejb-ref>

    If you use WebSphere® Integration Developer 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 WebSphere Integration Developer documentation.

  2. Package the generated stubs with your application.

    If your application runs on a different Java Virtual Machine (JVM) from the one where the BPEContainer application or the TaskContainer application runs, complete the following actions:

    1. For process applications, package the <install_root>/ProcessChoreographer/client/bpe137650.jar file with the enterprise archive (EAR) file of your application.
    2. For task applications, package the <install_root>/ProcessChoreographer/client/task137650.jar file with the EAR file of your application.
    3. If you use complex data types in your business process or human task and your client does not run in an EJB application or a Web application, package the corresponding XSD or WSDL files with the EAR file of your application.
    4. Set the Classpath parameter in the manifest file of the application module to include the JAR file.

      The application module can be a J2EE application, a Web application, or an EJB application.

  3. Retrieve a reference to the home interface of the remote session bean from 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 remote home interface of the BusinessFlowManager bean
      Object result = 
             initialContext.lookup("java:comp/env/ejb/BusinessFlowManagerHome");
    
    // Convert the lookup result to the proper type
       BusinessFlowManagerHome processHome = 
               (BusinessFlowManagerHome)javax.rmi.PortableRemoteObject.narrow
               (result,BusinessFlowManagerHome.class);
    The home interface of the session bean contains a create method for EJB objects. The method returns the remote interface of the session bean.
  4. Access the remote interface of the session bean.

    The following example shows this step for a process application:

    BusinessFlowManager 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 J2EE roles. The context is used to check the caller's authorization for each call, even when global security is not set. If global security is not set, the caller's principal ID has the value UNAUTHENTICATED.

  5. 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("jta/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 transactions:
    // Obtain user transaction interface
    UserTransaction transaction= 
           (UserTransaction)initialContext.lookup("jta/usertransaction");
    
    transaction.begin();
    
    //read lock on the activity instance 
    process.getActivityInstance(aiid);     
    //write lock on the activity instance
    process.claim(aiid);               
         
    transaction.commit();

Example

Example

Here is an example of how steps 3 through 5 might look for a task application.

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

//Lookup the remote home interface of the HumanTaskManager bean
Object result = 
         initialContext.lookup("java:comp/env/ejb/HumanTaskManagerHome");

//Convert the lookup result to the proper type
HumanTaskManagerHome taskHome = 
           (HumanTaskManagerHome)javax.rmi.PortableRemoteObject.narrow
           (result,HumanTaskManagerHome.class);

...
//Access the remote interface of the session bean.
HumanTaskManager task = taskHome.create();

...
//Call the business functions exposed by the service interface
task.callTask(tkiid,input);
Related concepts
Authorization roles for business processes
Authorization roles for human tasks

(c) Copyright IBM Corporation 2005, 2006.
This information center is powered by Eclipse technology (http://www.eclipse.org)