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
.
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 methodsdeploy
,undeploy
,getRuntimeManager
,getDeployedUnits
,isDeployed
,activate
,deactivate
, andgetDeployedUnit
. Calling thedeploy
method with an instance ofDeploymentUnit
deploys the unit into the runtime engine by building aRuntimeManager
instance. After a successful deployment, an instance ofDeployedUnit
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 asactivate
,start
,stop
, andexecute
. -
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.
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
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"); } }
- Build your EJB project to generate the WAR file according to your project configuration.
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. TheSingleton
strategy can cause applications to load the sameksession
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 thehibernate.hbm2ddl.auto
property toupdate
instead ofcreate
.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.