Pipeline Web Service API
Menu
Script Management
Pipeline Jobs are based on Pipeline Scripts files. The user can chose to maintain their own collection of Scripts, or can alternatively rely on the built-in collection that comes with the Pipeline distribution. In the latter case, the Pipeline-maintained script collection can be accessed via:
public List<String> getScriptNames()—Returns the list of the names (unique ID) of the scripts available in the system.public Script getScript(String name)Optional—Returns the script with the given name.public List<Script> getScripts()Optional—Returns a list of the scripts available in the system.
Potentially, the Pipeline-maintained collection of scripts can be editable via:
public void addScript(Script script)—Adds the given script to the Pipeline-maintained collection of scripts.public void removeScript(String name)—Removes the script of the given name from the Pipeline-maintained collection of scripts
Job Execution
To execute a Pipeline job, the user needs to give the Pipeline a reference to the script that it is based on, and a set of valued parameters for configuring this job. If the user maintains his/her own collection of scripts, then they have to forward the script to the Pipeline upon each execution request, using:
public Long execute (Script script, List<Parameters> parameters)—Executes the job defined by the given script configured with the given parameters. Returns the ID of the job being executed, for later reference.
If on contrary the user wants to execute a job based on a script maintained by the Pipeline, it will use:
public Long execute (String scriptName, List<Parameters> parameters)—Executes the job defined by the Pipeline-maintained script with the given name and configured with the given parameters. Returns the ID of the job being executed, for later reference.
Because most of the Pipeline scripts require one or several input files as parameters, it may be relevant to provide an independent method to upload this content to the Pipeline service (in case this service is running on a remote host):
public String upload (byte[] file)—Uploads the byte content to the Pipeline service, and returns the path (or ID) of the content on the Pipeline system, for later use as a parameter.
Message Notification
The Pipeline can send messages occurring during a job execution with both push or pull patterns.
In the pull approach, the client asks the Pipeline for messages for a particular job, via:
public List<Message> getMessages(Long jobID)—Returns the list of messages that were sent during the execution of the job with the given ID.
In the push approach, the Pipeline will notify the clients whenever a job execution raises a new message. This implies that the client has provided the Pipeline service with a reply-to address in the job execution request. The client will have to provide the following method:
- public void receiveMessage(Message message, Long jobID)
—Receives a Pipeline message coming from the execution of the job with the given ID.
Status and Results Retrieval
The client can query the status of a job, especially in the pull approach, via:
public Status getStatus(Long jobID)—Returns the current status of the job with the given name.
Alternatively, in the push approach, the Pipeline could notify the client of any status change. Again, this implies that the client has provided the Pipeline service with a reply-to address in the job execution request.
public void statusChanged(Long jobID, Status status)—Notifies that the status of the job with the given ID changed.
In the previous methods, the Status type is basically an enumeration, it could be a String. The service may also provide similar methods to query the status of each transformer step in a job.
Once the Pipeline job has been executed, the client can retrieve an archive containing the results with:
public byte[] getJobResults(Long jobID)—Returns an archive containing the result file set of the job with the given ID.