ClientServerApi

1. Client/Server API

This page describes the protocol for communication between OMG client and a remote server (cluster or grid).

We still have to define whether those services will be defined as an object API (SOAP) or as a document model (XML Schema). For now, they are defined to guide the implementation of the abstraction that will handle local or remote services.

2. Available Services

1. Get Capabilities: provide metadata about datasets and algorithms available on the server

2. Submit Creation Job: allow submition of model creation job to the server

3. Submit Reprojection Job: allow submition of model reprojection to the server

4. Get Progress: get status of submitted job (and individual tasks)

5. Download Results: allows download of results from a specified set of tasks or all tasks from a job.

3. Description of Services

3.1. 1. Get Capabilities

• Parameters: Connection info, i.e., connection point or URL, user name, password, etc;

• Return: Description of datasets and algorithms available on the server.

The description of available datasets must describe completely what are the available datasets, its path (or handle) on the server, which layers each dataset contain, their paths. Server must flag whether it supports the use of remote datasets and layers (loading via generic URI) or only locally stored ones.

The description of available algorithms must contain all information present on an openModeller algorithm metadata structure: list of algorithms, each containing the following fields: with id, name, version, overview, description, author, bibliography, code author, code author contact, accept categorical data flag, accept absence data flag, number of parameters and list of parameters. Each parameter in this list must have: id, name, type, overview, description, lower bound flag, lower bound value, upper bound flag, upper bound value, default value.

When using a remote (cluster) backend, the client application should use the algorithm descriptions obtained from the server to build the part of the requests regarding the algorithms, instead of a local OM instance. That is because the algorithm code that will execute the job is sitting on the server, so it doesn't matter what algorithms are available on the client.

This request can serve as a ping request (or ping can be defined separately).

3.2. 2. Submit Creation Job

• Parameters: Job Creation Description

• Return: Job ID (ticket) or error message

Job description must come the following format:

1. Array of specimen locality data (one element per species)
2. Array of algorithms (id + array of parameters)
3. Native range dataset
4. Array of projection datasets

All objects and entities on this definition file must have (or be assigned) an id so it can be identified and referred to in later calls.

On success, the return value is the newly created job id, that will be used for further queries for job status by the client, or a diagnostic message on failure.

3.3. 3. Submit Reprojection Job

• Parameters: Job Reprojection Description

• Return: Job ID (ticket) or error message

Job reprojection format contains:

1. Array of serialized models
2. Array of projection datasets

3.4. 4. Get Progress

• Parameters: Job ID

• Return: Job and task status information

The return data contains:

1. Job info
2. Array of tasks belonging to that job, including: task id, algorithm id, native and projection dataset ids, status (on queue, being processed, finished), progress, message.

3.5. 5. Download Results

• Parameters: Job ID and list of task ids

• Return: job and task results (or provide links for later download)