com.bigdata.service.mapred
Interface IJobAndTaskService<M extends IJobMetadata,T extends ITask>

Type Parameters:

M - The type for the job metadata parameter in #startJob(UUID, Object).

T - The type for the task in #submit(UUID, Object).

All Superinterfaces:

Remote

All Known Subinterfaces:

IMapService, IReduceService

All Known Implementing Classes:

AbstractJobAndTaskService, MapServer.AdministrableMapService, MapService, MapService.EmbeddedMapService, ReduceServer.AdministrableReduceService, ReduceService, ReduceService.EmbeddedReduceService

public interface IJobAndTaskService<M extends IJobMetadata,T extends ITask>
extends Remote

A interface for a service using a job and task model. The service may have many clients, and each client may start jobs and execute tasks within running jobs. A job must be started before tasks may be submitted. Tasks run with some unknown concurrency. The service MUST be sent a heartbeat for each job to keep tasks running in that job. The heartbeat returns the #of completed tasks for that job. The client can drain the completed tasks for a job, transferring information about their Outcome to itself. A pending or running task may be cancelled, in which case it will show up as completed (with Status.Cancelled). If the service does not receive several heatbeats in a row for a job, then it will cancel the job and all tasks running in that job. When the client is done executing tasks for a job, it should cancel the job. When a job is cancelled, all state for that job is thrown away.

Note: This interface extends Remote since it may be used as a remote service. Per the contract of the Remote interface, methods on this interface are declared to throw IOException since they may be invoked by RMI.

Version:

$Id: IJobAndTaskService.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

TODO:

add a status message returning a String containing a service specific status summary.

Method Summary

boolean	cancel(UUID job, UUID task) Cancel a task.
void	cancelJob(UUID job) Terminate a job.
Outcome[]	drain(UUID job) Drains the Outcomes for all completed tasks.
UUID	getServiceUUID() The unique identifier for this service.
int	heartbeat(UUID job) The service will cancelJob(UUID) the job if it does not continue to receive heartbeat for that job.
void	startJob(M jobMetadata) Declare a job.
void	submit(UUID job, T task, long timeout) Submit a task to be executed as part of a job (asynchronous).

Method Detail

getServiceUUID

UUID getServiceUUID()
                    throws IOException

The unique identifier for this service.

Returns:

The unique service identifier.

Throws:

IOException

startJob

void startJob(M jobMetadata)
              throws IOException

Declare a job. The service will now accept tasks for the job. The client MUST send heartbeat(UUID) messages or the service will cancel the job.

Parameters:

jobMetadata - The service specific job metadata.

Throws:

IOException

cancelJob

void cancelJob(UUID job)
               throws IOException

Terminate a job. The service will no longer accept tasks for this job. Any running tasks will be terminated. This method SHOULD be invoked whether a job is terminated normally or aborted. It will be invoked by the service in any case if the service no longer recieves heartbeat(UUID) messages for this job.

Parameters:

job - The job identifier.

Throws:

IllegalStateException - if the job is not known to the service.

IOException

heartbeat

int heartbeat(UUID job)
              throws IOException

The service will cancelJob(UUID) the job if it does not continue to receive heartbeat for that job. The service timeout for a job is on the order of a few seconds, but clients are encouraged to send heartbeats ever 100ms.

Note: Clients may also use this message to monitor the progression of tasks for the specified job.

Parameters:

job - The job identifier.

Returns:

The #of completed tasks for that job.

Throws:

IOException

drain

Outcome[] drain(UUID job)
                throws IOException

Drains the Outcomes for all completed tasks. The Outcome for those tasks is no longer available from the service.

Parameters:

job - The job identifier.

Returns:

The task Outcomes.

Throws:

IOException

submit

void submit(UUID job,
            T task,
            long timeout)
            throws IOException

Submit a task to be executed as part of a job (asynchronous). The task will be placed into a queue and will begin executing once there is an available worker. When the tasks completes with any Status, it will be reported by heartbeat(UUID) and its Outcome will be made available by drain(UUID).

Parameters:

job - The job identifier.

task - The task to be executed.

timeout - When non-zero, the timeout in milliseconds for this task once it begins to execute on the service (this controls the actual maximum run time of the task rather than the time since the task was submitted or since the job was started).

Throws:

IOException

cancel

boolean cancel(UUID job,
               UUID task)
               throws IOException

Cancel a task. If the task is queued it will not be run. It is is running, it will be cancelled. If the task has already completed the service will ignore this message.

Parameters:

job - The job identifier.

task - The task identifier.

Returns:

false if the task could not be cancelled (per Future.cancel(boolean)).

Throws:

IOException