agi.parallel.client

Class ClusterJobScheduler

java.lang.Object

agi.parallel.client.ClusterJobScheduler

All Implemented Interfaces:

IEnforceTaskPrecondition, IGetAgentInfo, IGetAuthorizationInfo, IGetLicenseInfo, IGetVersionInfo, IJobScheduler, IMessageEndpoint, java.io.Closeable, java.lang.AutoCloseable

public final class ClusterJobScheduler
extends java.lang.Object
implements IJobScheduler, IEnforceTaskPrecondition, IGetLicenseInfo, IGetAgentInfo, IGetAuthorizationInfo, IGetVersionInfo, IMessageEndpoint

Provides the methods used to submit and monitor jobs to cluster scheduler. After creating an instance of this class, call the connect() method to connect to the cluster scheduler. You can then submit and monitor jobs. We recommend that instead of using this class you instead use the IJobScheduler interface if possible.

Constructor Summary

Constructors

Constructor and Description
ClusterJobScheduler() Initializes a new instance of the ClusterJobScheduler class.
ClusterJobScheduler(java.lang.String coordinatorMachineName) Initializes a new instance of the ClusterJobScheduler class with the specified coordinator hostname.
ClusterJobScheduler(java.lang.String coordinatorMachineName, int coordinatorPort) Initializes a new instance of the ClusterJobScheduler class with the specified coordinator hostname and coordinator port.
ClusterJobScheduler(java.lang.String coordinatorMachineName, int coordinatorPort, boolean useSsl, boolean allowSelfSignedCertificates) Initializes a new instance of the ClusterJobScheduler class with the specified coordinator host name, port, and security options.

Method Summary

Modifier and Type	Method and Description
void	addNewMessageListener(NewMessageListener listener) Adds a handler for an event that occurs when a new message arrives.
void	cancelJob(java.util.UUID jobId, boolean listenForCancellationEvent) Cancels the job with the specified id.
void	cancelTask(java.util.UUID taskId) Cancels the task with the specified id.
void	close() Closes this JobScheduler and releases any system resources associated with it.
void	connect() Connects client to specified cluster scheduler.
Job	createJob() Returns a new job that can later be used to submit to the job scheduler.
void	disconnect() Disconnects client from specified job scheduler.
void	dispose() Deprecated. Please use close()
java.util.List<AgentSnapshot>	getAgentInfo() Returns the list of agents and their current states.
boolean	getAllowSelfSignedCertificates() Gets a value indicating whether to allow self-signed certificates when communicating with the coordinator.
java.lang.String	getCoordinatorMachineName() Gets the name of the coordinator.
int	getCoordinatorPort() Gets port number of the coordinator.
int	getCoordinatorReconnectionDelay() Retrieves the amount of time, in milliseconds, the scheduler should wait before attempting to reconnect to the coordinator.
int	getCoordinatorReconnectionInterval() Gets the amount of time, in milliseconds, the scheduler should wait in between each reconnection attempt.
java.lang.String	getCoordinatorThumbprint() Returns the expected thumbprint of the coordinator's certificate.
int	getCoordinatorTimeout() Gets the timeout wait time in milliseconds This value is readonly after you have already connected to the coordinator.
java.util.UUID	getId() Gets the id of this job scheduler.
boolean	getIsConnected() Gets a value indicating whether the job scheduler is connected.
LicenseInfo	getLicenseInfo(LicenseParameters licenseParameters) Gets the license info that matches the provided license parameters.
int	getMaximumHostCount() Returns the maximum number of hosts that is available to the job scheduler.
int	getMaximumReconnectionAttempts() Gets the maximum number of times the job scheduler should try to reconnect to the coordinator before aborting.
boolean	getProvideClientCertificate() Gets a value indicating whether or not to provide a client certificate to the coordinator.
AuthorizationType	getUserAuthorization() Determines whether the user is authorized for the job submission protocol.
boolean	getUseSsl() Gets a value indicating whether or not to use SSL when communicating with the coordinator.
VersionInfo	getVersionInfo() Gets the version info of the job scheduler.
void	onCoordinatorDisconnected() Called when the job scheduler connection with the coordinator is interrupted.
void	postMessage(java.lang.Object message, java.util.UUID target) Posts a message to the specified target mailbox.
void	postMessage(java.lang.Object message, java.util.UUID target, boolean quietlyFail) Posts a message to the specified target mailbox.
java.lang.Object	receiveMessage() Receives a message from the participant's mailbox.
java.lang.Object	receiveMessage(int millisecondsTimeout) Receives a message from the participant's mailbox.
java.lang.Object	receiveMessage(int millisecondsTimeout, java.util.UUID[] sender) Receives a message from the participant's mailbox.
java.lang.Object	receiveMessage(java.util.UUID[] sender) Receives a message from the participant's mailbox.
void	removeNewMessageListener(NewMessageListener listener)
void	setAllowSelfSignedCertificates(boolean value) Sets a value indicating whether to allow self-signed certificates when communicating with the coordinator.
void	setCoordinatorMachineName(java.lang.String value) Sets the name of the coordinator.
void	setCoordinatorPort(int value) Sets port number of the coordinator.
void	setCoordinatorReconnectionDelay(int delay) Sets the amount of time, in milliseconds, the scheduler should wait before attempting to reconnect to the coordinator.
void	setCoordinatorReconnectionInterval(int interval) Sets the amount of time, in milliseconds, the scheduler should wait in between each reconnection attempt.
void	setCoordinatorThumbprint(java.lang.String thumbprint) Sets the expected thumbprint of the coordinator's certificate.
void	setCoordinatorTimeout(int timeout) Sets the timeout wait time in milliseconds.
void	setMaximumReconnectionAttempts(int maximum) Sets the maximum number of times the job scheduler should try to reconnect to the coordinator before aborting.
void	setProvideClientCertificate(boolean provide) Sets a value indicating whether to provide a client certificate to the coordinator.
void	setUseSsl(boolean value) Sets a value indicating whether or not to use SSL when communicating with the coordinator.
void	submitJob(Job job, JobSubmitListener listener) Submits job to the job scheduler so that the job scheduler can add the job to it's queue.
java.lang.String	toString()
boolean	waitUntilDone(java.util.UUID jobId, int millisecondsTimeout, java.lang.Runnable heartbeatCallback, int millisecondsHeartbeat) Blocks until all tasks in this job complete or the operation times out.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClusterJobScheduler

public ClusterJobScheduler()

Initializes a new instance of the ClusterJobScheduler class.

ClusterJobScheduler

public ClusterJobScheduler(java.lang.String coordinatorMachineName)

Initializes a new instance of the ClusterJobScheduler class with the specified coordinator hostname.

Parameters:

coordinatorMachineName - The DNS name of the coordinator you intend to connect.

ClusterJobScheduler

public ClusterJobScheduler(java.lang.String coordinatorMachineName,
                           int coordinatorPort)

Initializes a new instance of the ClusterJobScheduler class with the specified coordinator hostname and coordinator port.

Parameters:

coordinatorMachineName - The DNS name of the coordinator you intend to connect.

coordinatorPort - The port number of the coordinator you intend to connect.

ClusterJobScheduler

public ClusterJobScheduler(java.lang.String coordinatorMachineName,
                           int coordinatorPort,
                           boolean useSsl,
                           boolean allowSelfSignedCertificates)

Initializes a new instance of the ClusterJobScheduler class with the specified coordinator host name, port, and security options.

Parameters:

coordinatorMachineName - The DNS name of the coordinator you intend to connect.

coordinatorPort - The port number of the coordinator you intend to connect.

useSsl - If set to true, use SSL to communicate with the coordinator.

allowSelfSignedCertificates - If set to true, allow self-signed certificates.

Method Detail

addNewMessageListener

public final void addNewMessageListener(NewMessageListener listener)
                                 throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Adds a handler for an event that occurs when a new message arrives.

Specified by:

addNewMessageListener in interface IMessageEndpoint

Throws:

JobSchedulerException

removeNewMessageListener

public final void removeNewMessageListener(NewMessageListener listener)
                                    throws JobSchedulerException

Throws:

JobSchedulerException

getCoordinatorMachineName

public final java.lang.String getCoordinatorMachineName()

Gets the name of the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorMachineName is read-only.

setCoordinatorMachineName

public final void setCoordinatorMachineName(java.lang.String value)

Sets the name of the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorMachineName is read-only.

getCoordinatorPort

public final int getCoordinatorPort()

Gets port number of the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorPort is read-only.

setCoordinatorPort

public final void setCoordinatorPort(int value)

Sets port number of the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorPort is read-only.

getUseSsl

public final boolean getUseSsl()

Gets a value indicating whether or not to use SSL when communicating with the coordinator. This value is readonly after you have already connected to the coordinator.

setUseSsl

public final void setUseSsl(boolean value)

Sets a value indicating whether or not to use SSL when communicating with the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorPort is read-only.

getAllowSelfSignedCertificates

public final boolean getAllowSelfSignedCertificates()

Gets a value indicating whether to allow self-signed certificates when communicating with the coordinator. This value is readonly after you have already connected to the coordinator.

setAllowSelfSignedCertificates

public final void setAllowSelfSignedCertificates(boolean value)

Sets a value indicating whether to allow self-signed certificates when communicating with the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorPort is read-only.

getCoordinatorTimeout

public final int getCoordinatorTimeout()

Gets the timeout wait time in milliseconds This value is readonly after you have already connected to the coordinator.

Returns:

Coordinator timeout (in milliseconds).

setCoordinatorTimeout

public void setCoordinatorTimeout(int timeout)

Sets the timeout wait time in milliseconds. This value is readonly after you have already connected to the coordinator.

Parameters:

timeout - Coordinator timeout (in milliseconds).

Throws:

java.lang.IllegalStateException - If CoordinatorTimeout is readonly.

getProvideClientCertificate

public boolean getProvideClientCertificate()

Gets a value indicating whether or not to provide a client certificate to the coordinator. This value is readonly after you have already connected to the coordinator.

setProvideClientCertificate

public void setProvideClientCertificate(boolean provide)

Sets a value indicating whether to provide a client certificate to the coordinator. This value is readonly after you have already connected to the coordinator.

Throws:

java.lang.IllegalStateException - Thrown if CoordinatorPort is read-only.

getId

public final java.util.UUID getId()

Description copied from interface: IJobScheduler

Gets the id of this job scheduler.

Specified by:

getId in interface IJobScheduler

Specified by:

getId in interface IMessageEndpoint

getIsConnected

public final boolean getIsConnected()

Description copied from interface: IJobScheduler

Gets a value indicating whether the job scheduler is connected. true if this scheduler is connected; otherwise, false.

Specified by:

getIsConnected in interface IJobScheduler

getCoordinatorReconnectionDelay

public int getCoordinatorReconnectionDelay()

Retrieves the amount of time, in milliseconds, the scheduler should wait before attempting to reconnect to the coordinator.

setCoordinatorReconnectionDelay

public void setCoordinatorReconnectionDelay(int delay)

Sets the amount of time, in milliseconds, the scheduler should wait before attempting to reconnect to the coordinator.

getCoordinatorReconnectionInterval

public int getCoordinatorReconnectionInterval()

Gets the amount of time, in milliseconds, the scheduler should wait in between each reconnection attempt.

setCoordinatorReconnectionInterval

public void setCoordinatorReconnectionInterval(int interval)

Sets the amount of time, in milliseconds, the scheduler should wait in between each reconnection attempt.

getMaximumReconnectionAttempts

public int getMaximumReconnectionAttempts()

Gets the maximum number of times the job scheduler should try to reconnect to the coordinator before aborting.

setMaximumReconnectionAttempts

public void setMaximumReconnectionAttempts(int maximum)

Sets the maximum number of times the job scheduler should try to reconnect to the coordinator before aborting.

getCoordinatorThumbprint

public java.lang.String getCoordinatorThumbprint()

Returns the expected thumbprint of the coordinator's certificate. The client checks this thumbprint matches that of the Coordinator's security certificate to ensure it can trust the Coordinator.

setCoordinatorThumbprint

public void setCoordinatorThumbprint(java.lang.String thumbprint)

Sets the expected thumbprint of the coordinator's certificate. The client checks this thumbprint matches that of the Coordinator's security certificate to ensure it can trust the Coordinator.

Parameters:

thumbprint - Expected coordinator certificate thumbprint.

cancelJob

public final void cancelJob(java.util.UUID jobId,
                            boolean listenForCancellationEvent)
                     throws JobSchedulerException

Description copied from interface: IJobScheduler

Cancels the job with the specified id.

Specified by:

cancelJob in interface IJobScheduler

Parameters:

jobId - The id of the job to cancel.

listenForCancellationEvent - if set to true, client will listen for the cancellation event. Otherwise, cancellation events can be ignored.

Throws:

JobSchedulerException - Thrown if client is not connected to the job scheduler yet.

cancelTask

public final void cancelTask(java.util.UUID taskId)
                      throws JobSchedulerException

Description copied from interface: IJobScheduler

Cancels the task with the specified id.

Specified by:

cancelTask in interface IJobScheduler

Parameters:

taskId - The id of the task to cancel.

Throws:

JobSchedulerException - Thrown if client is not connected to the job scheduler yet.

getMaximumHostCount

public final int getMaximumHostCount()
                              throws JobSchedulerException

Description copied from interface: IJobScheduler

Returns the maximum number of hosts that is available to the job scheduler.

Specified by:

getMaximumHostCount in interface IJobScheduler

Returns:

Maximum number of threads for the job scheduler.

Throws:

JobSchedulerException - If operation fails.

getAgentInfo

public final java.util.List<AgentSnapshot> getAgentInfo()
                                                 throws JobSchedulerException

Description copied from interface: IGetAgentInfo

Returns the list of agents and their current states. This method may block, especially if the data must be fetched from the coordinator.

Specified by:

getAgentInfo in interface IGetAgentInfo

Returns:

List of agent snapshots.

Throws:

JobSchedulerException - If there was a problem getting the agent info (e.g., the connection was lost).

getUserAuthorization

public final AuthorizationType getUserAuthorization()
                                             throws JobSchedulerException

Description copied from interface: IGetAuthorizationInfo

Determines whether the user is authorized for the job submission protocol. This method may block, especially if the data must be fetched from the coordinator.

Specified by:

getUserAuthorization in interface IGetAuthorizationInfo

Returns:

true if this user is authorized; else false.

Throws:

JobSchedulerException - If there was a problem getting the authorization info (e.g., the connection was lost)

getVersionInfo

public final VersionInfo getVersionInfo()
                                 throws JobSchedulerException

Description copied from interface: IGetVersionInfo

Gets the version info of the job scheduler. This method may block, especially if the data must be fetched from the coordinator.

Specified by:

getVersionInfo in interface IGetVersionInfo

Returns:

The version info.

Throws:

JobSchedulerException - If there was a problem getting the version info (e.g., the connection was lost).

postMessage

public final void postMessage(java.lang.Object message,
                              java.util.UUID target)
                       throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Posts a message to the specified target mailbox.

Specified by:

postMessage in interface IMessageEndpoint

Parameters:

message - The message.

target - The target.

Throws:

JobSchedulerException - If target mailbox does not exist.

postMessage

public final void postMessage(java.lang.Object message,
                              java.util.UUID target,
                              boolean quietlyFail)
                       throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Posts a message to the specified target mailbox.

Specified by:

postMessage in interface IMessageEndpoint

Parameters:

message - The message.

target - The target.

quietlyFail - If true will not throw an exception if target does not exist.

Throws:

JobSchedulerException - If target mailbox does not exist.

receiveMessage

public final java.lang.Object receiveMessage()
                                      throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Receives a message from the participant's mailbox. Blocks the current thread until a message arrives.

Specified by:

receiveMessage in interface IMessageEndpoint

Returns:

The message.

Throws:

JobSchedulerException - If target mailbox does not exist.

receiveMessage

public final java.lang.Object receiveMessage(int millisecondsTimeout)
                                      throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Receives a message from the participant's mailbox. Blocks the current thread until a message arrives

Specified by:

receiveMessage in interface IMessageEndpoint

Parameters:

millisecondsTimeout - The number of milliseconds to wait, or -1 to wait indefinitely.

Returns:

The message.null if timeout is elapsed.

Throws:

JobSchedulerException

receiveMessage

public final java.lang.Object receiveMessage(java.util.UUID[] sender)
                                      throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Receives a message from the participant's mailbox. Blocks the current thread until a message arrives.

Specified by:

receiveMessage in interface IMessageEndpoint

Parameters:

sender - The address of the sender of the message.

Returns:

The message.

Throws:

JobSchedulerException

receiveMessage

public final java.lang.Object receiveMessage(int millisecondsTimeout,
                                             java.util.UUID[] sender)
                                      throws JobSchedulerException

Description copied from interface: IMessageEndpoint

Receives a message from the participant's mailbox. Blocks the current thread until a message arrives

Specified by:

receiveMessage in interface IMessageEndpoint

Parameters:

millisecondsTimeout - The number of milliseconds to wait, or -1 to wait indefinitely.

sender - The address of the sender of the message.

Returns:

The message. null if timeout is elapsed.

Throws:

JobSchedulerException

getLicenseInfo

public final LicenseInfo getLicenseInfo(LicenseParameters licenseParameters)
                                 throws JobSchedulerException

Description copied from interface: IGetLicenseInfo

Gets the license info that matches the provided license parameters. This method may block, especially if the data must be fetched from the coordinator.

Specified by:

getLicenseInfo in interface IGetLicenseInfo

Parameters:

licenseParameters - The license parameters.

Returns:

License info.

Throws:

JobSchedulerException - If there was a problem getting the license info (e.g., the connection was lost).

connect

public final void connect()
                   throws JobSchedulerException

Connects client to specified cluster scheduler.

Call this method to establish a synchronous remote connection the coordinator specified at the host name (CoordinatorMachineName (get / set)), and port (CoordinatorPort (get / set)).

Specified by:

connect in interface IJobScheduler

Throws:

java.lang.IllegalStateException - The client is already connected.

JobSchedulerException - coordinator CoordinatorMachineName (get / set) is not specified, or coordinator could not be reached at hostname and port.

submitJob

public final void submitJob(Job job,
                            JobSubmitListener listener)
                     throws JobSchedulerException

Description copied from interface: IJobScheduler

Submits job to the job scheduler so that the job scheduler can add the job to it's queue.

Specified by:

submitJob in interface IJobScheduler

Parameters:

job - The job to be submitted.

Throws:

JobSchedulerException - If a task or task environment cannot be serialized.

createJob

public final Job createJob()
                    throws JobSchedulerException

Description copied from interface: IJobScheduler

Returns a new job that can later be used to submit to the job scheduler.

Specified by:

createJob in interface IJobScheduler

Returns:

Job that can be used to submit tasks to the job scheduler.

Throws:

JobSchedulerException - Thrown if client is not connected to the job scheduler yet.

disconnect

public final void disconnect()

Description copied from interface: IJobScheduler

Disconnects client from specified job scheduler.

Specified by:

disconnect in interface IJobScheduler

onCoordinatorDisconnected

public final void onCoordinatorDisconnected()
                                     throws JobSchedulerException

Called when the job scheduler connection with the coordinator is interrupted. Attempts to reestablish a connection with the coordinator until either a connection is obtained or the maximum number of attempts to reconnect has been reached.

Throws:

JobSchedulerException

waitUntilDone

public final boolean waitUntilDone(java.util.UUID jobId,
                                   int millisecondsTimeout,
                                   java.lang.Runnable heartbeatCallback,
                                   int millisecondsHeartbeat)
                            throws JobSchedulerException

Description copied from interface: IJobScheduler

Blocks until all tasks in this job complete or the operation times out. The callback passed in for the heartbeat is called with the period specified by the millisecondsHeartbeat argument.

Specified by:

waitUntilDone in interface IJobScheduler

Parameters:

jobId - The job id for the job to be submitted.

millisecondsTimeout - The timeout (in milliseconds).

heartbeatCallback - The heartbeat callback.

millisecondsHeartbeat - The heartbeat period (in milliseconds).

Returns:

true if job completed, false if timed-out.

Throws:

JobSchedulerException - Thrown if client disconnects from the job scheduler.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

close

public void close()

Description copied from interface: IJobScheduler

Closes this JobScheduler and releases any system resources associated with it.

Specified by:

close in interface IJobScheduler

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

dispose

@Deprecated
public final void dispose()

Deprecated. Please use close()

Specified by:

dispose in interface IJobScheduler