Moab Workload Manager
Home Up

Moab Java API Quick Start Guide

Introduction

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.

Requirements

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.

Basic Usage

The communication process from the client's point of view can be simplified in the following 3-step process:

  1. Client creates a secure connection to the Moab Workload Manager.
  2. Client queries Moab for system information such as jobs or reservations.
  3. Client may create commands to manipulate these objects or create new commands in Moab.

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.

Create a Connection to the Moab Workload Manager

In this API, there are two types of supported connections to the Moab Workload Manager:

  • Local connections for instances of Moab running on the local machine. (See LocalConnection.java for more information.)
  • SSH connections for instances of Moab running on any other host. (See SSHConnection.java for more information.)

    • 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.

    Example SSH Connection
    //Setup connection with the server called "myServer"
SSHConnection connection = new SSHConnection("myServer", 22);
//Attempt to connected with user bob. Returns true if successful.
boolean result = connection.connectWithPassword("bob", password);

    Querying Moab

    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.

    Job Queries (JobQuery.java)

    There are five basic job queries in this version of the API:

    • getActiveJobs: Returns a list of all the jobs currently active—not completed.
    • getCompletedJobs: Returns all completed jobs still left in Moab's completed job buffer.
    • getCompleteJobSummary: Gets the job summary information for all users from Moab.
    • getSpecificJob: Gets a specific job from Moab.
    • getUserJobSummary: Gets the job summary information for a certain user.

    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.

    Node (or Server) Queries (NodeQuery.java)

    There are four node queries in this version of the API:

    • getAllNodes: Returns all nodes reported to Moab.
    • getUserSpecificNodes: Returns all the nodes to which the given user has access.
    • getSpecificNode: Gets a specific node from Moab.
    • getNodeSummary: Returns a node summary either for all nodes or just the nodes accessible by a specified user.

    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.

    Reservation Queries (ReservationQuery.java)

    There are three basic reservation queries in this version of the API:

    • GetReservationByName: Returns the reservation corresponding to a specific reservation ID.
    • getAllReservations: Queries Moab for all of the reservations in the system.
    • getStandingReservations: Returns a list of all standing reservations in Moab.

    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.

    Credential Queries (CredentialQuery.java)

    There are two credential queries in this version of the API:

    • getAllCredentialsOfType: Returns a list of all credentials of a given type (such as user or account).
    • getAllCredentials: Returns a list of all standard credentials that this user can see.

    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.

    Sending Requests to Modify or Create Objects in Moab

    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.

    Submit Job Request (SubmitJobRequest.java)

    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:

    • Generic resources: type,quantity, and (optionally) the time frame
    • Job dependencies
    • Specified credentials (such as Account or QoS requested)
    • Email notifications
    • File operations (such as specifying the stdout file)
    • Host list
    • Job flags
    • Job requirements including:
      • Processors per task
      • Node features (both required and preferred)
      • Operating system
      • Architecture
      • Node memory
      • Node swap space
      • Partition
      • Required reservation
    • Job name
    • Initial working directory
    • User priority
    • Template list
    • Requested wall time
    • Earliest start date requested

    Example Submit Job Request
    //Create the job as a Java object
MoabJob job = new MoabJob();
		
//Set the various attributes for the Job upon submission
job.setJobName("myFirstJob");
job.setCommandFile("/path/to/command/file");
job.setAccount("Engineering");
job.setWallclockRequested(18000); //Job should run for 5 hours
job.setNodeCountRequested(15);
	
SubmitJobRequest request = new SubmitJobRequest(job);

List<String> moabCommands = request.getMoabCommands();
//Execute moabCommands
...

    Modify Job Request (ModifyJobRequest.java)

    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.

    Example Modify Job Request
    //Load the job from Moab
MoabJob newJob = JobQuery.getSpecificJob(...);
MoabJob oldJob = JobQuery.getSpecificJob(...);

newJob.setNodeCountRequested(10); //Set a different node count here

ModifyJobRequest request = new ModifyJobRequest(originalJob, newJob, 
	ModifyJobType.JOB_ATTRIBUTES,moabConnection);

List<String> moabCommands = request.getMoabCommands();
//The moabCommands now contains the command to modify the node count to 10.

    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:

    • Job holds
    • Credential changes (such as Account or QoS)
    • Job name
    • Adding messages (but not removing messages)
    • Requested node count
    • System priority
    • Requested reservation
    • The job's partition access list
    • Variables
    • Requested wall time

    Create Reservation Request (CreateOneTimeRsvRequest.java, CreateStandingRsvRequest.java)

    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:

    • All reservation requirements including
      • Task specification (and task count)
      • Architecture
      • Any node features
      • Network
      • Operating system
      • Node count
      • Host list
    • Reservation owner
    • The DEDICATEDRESOURCE flag
    • Partition
    • Start and end dates
    • Trigger list
    • Host list expression
    • An access control list (ACL)

    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.

    Modify Reservation Request (ModifyReservationRequest.java)

    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:

    • Reservation duration
    • Start time
    • End time
    • Any flags set (including the ability to unset flags)
    • Host list expression

    For more information, please review the Moab documentation about modifying reservation attributes.

    Example Modify Job Request
    //Load the reservation from Moab
Reservation originalRsv = ReservationQuery.getReservationByName(...);
Reservation modifiedRsv = ReservationQuery.getReservationByName(...);
		
//Change the flags and the start date
ReservationFlags flags = modifiedRsv.getFlags();
flags.removeAll();
flags.addFlag(ReservationFlag.ADVRES);
flags.addFlag(ReservationFlag.ALLOWPRSV);
		
modifiedRsv.setStartDate(new Date(modifiedRsv.getStartDate().getTime() + 360000));

//Create the modification request and get the commands
ModifyReservationRequest request = new ModifyReservationRequest(originalRsv, modifiedRsv);
List<String> moabCommands = request.getMoabCommands();

    Additional Notes

    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.

    Home Up