The Moab Java API is a Java library that allows Java developers to easily communicate with and interact with the Moab Workload Manager. The API handles the details of creating a secure connection, reporting information about workload and resources, and creating basic commands.
Throughout this guide there are simple examples on how to use the various classes. The full code for these examples is included in the API in the com.ace.moab.example package. Please review these files for more detailed information on the various classes.
Also, note that the client is the program that will use the Moab Java API.
This guide is intended to show how to begin using the Moab Java API for any Java based application. It assumes users have a basic knowledge of Moab and its commands. It is recommended that users consult other reference and tutorial resources for information about Moab and its use and purpose.
The communication process from the client's point of view can be simplified in the following 3-step process:
The purpose of this API is to simplify each of the three steps in this process.
Note: In the documentation, request and command may be used interchangeably when speaking about a request to the Moab server.
In this API, there are two types of supported connections to the Moab Workload Manager:
Both of the connection types implement the same interface that provides the necessary functions to communicate with Moab. All Moab queries require an IMoabConnection object to execute commands and return the results. Typically, there only needs to be one IMoabConnection per Java application.
The IMoabConnection object allows users to not only create a connection, but to also run commands over this connection. However, in most cases the client will rarely have to call the executeCommand method directly; this will be called by the various query commands explained in the next section.
As previously stated, the Moab API uses commands to communicate with the Moab Workload Manager, and it parses the server's response. The client runs any necessary command and gets the response through the MoabInputStream object. However, this API greatly simplifies the process of querying Moab using the various Query objects. These objects create the appropriate commands, sends them over the connection, parses the response from Moab, and returns to the caller the appropriate Java objects.
There are five basic job queries in this version of the API:
A job in Moab is represented in the API as a MoabJob object. For more information on these classes, please review the Java documentation under the JobQuery and MoabJob classes.
There are four node queries in this version of the API:
A node or server in Moab is represented in the API as a MoabNode object. For more information on these classes, please review the Java documentation under the NodeQuery and MoabNode classes.
There are three basic reservation queries in this version of the API:
A reservation in Moab is represented in the API as a Reservation object. Standing reservations (also known as reoccurring reservations) are represented as a StandingReservation object. For more information on these classes, please review the Java documentation under the ReservationQuery, Reservation, and StandingReservation classes.
There are two credential queries in this version of the API:
All credential types in Moab are represented in the API as a Credential object. This includes users, groups, accounts, classes, and quality of service (QoS) objects. For more information on these classes, please review the Java documentation under the CredentialQuery and Credential classes.
The Moab API not only enables Java clients to query Moab and parse the results, but it also allows clients the option to create simple Java objects and then use these objects to create identical objects in Moab. This greatly simplifies the process of submitting jobs and reservations as clients do not need to determine the Moab commands necessary to create objects inside Moab. Instead, clients create simple Java objects and then use the Request interface to get the commands necessary to create these same objects in Moab. For example, a client may create a MoabJob object with a command file, a node list, and certain credentials specified. Instead of determining the Moab commands necessary to duplicate this job's attributes for submission, the client can use the SubmitJobRequest object to retrieve the commands necessary to submit this job to Moab.
As of this version of the API, the two supported objects that use the Request interface are jobs and reservations. For jobs, clients should use SubmitJobRequest for job submission and ModifyJobRequest to modify an existing job in Moab. For reservations, clients may use the ModifyReservationRequest, CreateOneTimeRsvRequest, and CreateStandingRsvRequest objects.
The SubmitJobRequest object uses data from a MoabJob object to create a job submit command. Clients create a MoabJob object, populate this object with various attributes to be set at job submission, then use the Request interface to get the commands to submit the job. However, not all attributes inside the MoabJob object make sense for job submission. For example, a MoabJob contains an attribute called "suspendDuration" that represents the number of seconds a job is suspended. Obviously a user cannot submit a job with a suspend duration greater than 0 as this does not make sense. Likewise setting a job's state at submission doesn't make sense as Moab determines job state.
The following are supported attributes for the submit job request:
There are many ways to modify an existing Moab job. Other than the job attributes like account or wall time, jobs can be canceled, suspended, and re-queued. For a complete list of modification types, see the ModifyJobType enum.
The modify job request is like the submit job request: clients manipulate Java objects and then use these objects to create Moab commands necessary to cause these changes. Many of the job modifications only require one MoabJob object (such as cancel, resume, or checkpoint). However, to modify job attributes, two separate MoabJob objects must be created. The ModifyJobRequest class will then find the differences between these two objects and determine the Moab commands necessary to modify the first object to have the same attributes as the second.
Like the submit job request, many job attributes cannot be modified using this class. The following is a list of supported attributes for the modify job request:
In Moab, there are two types of reservations: (1) one-time reservations and (2) reoccurring (or standing) reservations. Because of the core differences between these reservation types, the Moab Java API has split these reservations into separate objects, Reservation and StandingReservation. The request classes used to create Moab commands for these objects are also different classes, but they are used the same way.
The attributes that can be set on a Reservation or StandingReservation object that will be used for reservation creation are listed below:
A valid reservation must have a host list expression specified or a positive number of tasks assigned to it. If task count is positive, the required task must be specified as well. Clients may verify a valid reservation before attempting to create the Moab commands by calling the verifyReservation method on the respective create reservation request object.
Modifying a reservation is very similar to the way clients may modify a job in Moab. The client passes two reservations into the ModifyReservationRequest object, the original and the reservation which contains the modifications. The request then compares the differences between the two reservations and creates Moab commands based on the differences between the reservations.
There are a limited number of attributes that can be modified after a reservation is created. The following is a list of supported attribute changes included in the API:
For more information, please review the Moab documentation about modifying reservation attributes.
All classes released in the API are either in the com.ace.moab.* package or the com.moab.* package. All classes and packages in the com.ace.* package structure are a standard part of the Moab Java API and will be supported in the future. All other packages outside of com.ace can change at any time without notice and are not officially supported. These classes are included in the API only because they provide some "behind the scenes" functionality for various methods. Clients that use these other packages must understand they are using code that may not be tested and may not function correctly. For these reasons, there is no documentation available for the com.moab.* classes.
The examples included in this guide are simplified versions of examples included in the com.ace.moab.example package. They will not necessarily compile "as is" and may require additional setup such as establishing an IMoabConnection or surrounding method calls in a try catch block. Please view the code examples included in the API for more details.