/*

 ============================================================================
                   The Apache Software License, Version 1.1
 ============================================================================

 Copyright (C) @year@ The Apache Software Foundation. All rights reserved.

 Redistribution and use in source and binary forms, with or without modifica-
 tion, are permitted provided that the following conditions are met:

 1. Redistributions of  source code must  retain the above copyright  notice,
    this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.

 3. The end-user documentation included with the redistribution, if any, must
    include  the following  acknowledgment:  "This product includes  software
    developed  by the  Apache Software Foundation  (http://www.apache.org/)."
    Alternately, this  acknowledgment may  appear in the software itself,  if
    and wherever such third-party acknowledgments normally appear.

 4. The names "Jakarta", "Avalon", "Excalibur" and "Apache Software Foundation"
    must not be used to endorse or promote products derived from this  software
    without  prior written permission. For written permission, please contact
    apache@apache.org.

 5. Products  derived from this software may not  be called "Apache", nor may
    "Apache" appear  in their name,  without prior written permission  of the
    Apache Software Foundation.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
 APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
 DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
 OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
 ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
 (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 This software  consists of voluntary contributions made  by many individuals
 on  behalf of the Apache Software  Foundation. For more  information on the
 Apache Software Foundation, please see <http://www.apache.org/>.

*/
package org.apache.infomover.jobmanager;

import org.apache.avalon.framework.configuration.Configuration;

/**
 * The <code>JobManager</code> interface exposes how we control the JobManager
 * externally.  We can use other Avalon applications, or the JMX interface.
 *
 * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
 * @version 1.0
 */
public interface JobManager
{
    String ROLE = JobManager.class.getName();

    /**
     * Adds a new job to the JobManager's Queue.  We pass in a configuration
     * file, and the JobManager will pass back the job name.
     *
     * @param  configuration  The job's configuration information
     *
     * @return the name of the job
     *
     * @throws JobException if the job is improperly defined
     */
    String addJob( Configuration conf ) throws JobException;

    /**
     * Removes an existing job from the JobManager's Queue.  If the job does not
     * exist, the JobManager will ignore it.
     *
     * @param  name  The name of the job we want to remove.
     */
    void removeJob( String name );

    /**
     * Cancel a running job.  It will return immediately if the Job does not exist.
     *
     * @param  name  The name of the job we want to remove.
     *
     * @throws JobException if there is no job by the name or there is a problem
     *         running the job.
     */
    void cancelJob( String name ) throws JobException;

    /**
     * Execute an existing job in the JobManager's Queue.  If the job does not
     * exist, the JobManager will throw an exception.
     *
     * @param  name  The name of the job we want to remove.
     *
     * @throws JobException if there is no job by the name or there is a problem
     *         running the job.
     */
    void executeJob( String name ) throws JobException;

    /**
     * Execute a job without adding it to the Queue.  The Job described by the
     * configuration file is run only once, unless the configuration does not
     * represent a valid job.
     *
     * @param  configuration  The configuration that defines the job.
     *
     * @throws JobException when the configuration does not represent a valid job.
     */
    void executeOneOff( Configuration config ) throws JobException;

    /**
     * Lists all the jobs that are in the Job queue.  We return the Job reference
     * itself so that we can directly execute it, or we can get its name.
     *
     * @return an array of Jobs.
     */
    JobDescriptor[] availableJobs();
}