Functional Specification

Introduction

The GridSAM system provides a Web Service for job submission and monitoring. The primary purpose is to bridge between traditional Distributed Resource Manager and user with a standard programmatic Web Service interface. The goal is to provide a single interface and language to describe and submit computational job. User should be agnostic of the underlying mechanism for executing the computation on the available resources. The motivation is presented in the Use Cases document.

This document specifies the operations of the GridSAM Web Service. This should be read in conjunction with the specification of the Job Submission Description Language. Together they define the description of a job to be launched through GridSAM and the operations to submit and monitor the job.

Port Type gridsam:JobSubmissionPortType

Operation gridsam:submitJob

The operation is used to place a job on a GridSAM system.

Input

The form of the gridsam:submitJob input message is:

<gridsam:submitJob startSuspended="xsd:boolean" xmlns:gridsam="...">
    <gridsam:JobDescription>
        <jsdl:JobDefinition>
            ...
        </jsdl:JobDefinition>
        <xsd:any/>*
    </gridsam:JobDescription>*
</gridsam:submitJob>
  • submitJob/JobDescription/jsdl:JobDefinition: A JSDL jsdl:JobDefinition element describing a computation to be launched through GridSAM. The sub-elements of this element is described in the Job Submission Description Language specification. GridSAM supports all mandatory elements defined in JSDL.
Result

The successful result of the gridsam:submitJob operation is an identifier for the newly submitted job. This identifier serves as the context to identify the job in other GridSAM operations.

<gridsam:submitJobResponse  xmlns:gridsam="...">
    <gridsam:JobIdentifier>
        <gridsam:ID>
            xsd:anyURI
        </gridsam:ID>
    </gridsam:JobIdentifier>* 
</gridsam:submitJobResponse>
Faults

A fault indicates the submission is void.

  • gridsam:JobSubmissionFault indicates the request requirements specified in the JSDL /JobDescription/jsdl:JobDefinition cannot be fulfilled. This is either caused by invalid or unsupported job description, or the system is refusing submission at the time of invocation.
  • gridsam:AuthorisationFault indicates the GridSAM system refuses to allow the caller to submit the job. The system infers the caller's authority from the context (e.g. identity established by the WS-Security signature, HTTPS mutual authentication).

Port Type gridsam:JobMonitoringPortType

Operation gridsam:getJobStatus

The operation is used to obtain status of a job previously submitted to a GridSAM system.

Input

The form of the gridsam:getJobStatus input message is:

<gridsam:getJobStatus xmlns:gridsam="...">                    
    <gridsam:JobIdentifier>
        <gridsam:ID>
            xsd:anyURI
        </gridsam:ID>
    </gridsam:JobIdentifier>*
</gridsam:getJobStatus>
  • getJobStatus/JobIdentifier: A structure obtained from a invocation of gridsam:submitJob. This serves as a opaque identifier for the job.
Result

The successful result of the gridsam:getJobStatus operation is a document describing the status of the submitted job.

<gridsam:getJobStatusResponse  xmlns:gridsam="...">                       
    <gridsam:JobStatus>
        <gridsam:JobIdentifier>
            <gridsam:ID>
                xsd:anyURI
            </gridsam:ID>
        </gridsam:JobIdentifier>
        <gridsam:Stage> +
            <gridsam:State>
                pending|staging-in|staged-in|active|executed|
                staging-out|staged-out|done|failed|undefined
            </gridsam:State>
            <gridsam:Description>xsd:string</gridsam:Description>
            <gridsam:Time>xsd:DateTime</gridsam:Time>
        </gridsam:Stage>

        <gridsam:Property name="xsd:anyURI">?
            xsd:string
        </gridsam:Property>?
    </gridsam:JobStatus>* 
</gridsam:getJobStatusResponse>
  • getJobStatusResponse/JobStatus/gridsam:Stage: A sequence of gridsam:Stage elements represents the chronological events of the job till the time of the invocation.
    • gridsam:State: The job state reached at that time
    • gridsam:Description: A human-readable description of the event
    • gridsam:Time: The timestamp when the event occurred
  • getJobStatusResponse/JobStatus/gridsam:Property: A sequence of gridsam:Property elements represents a set of key-value metadata associated with the job. This allows the GridSAM system to convey additional per-job information to the caller.

    The GridSAM system defines the following terms:

    • urn:gridsam:exitcode: The exit code of a POSIX application.
  • A submitted job undergoes the following state transition.GridSAM Job State Transition
Faults

A fault indicates status cannot be obtained.

  • gridsam:UnknownJobFault indicates the input does not identify a job recognised by the GridSAM system.
  • gridsam:JobMonitoringFault indicates the GridSAM system is unable to retrieve the job status.
  • gridsam:AuthorisationFault indicates the GridSAM system refuses to allow the caller to gather status of the identified job. The system infers the caller's authority from the context (e.g. identity established by the WS-Security signature, HTTPS mutual authentication).

Port Type gridsam:JobControlPortType

Operation gridsam:terminateJob

The operation is used to initiate termination of a job previously submitted to a GridSAM system.

Input

The form of the gridsam:terminateJob input message is:

<gridsam:terminateJob xmlns:gridsam="...">                    
    <gridsam:JobIdentifier>
        <gridsam:ID>
            xsd:anyURI
        </gridsam:ID>
    </gridsam:JobIdentifier>
</gridsam:terminateJob>
  • terminateJob/JobIdentifier: A structure obtained from a invocation of gridsam:submitJob. This serves as a opaque identifier for the job.
Result

The successful result of the gridsam:terminateJob operation is a document describing the status of the terminating job as specified in the gridsam:getJobStatus operation. The termination sequence happens asynchronously. The result document may mark the job as in the terminating stage, however, this is not guaranteed.

Faults

A fault indicates the termination is unsuccessful

  • gridsam:UnknownJobFault indicates the input does not identify a job recognised by the GridSAM system.
  • gridsam:JobControlFault indicates the GridSAM system is unable to terminate the job.
  • gridsam:AuthorisationFault indicates the GridSAM system refuses to allow the caller to terminate the identified job. The system infers the caller's authority from the context (e.g. identity established by the WS-Security signature, HTTPS mutual authentication).