/*
 This file is part of the software framework JStatCom, 
 a library for building applications for data based analysis.

 Copyright (C) 2000-2005  Markus Kraetzig

 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as
 published by the Free Software Foundation; either version 2.1 of the
 License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 USA
 */

package com.jstatcom.engine;

import com.jstatcom.model.JSCData;
import com.jstatcom.model.JSCTypes;

/**
 * This interface defines the general contract that all implemented concrete
 * engines must satisfy. Engine clients can communicate to a specific
 * computational engine exclusively via method calls defined in this interface.
 * 

 * Usage Note:

 * The methods defined in this interface should be sufficient to generalize the
 * communication to every potential computational engine.
 * 

 * Implemented methods should throw the following unchecked exceptions:
 * 

 * 
IllegalArgumentException if a given argument was not
 * valid
 * 
RuntimeException if execution failed for some reason
 * 
IllegalStateException if the engine was in a wrong state
 * for the given method call
 * 
 * 

 * Each engine implementation should be created in a new package whith
 * implementations of:
 * 

 * 
Engine for the communication with the external software
 * 
AbstractConfigPanel for user input of engine specific
 * settings on the user machine (DefaultConfigPanel can be used
 * as well)
 * 
LoadTypes to define extra module types that might be
 * loaded by that engine
 * 
EngineTypes mediator to set the name, check settings and
 * bind the other classes together
 * 
ConfigKeys to define configuration settings for the
 * engine
 * 
 * The communication to an external engine always depends on certain resources,
 * like libraries, other executables or configuration files. The specific
 * implementations of ConfigKeys, EngineTypes and
 * AbstractConfigPanel should make sure that these resources are
 * found and that they are in a consistent state to run the Engine
 * instance.
 * 
 * @see com.jstatcom.engine.AbstractConfigPanel
 * @see com.jstatcom.engine.LoadTypes
 * @see com.jstatcom.engine.EngineTypes
 * @see com.jstatcom.engine.ConfigKeys
 * 
 * @author Markus Kraetzig
 */
public interface Engine {

    /**
     * Calls a procedure with input and return parameters specified.
     * 

     * The return parameters define the data types that are returned. If the
     * procedure returns types that are not compatible with the types in
     * retData then a RuntimeException should be
     * thrown.
     * 

     * Elements in retData must not be null. All
     * elements in retData and args must be
     * understood by this engine, which is defined by the isValid
     * method.
     * 

     * Returned values should be set to the elements in retData,
     * instead of creating new data objects and replacing the array elements.
     * 
     * @param procName
     *            procedure to be executed by this engine
     * @param args
     *            the data to be used as input
     * @param retData
     *            the return types
     */
    void call(String procName, JSCData[] args, JSCData[] retData);

    /**
     * Gets whether type can be handled by this engine.
     * 
     * @param type
     *            the data type to be checked
     * @return true if ok, false if
     *         type cannot be handled by this engine
     */
    boolean isValid(JSCTypes type);

    /**
     * Loads an engine specific type that is defined by a load type.
     * Implementations of this method can perform various specific actions
     * according to loadType, for example library loading,
     * setting of filenames for modules or object creation with
     * args.
     * 
     * @param module
     *            the name of the module to load
     * @param loadType
     *            the type of module to load
     * @param args
     *            (optional) module load arguments if needed
     */
    void load(String module, LoadTypes loadType, JSCData... args);

    /**
     * Stops a running execution. If there is nothing to do for this engine,
     * this method must throw an UnsupportedOperationException.
     * 
     * @throws UnsupportedOperationException
     */
    void stop() throws UnsupportedOperationException;

    /**
     * Terminates this engine and does clean up tasks. Whenever a
     * load or execute is called afterwards this
     * engine should be reinitialized.
     */
    void shutdown();

}