Class Scheduler
- java.lang.Object
-
- nl.esciencecenter.xenon.schedulers.Scheduler
-
- All Implemented Interfaces:
java.lang.AutoCloseable
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
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description 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 theadaptor
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 theadaptor
connecting to thelocation
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 theadaptor
connecting to thelocation
usingcredentials
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 theadaptor
connecting to thelocation
usingcredentials
to get access.boolean
equals(java.lang.Object o)
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 int
getDefaultRuntime()
Get the default runtime of a job in minutes.abstract FileSystem
getFileSystem()
Retrieve theFileSystem
used internally by thisScheduler
.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 specifiedjobs
.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 thequeue
.abstract QueueStatus[]
getQueueStatuses(java.lang.String... queueNames)
Get the status of allqueues
.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.
-
-
-
Method Detail
-
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 ingetAdaptorNames()
.
-
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 theadaptor
connecting to thelocation
usingcredentials
to get access. Useproperties
to (optionally) configure the scheduler when it is created. Make sure to always closeScheduler
instances by callingScheduler.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 theadaptor
connecting to thelocation
usingcredentials
to get access. Make sure to always closeScheduler
instances by callingScheduler.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 theadaptor
connecting to thelocation
using the default credentials to get access. Make sure to always closeScheduler
instances by callingScheduler.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 theadaptor
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 closeScheduler
instances by callingScheduler.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:
nl.esciencecenter.xenon.adaptors.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 interfacejava.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:
nl.esciencecenter.xenon.adaptors.NotConnectedException
- If scheduler is closed.XenonException
- If an I/O error occurred.
-
getDefaultRuntime
public abstract int getDefaultRuntime() throws XenonException
Get the default runtime of a job in minutes. If no default runtime is available,-1
will be returned. If the default runtime is infinite,0
will be returned.- Returns:
- the default runtime of a job in minutes,
-1
if no default is available,0
if the default is infinite. - Throws:
nl.esciencecenter.xenon.adaptors.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:
nl.esciencecenter.xenon.adaptors.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 thequeue
.- 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 allqueues
. 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 specifiedjobs
.The array of
JobStatus
contains one entry for each of thejobs
. The order of the elements in the returnedJobStatus
array corresponds to the order in which thejobs
are passed as parameters. If ajob
isnull
, the corresponding entry in theJobStatus
array will also benull
. If the retrieval of theJobStatus
fails for a job, the exception will be stored in the correspondingJobsStatus
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. ThewaitUntilDone
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 negativeNoSuchJobException
- 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 negativeNoSuchJobException
- 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 theFileSystem
used internally by thisScheduler
.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 aFileSystem
internally.
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
-