obol/lang/API.java

package obol.lang;

import java.io.InputStream;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.URL;
import java.util.Iterator;

/** This inteface defines the interface for applications to use when talking
 * to Obol.
 * @version $Id: API.java,v 1.1 2007/03/16 16:22:08 perm Exp $
 */
public interface API {
    /** Tell the obol runtime to load a script by name, and return the
     * loaded script's info.
     * These methods load all versions of the named script, but return the
     * first found version of the script.
     * Use the versioned getScriptInstance method to obtain a particular version.
     * @param name Name of script to load
     * Returns <tt>null</tt> if the script wasn't found. */
    public LoadedScriptInfo loadScript(String name, InputStream in) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, File file) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, String filename) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, URL url) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, URI uri) throws ObolException, IOException;

    /** Tell the obol runtime to load a script by name and version, and
     * return the loaded script's info.
     * These methods stop at the first matching script.
     * @param name Name of script to load
     * @param version Version string of script to load, or <tt>null</tt> to
     * get the first version found on the input.
     * Returns <tt>null</tt> if the script wasn't found. */
    public LoadedScriptInfo loadScript(String name, String version, InputStream in) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, String version, File file) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, String version, String filename) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, String version, URL url) throws ObolException, IOException;
    public LoadedScriptInfo loadScript(String name, String version, URI uri) throws ObolException, IOException;

    /** Tell the obol runtime to load all versions of all scripts available
     * in the input (ie until EOF), and return an array of info-structures.
     * Returns <tt>null</tt> if no scripts were found/loaded */
    public LoadedScriptInfo[] loadScripts(InputStream in) throws ObolException, IOException;
    public LoadedScriptInfo[] loadScripts(File file) throws ObolException, IOException;
    public LoadedScriptInfo[] loadScripts(String filename) throws ObolException, IOException;
    public LoadedScriptInfo[] loadScripts(URL url) throws ObolException, IOException;
    public LoadedScriptInfo[] loadScripts(URI uri) throws ObolException, IOException;

    /** get a script instance of the first loaded version of the named
     * script.  */
    public ScriptHandle getScriptInstance(String scriptname) throws ObolException;

    /** get a specific version of a script instance. */
    public ScriptHandle getScriptInstance(String scriptname, String version) throws ObolException;

    /** get a specific version of a script instance. */
    public ScriptHandle getScriptInstance(LoadedScriptInfo scriptinfo) throws ObolException;

    /** Return the information about a particular version of a loaded
     * script.
     * The information returned is static information about a loaded script,
     * not a script instance.
     * @param scriptname name of loaded script to return info about.
     * @param version version string of loaded script to return info about,
     * or <tt>null</tt> to indicate the default version (i.e. the one first
     * encountered during script loading).
     * @return LoadedScriptInfo instance describing the loaded script, or
     * <tt>null<tt> if no such script were found.
     */
    public LoadedScriptInfo getInfo(String scriptname, String version);

    /** Return the information about a particular loaded script.
     * The information returned is static information about a loaded script,
     * not a script instance.
     * The version of the named script is the default/canonical version,
     * i.e. the first loaded script of that name.
     * @param scriptname name of loaded script to return info about.
     * @return LoadedScriptInfo instance describing the loaded script, or
     * <tt>null<tt> if no such script were found.
     */
    public LoadedScriptInfo getInfo(String scriptname);

    /** Return an iteration containing LoadedScriptInfo instanced for all
     * loaded scripts.
     */
    public Iterator getInfoIterator();

    /** Return an iteration containing LoadedScriptInfo instanced for all
     * scripts that exactly matches the name and version criteria.
     * @param scriptname name of scripts to include, or <tt>null</tt> for all
     * scripts.
     * @param version version string of scripts to include, or <tt>null</tt>
     * for all versions of that script.
     * @return Iterator that gives the scripts that matched the above
     * criteria.
     */
    public Iterator getInfoIterator(String scriptname, String version);

    /** Return an iteration containing LoadedScriptInfo instanced for all
     * scripts that, ignoring case, matches the name and version criteria.
     * @param scriptname name of scripts to include, or <tt>null</tt> for all
     * scripts.
     * @param version version string of scripts to include, or <tt>null</tt>
     * for all versions of that script.
     * @return Iterator that gives the scripts that case-insensitively
     * matched the above criteria.
     */
    public Iterator getInfoIteratorIgnoreCase(String scriptname, String version);


    /** Return an iteration containing LoadedScriptInfo instanced for all
     * scripts that matches the name and version regular expressions.
     * @param scriptname regular expression to match name of scripts to
     * include, or <tt>null</tt> for all scripts. 
     * @param version regular expression to match version string of scripts
     * to include, or <tt>null</tt> for all versions of that script.
     * @return Iterator that gives the scripts that matched the above
     * regular expressions.
     */
    public Iterator getMatchingInfoIterator(String scriptname, String version);

    /** Return an iteration containing LoadedScriptInfo instanced for all
     * scripts that case-insensitively matches the name and version regular
     * expressions.
     * @param scriptname regular expression to match name of scripts to
     * include, or <tt>null</tt> for all scripts. 
     * @param version regular expression to match version string of scripts
     * to include, or <tt>null</tt> for all versions of that script.
     * @return Iterator that gives the scripts that case-insensitively
     * matched the above regular expressions.
     */
    public Iterator getMatchingInfoIteratorIgnoreCase(String scriptname, String version);

}