GeoGig

Web API: Asynchronous tasks

Some web API commands can run for a long time depending on how much data they’re dealing with, and hence, are executed asynchronously, meaning that, once invoked, they start the job in a background thread and return immediately.

The response contains a unique identifier for the asynchronous task and information on the task’s running status. This task identifier can then be used to poll the status of the task by querying the /tasks/<task id> API endpoint.

If no task is given, e.g. by querying the /tasks endpoint, a list of all available tasks will be returned.

A running task can be canceled with the cancel=true argument. For example:

http://localhost:8182/tasks/3?cancel=true

This request will ask the operation to cancel and return immediately. Note, however, that it may take some time for the cancellation request to complete, as the running task may be blocking on I/O or in a temporarily non-cancelable state. Polling the task repeatedly with the cancel=true parameter is not a problem, though.

Finished tasks, whether they finished successfully, an error occurred, or were canceled, will be kept in memory for 10 minutes in order to allow their status to be queried. Finished tasks can be explicitly pruned with the prune=true parameter. For example:

http://localhost:8182/tasks/3?prune=true

Prune has no effect on unfinished tasks.

Examples

When the command is invoked, it returns a result such as the following XML-formatted response.

<task>
   <id>5</id>
   <status>RUNNING</status>
   <description>{command description}</description>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8182/tasks/5.xml" type="application/xml"/>
   <progress>
      <task>Connecting to http://overpass-api.de/api/interpreter...</task>
      <amount>0.0</amount>
   </progress>
</task>

Or the JSON format:

{"task":
   {
      "id":5,
      "status":"RUNNING",
      "description":"osm download filter: null, bbox: -32.9621,-60.6309,-32.9541,-60.6154",
      "href":"http://localhost:8182/tasks/5.json"
      "progress" :
      {
          "task" : "Connecting to http://overpass-api.de/api/interpreter...",
          "amount" : 0.0
      }
   }
}

Note, the atom:link in the XML response and the href property in the JSON response, represent the status polling URL for the specific task ID.

The status attribute will have one of the following values: WAITING, RUNNING, FINISHED, FAILED, CANCELLED.

WAITING means that there are other tasks being run in the thread pool and this one has been scheduled to be run as soon as a spot frees up in the thread pool. The others are self-explanatory.

The content of the task query response varies slightly depending on the task status.

Running tasks may or may not contain a progress indicator. It will depend on the type of task and how far along the task is at the point the response is generated.

<task>
   <id>4</id>
   <status>RUNNING</status>
   <description> Importing geopackage...</description>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8182/tasks/4.xml" type="application/xml"/>
   <progress>
      <task>Importing into GeoGig repo...</task>
      <amount>1397120.0</amount>
   </progress>
</task>

Successfully finished tasks may contain a result summary which is specific to the command executed. The following is an example of the result for a successful OSM import operation.

<task>
   <id>5</id>
   <status>FINISHED</status>
   <description>Importing geopackage....</description>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8182/tasks/5.xml" type="application/xml"/>
   <result>
      <OSMReport>
         <latestChangeset>17218621</latestChangeset>
         <latestTimestamp>1412698140574</latestTimestamp>
         <processedEntities>901852</processedEntities>
         <nodeCount>865542</nodeCount>
         <wayCount>35778</wayCount>
         <unpprocessedCount>4</unpprocessedCount>
      </OSMReport>
   </result>
</task>

And failed tasks contain an exception report.

<task>
   <id>7</id>
   <status>FAILED</status>
   <description>Importing geopackage...</description>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8182/tasks/7.xml" type="application/xml"/>
   <error>
      <message>Nothing to commit after bea73023a9452a9d64f64264d2911ce1ec2b47f2</message>
      <stackTrace>
      <![CDATA[
         org.locationtech.geogig.api.porcelain.NothingToCommitException: Nothing to commit after bea73023a9452a9d64f64264d2911ce1ec2b47f2
         at org.locationtech.geogig.api.porcelain.CommitOp._call(CommitOp.java:320)
         at org.locationtech.geogig.api.porcelain.CommitOp._call(CommitOp.java:57)
         at org.locationtech.geogig.api.AbstractGeoGigOp.call(AbstractGeoGigOp.java:133)
         at org.locationtech.geogig.osm.internal.OSMImportOp._call(OSMImportOp.java:234)
         at org.locationtech.geogig.osm.internal.OSMImportOp._call(OSMImportOp.java:75)
         at org.locationtech.geogig.api.AbstractGeoGigOp.call(AbstractGeoGigOp.java:133)
         at org.locationtech.geogig.osm.internal.OSMDownloadOp._call(OSMDownloadOp.java:155)
         at org.locationtech.geogig.osm.internal.OSMDownloadOp._call(OSMDownloadOp.java:28)
         at org.locationtech.geogig.api.AbstractGeoGigOp.call(AbstractGeoGigOp.java:133)
         at org.locationtech.geogig.rest.AsyncContext$CommandCall.call(AsyncContext.java:192)
         at java.util.concurrent.FutureTask.run(FutureTask.java:262)
         ...
      ]]>
      </stackTrace>
   </error>
</task>
Previous: Web API: Serving and Managing Repositories
Next: Web API: Issues

back to top