The ESE API enables IDL programs to perform remote processing using the ESE Rest API provided by the Geospatial Services Framework. To use the API, you need IDL and an GSF that is running locally or remotely.

The benefits of remote processing are:

  • It allows processing to be performed where the data is located. Instead of bringing the data to the processing, the processing is brought to the data. This is especially important when the data is large, relative to the capacity of the network connection.
  • It is often performed on a powerful server.
  • Algorithms can be easily shared among users.

The benefits of using the ESE API to run tasks are:

  • Simplified Web Services: Programming is done in IDL, with little need to understand web technologies. The API forms HTTP requests, performs network communication, and manages execution. Error checking and robustness are built into the API.
  • Task Chaining: The API makes it easy to chain tasks, taking the output from one task and using as the input to the next task.
  • Parallel Processing: The API has methods that assist the synchronization of the client application and multiple, concurrent tasks.

The API can be used by IDL desktop applications and tasks since they are written in IDL. For example, a task could be implemented as an amalgamation of several other tasks that are chained or even running concurrently.

Getting Started with the ESE API

The ESE API provides classes that represent ESE Rest API endpoints. There is an ESETask class that allows setting of input and task execution. There is an ESEJob that provides information on job output from task execution.

There is an ESE static class that provides a starting point to writing an ESE client application. It is never instantiated and has only static methods. Typically applications will start by using ESE::FindTask, ESE::GetTask or ESE::GetServer, depending on whether you want to quickly run a task, or introspect the available services and tasks. The ESE class also has mechanisms for controlling jobs that are running concurrently and for handling custom data types.

A common pattern for running a task is:

  • Get the task. Call ESE::FindTask or ESE::GetTask to get an ESETask object. ESE::FindTask searches the GSF installation for the named task. Regular expressions searches are possible. If a matching task is not found then, !null is returned.
  • Run the task. Invoke the task's run method. The task's parameters are set by using them as keywords to run. You can also use ESETask::GetParameters to introspect a task for its parameters. The return value from ESETask::Run is an ESEJob object. Every time a task object has its run method called, a new ESEJob object is generated.
  • Check the job's status. The ESEJob objects have metadata with the job's status, which indicates if they have run successfully or not. All the possible states of a job are present as constants in the ESE class. For example, to check for success, compare the job's status metadata to ESE.jobSucceeded.
  • Get the result. Successful jobs have their output parameters presented as object properties. For example, the "addition" task has the output parameter "C". Both input and output parameters can be accessed by using IDL's "dot" notation. See Custom IDL Tasks on how to create the addition task. Copy the custom task to your IDL installation lib directory for it to be available on the server.

For example:

Task = ESE.GetTask('http://localhost:9191/ese/services/IDL/addition')
 
Job = Task.Run(a=2, b=2)
 
Info = Job.Info()
 
IF (Info.Status eq ESE.jobSucceeded) THEN BEGIN
  PRINT, strtrim(job.a, 2) + ' + ' + strtrim(job.b, 2) + ' = ' + strtrim(job.c, 2)
ENDIF ELSE BEGIN
  PRINT, 'Error: ' + Info.Status
ENDELSE

Highlights of the ESE API

As described previously, you can use the ESE API can to find tasks, run them, and get results. The ESE API topics provide details of the API's capabilities. Some highlights of those capabilities are:

  • Run a job asynchronously by using the /ASYNC keyword of ESETask::Run.
  • Synchronize on multiple concurrently executing jobs by invoking ESE::Join.
  • Monitor a job without blocking by using ESEJob::Monitor.
  • Download data to a server by using ESEServer::DownloadFile.
  • Handle custom task data types by using the serialization and deserialization mechanisms of the ESE class.