Migrating to JBPM4

As you well know, I was using for one of my projects JBPM3, but then I decided to to jump into something more stable and even cool! (which will give me more automatization and the ability to recover from server crashes - in other words, restart a process previously interrupted :) )

The API changed completely, some classes were renamed others were removed, methods are not the same, configuration is different, in a few words "It doesn't have any relation with the previous version"

Cons:

You won't be able to keep your logs or comments on your tables, no more Transient variables, no more stoping process due to Exceptions, no more suspend or resume process (using the API), poor history of each execution - but it really helps what you see (if you want more details, I recommend you to use wisely your Log4J), if you don't believe me, look at my base handler after I migrated
public abstract class BaseCustomJbpm4Handler { /** * Retrieve a variable from the context * * @param name * @param executionContext * @return Object */ protected final Object getVariableFromContext(final String name, OpenExecution openExecution){ return openExecution.getProcessInstance().getVariable(name); } /** * Add a variable into the context<br> * <b>All variables to be added into the Context MUST Implement <code>java.io.Serializable</code> Interface</b> * * @param name * @param executionContext * @return Object */ protected final void setVariableIntoContext(final String name, Object value, OpenExecution openExecution){ openExecution.getProcessInstance().setVariable(name, value); } /** * Add a variable into the context and Keep track of it on JBPM4_HIST_VAR table<br> * <b>All variables to be added into the Context MUST Implement <code>java.io.Serializable</code> Interface</b> * * @param name * @param executionContext * @return Object */ protected final void createVariable(final String name, Object value, OpenExecution openExecution){ ((ExecutionImpl)openExecution).createVariable(name, value, "string", true); } /** * Retrieve a Transient variable from the context.<br>Transient variables are not stored in DB. * * @param name * @param executionContext * @return Object */ protected final Object getTransientVariableFromContext(final String name, OpenExecution openExecution){ return this.getVariableFromContext(name, openExecution);//Transient Variables NOT AVAILABLE on JBPM4 } /** * Add a Transient variable into the context.<br>Transient variables are not stored in DB.<br> * <b>All variables to be added into the Context MUST Implement <code>java.io.Serializable</code> Interface</b> * * @param name * @param executionContext * @return Object */ protected final void setTransientVariableIntoContext(final String name, Object value, OpenExecution openExecution){ this.setVariableIntoContext(name, value, openExecution);//Transient Variables NOT AVAILABLE on JBPM4 } /** * Retrieves a reference to a Seam session bean component stub, * which can then be used to remotely execute methods against your component.<br> * This method returns a singleton for the specified component, * so calling it twice in a row with the same component name * will return the same instance of the component.<br> * If the component doesn't exist, by default we're telling Seam to create a new instance. * * @param componentName * @param scopeType * @return Object */ protected Object getSeamComponentInstance(final String componentName, final ScopeType scopeType){ //For Asyc Calls we have to do this to avoid "IllegalStateException: No event context active" when using Component.getInstance() if (!Contexts.isApplicationContextActive() || !Contexts.isEventContextActive() || !Contexts.isSessionContextActive() || !Contexts.isConversationContextActive() || !Contexts.isMethodContextActive()){ Lifecycle.beginCall(); } return Component.getInstance(componentName, scopeType, true); } }

Pros:

Process definition is the same file which describes de Diagram spec (no more hidden files), configuration file is much simpler (the default params work really nice - It's almost ready for production out of the box), hibernate configuration is much easy to read, process could be started easily by using code (FEWER lines that in JBPM3), ASYNC process really work!, resume processes interrupted, you can define a business key for each execution - look into table JBPM4_HIST_PROCINST, Timer really works! - you'll see it on my process definition

This is how I started my process (due to my process is ASYNC, it doesn't wait until process is completed to return a response - which is great for Fire and Forget, obviously the first request will be the one which takes longer, because it will have to wait until everything is loaded but the next request will be super fast! - I've seen and Avg. of 70ms)
@Name("rtcapProcessExecutor") @Scope(ScopeType.APPLICATION) @Startup @BypassInterceptors @Install(precedence = Install.APPLICATION) public final class RtcapProcessRunner { private static Logger log = Logger.getLogger(RtcapProcessRunner.class); private ProcessEngine processEngine; private RepositoryService repositoryService; private ExecutionService executionService; /** * Initiates the jBPM Context * */ @Create public void startup() { try{ String jbpmConfigFile = GenericConstants.JBPM_RTCAP_DISABLED_CONFIG_FILE; if(BooleanUtils.toBoolean(System.getProperty(GenericConstants.RTCAP_ENABLED, "false"))){//Verify if JobExecutor is enabled in order to determine which config file to load jbpmConfigFile = GenericConstants.JBPM_RTCAP_ENABLED_CONFIG_FILE; } log.info("Creating JBPM process engine using configuration file ("+jbpmConfigFile+") and Loading process definition ("+GenericConstants.PROCESS_DEFINITION_FILE+")"); this.processEngine = new Configuration().setResource(jbpmConfigFile).buildProcessEngine(); this.repositoryService = this.processEngine.getRepositoryService(); this.executionService = this.processEngine.getExecutionService(); this.repositoryService.createDeployment().addResourceFromClasspath(GenericConstants.PROCESS_DEFINITION_FILE).setName(GenericConstants.RTCAP).setTimestamp(new Date().getTime()).deploy(); }catch (Exception ex) { log.fatal("Error while loading RTCAP process definition and configuration file",ex); } } /** * Close JBPM process engine */ @Destroy public void shutdown() { log.info("Destroying JBPM process engine"); if (this.processEngine != null) { this.processEngine.close(); } } @Constructor public RtcapProcessRunner(){ log.debug("Creating instance of RtcapProcessRunner"); } /** * Execute the process by creating a new ProcessInstance per call * * @param variablesMap * @param message */ public Boolean executeProcessInstance(Map<String, Object> variablesMap, MessageEntity message){ RtcapLogger.info(log, "Starting process instance for "+GenericConstants.ENROLLMENT_ID+"="+message.getEnrollmentId(), message.getMsgId()); Boolean result = false; ProcessInstance processInstance = null; try{ processInstance = this.executionService.startProcessInstanceByKey(GenericConstants.RTCAP, variablesMap, variablesMap.get(GenericConstants.ENROLLMENT_ID)+""); //Keep track of some variables on JBPM4_HIST_VAR table - Shows an error on console (which doesn't stop the execution): org.hibernate.StaleObjectStateException: Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect): [org.jbpm.pvm.internal.model.ExecutionImpl#] this.executionService.createVariable(processInstance.getId() ,GenericConstants.MESSAGE_ID, variablesMap.get(GenericConstants.MESSAGE_ID), true); this.executionService.createVariable(processInstance.getId() ,GenericConstants.SYSTEM_NAME, variablesMap.get(GenericConstants.SYSTEM_NAME), true); }catch (Exception ex) { RtcapLogger.warn(log, "Error while starting process instance for "+GenericConstants.ENROLLMENT_ID+"="+message.getEnrollmentId(), ex, message.getMsgId()); message.setErrorMessage("Error while starting process instance for "+GenericConstants.ENROLLMENT_ID+"="+message.getEnrollmentId()+". Please contact System Administrator: "+ex.getMessage()); } if(processInstance!=null){ message.setProcessInstanceId(processInstance.getId()); message.setProcessDefinitionId(processInstance.getProcessDefinitionId()); } RtcapLogger.debug(log, "Control over the process delegated to JBPM engine", message.getMsgId()); return result; } }
My process definition is cleaner and I really like it <?xml version="1.0" encoding="UTF-8"?> <process key="RTCAP" name="myRTCAPv4" xmlns="http://jbpm.org/4.4/jpdl"> <start g="60,12,48,48" name="start"> <transition g="-53,-18" name="toVerifyParameters" to="Verify Parameters"/> </start> <end g="1224,576,48,48" name="end"/> <end-error g="781,180,169,52" name="end-error_EnrollmentNotEligible"/> <end-cancel g="60,456,169,52" name="end-cancel_ExistingEnrollment"/> <end-cancel g="516,36,48,48" name="end-cancel_MaxNumberAttemptsReached"/> <end-error g="768,456,48,48" name="end-error_ExceptionOnProcess"/> <custom class="com.kaplan.jbpm.action.integration.jbpm4.VerifyParamsActionHandler" continue="async" g="24,144,121,52" name="Verify Parameters"> <transition g="-76,-18" name="toEnrollmentExists?" to="Enrollment Exists?"/> </custom> <decision continue="async" g="60,288,48,48" name="Enrollment Exists?"> <handler class="com.kaplan.jbpm.decision.integration.jbpm4.EnrollmentExistDecisionHandler" /> <transition g="-60,-18" name="ExistingEnrollment" to="end-cancel_ExistingEnrollment"/> <transition g="-33,-22" name="NewEnrollment" to="Wait"/> </decision> <decision continue="async" g="516,144,60,48" name="Enrollment Details Available?"> <handler class="com.kaplan.jbpm.decision.integration.jbpm4.EnrollmentDetailsAvailableDecisionHandler" /> <transition g="288,169:-53,-18" name="NotAvailable" to="Wait"/> <transition g="637,167;637,62:-7,-70" name="Available" to="Is Eligible for Integration?"/> <transition g="-112,-2" name="maxNumberAttemptsReached" to="end-cancel_MaxNumberAttemptsReached"/> </decision> <state continue="async" g="240,288,97,52" name="Wait"> <transition g="288,408:9,-22" name="toRetrieveEnrollmentDetails" to="Retrieve Enrollment Details"> <timer duedate="10 minutes"/> <event-listener class="com.kaplan.jbpm.action.integration.jbpm4.WaitEventListener"/> </transition> </state> <custom class="com.kaplan.jbpm.action.integration.jbpm4.RetrieveEnrollmentDetailsActionHandler" continue="async" g="444,384,193,52" name="Retrieve Enrollment Details"> <transition g="-65,-17" name="toVerifyEnrollmentDetails" to="Enrollment Details Available?"/> </custom> <decision continue="async" g="781,36,97,52" name="Is Eligible for Integration?"> <handler class="com.kaplan.jbpm.decision.integration.jbpm4.EnrollmentEligibleDecisionHandler" /> <transition g="-53,-18" name="EnrollmentNotEligible" to="end-error_EnrollmentNotEligible"/> <transition g="-53,-18" name="EnrollmentEligible" to="Retrieve Student Details"/> </decision> <custom class="com.kaplan.jbpm.action.integration.jbpm4.RetrieveStudentDetailsActionHandler" continue="async" g="973,37,169,52" name="Retrieve Student Details"> <transition g="-93,-16" name="toStudentExists?" to="Student Exists?"/> </custom> <decision continue="async" g="1032,203,48,48" name="Student Exists?"> <handler class="com.kaplan.jbpm.decision.integration.jbpm4.StudentExistDecisionHandler" /> <transition g="907,281:-60,-18" name="NewStudent" to="Save Student Details"/> <transition g="1200,287:-8,-18" name="ExistingStudent" to="Update Student Details"/> </decision> <decision continue="async" g="1032,456,48,48" name="Course Access Is Available?"> <handler class="com.kaplan.jbpm.decision.integration.jbpm4.CourseAccessAvailableDecisionHandler" /> <transition g="-58,-16" name="courseAccessNotAvailable" to="end-error_ExceptionOnProcess"/> <transition g="-69,-18" name="courseAccessAvailable" to="Bulk Post"/> </decision> <custom class="com.kaplan.jbpm.action.integration.jbpm4.SaveStudentActionHandler" continue="async" g="831,324,152,52" name="Save Student Details"> <transition g="-136,-25" name="toCourseAccessAvailableFromSave" to="Course Access Is Available?"/> </custom> <custom class="com.kaplan.jbpm.action.integration.jbpm4.UpdateStudentActionHandler" continue="async" g="1127,324,152,52" name="Update Student Details"> <transition g="-53,-26" name="toCourseAccessAvailableFromUpdate" to="Course Access Is Available?"/> </custom> <custom class="com.kaplan.jbpm.action.integration.jbpm4.BulkPostActionHandler" continue="async" g="1008,576,97,52" name="Bulk Post"> <transition g="-47,-18" name="toEnd" to="end"/> </custom> </process>

Finally, let me show you a couple of Handlers, except for a few changes, I didn't change them a lot compared with my original JBPM3 code :) Cool beans!
public class CourseAccessAvailableDecisionHandler extends BaseCustomJbpm4Handler implements DecisionHandler { private static final long serialVersionUID = -4617542811826572467L; private static Logger log = Logger.getLogger(CourseAccessAvailableDecisionHandler.class); @Override public String decide(OpenExecution openExecution) { String messageId = (String)this.getVariableFromContext(GenericConstants.MESSAGE_ID, openExecution); StudentDetails studentDetails = (StudentDetails)this.getVariableFromContext(GenericConstants.STUDENT_DETAILS_KEY, openExecution); EnrollmentDetails enrollmentDetails = (EnrollmentDetails)this.getVariableFromContext(GenericConstants.ENROLLMENT_DETAILS_KEY, openExecution); String enrollmentId = (String)this.getVariableFromContext(GenericConstants.ENROLLMENT_ID, openExecution); String decision = null; RtcapLogger.debug(log, "Verify if Save or Update Student Details was executed successfully for "+studentDetails.toStringMinimal()+" and "+GenericConstants.ENROLLMENT_ID+"="+enrollmentId, messageId); if(StringUtils.isEmpty(enrollmentDetails.getCourseAccessId())){ RtcapLogger.warn(log, "CourseAccessId is NOT AVAILABLE, which means there was an error on the process", messageId); decision = GenericConstants.COURSE_ACCESS_NOT_AVAILABLE; }else{ RtcapLogger.info(log, "CourseAccessId is AVAILABLE, no errors during the process execution yet", messageId); decision = GenericConstants.COURSE_ACCESS_AVAILABLE; } RtcapLogger.debug(log, "Deciding what to do for "+studentDetails.toStringMinimal()+" and "+GenericConstants.ENROLLMENT_ID+"="+enrollmentId+"::Decision taken=" + decision, messageId); return decision; } }
public class SaveStudentActionHandler extends BaseCustomJbpm4Handler implements ActivityBehaviour { private static final long serialVersionUID = 6927651964198687636L; private static Logger log = Logger.getLogger(SaveStudentActionHandler.class); private IStudentDetailsService studentDetailsService; public void execute(ActivityExecution activityExecution) throws Exception { Boolean result = false; StudentDetails studentDetails = (StudentDetails)this.getVariableFromContext(GenericConstants.STUDENT_DETAILS_KEY, activityExecution); EnrollmentDetails enrollmentDetails = (EnrollmentDetails)this.getVariableFromContext(GenericConstants.ENROLLMENT_DETAILS_KEY, activityExecution); String messageId = (String)this.getVariableFromContext(GenericConstants.MESSAGE_ID, activityExecution); RtcapLogger.debug(log, "Execute for " +studentDetails, messageId); this.studentDetailsService = (IStudentDetailsService) this.getSeamComponentInstance("studentDetailsServiceBean"); try{ RtcapLogger.info(log, "Saving "+studentDetails.toStringMinimal(), messageId); result = this.studentDetailsService.saveStudentDetails(studentDetails, enrollmentDetails); }catch (Exception ex) { RtcapLogger.error(log, GenericConstants.ERROR_MSG_STUDENT_DETAILS_BEAN+" [studentId="+studentDetails.getStudentId()+","+GenericConstants.ENROLLMENT_ID+"="+enrollmentDetails.getEnrollmentId()+"]", ex, messageId); this.raiseException(activityExecution, new Exception(GenericConstants.ERROR_MSG_STUDENT_DETAILS_SAVING+" [studentId="+studentDetails.getStudentId()+","+GenericConstants.ENROLLMENT_ID+"="+enrollmentDetails.getEnrollmentId()+"] In "+SaveStudentActionHandler.class.getName(), ex.getCause())); } if(!result){ RtcapLogger.fatal(log, GenericConstants.ERROR_MSG_STUDENT_DETAILS_SAVING+" [studentId="+studentDetails.getStudentId()+","+GenericConstants.ENROLLMENT_ID+"="+enrollmentDetails.getEnrollmentId()+"]", messageId); this.raiseException(activityExecution, new Exception(GenericConstants.ERROR_MSG_STUDENT_DETAILS_SAVING+" [studentId="+studentDetails.getStudentId()+","+GenericConstants.ENROLLMENT_ID+"="+enrollmentDetails.getEnrollmentId()+"]")); }else{ RtcapLogger.info(log, "StudentDetails saved successfully!", messageId); } } }