# Distributed Resource Management Application API

This guide is a tutorial for getting started programming with the DRMAA JavaTMsup> language binding. It assumes that you already know what DRMAA is and know how to find and install the Grid Engine 6.0u2 release. If you do not already know these things, try these web sites:

- The DRMAA Website
- The Grid Engine 6.0 DRMAA Java language binding JavaDocs
- The Grid Engine 6.0 DRMAA Java language binding README
- The Grid Engine 6.0 DRMAA C binding README
- The Grid Engine libdrmaa docs
- The Grid Engine libjapi docs

Note that the example programs in this howto can be found in the CVS source tree.

## Starting and Stopping a Session

The following code segment shows the most basic DRMAA Java language binding program:

### Example 1

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto1 {
    06:    public static void main (String[] args) {
    07:       SessionFactory factory = SessionFactory.getFactory ();
    08:       Session session = factory.getSession ();
    09:
    10:       try {
    11:          session.init (null);
    12:          session.exit ();
    13:       }
    14:       catch (DrmaaException e) {
    15:          System.out.println ("Error: " + e.getMessage ());
    16:       }
    17:    }
    18: }

Everything that you as a programmer will do with DRMAA, you will do through a Session object. You will get the Session object from a SessionFactory. You will get the SessionFactory from the static SessionFactory.getFactory() method. The reason for this chain is that the org.ggf.drmaa.* classes should be considered an immutable package to be used by every DRMAA Java language binding implementation. Because the package is immutable, to load a specific implementation, the SessionFactory uses a system property to find the implementation's session factory, which it then loads. That session factory is then responsible for creating the session in whatever why it sees fit. Without the session factory, the Session would have to do that work, and the implementation-defined session object would have to be instantiated with some predefined constructor signature. With the session factory, the implementation is free to define for itself how the session object will be instatiated. It should be noted that even though there is a session factory, only one session may exist at a time.

Now let's look at the code. First, on line 7, we get a session factory instance with SessionFactory.getFactory(), and on line 8 we get the session instance with SessionFactory.getSession(). Once we have the session, we can initialize it on line 11 by calling Session.init(). We pass in `null` as the contact string because the C binding upon which the Java language binding is built ignores the contact string altogether. The plan is that at some point in the future the contact string will be a combination of $SGE_ROOT and $SGE_CELL.

Session.init() creates a session and starts an event client listener thread. The session is used for organizing jobs submitted through DRMAA, and the thread is used to receive updates from the queue master about the state of jobs and the system in general. Once Session.init() has been called successfully, it is the responsibility of the calling application to also call Session.exit() before terminating. If an application does not call Session.exit() before terminating, session state may be left behind in the user's home directory (under .sge/drmaa), and the queue master may be left with a dead event client handle, which can decrease queue master performance. I recommend using the Runtime.addShutdownHook () method to make sure Session.exit() gets called.

At the end of our program, on line 12, we call Session.exit(). Session.exit() cleans up the session and stops the event client listener thread. Most other DRMAA methods must be called before Session.exit(). Some functions, like Session.getContact(), can be called after exit(), but these functions only provide general information. Any function that does work, such as Session.runJob() or Session.wait() must be called before Session.exit() is called. If such a function is called after exit() is called, it will throw a NoActiveSessionException.

## Running a Job

The following code segment shows how to use the DRMAA Java language binding to submit a job to Grid Engine:

### Example 2

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto2 {
    06:    public static void main (String[] args) {
    07:       SessionFactory factory = SessionFactory.getFactory ();
    08:       Session session = factory.getSession ();
    09:
    10:       try {
    11:          session.init (null);
    12:          JobTemplate jt = session.createJobTemplate ();
    13:          jt.setRemoteCommand ("sleeper.sh");
    14:          jt.setArgs (new String[] {"5"});
    15:
    16:          String id = session.runJob (jt);
    17:
    18:          System.out.println ("Your job has been submitted with id " + id);
    19:
    20:          session.deleteJobTemplate (jt);
    21:          session.exit ();
    22:       }
    23:       catch (DrmaaException e) {
    24:          System.out.println ("Error: " + e.getMessage ());
    25:       }
    26:    }
    27: }

The beginning and end of this program are the same as the previous one. What's different is in lines 12-20. On line 12 we ask DRMAA to allocate a JobTemplate for us. A JobTemplate is an Object used to store information about a job to be submitted. The same template can be reused for multiple calls to Session.runJob() or Session.runBulkJobs().

On line 13 we set the remoteCommand attribute. This attribute tells DRMAA where to find the program we want to run. Its value is the path to the executable. The path be be either relative or absolute. If relative, it is relative to the workingDirectory attribute, which if not set defaults to the user's home directory. For more information on DRMAA attributes, please see the drmaa_attributes man page. Note that for this program to work, the script "sleeper.sh" must be in your default path, i.e. the path set by your shell script when you log in.

On line 14 we set the args attribute. This attribute tells DRMAA what arguments to pass to the executable. For more information on DRMAA attributes, please see the drmaa_attributes man page.

On line 16 we submit the job with Session.runJob(). This method will return the id assigned to the job by the queue master. The job is now running as though submitted by qsub. At this point calling Session.exit() and/or terminating the program will have no effect on the job.

To clean things up, we delete the job template on line 20. This frees the memory DRMAA set aside for the job template, but has no effect on submitted jobs.

If instead of a single job we had wanted to submit an array job, we could have replaced the code on lines 16-18 with the following:

### Example 2.1

    16: java.util.List ids = session.runBulkJobs (jt, 1, 30, 2);
    17: java.util.Iterator i = ids.iterator ();
    18:
    19: while (i.hasNext ()) {
    20:    System.out.println ("Your job has been submitted with id " + i.next ());
    21: }

This code segment submits an array job with 15 tasks numbered 1, 3, 5, 7, etc. An important difference to note is that Session.runBulkJobs() returns the job ids in a java.util.List. On line 17 we get an Iterator for the list and loop through, printing each submitted job's id, on lines 19-21.

## Waiting for a Job

Now we're going to extend our example to include waiting for a job to finish.

### Example 3

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import java.util.*;
    04:
    05: import org.ggf.drmaa.*;
    06:
    07: public class Howto3 {
    08:    public static void main (String[] args) {
    09:       SessionFactory factory = SessionFactory.getFactory ();
    10:       Session session = factory.getSession ();
    11:
    12:       try {
    13:          session.init (null);
    14:          JobTemplate jt = session.createJobTemplate ();
    15:          jt.setRemoteCommand ("sleeper.sh");
    16:          jt.setArgs (new String[] {"5"});
    17:
    18:          String id = session.runJob (jt);
    19:
    20:          System.out.println ("Your job has been submitted with id " + id);
    21:
    22:          session.deleteJobTemplate (jt);
    23:
    24:          JobInfo info = session.wait (id, Session.TIMEOUT_WAIT_FOREVER);
    25:
    26:          if (info.wasAborted ()) {
    27:             System.out.println("Job " + info.getJobId () + " never ran");
    28:          }
    29:          else if (info.hasExited ()) {
    30:             System.out.println("Job " + info.getJobId () +
    31:                                " finished regularly with exit status " +
    32:                                info.getExitStatus ());
    33:          }
    34:          else if (info.hasSignaled ()) {
    35:             System.out.println("Job " + info.getJobId () +
    36:                                " finished due to signal " +
    37:                                info.getTerminatingSignal ());
    38:          }
    39:          else {
    40:             System.out.println("Job " + info.getJobId () +
    41:                                " finished with unclear conditions");
    42:          }
    43:
    44:          System.out.println ("Job Usage:");
    45:
    46:          Map rmap = info.getResourceUsage ();
    47:          Iterator i = rmap.keySet ().iterator ();
    48:
    49:          while (i.hasNext ()) {
    50:             String name = (String)i.next ();
    51:             String value = (String)rmap.get (name);
    52:
    53:             System.out.println("  " + name + "=" + value);
    54:          }
    55:
    56:          session.exit ();
    57:       }
    58:       catch (DrmaaException e) {
    59:          System.out.println ("Error: " + e.getMessage ());
    60:       }
    61:    }
    62: }

This example is very similar to Example 2 except for lines 24-54. (The line numbers are shifted from Example 2 because of the additional import statement for java.util.*.) On line 24 we call Session.wait() to wait for the job to end. We have to give Session.wait() both the id of the job for which we want to wait and how long we are willing to wait for the job to finish. The later could be a number of seconds, or it could be either `Session.DRMAA_TIMEOUT_WAIT_FOREVER` or `Session.DRMAA_TIMEOUT_NO_WAIT`. Session.wait() returns a JobInfo object, which contains useful information how the job exited and how much resources it used. The JobInfo object also contains the id of the job for which we actually waited because the job id we pass in could be `Session.DRMAA_JOB_IDS_SESSION_ANY`, in which case Session.wait() must have a way of tell us which job is the one that made it return.

Assuming the wait worked, we query the job's exit status on lines 26-42 using the JobInfo accessor methods. This if structure is a common usage pattern for Session.wait() and should be encapsulated in a method for ease of use.

After checking the exit status, we query the job's usage on lines 44-54. We use JobInfo.getResourceUsage() to get a Map of the resources consumed and print out the results.

An alternative to Session.wait() when working with multiple jobs, such as jobs submitted by Session.runBulkJobs() or multiple calls to Session.runJob() is Session.synchronize(). Session.synchronize() waits for a List of jobs to finish. To use Session.synchronize(), we could replace lines 18-54 with the following:

### Example 3.1

    18: List ids = session.runBulkJobs (jt, 1, 30, 2);
    19: Iterator i = ids.iterator ();
    20:
    21: while (i.hasNext ()) {
    22:    System.out.println ("Your job has been submitted with id " + i.next ());
    23: }
    24:
    25: session.deleteJobTemplate (jt);
    26: session.synchronize (Collections.singletonList (Session.JOB_IDS_SESSION_ALL),
    27:                      Session.TIMEOUT_WAIT_FOREVER, true);
    28:
    29: System.out.println ("All jobs have finished.");

### Example 3.1

Lines 18-23 now call Session.runBulkJobs() so that we have several jobs for which to wait. On line 26, instead of calling Session.wait(), we call Session.synchronize(). Session.synchronize() takes only three parameters. The first is the List of ids for which to wait. If the special id, `Session.DRMAA_JOB_IDS_SESSION_ALL`, appears in the List, Session.synchronize() will wait for all jobs submitted via DRMAA during this session, i.e. since Session.init() was called. The second parameter is how long to wait for all the jobs in the list to finish. This is the same as the timeout parameter for Session.wait(). The third parameter is whether this call to Session.synchronize() should clean up after the job. After a job completes, it leaves behind accounting information, such as exist status and usage, until either Session.wait() or Session.synchronize() with dispose set to `true` is called. It is the responsibility of the application to make sure one of these two functions is called for every job. Not doing so creates a memory leak. Note that calling Session.synchronize() with dispose set to `true` flushes all accounting information for all jobs in the list. If you want to use Session.synchronize() and still recover the accounting information, set dispose to `false` and call Session.wait() for each job. To do this in Example 3, we would replace lines 18-54 with the following:

### Example 3.2

    18: int start = 1;
    19: int end  = 30;
    20: int step = 2;
    21:
    22: List ids = session.runBulkJobs (jt, start, end, step);
    23: Iterator i = ids.iterator ();
    24:
    25: while (i.hasNext ()) {
    26:    System.out.println ("Your job has been submitted with id " + i.next ());
    27: }
    28:
    29: session.deleteJobTemplate (jt);
    30: session.synchronize (Collections.singletonList (Session.JOB_IDS_SESSION_ALL),
    31:                      Session.TIMEOUT_WAIT_FOREVER, false);
    32:
    33: for (int count = start; count < end; count += step) {
    34:    JobInfo info = session.wait (Session.JOB_IDS_SESSION_ANY,
    35:                                 Session.TIMEOUT_WAIT_FOREVER);
    36:
    37:    if (info.wasAborted ()) {
    38:       System.out.println("Job " + info.getJobId () + " never ran");
    39:    }
    40:    else if (info.hasExited ()) {
    41:       System.out.println("Job " + info.getJobId () +
    42:                          " finished regularly with exit status " +
    43:                          info.getExitStatus ());
    44:    }
    45:    else if (info.hasSignaled ()) {
    46:       System.out.println("Job " + info.getJobId () +
    47:                          " finished due to signal " +
    48:                          info.getTerminatingSignal ());
    49:    }
    50:    else {
    51:       System.out.println("Job " + info.getJobId () +
    52:                          " finished with unclear conditions");
    53:    }
    54:
    55:    System.out.println ("Job Usage:");
    56:
    57:    Map rmap = info.getResourceUsage ();
    58:    Iterator r = rmap.keySet ().iterator ();
    59:
    60:    while (r.hasNext ()) {
    61:       String name = (String)r.next ();
    62:       String value = (String)rmap.get (name);
    63:
    64:       System.out.println("  " + name + "=" + value);
    65:    }
    66: }

What's different is that on line 30, we set dispose to false, and then on lines 33-66 we wait once for each job, printing the exit status and usage information as we did in Example 3. We pass `Session.DRMAA_JOB_IDS_SESSION_ANY` to Session.wait() as the job id because we already know that all the jobs have finished, so we don't really care in what order we process them. In an interactive system where we couldn't guarantee that more jobs wouldn't be submitted between the synchronize and the wait, we would have to store the job ids from the Session.runBulkJobs() in an array and then wait for each job specifically. Otherwise, the Session.wait() could end up waiting for a job submitted after the call to Session.synchronize().

## Controling a Job

Now let's look at an example of how to control a job from DRMAA:

### Example 4

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto4 {
    06:    public static void main (String[] args) {
    07:       SessionFactory factory = SessionFactory.getFactory ();
    08:       Session session = factory.getSession ();
    09:
    10:       try {
    11:          session.init (null);
    12:          JobTemplate jt = session.createJobTemplate ();
    13:          jt.setRemoteCommand ("sleeper.sh");
    14:          jt.setArgs (new String[] {"5"});
    15:
    16:          String id = session.runJob (jt);
    17:
    18:          System.out.println ("Your job has been submitted with id " + id);
    19:
    20:          session.control (id, Session.TERMINATE);
    21:
    22:          System.out.println("Your job has been deleted");
    23:
    24:          session.deleteJobTemplate (jt);
    25:          session.exit ();
    26:       }
    27:       catch (DrmaaException e) {
    28:          System.out.println ("Error: " + e.getMessage ());
    29:       }
    30:    }
    31: }

This example is very similar to Example 2 except for lines 20-22. On line 20 we use Session.control() to delete the job we just submitted. Aside from deleting the job, we could have also used Session.control() to suspend, resume, hold, or release it. For more information, see the drmaa_control man page.

Note that Session.control() can be used to control jobs not submitted through DRMAA. Any valid SGE job id could be passed to Session.control() as the id of the job to delete.

## Getting Job Status

Here's an example of using DRMAA to query the status of a job:

### Example 5

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto5 {
    06:    public static void main (String[] args) {
    07:       SessionFactory factory = SessionFactory.getFactory ();
    08:       Session session = factory.getSession ();
    09:
    10:       try {
    11:          session.init (null);
    12:          JobTemplate jt = session.createJobTemplate ();
    13:          jt.setRemoteCommand ("sleeper.sh");
    14:          jt.setArgs (new String[] {"5"});
    15:
    16:          String id = session.runJob (jt);
    17:
    18:          System.out.println ("Your job has been submitted with id " + id);
    19:
    20:          try {
    21:             Thread.sleep (20 * 1000);
    22:          }
    23:          catch (InterruptedException e) {
    24:             // Don't care
    25:          }
    26:
    27:          int status = session.getJobProgramStatus (id);
    28:
    29:          switch (status) {
    30:             case Session.UNDETERMINED:
    31:                System.out.println ("Job status cannot be determined\n");
    32:                break;
    33:             case Session.QUEUED_ACTIVE:
    34:                System.out.println ("Job is queued and active\n");
    35:                break;
    36:             case Session.SYSTEM_ON_HOLD:
    37:                System.out.println ("Job is queued and in system hold\n");
    38:                break;
    39:             case Session.USER_ON_HOLD:
    40:                System.out.println ("Job is queued and in user hold\n");
    41:                break;
    42:             case Session.USER_SYSTEM_ON_HOLD:
    43:                System.out.println ("Job is queued and in user and system hold\n");
    44:                break;
    45:             case Session.RUNNING:
    46:                System.out.println ("Job is running\n");
    47:                break;
    48:             case Session.SYSTEM_SUSPENDED:
    49:                System.out.println ("Job is system suspended\n");
    50:                break;
    51:             case Session.USER_SUSPENDED:
    52:                System.out.println ("Job is user suspended\n");
    53:                break;
    54:             case Session.USER_SYSTEM_SUSPENDED:
    55:                System.out.println ("Job is user and system suspended\n");
    56:                break;
    57:             case Session.DONE:
    58:                System.out.println ("Job finished normally\n");
    59:                break;
    60:             case Session.FAILED:
    61:                System.out.println ("Job finished, but failed\n");
    62:                break;
    63:          } /* switch */
    64:
    65:          session.deleteJobTemplate (jt);
    66:          session.exit ();
    67:       }
    68:       catch (DrmaaException e) {
    69:          System.out.println ("Error: " + e.getMessage ());
    70:       }
    71:    }
    72: }

Again, this example is very similar to Example 2, this time with the exception of lines 20-63. First, after submitting the job, we sleep for 20 seconds to give SGE time to schedule the job. Then, on line 27, we use Session.getJobProgramStatus() to get the status of the job. Lines 29-63 determine what the job status is and report it. This switch is a common usage pattern for Session.getJobProgramStatus() and should be encapsulated in a method for ease of use.

## Getting DRM Information

Next, let's look at how to query the DRMAA library for information about the DRMS and the DRMAA implementation itself:

### Example 6

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto6 {
    06:    public static void main (String[] args) {
    07:       SessionFactory factory = SessionFactory.getFactory ();
    08:       Session session = factory.getSession ();
    09:
    10:       try {
    11:          System.out.println ("Supported contact strings: \"" +
    12:                              session.getContact () + "\"");
    13:          System.out.println ("Supported DRM systems: \"" +
    14:                              session.getDrmSystem () + "\"");
    15:          System.out.println ("Supported DRMAA implementations: \"" +
    16:                              session.getDrmaaImplementation () + "\"");
    17:
    18:          session.init (null);
    19:
    20:          System.out.println ("Using contact strings: \"" +
    21:                              session.getContact () + "\"");
    22:          System.out.println ("Using DRM systems: \"" +
    23:                              session.getDrmSystem () + "\"");
    24:          System.out.println ("Using DRMAA implementations: \"" +
    25:                              session.getDrmaaImplementation () + "\"");
    26:
    27:          Session.Version version = session.getVersion ();
    28:
    29:          System.out.println("Using DRMAA version " + version.toString ());
    30:
    31:          session.exit ();
    32:       }
    33:       catch (DrmaaException e) {
    34:          System.out.println ("Error: " + e.getMessage ());
    35:       }
    36:    }
    37: }

On line 11, we print the contact string list. This is the list of contact strings that will be understood by this DRMAA instance. Normally one of these strings is used to select to which DRM this DRMAA instance should be bound. In the Grid Engine 6.0u2 implementation, the contact string list is empty because there is only ever one possible DRM to which to bind.

On line 13, we print the list of supported DRM systems. For the Grid Engine 6.0u2 implementation, this will always be Grid Engine 6.0u2.

On line 15, we print the list of supported DRMAA implementations. For the Grid Engine 6.0u2 implementation, this will always be Grid Engine 6.0u2.

On line 18, we call Session.init(). After Session.init() has been called, the Session.getContact(), Session.getDrmSystem(), and Session.getDrmaaImplementation() calls change.

On line 20, we call Session.getContact() again, this time to get the contact string that was used to bind to a DRMS in Session.init(). For the Grid Engine 6.0u2 implementation, this will always be an empty string.

On line 22, we call Session.getDrmSystem() again, this time to get the name of the DRMS to which DRMAA is bound. For the Grid Engine 6.0u2 implementation, this will always be Grid Engine 6.0u2.

On line 24, we call Session.getDrmaaImplementation() again, this time to get the name of the DRMAA implementation to which the application is bound. For the Grid Engine 6.0u2 implementation, this will always be Grid Engine 6.0u2.

On line 29, we get the version number of the DRMAA Java language binding specification supported by this DRMAA implementation. For the Grid Engine 6.0u2 implementation this is currently version 0.5.

Finally, on line 31, we end the session with drmaa_exit().

## Using the New Utility Classes

The JobTemplate class uses two new classes to represent some of its property types. They are FileTransferMode and PartialTimestamp. The PartialTimestampFormat is used to print a PartialTimestamp. The Session interface uses the Version class to represent version information.

### FileTransferMode

The FileTransferMode class is a simple container which holds the state of three boolean properties: errorStream, inputStream, and outputStream. Each property indicated whether the given stream should be used for file transfers. When a given property is true, the corresponding path property is taken to represent the source or destination for the file transfer. For example, if the errorStream property of the active FileTransferMode object is true, the errorPath property of the JobTemplate object is treated as the destination to which to copy the resulting error output.

### PartialTimestamp

The PartialTimestamp class is used to represent incomplete time specifications, e.g. "1:00" as opposed to "2005/01/05 01:00". Such partial time specifications will be resolved to the soonest time which is still in the future. For example, before 1:00, "1:00" will be resolved to 1:00 on that same day. After 1:00, it will be resolved to 1:00 on the next day. The PartialTimestamp class is a subclass of java.util.Calendar and behaves as much like java.util.GregorianCalendar as possible, with the exception of allowing incomplete time specifications.

The PartialTimestamp class has one other new feature not present in the java.util.Calendar class, field modifiers. Since it may be desirable to appy a modifier to a field which is not yet set, the PartialTimestamp class allows for field modifiers to be kept separately from field values. If a modifier is applied to a set field, that modifier is ultimately added to the field's value. If a modifier is applied to an unset field, the modifier is added to the field's value at the time it is resolved. For example, if a PartialTimestamp object has HOUR_OF_DAY=1 and MINUTE=0 and a +1 modifier to the DAY_OF_MONTH field, and the PartialTimestamp object is resolved at 0:55 on a Tuesday, the result will be 1:00 on the following Wednesday. If the same PartialTimestamp object were resolved at 1:01 on a Tuesday, the result would be 1:00 on the following Thursday.

For a PartialTimestamp object, there are primary fields and secondary fields. The primary fields are actually used by DRMAA and the PartialTimestampFormat class. The secondary fields are used only to calculate the unset primary fields. The primary fields are CENTURY, YEAR, MONTH, DAY_OF_MONTH/DATE, HOUR_OF_DAY, MINUTE, SECOND, and ZONE_OFFSET. The secondary fields are DAY_OF_WEEK, DAY_OF_YEAR, DAY_OF_WEEK_IN_MONTH, WEEK_OF_MONTH, and WEEK_OF_YEAR. The MILLISECOND field is neither primary nor secondary because it outside of the scope of the DRMAA time stamp format specification, and hence is largely ignored.

### PartialTimestampFormat

To convert a PartialTimestamp object to or from a String, one should use a PartialTimestampFormat object. The parse() method converts a String into a PartialTimestamp object, and the format() method convers a PartialTimestamp object into a String. In order for the PartialTimestampFormat class to properly do the conversions, the no field of a lower order than the highest order set field may be unset. For example, if the DAY_OF_WEEK field is set, the HOUR_OF_DAY and MINUTE fields must also be set. (These two field are actually required in all cases.) If the MONTH field is set, the DAY_OF_MONTH, HOUR_OF_DAY, and MINUTE fields must be set. If the CENTURY field is set, the YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, and MINUTE fields must be set. If the MILLISECOND field is set, the HOUR_OF_DAY, MINUTE, and SECOND fields must be set. The SECOND and ZONE_OFFSET fields are always optional. The same applies for strings to be parsed.

Since the PartialTimestamp class is somewhat complicated, let's look at an example:

### Example 7

    01: package com.sun.grid.drmaa.howto;
    02:
    03: import org.ggf.drmaa.*;
    04:
    05: public class Howto7 {
    06:    public static void main (String[] args) {
    07:       try {
    08:          PartialTimestamp date = new PartialTimestamp ();
    09:          PartialTimestampFormat format = new PartialTimestampFormat ();
    10:
    11:          date.set (PartialTimestamp.HOUR_OF_DAY, 13);
    12:          date.set (PartialTimestamp.MINUTE, 0);
    13:
    14:          System.out.println (format.format (date));
    15:
    16:          date.setModifier (PartialTimestamp.DAY_OF_MONTH, 1);
    17:
    18:          System.out.println (format.format (date));
    19:          System.out.println (date.getTime ().toString ());
    20:
    21:          date.setTimeInMillis (System.currentTimeMillis ());
    22:
    23:          System.out.println (format.format (date));
    24:
    25:          date = format.parse ("01/05 14:07:29");
    26:
    27:          System.out.println (format.format (date));
    28:       }
    29:       catch (java.text.ParseException e) {
    30:          System.out.println ("Error: " + e.getMessage ());
    31:       }
    32:    }
    33: }

Since the PartialTimestamp class is useable outside of a DRMAA session, this example does not create a SessionFactory or Session instance.

On line 8, we create a PartialTimestamp with no fields set. Other constructors could be used to create a PartialTimestamp object with various fields already set. See the JavaDocs for more details.

On line 9, we create a PartialTimestampFormat object.

On lines 11 and 12, we set the two required PartialTimestamp fields.

On line 14, we use the PartialTimestampFormat object to convert the PartialTimestamp to a String and print it out. This will print "13:00".

On line 16, we set a modifier for the DAY_OF_MONTH field. This means that when the PartialTimestamp is resolved to a concrete time, that time will be one day later than the earliest time which is still in the future.

On line 18, we use the PartialTimestampFormat object to convert the PartialTimestamp to a String and print it out again. This will also print "13:00" because modifiers are ignored by the PartialTimestampFormat class.

On line 19, we resolve the PartialTimestamp to a concrete Date object and print the value of that object. If this code is executed at 3:49:25pm on Tuesday, January 4th 2005, the result will be "Thu Jan 06 13:00:00 MET 2005". (The timezone is MET because that's where I am.)

On line 21, we set the value of the time to the current time in milliseconds. Setting the time directly, either in milliseconds or as a Date object, results in all fields being set.

On line 23, we use the PartialTimestampFormat object to convert the PartialTimestamp to a String and print it out. Because all the fields have been set, the result is "2005/01/05 15:49:25 +01:00". (Again, the timezone setting is because I am in GMT+1.)

On lines 25-27, we use the PartialTimestampFormat object to convert the String to a PartialTimestamp and then back to a String to be printed it out. The result is the same string, "01/05 14:07:29"

### Version

The Version class is used by the Session instance to return the version of DRMAA supported by the implementation. The major and minor fields of the Version class represent the major and minor version numbers, respectively. For example, DRMAA 1.0 is represented by a Version object with major=1 and minor=0.