README.md

Args Class Generator

This tool generates custom Args subclasses based on the REST API documentation for the associated endpoint.

Example Usage

./gen_args_class.py < specs/JobArgs_POST__search_jobs.argspec > Output.java

Quickstart

For each class that you want to generate, an .argspec file must be created that defines the specific parameters supported by the Args class, along with its Java datatype and documentation.

For example, the specification:

auto_cancel
AutoCancel
int
Sets the number of seconds of inactivity after which to automatically cancel a job. A value of 0 means never auto-cancel.
-
The number of seconds after which to cancel a job.
===

...generates the following code:

    /* BEGIN AUTOGENERATED CODE */
    
    /**
     * Sets the number of seconds of inactivity after which to automatically cancel a job. A value of 0 means never auto-cancel.
     * 
     * @param autoCancel
     *      The number of seconds after which to cancel a job.
     */
    public void setAutoCancel(int autoCancel) {
        this.put("auto_cancel", autoCancel);
    }
    
    /* END AUTOGENERATED CODE */

Notice that the generator does not generate an entire class, but rather only its methods. The user must manually:

• Create the class definition and documentation.
• Add the constructor.
• Add any nested enum types that the generated setters require.

Argument Specification Format

Any line that begins with # is a comment and will be ignored. Blank lines are significant (and are not ignored).

Any line at the beginning of the file that begins with ! is a directive and will change the behavior of the generator. For example:

# Some arguments are defined multiple times by different copied sections.
# Ignore errors related to this. The first version wins.
!SET ignore_duplicates 1

The rest of the file is a series of argument definitions:

<< machine name >>
<< Java name (upper camelcase) >>
<< Java type >>
<< method description line #1 >>
<< method description line .. >>
<< method description line #n >>
-
<< parameter description line #1 >>
<< parameter description line .. >>
<< parameter description line #n >>
===

Note that the last specification must still end with a === line.

Special Java Types

A few values for << Java type >> are handled specially:

• String[]-MULTIPLE - Each value will be a separate parameter.
  • For example "f = {1,2,3}" would appear as f=1&f=2&f=3 in the final URL.
• String[]-CSV - Values will be submitted as a single comma-separated parameter.
  • For example "f = {1,2,3}" would appear as f=1,2,3 in the final URL.

Custom Setter Code

For more complex cases where the generated accessor is not appropriate (like the Java type Date), you can also specify custom code for an argument by adding a !CODE line after the argument description and follow that line with custom Java code.

For example:

dispatch.earliest_time
DispatchEarliestTime
Date
Sets the earliest time for this search. 
-
A date that specifies the earliest time for this search.
!CODE
        String javaFormatString =    "yyyy-MM-dd'T'HH:mm:ss.SSSZ";
        String timeString = new SimpleDateFormat(javaFormatString).format(dispatchEarliestTime);
        this.put("dispatch.earliest_time", timeString);
===

...generates this code:

    /**
     * Sets the earliest time for this search. 
     * 
     * @param dispatchEarliestTime
     *      A date that specifies the earliest time for this search.
     */
    public void setDispatchEarliestTime(Date dispatchEarliestTime) {
        String javaFormatString =    "yyyy-MM-dd'T'HH:mm:ss.SSSZ";
        String timeString = new SimpleDateFormat(javaFormatString).format(dispatchEarliestTime);
        this.put("dispatch.earliest_time", timeString);
    }