Saturday, August 18, 2012

How to integrate TimeMachine Scheduler in Spring based application

One of the goals for TimeMachine Scheduler is to make use of POJO as friendly as possible so that we can integrate into any IoC container easily. I've prepared a demo that will show you how to integrate TimeMachine with Spring based application.

We will mainly focus on the Spring xml config part in this article, so if you don't feel like checking out the demo project source code in details, then simply grab the binary package of the timemachine-spring-demo.zip and follow along.

Introducing a tiny Spring Server

If you don't already have a Spring project going, then take a look at my little Spring server. It can bootstrap any spring configuration xml file and then sits and wait for a CTRL+C to end. Unzip the demo and try it out like this.

$ cd timemachine-spring-demo
$ bin/run-spring config/hello-spring.xml

You should see a "Hello World!" message printed. Hit CTRL+C to end it. The xml just declares a simple HelloService bean like this.

<beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.springframework.org/schema/beans
     http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="helloService" class="timemachine.spring.HelloService" init-method="run">
        <property name="name" value="World"></property>
    </bean>

</beans>

That's your typical Spring declaration file. With this tiny Spring server, you can quickly experiment any POJOs wired up in any way you wish and put them in action.

Setting up TimeMachine Scheduler beans

In Java code, you can easily create an instance of the TimeMachine scheduler as follow:

SchedulerFactory schedulerFactory = new SchedulerFactory("config/scheduler.properties");
Scheduler scheduler = schedulerFactory.createScheduler();
scheduler.start();
// Then we would also need to call scheduler.destroy() before we exit the Java program. (eg: in shutdownHook)

You can easily translate that into Spring xml config like in config/timemachine-pojo-spring.xml:

<beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.springframework.org/schema/beans
     http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="schedulerFactory" class="timemachine.scheduler.SchedulerFactory">
        <constructor-arg value="config/scheduler.properties"></constructor-arg>
    </bean>
    <bean id="scheduler" class="timemachine.scheduler.Scheduler" 
        factory-bean="schedulerFactory" factory-method="createScheduler"
        init-method="start" destroy-method="destroy">
    </bean>

</beans>

The benefit of using Spring xml is that your scheduler lifecycles would be automatically taken care of without setting any shutdown hook. Running above should give you a plain scheduler started, and pressing CTRL+C should shutdown gracefully.

Going further with a custom SchedulerFactoryBean

Now above is not much excitement using Spring since you would still configure the scheduler through config/scheduler.properties. You certainly can load jobs and add custom services there. But if we are going to use Spring, we might as well take full advantage of it to create the Job Definition and Schedule inside the xml config! To do this, I created a simple timemachine.scheduler.spring.SchedulerFactoryBean in my demo project, and you can try it out like this:

<beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.springframework.org/schema/beans
     http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="scheduler" class="timemachine.scheduler.spring.SchedulerFactoryBean">
        <property name="configPropsUrl" value="config/scheduler.properties"></property>
        <property name="autoStart" value="true"></property>
        <property name="autoAddJobDef" value="true"></property>
    </bean>
    <bean id="jobDef01" class="timemachine.scheduler.JobDef">
        <property name="jobTaskClassName" value="timemachine.scheduler.jobtask.ScriptingJobTask"></property>
        <property name="props">
            <map>
                <entry key="scriptEngineName" value="Groovy"></entry>
                <entry key="scriptText" value="println('Hello World.')"></entry>
            </map>
        </property>
        <property name="schedules">
            <list>              
                <bean class="timemachine.scheduler.schedule.CronSchedule">
                    <property name="expression" value="0/3 * * * * ?"></property>
                </bean>
            </list>
        </property>
    </bean>

</beans>

Above will create not only the scheduler but also auto manage the lifecycles for you without you explicitly declare it. The factory bean will also auto detect any JobDef and Schedule bean types and add them into the scheduler instance. This would make your scheduler config all in the Spring xml, and it's well integrated.

There is also another similar sample in config/timemachine-spring.xml you may try. It will invoke an external groovy script instead of inline text.

Going extra mile on exposing TimeMachine Scheduler through JMX

The TimeMachine doesn't support any JMX instrumentation, however when running with the Spring, you can easily expose any Java interface to the local MBean Server Platform using Spring's MBeanExporter. For example in config/timemachine-jmx-spring.xml you will see:

<beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.springframework.org/schema/beans
     http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="scheduler" class="timemachine.scheduler.spring.SchedulerFactoryBean">
        <property name="configPropsUrl" value="config/scheduler.properties"/>
    </bean> 
    <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter">
        <property name="assembler">
            <bean class="org.springframework.jmx.export.assembler.InterfaceBasedMBeanInfoAssembler">
                <property name="managedInterfaces">
                    <list>
                        <value>timemachine.scheduler.Scheduler</value>
                    </list>
                </property>
            </bean>
        </property>
        <property name="beans">
            <map>
                <entry key="timemachine.scheduler:name=Scheduler" value-ref="scheduler"/>
            </map>
        </property>
    </bean>

</beans>

Above will start an empty scheduler, and expose the timemachine.scheduler.Scheduler interface to the JMX local server. You may use $JAVA_HOME/bin/jconsole to connect and will see all the methods automatically exposed. There few methods that contains custom java objects that exporter will not able to convert properly, but at least you will get all the lifecycles and some simple getters that available to you.

4 comments:

  1. Any difference in features between this timemachine and the spring 3.1's scheduler?

    ReplyDelete
  2. Hello dxxvi,

    It's true that Spring provides a scheduling abstraction layer service already. They made it so that you may choose an implementation to provide scheduling need such as JDK timer, Quartz, or in late Spring release, they even provided their own CRON schedule service.

    You may think of TimeMachine as one more alternative choice you can use in the Spring as above. However TimeMachine provides little more than CRON scheduling though. You can easily create your own customized schedule with TimeMachine API, store your scheduling data into database, or have a cluster of scheduler servers to run jobs. You can create and control one or more thread pools to run the jobs in etc. Obviously you can use TimeMachine as standalone outside of Spring as well. You can visit the project site to see more its features.

    * Another minor difference is Spring's CRON can only up to MINUTE as smallest scheduling interval, while the TimeMachine's CRON can use SECOND as smallest interval unit.

    ReplyDelete
  3. Spring does support second interval:
    public @interface Scheduled {

    /**
    * A cron-like expression, extending the usual UN*X definition to include
    * triggers on the second as well as minute, hour, day of month, month
    * and day of week. e.g. "0 * * * * MON-FRI" means once
    * per minute on weekdays (at the top of the minute - the 0th second).
    * @return an expression that can be parsed to a cron schedule
    */
    String cron() default "";

    ReplyDelete
  4. A user "lithium147" has corrected me that Spring's @Scheduled#cron does support SECOND interval. I am not sure the comments is not showing up here, but I thank you for the correction.

    ReplyDelete