orc.orchard.api
Interface ExecutorServiceInterface

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

AbstractExecutorService, ExecutorService, ExecutorService, ExecutorService

public interface ExecutorServiceInterface
extends java.rmi.Remote

Broker used to create and manage running jobs.

The lifecycle of a job:

1. Client calls compile to get a job ID.
2. Client calls jobStart to start the job.
3. In a loop,
   1. Client calls jobEvents to get publications.
   2. Client calls purgeJobEvents to clear the publication buffer.
4. Client may call haltJob to force the job to end.
5. Job finishes.
6. Client calls finishJob to clean up the job.

Note that the job publication buffer has a fixed size, so if you don't call purgeJobEvents regularly your job will be suspended when the buffer fills. *

Originally the executor only allow clients to create jobs and clients had to use a separate service to manage running jobs. This did make the interfaces cleaner and required fewer arguments, but it created a lot of extra work for both the client and the server, so I combined the services. Some examples of the "extra work" (mostly caused by limitations of the Java web services and servlet environments):

• Clients must support dynamically-generated web service proxies. (This is really the killer issue, since some platforms like Java make this hard).
• It's awkward to pass information between the executor and job services. It requires an out-of-band channel.
• It requires context to be encoded in the URL, which may not be practical for some services. In RPC-style services it's best if all context is passed explicitly as arguments.
• Building job URLs requires knowledge about the protocol, so it creates a lot more work to build a new protocol front-end.

Author:

quark

Method Summary

void	cancelPrompt(java.lang.String devKey, java.lang.String job, int promptID) Cancel a prompt (initiated by the Prompt site).
java.lang.String	compileAndSubmit(java.lang.String devKey, java.lang.String program) Combine compilation and submission into a single step.
java.lang.String	compileAndSubmitConfigured(java.lang.String devKey, java.lang.String program, JobConfiguration configuration) Combine compilation and submission into a single step.
void	finishJob(java.lang.String devKey, java.lang.String job) Indicate that the client is done with the job.
void	haltJob(java.lang.String devKey, java.lang.String job) Halt the job safely, using the same termination semantics as the "pull" combinator.
java.util.List<JobEvent>	jobEvents(java.lang.String devKey, java.lang.String job) Retrieve events.
java.util.Set<java.lang.String>	jobs(java.lang.String devKey) URIs of unfinished jobs started from this executor.
java.lang.String	jobState(java.lang.String devKey, java.lang.String job) What is the job's state? Possible return values: NEW: not yet started.
void	purgeJobEvents(java.lang.String devKey, java.lang.String job) Purge all events from the event buffer which have been returned by jobEvents.
void	respondToPrompt(java.lang.String devKey, java.lang.String job, int promptID, java.lang.String response) Submit a response to a prompt (initiated by the Prompt site).
void	startJob(java.lang.String devKey, java.lang.String job) Begin executing the job.
java.lang.String	submit(java.lang.String devKey, Oil program) Register a new job for execution, using a default JobConfiguration.
java.lang.String	submitConfigured(java.lang.String devKey, Oil program, JobConfiguration configuration) Register a new job for execution, using the provided job configuration.

Method Detail

submitConfigured

java.lang.String submitConfigured(java.lang.String devKey,
                                  Oil program,
                                  JobConfiguration configuration)
                                  throws QuotaException,
                                         InvalidOilException,
                                         UnsupportedFeatureException,
                                         java.rmi.RemoteException

Register a new job for execution, using the provided job configuration.

Returns:

String Job ID of new job.

Throws:

QuotaException - if registering this job would exceed quotas.

InvalidOilException - if the program is invalid.

UnsupportedFeatureException - if the executor does not support some part of the configuration.

java.rmi.RemoteException

submit

java.lang.String submit(java.lang.String devKey,
                        Oil program)
                        throws QuotaException,
                               InvalidOilException,
                               java.rmi.RemoteException

Register a new job for execution, using a default JobConfiguration.

Throws:

QuotaException

InvalidOilException

java.rmi.RemoteException

compileAndSubmit

java.lang.String compileAndSubmit(java.lang.String devKey,
                                  java.lang.String program)
                                  throws QuotaException,
                                         InvalidProgramException,
                                         InvalidOilException,
                                         java.rmi.RemoteException

Combine compilation and submission into a single step. This is useful for simple clients that don't want to bother calling a separate compiler.

Throws:

QuotaException

InvalidProgramException

InvalidOilException

java.rmi.RemoteException

compileAndSubmitConfigured

java.lang.String compileAndSubmitConfigured(java.lang.String devKey,
                                            java.lang.String program,
                                            JobConfiguration configuration)
                                            throws QuotaException,
                                                   InvalidProgramException,
                                                   InvalidOilException,
                                                   UnsupportedFeatureException,
                                                   java.rmi.RemoteException

Combine compilation and submission into a single step.

Throws:

QuotaException

InvalidProgramException

InvalidOilException

UnsupportedFeatureException

java.rmi.RemoteException

jobs

java.util.Set<java.lang.String> jobs(java.lang.String devKey)
                                     throws java.rmi.RemoteException

URIs of unfinished jobs started from this executor.

Throws:

java.rmi.RemoteException

startJob

void startJob(java.lang.String devKey,
              java.lang.String job)
              throws InvalidJobException,
                     InvalidJobStateException,
                     java.rmi.RemoteException

Begin executing the job.

Throws:

InvalidJobStateException - if the job was already started, or was aborted.

InvalidJobException

java.rmi.RemoteException

finishJob

void finishJob(java.lang.String devKey,
               java.lang.String job)
               throws InvalidJobException,
                      InvalidJobStateException,
                      java.rmi.RemoteException

Indicate that the client is done with the job. The job will be halted if necessary.

Once this method is called, the service provider is free to garbage collect the service and the service URL may become invalid, so no other methods should be called after this.

Throws:

InvalidJobStateException - if the job is RUNNING or WAITING.

java.rmi.RemoteException

InvalidJobException

haltJob

void haltJob(java.lang.String devKey,
             java.lang.String job)
             throws InvalidJobException,
                    java.rmi.RemoteException

Halt the job safely, using the same termination semantics as the "pull" combinator.

Throws:

InvalidJobException

java.rmi.RemoteException

jobState

java.lang.String jobState(java.lang.String devKey,
                          java.lang.String job)
                          throws InvalidJobException,
                                 java.rmi.RemoteException

What is the job's state? Possible return values: NEW: not yet started. RUNNING: started and processing tokens. WAITING: started and waiting for response from a site. DONE: finished executing.

Returns:

the current state of the job.

Throws:

InvalidJobException

java.rmi.RemoteException

jobEvents

java.util.List<JobEvent> jobEvents(java.lang.String devKey,
                                   java.lang.String job)
                                   throws InvalidJobException,
                                          java.lang.InterruptedException,
                                          java.rmi.RemoteException

Retrieve events. If no events occurred, block until at least one occurs. If the job finishes without any more events happening, an empty list will be returned.

FIXME: ensure clients like web/orc.js can recover from connection timeouts.

Throws:

java.lang.InterruptedException - if the request times out.

InvalidJobException

java.rmi.RemoteException

purgeJobEvents

void purgeJobEvents(java.lang.String devKey,
                    java.lang.String job)
                    throws InvalidJobException,
                           java.rmi.RemoteException

Purge all events from the event buffer which have been returned by jobEvents. The client is responsible for calling this method regularly to keep the event buffer from filling up.

Throws:

java.rmi.RemoteException

InvalidJobException

respondToPrompt

void respondToPrompt(java.lang.String devKey,
                     java.lang.String job,
                     int promptID,
                     java.lang.String response)
                     throws InvalidJobException,
                            InvalidPromptException,
                            java.rmi.RemoteException

Submit a response to a prompt (initiated by the Prompt site).

Throws:

InvalidPromptException - if the promptID is not valid.

InvalidJobException

java.rmi.RemoteException

cancelPrompt

void cancelPrompt(java.lang.String devKey,
                  java.lang.String job,
                  int promptID)
                  throws InvalidJobException,
                         InvalidPromptException,
                         java.rmi.RemoteException

Cancel a prompt (initiated by the Prompt site).

Throws:

InvalidPromptException - if the promptID is not valid.

InvalidJobException

java.rmi.RemoteException