Chapter 9. EJB API for KIE sessions and task services

Red Hat Process Automation Manager provides an Enterprise JavaBeans (EJB) API that you can use for embedded use cases to access KieSession and TaskService objects remotely from an application. The EJB API enables close transaction integration between the process engine in Red Hat Process Automation Manager and remote customer applications.

Although KIE Server does not support EJB, you can use EJB as a remote protocol for the process engine similar to remote REST or JMS operations with KIE Server.

The implementation of the EJB interface is a single framework-independent and container-agnostic API that you can use with framework-specific code. The EJB services are exposed through the org.jbpm.services.api and org.jbpm.services.ejb packages in Red Hat Process Automation Manager. The implementation does not support the RuleService class, but the ProcessService class exposes an execute method that enables you to use various rule-related commands, such as InsertCommand and FireAllRulesCommand.

Note

Contexts and Dependency Injection (CDI) is also supported through the org.jbpm.services.cdi package in Red Hat Process Automation Manager. However, to avoid conflicts in your EJB integration, do not use EJB and CDI together.

9.1. Supported EJB services

For the full list of available Enterprise JavaBeans (EJB) services in Red Hat Process Automation Manager, download the Red Hat Process Automation Manager 7.8.0 Maven Repository from the Red Hat Customer Portal and navigate to ~/jboss-rhba-7.8.0.GA-maven-repository/maven-repository/org/jbpm/jbpm-services-ejb-*.

The artifacts that provide the EJB interface to the jBPM services are in the following packages:

  • org.jbpm.services.ejb.api: Contains extensions of the jBPM services API for the EJB interface
  • org.jbpm.services.ejb.impl: Contains EJB wrappers on top of the core service implementation
  • org.jbpm.services.ejb.client: Contains the EJB remote client implementation, supported on Red Hat JBoss EAP only

The org.jbpm.services.ejb.api package contains the following service interfaces that you can use with remote EJB clients:

  • DefinitionServiceEJBRemote: Use this interface to gather information about processes (ID, name, and version), process variables (name and type), defined reusable subprocesses, domain-specific services, user tasks, and user task inputs and outputs.
  • DeploymentServiceEJBRemote: Use this interface to initiate deployments and undeployments. The interface includes the methods deploy, undeploy, getRuntimeManager, getDeployedUnits, isDeployed, activate, deactivate, and getDeployedUnit. Calling the deploy method with an instance of DeploymentUnit deploys the unit into the runtime engine by building a RuntimeManager instance. After a successful deployment, an instance of DeployedUnit is created and cached for further use. (To use these methods, you must install the artifacts of the project in a Maven repository.)
  • ProcessServiceEJBRemote: Use this interface to control the life cycle of one or more processes and work items.
  • RuntimeDataServiceEJBRemote: Use this interface to retrieve data related to the run time, such as process instances, process definitions, node instance information, and variable information. The interface includes several convenience methods for gathering task information based on owner, status, and time.
  • UserTaskServiceEJBRemote: Use this interface to control the life cycle of a user task. The interface includes several convenience methods for interacting with user tasks, such as activate, start, stop, and execute.
  • QueryServiceEJBRemote: Use this interface for advanced queries.
  • ProcessInstanceMigrationServiceEJBRemote: Use this interface to migrate process instances when a new version of a process definition is deployed.

If you run EJB applications and Business Central on the same KIE Server instance, you can synchronize the information between EJB and Business Central at a specified interval by setting the org.jbpm.deploy.sync.int system property. After the service finishes the synchronization, you can access the updated information using REST operations.

Note

EJB services in Red Hat Process Automation Manager are intended for embedded use cases. If you run EJB applications and Business Central on the same KIE Server instance, you must also add the kie-services package on the class path of your EJB application.

9.2. Deploying an EJB services WAR file

You can use the Enterprise JavaBeans (EJB) interface to create and deploy an EJB services WAR file that you want to use as part of your Red Hat Process Automation Manager distribution.

Procedure

  1. Register a human task callback using a startup Java class, such as the following example:

    @Singleton
    @Startup
    public class StartupBean {
    
      @PostConstruct
      public void init()
      { System.setProperty("org.jbpm.ht.callback", "jaas"); }
    
    }
  2. Build your EJB project to generate the WAR file according to your project configuration.
  3. Deploy the generated file on the Red Hat JBoss EAP instance where Red Hat Process Automation Manager is running.

    Avoid using the Singleton strategy for your runtime sessions. The Singleton strategy can cause applications to load the same ksession instance multiple times from the underlying file system and cause optimistic lock exceptions.

    If you want to deploy the EJB WAR file on a Red Hat JBoss EAP instance separate from the one where Red Hat Process Automation Manager is running, configure your application or the application server to invoke a remote EJB and to propagate the security context.

    If you are using Hibernate to create a database schema for Red Hat Process Automation Manager, update the persistence.xml file in Business Central and set the value of the hibernate.hbm2ddl.auto property to update instead of create.

  4. Test the deployment locally by creating a basic web application and injecting the EJB services, as shown in the following example:

    @EJB(lookup = "ejb:/sample-war-ejb-app/ProcessServiceEJBImpl!org.jbpm.services.ejb.api.ProcessServiceEJBRemote")
    private ProcessServiceEJBRemote processService;
    
    @EJB(lookup = "ejb:/sample-war-ejb-app/UserTaskServiceEJBImpl!org.jbpm.services.ejb.api.UserTaskServiceEJBRemote")
    private UserTaskServiceEJBRemote userTaskService;
    
    @EJB(lookup = "ejb:/sample-war-ejb-app/RuntimeDataServiceEJBImpl!org.jbpm.services.ejb.api.RuntimeDataServiceEJBRemote")
    private RuntimeDataServiceEJBRemote runtimeDataService;

For more information about developing and deploying EJB applications with Red Hat JBoss EAP, see Developing EJB Applications.