package net.sourceforge.cruisecontrol.builders;
import java.io.InputStream;
import java.util.Map;
import org.jdom.Element;
import net.sourceforge.cruisecontrol.CruiseControlException;
import net.sourceforge.cruisecontrol.Progress;
import net.sourceforge.cruisecontrol.gendoc.annotations.SkipDoc;
/**
* The interface which commands run within {@link PipedExecBuilder} must implement.
*/
interface PipedScript extends Runnable {
/**
* Validates the object (checks if all the attributes are set and correct)
* @throws CruiseControlException
*/
void validate() throws CruiseControlException;
/**
* Object initialisation method - it is supposed to prepare the script for running. It is
* ensured that the method will only be called when {@link #validate()} will pass and
* before {@link #run()} is called. However, it can be called repeatedly for the object.
*/
void initialize();
/**
* The {@link Runnable#run()} method. It is ensured that the method will only be called after
* {@link #initialize()} method. It can be called repeatedly for the object (every time preceded
* by the call of {@link #initialize()}, however).
*/
@Override
void run();
/**
* Sets the ID of the script from <code>id=""</code> attribute in XML configuration
* (referenced by <code>pipefrom=""</code> and <code>waitfor=""</code>). Required.
* Each script must have <b>unique</b> ID assigned.
*
* @param value ID of the script.
*/
void setID(String value);
/**
* Gets the ID of the script set by {@link #setID(String)}, or <code>null</code> if not
* set yet.
*
* @return the ID of the script.
*/
String getID();
/**
* Sets the ID of the script from <code>pipefrom=""</code> attribute in XML
* configuration. The STDIN of the current script is read from STDOUT of the script with
* ID set. The attribute is optional if it is not required to read input from another
* script.
*
* @param value ID of the script to read input from.
*/
void setPipeFrom(String value);
/**
* Gets the ID of the script set by {@link #setPipeFrom(String)}, or <code>null</code>
* if not set yet.
*
* @return the ID of the script to read input from.
*/
String getPipeFrom();
/**
* Sets the ID of the script from <code>waitfor=""</code> attribute in XML configuration.
* The execution of the current script will be delayed until the script with given ID is
* completed - it is aimed to prevent consecutive run of commands which consume large
* amount of memory, or to wait for file(s) generated by another script (not the data
* passed through STDIO). The attribute is optional if the script is not required to
* wait for another script.
*
* @param value ID of the script to wait for.
*/
void setWaitFor(String value);
/**
* Gets the ID of the script set by {@link #setWaitFor(String)}, or <code>null</code>
* if not set yet.
*
* @return the ID of the script to wait for.
*/
String getWaitFor();
/**
* Sets the ID of the script ton which an existing (and pre-configured) script is "repiped".
* The directive is helpful when the {@link PipedExecBuilder} is preconfigured as plugin (with
* exec-childs sequence defined) and it needs to be redefined.
*
* In case of repiping, neither {@link #setPipeFrom(String)} nor any other options (except
* {@link #setID(String)} must be filled!
*
* @param repipe <code>true</code> if to re-pipe the exec to another source.
*/
void setRepipe(String repipe);
/**
* Gets the value set through {@link #setRepipe(String)}, or <code>null</code> if repipe
* was not set in case of "full" script configuration.
*
* @return <code>true/false</code> or <code>null</code>.
*/
String getRepipe();
/**
* Set <code>true</code> if to disable the given script and ALL SCRIPTS PIPED FROM IT. The
* directive is helpful when the {@link PipedExecBuilder} is pre-configured as plugin (with
* exec-childs sequence defined) and it needs to be redefined in such a way that some
* scripts from the original sequence will not be used anymore.
*
* In case of disabling, neither {@link #setPipeFrom(String)} nor any other options (except
* {@link #setID(String)} must be filled!
*
* @param disable <code>true</code> if to disable the execution of the script as well as the
* execution of all scripts piped from the script.
*/
void setDisable(boolean disable);
/**
* Gets the value set through {@link #setDisable(boolean)}, or <code>false</code> in case
* "full" script configuration.
*
* @return <code>true/false</code>.
*/
boolean getDisable();
/**
* Sets the XML element into which the build log returned by
* {@link net.sourceforge.cruisecontrol.Builder#build(Map, Progress)}, when called in {@link #run()},
* is required to be stored.
*
* @param buildLogParent the required parent of build log element.
* @see net.sourceforge.cruisecontrol.Builder#build(Map, Progress)
*/
@SkipDoc
void setBuildLogParent(Element buildLogParent);
/**
* Sets the map of build properties passed to the
* {@link net.sourceforge.cruisecontrol.Builder#build(Map, Progress)} when called in {@link #run()}.
*
* @param buildProperties build properties, may be <code>null</code>.
* @see net.sourceforge.cruisecontrol.Builder#build(Map, Progress)
*/
@SkipDoc
void setBuildProperties(final Map<String, String> buildProperties);
/**
* Sets the callback to provide progress updates, passed to the
* {@link net.sourceforge.cruisecontrol.Builder#build(Map, Progress)} when called in {@link #run()}.
*
* @param progress callback to provide progress updates, may be <code>null</code>.
* @see net.sourceforge.cruisecontrol.Builder#build(Map, Progress)
*/
@SkipDoc
void setProgress(final Progress progress);
/**
* Sets the stream to read input of the script from.
*
* @param input the stream to read input from, set to <code>null</code> if
* the script is not expected to have data in its input.
*/
@SkipDoc
void setInputProvider(final InputStream input);
/**
* Returns the stream from which the output of the script can be read.
* The output data of the script is buffered, so the method can be called multiple times,
* each time new stream reading data from the beginning is returned.
*
* @return the stream from which to read the output of the script.
*/
InputStream getOutputReader();
/**
* @return <code>true</code> when the script finished its work and <code>false</code>
* when it is running or has not been started yet.
*/
boolean isDone();
/**
* Sets the directory in which the script will be running (all non-absolute the paths in the
* script's configuration are tried relative to this directory.
*
* @param workingDir the path to the directory (if not absolute, first is tried relative to the
* current CC working directory is tried, than relative to CC's home directory.
*/
void setWorkingDir(String workingDir);
/**
* @return the value set through {@link #setWorkingDir(String)} method, or <code>null</code>
* if not set.
*/
String getWorkingDir();
/**
* Should the output of scripts be kept gzipped within the builder?
* See {@link PipedExecBuilder#setGZipStdout(boolean)} for more details.
*
* @param gzip <code>true</code> if script's output is required to be stored gzipped,
* <code>false</code> if raw output content is kept.
*/
void setGZipStdout(boolean gzip);
/**
* @return <code>null</code> if not set otherwise by {@link #setGZipStdout(boolean)}.
*/
Boolean getGZipStdout();
/**
* Is the output content of the script in binary form?
* See {@link PipedExecBuilder#setBinaryStdout(boolean)} for more details.
*
* @param binary <code>true</code> if script's output is in binary form, <code>false</code>
* if STDOUT is text.
*/
void setBinaryOutput(boolean binary);
/**
* @return <code>null</code> if not set otherwise by {@link #setBinaryOutput(boolean)}.
*/
Boolean getBinaryOutput();
/**
* Sets the amount of time [in secs] which may by consumed by during the running of the script.
* The the timeout is passed, the script may be killed by CC.
*
* @param time the timeout value
*/
void setTimeout(long time);
/**
* @return {@link ScriptRunner#NO_TIMEOUT} of the value set by {@link #setTimeout(long)}
*/
long getTimeout();
}