ca.eandb.jdcp.remote

Interface JobService

All Superinterfaces:

Remote, TaskService

public interface JobService
extends TaskService

A remote service for accepting ParallelizableJobs, managing the distribution of tasks to workers, and aggregating the results submitted by workers.

Author:

Brad Kimmel

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_PRIORITY The default job priority.

Method Summary

Modifier and Type	Method and Description
void	cancelJob(UUID jobId) Cancels the specified job.
UUID	createJob(String description) Creates a new job on the server.
byte[]	getClassDigest(String name) Gets the MD5 digest for the most recent definition of the given class.
JobStatus	getJobStatus(UUID jobId) Gets the current status of the specified job.
void	registerTaskService(String name, TaskService service) Registers a TaskService to receive tasks from an external source.
void	setClassDefinition(String name, byte[] def) Sets the class definition for the specified class.
void	setClassDefinition(String name, UUID jobId, byte[] def) Sets the definition of a given class only for the specified job.
void	setIdleTime(int idleSeconds) Sets the amount of time (in seconds) that workers should idle when there are no tasks to be performed.
void	setJobPriority(UUID jobId, int priority) Sets the priority of the specified job.
UUID	submitJob(ca.eandb.util.rmi.Serialized<ParallelizableJob> job, String description) Submits a new job to be processed.
void	submitJob(ca.eandb.util.rmi.Serialized<ParallelizableJob> job, UUID jobId) Submits a job previously created using createJob(String).
void	unregisterTaskService(String name) Unregisters a TaskService.
JobStatus	waitForJobStatusChange(long lastEventId, long timeoutMillis) Waits for a status change for any job hosted on this server.
JobStatus	waitForJobStatusChange(UUID jobId, long lastEventId, long timeoutMillis) Waits for a status change for the specified job.

Methods inherited from interface ca.eandb.jdcp.remote.TaskService

getClassDefinition, getClassDigest, getFinishedTasks, getTaskWorker, reportException, requestTask, submitTaskResults

Field Detail

DEFAULT_PRIORITY

static final int DEFAULT_PRIORITY

The default job priority.

See Also:

Constant Field Values

Method Detail

createJob

UUID createJob(String description)
        throws SecurityException,
               RemoteException

Creates a new job on the server. This method allows job-specified classes to be uploaded before the job is submitted for execution.

Parameters:

description - A description for the job.

Returns:

The UUID identifying the new job.

Throws:

SecurityException - If the caller does not have permission to submit jobs.

RemoteException - If a communication error occurs.

See Also:

setClassDefinition(String, UUID, byte[]), submitJob(Serialized, UUID)

submitJob

void submitJob(ca.eandb.util.rmi.Serialized<ParallelizableJob> job,
               UUID jobId)
        throws IllegalArgumentException,
               SecurityException,
               ClassNotFoundException,
               RemoteException,
               JobExecutionException

Submits a job previously created using createJob(String).

Parameters:

job - The ParallelizableJob being submitted. It must be wrapped in a Serialized wrapper to bypass RMI deserialization.

jobId - The UUID associated with the previously created job.

Throws:

IllegalArgumentException - If jobId does not correspond to a job on the server that is awaiting submission.

SecurityException - If the caller does not have permission to submit jobs.

ClassNotFoundException - If deserialization of job requires a class which does not exist on the server.

RemoteException - If a communication error occurs.

JobExecutionException - If the submitted job throws an exception while being initialized.

submitJob

UUID submitJob(ca.eandb.util.rmi.Serialized<ParallelizableJob> job,
               String description)
        throws SecurityException,
               ClassNotFoundException,
               RemoteException,
               JobExecutionException

Submits a new job to be processed.

Parameters:

job - The ParallelizableJob to be processed.

description - A description for the job.

Returns:

The UUID assigned to the job, or null if the job was not accepted.

Throws:

SecurityException - If the caller does not have permission to submit jobs.

ClassNotFoundException - If deserialization of job requires a class which does not exist on the server.

RemoteException - If a communication error occurs.

JobExecutionException - If the submitted job throws an exception while being initialized.

cancelJob

void cancelJob(UUID jobId)
        throws IllegalArgumentException,
               SecurityException,
               RemoteException

Cancels the specified job.

Parameters:

jobId - The UUID identifying the job to be cancelled.

Throws:

IllegalArgumentException - If there is no job on the server with the specified UUID.

SecurityException - If the caller does not have permission to cancel jobs.

RemoteException - If a communication error occurs.

getClassDigest

byte[] getClassDigest(String name)
               throws SecurityException,
                      RemoteException

Gets the MD5 digest for the most recent definition of the given class.

Parameters:

name - The fully qualified name of the class whose digest to obtain.

Returns:

The MD5 digest for the most recent definition of the given class.

Throws:

SecurityException - If the caller does not have permission to obtain class digests.

RemoteException - If a communication error occurs.

setClassDefinition

void setClassDefinition(String name,
                        byte[] def)
                 throws SecurityException,
                        RemoteException

Sets the class definition for the specified class.

Parameters:

name - The fully qualified name of the class whose definition is being provided.

def - The definition of the class.

Throws:

SecurityException - If the caller does not have permission to set class definitions.

RemoteException - If a communication error occurs.

setClassDefinition

void setClassDefinition(String name,
                        UUID jobId,
                        byte[] def)
                 throws IllegalArgumentException,
                        SecurityException,
                        RemoteException

Sets the definition of a given class only for the specified job.

Parameters:

name - The fully qualified name of the class whose definition is being provided.

jobId - The UUID identifying the job to associate the class definition with.

def - The definition of the class.

Throws:

IllegalArgumentException - If there is no job awaiting submission with the specified job ID.

SecurityException - If the caller does not have permission to set class definitions.

RemoteException - If a communication error occurs.

setIdleTime

void setIdleTime(int idleSeconds)
          throws IllegalArgumentException,
                 SecurityException,
                 RemoteException

Sets the amount of time (in seconds) that workers should idle when there are no tasks to be performed.

Parameters:

idleSeconds - The amount of time (in seconds) that workers should idle when there are no tasks to be performed.

Throws:

IllegalArgumentException - If idleSeconds is negative.

SecurityException - If the caller does not have permission to set the idle time.

RemoteException - If a communication error occurs.

setJobPriority

void setJobPriority(UUID jobId,
                    int priority)
             throws IllegalArgumentException,
                    SecurityException,
                    RemoteException

Sets the priority of the specified job.

Parameters:

jobId - The UUID identifying the job whose priority is to be set.

priority - The new priority to assign to the job.

Throws:

IllegalArgumentException - If the priority is invalid or if there is no job with the specified job ID on the server.

SecurityException - If the caller does not have permission to set job priorities.

RemoteException - If a communication error occurs.

registerTaskService

void registerTaskService(String name,
                         TaskService service)
                  throws SecurityException,
                         RemoteException

Registers a TaskService to receive tasks from an external source.

Parameters:

name - A unique string identifying the service to register. If a service with the same name is already registered, it will be unregistered first.

service - The TaskService to use to obtain tasks to work on.

Throws:

SecurityException - If the caller does not have permission to register a TaskService.

RemoteException - If a communication error occurs.

unregisterTaskService

void unregisterTaskService(String name)
                    throws IllegalArgumentException,
                           SecurityException,
                           RemoteException

Unregisters a TaskService.

Parameters:

name - The name of identifying the TaskService to unregister.

Throws:

IllegalArgumentException - If serviceId does not refer to a registered TaskService.

SecurityException - If the caller does not have permission to unregister a TaskService.

RemoteException - If a communication error occurs.

waitForJobStatusChange

JobStatus waitForJobStatusChange(long lastEventId,
                                 long timeoutMillis)
                          throws SecurityException,
                                 RemoteException

Waits for a status change for any job hosted on this server.

Parameters:

lastEventId - The ID of the last event received, or Long.MIN_VALUE to indicate that no events had been received previously.

timeoutMillis - The maximum amount of time (in milliseconds) to wait before returning. If zero, then the call will return immediately. If negative, the call will wait indefinitely.

Returns:

If an event has already occurred subsequent to the event with ID lastEventId, the pending JobStatus event will be returned. Otherwise, the call will wait up to timeoutMillis milliseconds for an event to occur. If one does occur in that time, that JobStatus will be returned. If no event occurs, null is returned.

Throws:

SecurityException - If the caller does not have permission wait for events.

RemoteException - If a communication error occurs.

waitForJobStatusChange

JobStatus waitForJobStatusChange(UUID jobId,
                                 long lastEventId,
                                 long timeoutMillis)
                          throws IllegalArgumentException,
                                 SecurityException,
                                 RemoteException

Waits for a status change for the specified job.

Parameters:

jobId - The UUID identifying the job to wait on.

lastEventId - The ID of the last event received, or Long.MIN_VALUE to indicate that no events had been received previously.

timeoutMillis - The maximum amount of time (in milliseconds) to wait before returning. If zero, then the call will return immediately. If negative, the call will wait indefinitely.

Returns:

If an event has already occurred subsequent to the event with ID lastEventId, the pending JobStatus event will be returned. Otherwise, the call will wait up to timeoutMillis milliseconds for an event to occur. If one does occur in that time, that JobStatus will be returned. If no event occurs, null is returned.

Throws:

IllegalArgumentException - If no job exists with the specified UUID.

SecurityException - If the caller does not have permission wait for events.

RemoteException - If a communication error occurs.

getJobStatus

JobStatus getJobStatus(UUID jobId)
                throws IllegalArgumentException,
                       SecurityException,
                       RemoteException

Gets the current status of the specified job.

Parameters:

jobId - The UUID identifying the job of which to get the status.

Returns:

The current JobStatus for the specified job.

Throws:

IllegalArgumentException - If no job exists with the specified UUID.

SecurityException - If the caller does not have permission to obtain the status of a job.

RemoteException - If a communication error occurs.