obol/lang/ScriptHandle.java
package obol.lang;
import java.util.Map;
import java.util.Set;
/** This interface is part of the API for using Obol, and describes what can
* be done with a given script instance.
* @version $Id: ScriptHandle.java,v 1.2 2007/03/21 00:17:59 perm Exp $
*/
public interface ScriptHandle {
/** Return name of script */
public String getName();
/** Return digest string of script. This is the hexadecimal digest of
* the raw script representation, followed by a slash "/", and the
* script's length in bytes, in decimal*/
public String getDigest();
/** Get the script's version string (where <tt>null</tt> means it's not provided). */
public String getVersion();
/** Return documentation string of script. */
public String getDocumentation();
/** Return the information object associated with this script instance.
* The returned object will contain exactly the same information as this
* class' getName(), getDigest(), getVersion(), and getDocumentation()
* methods. */
public LoadedScriptInfo getScriptInfo();
/** Return a Map describing the required input arguments.
* The required input arguments are symbol names that must set using
* this interface's setSymbol() method, using the specified obol-type
* (typically binary,
* string or nummeric values).
* <P>The map is keyed on symbolname, and the value is a Map, containing
* obol properties, of which at least the <tt>SymbolProperties.Type</tt>
* key will be present. Other properties are present for the convenience
* (or ignorance) of the user.
* @return Map of required input symbols.
*/
public Map getInputRequirements();
/** Obtain the set of missing input requirements.
* Can be used for figuring out what an intermediate (interactive) input
* requirement is.
* The returned set contains only symbol names.
* In order to get the type and supplemental information, use the symbol
* name to look it up in the getInputRequirements() method's return Map.
* @return Set of required input arguments that has not yet been set
* using the setSymbol() method. The returned set can be empty.
*/
public Set getMissingInputRequirements();
/** Set missing input requirements from a map.
* This method calls simply calls <tt>setMissingInputRequirements(args,
* false)</tt>.
* This is a convenience method for setting a script's missing input
* requirements from a map of available (symbol-name, value).
* @param args map where keys are strings naming symbols, and the values
* Objects that can be symbol values.
* @return <tt>true</tt> if all missing input requrements were set,
* <tt>false</tt> if there still are missing input requirements.
*/
public boolean setMissingInputRequirements(Map args) throws ObolException;
/** Set missing input requirements from a map, also providing input
* properties.
* This method calls this class' <tt>setSymbol() method</tt>.
* This is a convenience method for setting a script's missing input
* requirements from a map of available (symbol-name, value).
* The value of all map entries must be an Object[], where index 0 is the
* value Object, and index 1 a Map providing the symbol properties.
* @param args map where keys are strings naming symbols, and the values
* Objects that can be symbol values.
* @param hasProperties if <tt>true</tt> the args-map's values must be
* Object[] as described above.
* @return <tt>true</tt> if all missing input requrements were set,
* <tt>false</tt> if there still are missing input requirements.
*/
public boolean setMissingInputRequirements(Map args,
boolean hasProperties) throws ObolException;
/** Set the given input requirements, returning only when they've all
* been set.
* This method calls this class' <tt>setSymbol() method</tt>.
* This is a convenience method for setting a know set of a script's
* input requirements.
* It differs from the <tt>setMissingInputRequirements()</tt> methods in
* that it will allow the script to execute while providing its
* input requirements (this is useful when dealing with loops in the
* script that expect input), <em>and</em> that it will not return until
* all inputs have been set.
* If the script require an unanticipated input requirement, this method
* will return <tt>false</tt>.
* When this method returns, the script may be in a running state.
* @param args map where keys are strings naming symbols, and the values
* Objects that can be symbol values.
* @param hasProperties if <tt>true</tt> the args-map's values must be
* Object[], where index 0 is the value Object, and index 1 a Map
* providing the symbol properties.
* @return <tt>true</tt> if all provided input requrements were set,
* <tt>false</tt> if the script requires arguments not provided.
*/
public boolean setAllInputRequirements(Map args,
boolean hasProperties) throws ObolException;
/** Set the given input requirements, returning only when they've all
* been set.
* @param args map where keys are strings naming symbols, and the values
* Objects that can be symbol values.
* @return <tt>true</tt> if all provided input requrements were set,
* <tt>false</tt> if the script requires arguments not provided.
*/
public boolean setAllInputRequirements(Map args) throws ObolException;
/** Wait for a given set of results to become available.
* Returns when all of the desired results are available to the caller,
* <em>or</em> if the script requires some input.
* Syntactic sugar for waitForResultAvailability(false, expected);
* @param expected Strings containing symbol names that one expects to
* be made available by the script when this method return
* <tt>true</tt>.
* @return <tt>true</tt> if all the results are available, or
* <tt>false</tt> if some input was required.
*/
public boolean waitForResultAvailability(String... expected) throws ObolException;
public boolean waitForResultAvailability(String expected) throws ObolException;
/** See if a given set of results have become available.
* Returns true when all of the desired results are available to the caller.
* @param wait <tt>true</tt> to wait until some results become
* available, or <tt>false</tt> to immediately check result
* availability.
* @param expected Strings containing symbol names that one expects to
* be made available by the script when this method return
* <tt>true</tt>.
* @return <tt>true</tt> if all the results are available, or
* <tt>false</tt> if not.
*/
public boolean checkForResults(boolean wait, String... expected) throws ObolException;
public boolean checkForResult(boolean wait, String expected) throws ObolException;
/** See if a given set of results have become available.
* Returns true when all of the desired results are available to the caller.
* Syntactic sugar for checkForResults(false, expected);
* @param expected Strings containing symbol names that one expects to
* be made available by the script when this method return
* <tt>true</tt>.
* @return <tt>true</tt> if all the results are available, or
* <tt>false</tt> if not.
*/
public boolean checkForResults(String... expected) throws ObolException;
public boolean checkForResult(String expected) throws ObolException;
/** Wait for a given set of results to become available.
* Returns when all of the desired results are available to the caller,
* <em>or</em> if the script requires some input.
* @param expected Set of Strings containing symbol names that one
* expects to be made available by the script when this method return
* <tt>true</tt>.
* @return <tt>true</tt> if all the results are available, or
* <tt>false</tt> if some input was required.
*/
public boolean waitForResultAvailability(Set expected) throws ObolException;
/**
* <strong>Internal use only! </strong>
*/
public boolean resetSetInputRequirement(String symbolName) throws ObolException;
/** Return a Map describing the result types.
* The result types are symbol names that are accessible using this
* interface's getSymbol() method.
* <P>The returned map is keyed on symbolname, and the value is a String
* Array with the following structure:
* <UL><i>obol-type</i>, <i>type-specific-parameters</i></UL>
* Both the obol-type and the type-specific parameters are optional.
* Typically, symbols stating protocol results provide both type and
* parameters, while "just" accessible symbols have only the symbol name
* given.
* The return value will also include the set of symbols returned by
* the getIntermediateResults() method.
* @return Map of accessible result symbols.
*/
public Map getResultSpecification();
/** Return an integer describing the current status. */
public int getStatus();
/** Script has loaded. */
public static final int STATUS_LOADED = 0x00000000;
/** Script requries input arguments. */
public static final int STATUS_ARGUMENTS_REQUIRED = 0x00000001;
/** Script is ready to be started */
public static final int STATUS_READY = 0x00000002;
/** Script has finished execution */
public static final int STATUS_DONE = 0x00000004;
/** Script execution has been halted, but can be continued. */
public static final int STATUS_HALTED = 0x00000008;
/** Script execution has been aborted, and cannot be continued. */
public static final int STATUS_ABORTED = 0x00000010;
/** There are result data available. */
public static final int STATUS_RESULT_AVAILABLE = 0x00000020;
/** Script is executing. */
public static final int STATUS_RUNNING = 0x00000040;
/** Script is initializing, and not ready. */
public static final int STATUS_INITIALIZING = 0x20000000;
/** Intermediate values are available. */
public static final int STATUS_INTERMEDIATE_AVAILABLE = 0x40000000;
/** Error data is available. */
public static final int STATUS_ERROR_AVAILABLE = 0x80000000;
/** Start the script instance.
* @return <tt>true</tt> if the script could be started, or
* <tt>false</tt> if something prevented it from starting, in which case
* the result from the getStatus() method should be examined, to see if
* it requires some more input arguments, an error has occured, or if it
* has terminated.
*/
public boolean startExecution();
/** Pause the script instance execution. */
public void pauseExecution();
/** Allow the script instance to continue executing.
* @return <tt>true</tt> if the script could continue executing, or
* <tt>false</tt> if something prevented it from continuing, in which
* case the result from the getStatus() method should be examined, to
* see if it requires some more input arguments, an error has occured,
* or if it has terminated.
*/
public boolean continueExecution();
/** Terminate the script instance. */
public void terminate();
/** Return <tt>true</tt> if errors have occured. */
public boolean errorAvailable();
/** Return an object array containing error descriptions. */
public Object[] getErrorDescriptions();
/** Return a integer array describing the current input position. Useful
* for figuring out where an error occured.
* @returns integer array describing line-number and column-number
* (character index in line) currently active, where <tt>-1</tt> means
* this information is not available.
*/
public int[] getCurrentPosition();
/** Return <tt>true</tt> if there is intermediate results available. */
public boolean intermediateAvailable();
/** Obtain any results added by the script after startExecution().
* Used for figuring out what an intermediate (interactive) results are.
* The returned set contains only symbol names.
* In order to get the type and supplemental information, use the symbol
* name to look it up in the getResultSpecification() method's return Map.
* @return Set of required input arguments that has been added since
* the script was started.
*/
public Set getIntermediateResults();
/** Get a copy of a named symbol, or null if non-existing or not allowed.
* The symbol must have previoiusly been provided by the methods
* getResult(), or getIntermediateResults().
* Getting a symbol that's not exported by these methods is an error.
* @param symbolName name of symbol to access.
* @return copy of named symbol, as a ReturnValue interface type, or
* <tt>null</tt> if the script exported a symbol it didn't update.
* @throws ObolException if named symbol hasn't been exported by the
* script, or if something goes wrong during the cloning.
*/
public ReturnValue getSymbol(String symbolName) throws ObolException;
/** Set the value (and some properties) of a symbol named by one of the
* Requirements methods.
* It is an error if the symbol-name has not been provided by the
* getInputRequirements() and/or getIntermediateRequirements()
* method(s).
* @param symbolName name of symbol to set value of
* @param value Object reference to the symbol's new value
* @param properties symbol properties, or <tt>null</tt>. The
* implementation of this interface should allow type-related
* properties, and ignore all others. Properties can be modified by the
* Obol Runtime.
* @throws ObolException if named symbol isn't marked as an input symbol
* by the script, or if one of the given properties is considered
* illegal for externals to provide.
*/
public void setSymbol(String symbolName, Object value, Map properties) throws ObolException;
/** Set the value (and some properties) of a symbol named by one of the
* Requirements methods.
* It is an error if the symbol-name has not been provided by the
* getInputRequirements() and/or getIntermediateRequirements()
* method(s).
* @param symbolName name of symbol to set value of
* @param value Object reference to the symbol's new value
* @throws ObolException if named symbol isn't marked as an input symbol
* by the script, or if one of the given properties is considered
* illegal for externals to provide.
*/
public void setSymbol(String symbolName, Object value) throws ObolException;
/** Wait until the specified flags are modified.
* Note that the flags STATUS_ABORTED and STATUS_DONE are always
* included in the <tt>mask</tt> parameter.
* @param mask flags that when set or cleared will wake calling thread.
* @return current status, as given by the getStatus() method.
*/
public int waitForStatus(int mask) throws ObolException;
/** Wait until the specified flags are modified in the specified way.
* Note that the flags STATUS_ABORTED and STATUS_DONE are always
* included in the <tt>setMask</tt> parameter.
* @param setMask flags that when set will wake calling thread (will
* always include STATUS_ABORTED and STATUS_DONE).
* @param clearMask flags that when cleared will wake calling thread.
* @return current status, as given by the getStatus() method.
*/
public int waitForStatus(int setMask, int clearMask) throws ObolException;
}
Generated by GNU enscript 1.6.4.