RELEASE_2_1_13/src/blocks/cron/java/org/apache/cocoon/components/cron/JobScheduler.java

/*
 * 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.
 */
package org.apache.cocoon.components.cron;

import java.util.Date;
import java.util.Map;
import java.util.NoSuchElementException;

import org.apache.avalon.framework.CascadingException;
import org.apache.avalon.framework.parameters.Parameters;

/**
 * This component schedules jobs.
 *
 * @author <a href="mailto:giacomo@apache.org">Giacomo Pati</a>
 * @version CVS $Id$
 *
 * @since 2.1.1
 */
public interface JobScheduler {
    /** The role of a JobScheduler */
    String ROLE = JobScheduler.class.getName();

    /**
     * Get the names of all scheduled jobs.
     *
     * @return state of execution successfullness
     */
    String[] getJobNames();

    /**
     * Get the JobSchedulerEntry for a scheduled job
     *
     * @return the entry
     */
    JobSchedulerEntry getJobSchedulerEntry(String jobname);

    /**
     * Schedule a time based job.  Note that if a job with the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param jobrole The Avalon components role name of the job itself
     * @param schedulingExpression the time specification using a scheduling expression
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     */
    void addJob(String name, String jobrole, String schedulingExpression, boolean canRunConcurrently)
    throws CascadingException;

    /**
     * Schedule a time based job.  Note that if a job with the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param jobrole The Avalon components role name of the job itself
     * @param schedulingExpression the time specification using a scheduling expression
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void addJob(String name, String jobrole, String schedulingExpression, boolean canRunConcurrently, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Schedule a time based job.  Note that if a job with the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     * @param schedulingExpression the time specification using a scheduling expression
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     */
    void addJob(String name, Object job, String schedulingExpression, boolean canRunConcurrently)
    throws CascadingException;

    /**
     * Schedule a job.  Note that if a job with the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     * @param schedulingExpression the time specification using a scheduling expression
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void addJob(String name, Object job, String schedulingExpression, boolean canRunConcurrently, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Schedule a periodic job. The job is started the first time when the period has passed.  Note that if a job with
     * the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param jobrole The Avalon components role name of the job itself
     * @param period Every period seconds this job is started
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void addPeriodicJob(String name, String jobrole, long period, boolean canRunConcurrently, Parameters params,
                        Map objects)
    throws CascadingException;
    
    /**
     * Schedule a periodic job. The job is started the first time when the period has passed.  Note that if a job with
     * the same name has already beed added it is overwritten.
     *
     * @param name the name of the job
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     * @param period Every period seconds this job is started
     * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void addPeriodicJob(String name, Object job, long period, boolean canRunConcurrently, Parameters params,
                        Map objects)
    throws CascadingException;

    /**
     * Fire a job once immediately
     *
     * @param jobrole The Avalon components role name of the job itself
     *
     * @return success state adding the job
     */
    boolean fireJob(String jobrole);

    /**
     * Fire a CronJob once immediately
     *
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     *
     * @return whether the job has been successfully started
     */
    boolean fireJob(Object job);

    /**
     * Fire a job once immediately
     *
     * @param jobrole The Avalon components role name of the job itself
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     *
     * @return whether the job has been successfully started
     */
    boolean fireJob(String jobrole, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Fire a job once immediately
     *
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     *
     * @return whether the job has been successfully started
     */
    boolean fireJob(Object job, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
     * overwritten.
     *
     * @param date The date this job should be scheduled
     * @param name the name of the job
     * @param jobrole The Avalon components role name of the job itself
     */
    void fireJobAt(Date date, String name, String jobrole)
    throws CascadingException;

    /**
     * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
     * overwritten.
     *
     * @param date The date this job should be scheduled
     * @param name the name of the job
     * @param jobrole The Avalon components role name of the job itself
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void fireJobAt(Date date, String name, String jobrole, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
     * overwritten.
     *
     * @param date The date this job should be scheduled
     * @param name the name of the job
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     */
    void fireJobAt(Date date, String name, Object job)
    throws CascadingException;

    /**
     * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
     * overwritten.
     *
     * @param date The date this job should be scheduled
     * @param name the name of the job
     * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
     *        specific class (i.e. org.quartz.Job)
     * @param params Additional Parameters to setup CronJob
     * @param objects A Map with additional object to setup CronJob
     */
    void fireJobAt(Date date, String name, Object job, Parameters params, Map objects)
    throws CascadingException;

    /**
     * Remove a scheduled job by name.
     *
     * @param name the name of the job
     */
    void removeJob(String name)
    throws NoSuchElementException;
}