nl.esciencecenter.xenon.schedulers

Class Scheduler

java.lang.Object

nl.esciencecenter.xenon.schedulers.Scheduler

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

JobQueueScheduler, ScriptingScheduler

public abstract class Scheduler
extends java.lang.Object
implements java.lang.AutoCloseable

Scheduler represents a (possibly remote) scheduler that can be used to submit jobs and retrieve queue information.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	adaptor
private static java.util.HashMap<java.lang.String,SchedulerAdaptor>	adaptors
private static java.lang.String	COMPONENT_NAME The name of this component, for use in exceptions
private Credential	credential
private java.lang.String	location
protected XenonProperties	properties
private java.lang.String	uniqueID

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Scheduler(java.lang.String uniqueID, java.lang.String adaptor, java.lang.String location, Credential credential, XenonProperties properties)

Method Summary

Modifier and Type	Method and Description
private static void	addAdaptor(SchedulerAdaptor adaptor)
protected void	assertNonNullOrEmpty(java.lang.String s, java.lang.String message)
protected void	assertPositive(long value, java.lang.String message)
abstract JobStatus	cancelJob(java.lang.String jobIdentifier) Cancel a job.
abstract void	close() Close this Scheduler.
static Scheduler	create(java.lang.String adaptor) Create a new Scheduler using the adaptor connecting to the default location and using the default credentials to get access.
static Scheduler	create(java.lang.String adaptor, java.lang.String location) Create a new Scheduler using the adaptor connecting to the location using the default credentials to get access.
static Scheduler	create(java.lang.String adaptor, java.lang.String location, Credential credential) Create a new Scheduler using the adaptor connecting to the location using credentials to get access.
static Scheduler	create(java.lang.String adaptor, java.lang.String location, Credential credential, java.util.Map<java.lang.String,java.lang.String> properties) Create a new Scheduler using the adaptor connecting to the location using credentials to get access.
boolean	equals(java.lang.Object o)
private static SchedulerAdaptor	getAdaptorByName(java.lang.String adaptorName)
static SchedulerAdaptorDescription	getAdaptorDescription(java.lang.String adaptorName) Gives the description of the adaptor with the given name.
static SchedulerAdaptorDescription[]	getAdaptorDescriptions() Gives a list of the descriptions of the available adaptors.
java.lang.String	getAdaptorName() Get the name of the adaptor that created this Scheduler.
static java.lang.String[]	getAdaptorNames() Gives a list names of the available adaptors.
Credential	getCredential() Get the credential that this Scheduler is using.
abstract java.lang.String	getDefaultQueueName() Get the name of the default queue.
abstract FileSystem	getFileSystem() Retrieve the FileSystem used internally by this Scheduler.
abstract java.lang.String[]	getJobs(java.lang.String... queueNames) Get all job identifier of jobs currently in (one ore more) queues.
abstract JobStatus	getJobStatus(java.lang.String jobIdentifier) Get the status of a Job.
JobStatus[]	getJobStatuses(java.lang.String... jobIdentifiers) Get the status of all specified jobs.
java.lang.String	getLocation() Get the location that this Scheduler is connected to.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Get the properties used to create this Scheduler.
abstract java.lang.String[]	getQueueNames() Get the queue names supported by this Scheduler.
abstract QueueStatus	getQueueStatus(java.lang.String queueName) Get the status of the queue.
abstract QueueStatus[]	getQueueStatuses(java.lang.String... queueNames) Get the status of all queues.
int	hashCode()
abstract boolean	isOpen() Test if the connection of this Scheduler is open.
abstract java.lang.String	submitBatchJob(JobDescription description) Submit a batch job.
abstract Streams	submitInteractiveJob(JobDescription description) Submit an interactive job (optional operation).
abstract JobStatus	waitUntilDone(java.lang.String jobIdentifier, long timeout) Wait until a job is done or until a timeout expires.
abstract JobStatus	waitUntilRunning(java.lang.String jobIdentifier, long timeout) Wait until a job starts running, or until a timeout expires.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPONENT_NAME

private static final java.lang.String COMPONENT_NAME

The name of this component, for use in exceptions

See Also:

Constant Field Values

adaptors

private static final java.util.HashMap<java.lang.String,SchedulerAdaptor> adaptors

uniqueID

private final java.lang.String uniqueID

adaptor

private final java.lang.String adaptor

location

private final java.lang.String location

credential

private final Credential credential

properties

protected final XenonProperties properties

Constructor Detail

Scheduler

protected Scheduler(java.lang.String uniqueID,
                    java.lang.String adaptor,
                    java.lang.String location,
                    Credential credential,
                    XenonProperties properties)

Method Detail

addAdaptor

private static void addAdaptor(SchedulerAdaptor adaptor)

getAdaptorByName

private static SchedulerAdaptor getAdaptorByName(java.lang.String adaptorName)
                                          throws UnknownAdaptorException

Throws:

UnknownAdaptorException

getAdaptorNames

public static java.lang.String[] getAdaptorNames()

Gives a list names of the available adaptors.

Returns:

the list

getAdaptorDescription

public static SchedulerAdaptorDescription getAdaptorDescription(java.lang.String adaptorName)
                                                         throws UnknownAdaptorException

Gives the description of the adaptor with the given name.

Parameters:

adaptorName - the type of scheduler to connect to (e.g. "slurm" or "torque")

Returns:

the description

Throws:

UnknownAdaptorException - If the adaptor name is absent in getAdaptorNames().

getAdaptorDescriptions

public static SchedulerAdaptorDescription[] getAdaptorDescriptions()

Gives a list of the descriptions of the available adaptors.

Returns:

the list

create

public static Scheduler create(java.lang.String adaptor,
                               java.lang.String location,
                               Credential credential,
                               java.util.Map<java.lang.String,java.lang.String> properties)
                        throws XenonException

Create a new Scheduler using the adaptor connecting to the location using credentials to get access. Use properties to (optionally) configure the scheduler when it is created. Make sure to always close Scheduler instances by calling Scheduler.close() when you no longer need them, otherwise their associated resources may remain allocated.

Parameters:

adaptor - the adaptor used to access the Scheduler.

location - the location of the Scheduler.

credential - the Credentials to use to get access to the Scheduler.

properties - optional properties to configure the Scheduler when it is created.

Returns:

the new Scheduler.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the Scheduler failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static Scheduler create(java.lang.String adaptor,
                               java.lang.String location,
                               Credential credential)
                        throws XenonException

Create a new Scheduler using the adaptor connecting to the location using credentials to get access. Make sure to always close Scheduler instances by calling Scheduler.close() when you no longer need them, otherwise their associated resources may remain allocated.

Parameters:

adaptor - the adaptor used to access the Scheduler.

location - the location of the Scheduler.

credential - the Credentials to use to get access to the Scheduler.

Returns:

the new Scheduler.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the Scheduler failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static Scheduler create(java.lang.String adaptor,
                               java.lang.String location)
                        throws XenonException

Create a new Scheduler using the adaptor connecting to the location using the default credentials to get access. Make sure to always close Scheduler instances by calling Scheduler.close() when you no longer need them, otherwise their associated resources may remain allocated.

Parameters:

adaptor - the adaptor used to access the Scheduler.

location - the location of the Scheduler.

Returns:

the new Scheduler.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the Scheduler failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static Scheduler create(java.lang.String adaptor)
                        throws XenonException

Create a new Scheduler using the adaptor connecting to the default location and using the default credentials to get access. Note that there are very few adaptors that support a default scheduler location. The local scheduler adaptor is the prime example. Make sure to always close Scheduler instances by calling Scheduler.close() when you no longer need them, otherwise their associated resources may remain allocated.

Parameters:

adaptor - the adaptor used to access the Scheduler.

Returns:

the new Scheduler.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the Scheduler failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

getAdaptorName

public java.lang.String getAdaptorName()

Get the name of the adaptor that created this Scheduler.

Returns:

the name of the adaptor.

getLocation

public java.lang.String getLocation()

Get the location that this Scheduler is connected to.

Returns:

the location this Scheduler is connected to.

getCredential

public Credential getCredential()

Get the credential that this Scheduler is using.

Returns:

the credential this Scheduler is using.

getProperties

public java.util.Map<java.lang.String,java.lang.String> getProperties()

Get the properties used to create this Scheduler.

Returns:

the properties used to create this Scheduler.

getQueueNames

public abstract java.lang.String[] getQueueNames()
                                          throws XenonException

Get the queue names supported by this Scheduler.

Returns:

the queue names supported by this Scheduler.

Throws:

NotConnectedException - If scheduler is closed.

XenonException - If an I/O error occurred.

close

public abstract void close()
                    throws XenonException

Close this Scheduler.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

XenonException - If the Scheduler failed to close.

isOpen

public abstract boolean isOpen()
                        throws XenonException

Test if the connection of this Scheduler is open.

Returns:

true if the connection of this Scheduler is still open, false otherwise.

Throws:

XenonException - If an I/O error occurred.

getDefaultQueueName

public abstract java.lang.String getDefaultQueueName()
                                              throws XenonException

Get the name of the default queue.

Returns:

the name of the default queue for this scheduler, or null if no default queue is available.

Throws:

NotConnectedException - If scheduler is closed.

XenonException - If an I/O error occurred.

getJobs

public abstract java.lang.String[] getJobs(java.lang.String... queueNames)
                                    throws XenonException

Get all job identifier of jobs currently in (one ore more) queues. If no queue names are specified, the job identifiers for all queues are returned. Note that job identifiers of jobs submitted by other users or other schedulers may also be returned.

Parameters:

queueNames - the names of the queues.

Returns:

an array containing the resulting job identifiers .

Throws:

NotConnectedException - If scheduler is closed.

NoSuchQueueException - If the queue does not exist in the scheduler.

XenonException - If the Scheduler failed to get jobs.

getQueueStatus

public abstract QueueStatus getQueueStatus(java.lang.String queueName)
                                    throws XenonException

Get the status of the queue.

Parameters:

queueName - the name of the queue.

Returns:

the resulting QueueStatus.

Throws:

NoSuchQueueException - If the queue does not exist in the scheduler.

XenonException - If the Scheduler failed to get its status.

getQueueStatuses

public abstract QueueStatus[] getQueueStatuses(java.lang.String... queueNames)
                                        throws XenonException

Get the status of all queues. Note that this method will only throw an exception when this exception will influence all status requests. For example, if the scheduler is no longer connected. Exceptions that only refer to a single queue are returned in the QueueStatus returned for that queue.

Parameters:

queueNames - the names of the queues.

Returns:

an array containing the resulting QueueStatus.

Throws:

XenonException - If the Scheduler failed to get the statuses.

submitBatchJob

public abstract java.lang.String submitBatchJob(JobDescription description)
                                         throws XenonException

Submit a batch job.

Parameters:

description - the description of the batch job to submit.

Returns:

the job identifier representing the running job.

Throws:

IncompleteJobDescriptionException - If the description did not contain the required information.

InvalidJobDescriptionException - If the description contains illegal or conflicting values.

UnsupportedJobDescriptionException - If the description is not legal for this scheduler.

XenonException - If the Scheduler failed to get submit the job.

submitInteractiveJob

public abstract Streams submitInteractiveJob(JobDescription description)
                                      throws XenonException

Submit an interactive job (optional operation).

Parameters:

description - the description of the interactive job to submit.

Returns:

a Streams object containing the job identifier and the standard streams of a job.

Throws:

IncompleteJobDescriptionException - If the description did not contain the required information.

InvalidJobDescriptionException - If the description contains illegal or conflicting values.

UnsupportedJobDescriptionException - If the description is not legal for this scheduler.

XenonException - If the Scheduler failed to get submit the job.

getJobStatus

public abstract JobStatus getJobStatus(java.lang.String jobIdentifier)
                                throws XenonException

Get the status of a Job.

Parameters:

jobIdentifier - the job identifier of the job to get the status for.

Returns:

the status of the Job.

Throws:

NoSuchJobException - If the job is not known.

XenonException - If the status of the job could not be retrieved.

getJobStatuses

public JobStatus[] getJobStatuses(java.lang.String... jobIdentifiers)
                           throws XenonException

Get the status of all specified jobs.

The array of JobStatus contains one entry for each of the jobs. The order of the elements in the returned JobStatus array corresponds to the order in which the jobs are passed as parameters. If a job is null, the corresponding entry in the JobStatus array will also be null. If the retrieval of the JobStatus fails for a job, the exception will be stored in the corresponding JobsStatus entry.

Parameters:

jobIdentifiers - the job identifiers for which to retrieve the status.

Returns:

an array of the resulting JobStatuses.

Throws:

XenonException - If an I/O error occurred

cancelJob

public abstract JobStatus cancelJob(java.lang.String jobIdentifier)
                             throws XenonException

Cancel a job.

A status is returned that indicates the state of the job after the cancel. If the job was already done it cannot be cancelled.

A JobStatus is returned that can be used to determine the state of the job after cancelJob returns. Note that it may take some time before the job has actually terminated. The waitUntilDone method can be used to wait until the job is terminated.

Parameters:

jobIdentifier - the identifier of job to kill.

Returns:

the status of the Job.

Throws:

NoSuchJobException - If the job is not known.

XenonException - If the status of the job could not be retrieved.

waitUntilDone

public abstract JobStatus waitUntilDone(java.lang.String jobIdentifier,
                                        long timeout)
                                 throws XenonException

Wait until a job is done or until a timeout expires.

This method will wait until a job is done (either gracefully or by being killed or producing an error), or until the timeout expires, whichever comes first. If the timeout expires, the job will continue to run.

The timeout is in milliseconds and must be >= 0. When timeout is 0, it will be ignored and this method will wait until the jobs is done.

A JobStatus is returned that can be used to determine why the call returned.

Parameters:

jobIdentifier - the identifier of the to wait for.

timeout - the maximum time to wait for the job in milliseconds.

Returns:

the status of the Job.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative

NoSuchJobException - If the job is not known.

XenonException - If the status of the job could not be retrieved.

waitUntilRunning

public abstract JobStatus waitUntilRunning(java.lang.String jobIdentifier,
                                           long timeout)
                                    throws XenonException

Wait until a job starts running, or until a timeout expires.

This method will return as soon as the job is no longer waiting in the queue, or when the timeout expires, whichever comes first. If the job is no longer waiting in the queue, it may be running, but it may also be killed, finished or have produced an error. If the timeout expires, the job will continue to be queued normally.

The timeout is in milliseconds and must be >= 0. When timeout is 0, it will be ignored and this method will wait until the job is no longer queued.

A JobStatus is returned that can be used to determine why the call returned.

Parameters:

jobIdentifier - the identifier of the to wait for.

timeout - the maximum time to wait in milliseconds.

Returns:

the status of the Job.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative

NoSuchJobException - If the job is not known.

XenonException - If the status of the job could not be retrieved.

getFileSystem

public abstract FileSystem getFileSystem()
                                  throws XenonException

Retrieve the FileSystem used internally by this Scheduler.

Often, a Scheduler needs to access files or directories on the machine it will schedule jobs. For example, to ensure a working directory exists, or to redirect the stdin, stdout or stderr streams used by a job.

This method returns this FileSystem so it can also be used by the application to prepare input files for the jobs, or retrieve the output files produced by the jobs.

Returns:

the FileSystem used by this Scheduler.

Throws:

XenonException - if this Scheduler does not use a FileSystem internally.

assertNonNullOrEmpty

protected void assertNonNullOrEmpty(java.lang.String s,
                                    java.lang.String message)

assertPositive

protected void assertPositive(long value,
                              java.lang.String message)

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object