org.gridlab.gat.resources
Interface ResourceBroker

public interface ResourceBroker

An instance of this class is used to submit Jobs or to reserve Resources. A ResourceBroker can be created using the factory methods of the GAT object (for instance GAT.createResourceBroker(gatContext, preferences, brokerURI)). Each ResourceBroker has a location which can be expressed using a URI. This URI should be passed to the factory method.

First of all, the ResourceBroker can be used to submit Jobs. A Job is described by a JobDescription. Using the one of the submitJob methods of the ResourceBroker, one can create a Job out of the JobDescription.

The ResourceBroker can also be used to reserve Resources. A Resource can either be a HardwareResource or a SoftwareResource. A SoftwareResource is simply an executable, therefore it makes little sense to reserve such. Thus, an instance of this class can currently only reserve a hardware resource.

If one wishes to reserve a HardwareResource, one must first describe it. This is accomplished by creating an instance of the class HardwareResourceDescription. After creating such an instance, one must specify the time period for which one wishes to reserve the HardwareResource. This is accomplished by creating an instance of the class TimePeriod, which specifies the time period for which one wishes to reserve the HardwareResource. Finally, one must obtain a reservation for the desired HardwareResource for the desired TimePeriod. This is accomplished by calling the method reserveHardwareResource() on an instance of the class ResourceBroker with the appropriate instance of HardwareResourceDescription and the appropriate instance of TimePeriod.

In addition, an instance of this class can be used to find HardwareResources. This is accomplished by creating an instance of the class HardwareResourceDescription which describes the HardwareResource that one wishes to find. After creating such an instance, one must find the corresponding HardwareResource. This is accomplished by calling the method findHardwareResources() on an instance of the class ResourceBroker with the appropriate instance of HardwareResourceDescription.

Method Summary

List<HardwareResource>	findResources(ResourceDescription resourceDescription) This method attempts to find one or more matching HardwareResources.
Reservation	reserveResource(ResourceDescription resourceDescription, TimePeriod timePeriod) This method attempts to reserve the specified Resource for the specified TimePeriod.
Reservation	reserveResource(Resource resource, TimePeriod timePeriod) This method attempts to reserve the specified Resource for the specified TimePeriod.
Job	submitJob(AbstractJobDescription description) This operation takes a JobDescription, and submits the specified job to some underlying resource management or allocation system.
Job	submitJob(AbstractJobDescription description, MetricListener listener, String metricDefinitionName) This operation takes a JobDescription, and submits the specified job to some underlying resource management or allocation system.

Method Detail

reserveResource

Reservation reserveResource(ResourceDescription resourceDescription,
                            TimePeriod timePeriod)
                            throws GATInvocationException

This method attempts to reserve the specified Resource for the specified TimePeriod. Upon reserving the specified Resource this method returns a Reservation. Upon failing to reserve the specified resource this method returns an error.

Parameters:

resourceDescription - A description, a ResourceDescription, of the HardwareResource to reserve

timePeriod - The time period, a TimePeriod, for which to reserve the HardwareResource

Returns:

the Reservation object that describes the reserved Resource

Throws:

GATInvocationException - a remote problem occurred

reserveResource

Reservation reserveResource(Resource resource,
                            TimePeriod timePeriod)
                            throws GATInvocationException

This method attempts to reserve the specified Resource for the specified TimePeriod. Upon reserving the specified Resource this method returns a Reservation. Upon failing to reserve the specified resource this method returns an error.

Parameters:

resource - The Resource to reserve.

timePeriod - The time period, a TimePeriod, for which to reserve the HardwareResource

Returns:

the Reservation object that describes the reserved Resource

Throws:

GATInvocationException - Thrown upon problems accessing the remote instance

GATInvocationException - a remote problem occurred

findResources

List<HardwareResource> findResources(ResourceDescription resourceDescription)
                                     throws GATInvocationException

This method attempts to find one or more matching HardwareResources. Upon finding the specified HardwareResource(s) this method returns a List of HardwareResource instances. Upon failing to find the specified HardwareResource this method returns an error.

Parameters:

resourceDescription - A description, a ResourceDescription, of the Resource(s) to find

Returns:

List of Resources upon success

Throws:

GATInvocationException - Thrown upon problems accessing the remote instance

submitJob

Job submitJob(AbstractJobDescription description)
              throws GATInvocationException

This operation takes a JobDescription, and submits the specified job to some underlying resource management or allocation system. On success, a Job instance is returned, which represents the job. Upon failing to submit the job, an exception is issued.

In former releases some resource broker adaptors would check the "resourcebroker.jobmanager" property to see to which jobmanager (e.g., fork, pbs, condor) should be used. This has been deprecated. Use the brokerURI which you have to set while creating the ResourceBroker instead.

Parameters:

description - The job description (JobDescription).

Returns:

a Job object that is a handle to the task that was submitted

Throws:

GATInvocationException - a remote problem occurred

submitJob

Job submitJob(AbstractJobDescription description,
              MetricListener listener,
              String metricDefinitionName)
              throws GATInvocationException

This operation takes a JobDescription, and submits the specified job to some underlying resource management or allocation system. On success, a Job instance is returned, which represents the job. Upon failing to submit the job, an exception is issued. The MetricListener listening to the Metric defined by the metricDefinitionName is attached to the Job as soon as it is created. This has the big advantage that Metrics that are fired during the submitJob can be caught in the provided listener.

If one, for instance, would like to listen to the state of a Job, using the "job.status" metricDefinitionName, during the submitJob the Metric containing the state PRE_STAGING will be fired. This state can only be caught in the listener, if the listener is directly provided with the submitJob invocation.

In former releases some resource broker adaptors would check the "resourcebroker.jobmanager" preference to see to which jobmanager (e.g., fork, pbs, condor) should be used. This has been deprecated. Use the brokerURI which you have to set while creating the ResourceBroker instead.

Parameters:

description - The job description.

listener - A metric listener that listens to the returned job

metricDefinitionName - The name of the metric the listener listens to

Returns:

a job object that is a handle to the task that was submitted

Throws:

GATInvocationException - a remote problem occurred