Class 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 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)  
      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 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

        getClass, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getAdaptorNames

        public static java.lang.String[] getAdaptorNames()
        Gives a list names of the available adaptors.
        Returns:
        the list
      • 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:
        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 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:
        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 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.
      • 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.
      • 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