scheduler/src/site/apt/userguide.apt

                                    ------
                                    User Guide
                                    ------
                                    The Apache Onami developers team
                                    ------
                                     2011-2012

~~
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~

User's guide

  The <<<org.apache.onami.scheduler.QuartzModule>>> makes easier the <<<org.quartz.Scheduler>>>
  creation and <<<org.quartz.Job>>> creation and scheduling.

* Scheduler

  Once the Guice Injector will be created using the <<<org.apache.onami.scheduler.QuartzModule>>>, the
  <<<org.quartz.Scheduler>>> will be ready and started. Users can require the <<<org.quartz.Scheduler>>> injection
  for custom operations and for shutdown it.

+--------------------------------------+
public class MyApplicationShutdownListener
{

    @Inject
    private org.quartz.Scheduler scheduler;

    public void shutdown()
        throws Exception
    {
        ...
        scheduler.shutdown();
        ...
    }

}
+--------------------------------------+

  Users that need to register listeners, can us the <<<org.apache.onami.scheduler.QuartzModule>>> EDSL:

+--------------------------------------+
Guice.createInjector(..., new org.apache.onami.scheduler.QuartzModule()
{

   @Override
   protected void schedule()
   {
       addJobListener( com.acme.MyJobListener.class );
       addTriggerListener( com.acme.MyTriggerListener.class );
       addSchedulerListener( com.acme.MySchedulerListener.class );
   }

});
+--------------------------------------+

  Don't create listeners instances manually, let Guice do the job for you!

* Job

  <<<org.quartz.Job>>> instances and scheduling are managed as well, a typical example of
  scheduling <<<org.quartz.Job>>> is:

+--------------------------------------+
Guice.createInjector(..., new org.apache.onami.scheduler.QuartzModule()
{

   @Override
   protected void schedule()
   {
       ...
       scheduleJob( com.acme.MyJobImpl.class ).withCronExpression( "0/2 * * * * ?" );
       ...
   }

});
+--------------------------------------+

  Don't create jobs instances manually, let Guice do the job for you!

  Please refer to {{{./apidocs/reference/org/apache/onami/scheduler/JobSchedulerBuilder.html}JobSchedulerBuilder}} Javadoc
  to see all the scheduling configuration parameters.

** Implicit scheduling

  Job classes annotated with <<<org.apache.onami.scheduler.Scheduled>>> will be automatically scheduled extracting
  configuration parameters, i.e. given the :

+--------------------------------------+
@javax.inject.Singleton
@org.apache.onami.scheduler.Scheduled( jobName = "test", cronExpression = "0/2 * * * * ?" )
public class com.acme.MyJobImpl
    implements org.quartz.Job
{

    @javax.inject.Inject
    private MyCustomService service;

    public void execute( JobExecutionContext context )
        throws JobExecutionException
    {
        service.customOperation();
    }

}
+--------------------------------------+

  Then, when creating the <<<Injector>>> instance:

+--------------------------------------+
Guice.createInjector(..., new org.apache.onami.scheduler.QuartzModule()
{

   @Override
   protected void schedule()
   {
       ...
       scheduleJob( com.acme.MyJobImpl.class );
       ...
   }

});
+--------------------------------------+

** Starting the schedule manually

  Since version 1.1 the <<<Scheduler>>> instance can be started manually; that feature is incredibly useful due to serious
  {{{https://github.com/google/guice/issues/183}deadlock}}
  {{{http://groups.google.com/group/google-guice/browse_thread/thread/c4ccd95b76192519}issue}} found in the main Guice
  thread:

+--------------------------------------+
Guice.createInjector(..., new org.apache.onami.scheduler.QuartzModule()
{

   @Override
   protected void schedule()
   {
       ...
       configureScheduler().withManualStart();
       ...
   }

});
+--------------------------------------+

  So users have to get the <<<Scheduler>>> instance and invoke the start explicitly.

  Simple enough, uh?