Enabling reminders and timers

Seam does not provide a mechanism for enabling jbpm timers and reminders. If you wish to use these features you need to enable the scheduler yourself. The following shows how I extended the jbpm component to make this work. This work is based largely from posts on the seam forum (see references below).

Jbpm.java

/**
 * Copyright Software Factory - 2009
 */
package nz.co.softwarefactory.risingstars.seam;

import org.jboss.seam.ScopeType;
import org.jboss.seam.annotations.Create;
import org.jboss.seam.annotations.Install;
import org.jboss.seam.annotations.Name;
import org.jboss.seam.annotations.Scope;
import org.jboss.seam.annotations.Startup;
import org.jboss.seam.annotations.intercept.BypassInterceptors;
import org.jboss.seam.bpm.BusinessProcessInterceptor;
import org.jboss.seam.core.Init;
import org.jboss.seam.log.Log;
import org.jboss.seam.log.Logging;
import org.jbpm.job.executor.JobExecutor;

/**
 * Seam provides no mechanism for initialising the scheduler used for timers and
 * reminders. This class extends the Jbpm component to initialise the scheduler
 * at startup.
 *
 * <p>
 * This class should be configured in your components xml instead of the regular
 * jbpm configuration. An example of this is:
 * </p>
 *
 * <xmp>
 * <component name="org.jboss.seam.bpm.jbpm"
 *          class="nz.co.softwarefactory.risingstars.seam.Jbpm">
 *      <property name="pageflow-definitions">
 *          <value>create_registration_details.jpdl.xml</value>
 *      </property>
 *      <property name="process-definitions">
 *          <value>processes/reporting.jpdl.xml</value>
 *      </property>
 *      <property name="schedulerEnabled">true</property>
 * </component>
 * </xmp>
 *
 * <p>
 * In addition to this the following is also needed in your components.xml:
 * </p>
 *
 * <xmp> <bpm:jbpm name="notused"></bpm:jbpm> </xmp>
 *
 * This is needed because seam looks for this element at startup to determine if
 * the {@link BusinessProcessInterceptor} should be installed.
 *
 * @see http
 *      ://seamframework.org/Documentation/JBPMDeploymentInProductionEnvironments
 *
 * @author craig
 */
@Scope(ScopeType.APPLICATION)
@BypassInterceptors
@Startup
@Name("org.jboss.seam.bpm.jbpm")
@Install(value = false, precedence = Install.APPLICATION)
public class Jbpm extends org.jboss.seam.bpm.Jbpm {

    private final Log log = Logging.getLog(Jbpm.class);

    private boolean schedulerEnabled;

    /**
     * @see org.jboss.seam.bpm.Jbpm#startup()
     */
    @Override
    @Create
    public void startup() throws Exception {
        log.info("Using jBPM extensions. scheduler: ", isSchedulerEnabled() ? "enabled" : "disabled");
        super.startup();

        // work around to let Seam know jbpm is actually installed.
        Init.instance().setJbpmInstalled(true);

        if (isSchedulerEnabled()) {

            log.info("Starting the jBPM scheduler");

            startScheduler();

            if (isRunning()) {
                log.info("jBPM scheduler has started.");
            }
            else {
                log.error("jBPM scheduler was not started.");
            }

        }
    }

    /**
     * Returns where the jbpm scheduler is enabled.
     *
     * @return
     */
    public boolean isSchedulerEnabled() {
        return schedulerEnabled;
    }

    public void setSchedulerEnabled(final boolean schedulerEnabled) {
        this.schedulerEnabled = schedulerEnabled;
    }

    /**
     * Returns the jbpm job executor.
     */
    public JobExecutor getJobExecutor() {
        return getJbpmConfiguration().getJobExecutor();
    }

    /**
     * Starts the jbpm scheduler
     */
    private void startScheduler() {
        final JobExecutor jobExecutor = getJobExecutor();
        if (jobExecutor != null) {
            jobExecutor.start();
        }
    }

    /**
     * Stops the jbpm scheduler.
     */
    private void stopScheduler() {
        final JobExecutor jobExecutor = getJobExecutor();
        if (jobExecutor != null) {
            try {
                jobExecutor.stopAndJoin();
            }
            catch (final InterruptedException e) {
                log.warn("Could not wait for job executor.", e);
            }
        }
    }

    /**
     * Returns true if the jbpm scheduler is running.
     *
     * @return
     */
    private boolean isRunning() {
        return getJobExecutor() != null && getJobExecutor().isStarted();
    }

    /**
     * Overridden to stop the jbpm scheduler if its running.
     */
    @Override
    public void shutdown() {
        if (isRunning()) {
            log.info("Stopping the jBPM scheduler.");
            stopScheduler();
        }
        else if (isSchedulerEnabled()) {
            log.debug("jBPM Scheduler can't be stopped because it was not running.");
        }
        super.shutdown();
    }
}


components.xml

To install our new Jbpm class we must add the following to our components.xml. Note you still need to specify your pageflow definitions and your process definitions. In addition there is an extra property (schedulerEnabled) which can be used to turn on and off the scheduler for timers and reminders.

<!-- HACK to trick seam into thinking JBPM is installed so the
        BusinessProcessInterceptor gets installed -->
<bpm:jbpm name="notused"></bpm:jbpm>

<component name="org.jboss.seam.bpm.jbpm"
        class="nz.co.softwarefactory.risingstars.seam.Jbpm">
    <property name="pageflow-definitions">
        <value>create_registration_details.jpdl.xml</value>
        <value>update_registration_details.jpdl.xml</value>
    </property>
    <property name="process-definitions">
        <value>processes/injury-reporting.jpdl.xml</value>
        <value>processes/hazard-reporting.jpdl.xml</value>
    </property>
    <property name="schedulerEnabled">true</property>
</component>

Q. Why do we need to add the above "hack" bpm:jbpm clause in our components.xml?
A. If we do not add a bpm:jbpm element Seam does not think jbpm is being used. Right at the beginning of the Seam initialisation a check is made to see if this element exists. If this element does not exist the BusinessProcessInterceptor is not installed and you cannot start business processes.

References

Comments