Seeding and Truncating

The GeoWebCache REST API provides a RESTful interface through which users can add or remove tiles from the cache on a per-layer basis.

Operations

URL: /gwc/rest/seed/<layer>.<format>

Method	Action	Return Code	Formats
GET	Return the status of the seeding threads	200	JSON
POST	Issue a seed or truncate task request	200	XML, JSON
PUT		405
DELETE		405

Representations:

XML
JSON

The examples below use the cURL tool, though the examples apply to any HTTP-capable tool or library.

Seeding

The following XML request initiates a seeding task:

curl -v -u admin:geoserver -XPOST -H "Content-type: text/xml" -d '<seedRequest><name>nurc:Arc_Sample</name><srs><number>4326</number></srs><zoomStart>1</zoomStart><zoomStop>12</zoomStop><format>image/png</format><type>truncate</type><threadCount>2</threadCount></seedRequest>'  "http://localhost:8080/geoserver/gwc/rest/seed/nurc:Arc_Sample.xml"

* About to connect() to localhost port 8080 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
* Server auth using Basic with user 'admin'
> POST /geoserver/gwc/rest/seed/nurc:Arc_Sample.xml HTTP/1.1
> Authorization: Basic YWRtaW46Z2Vvc2VydmVy
> User-Agent: curl/7.21.3 (x86_64-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: localhost:8080
> Accept: */*
> Content-type: text/xml
> Content-Length: 209
> 
< HTTP/1.1 200 OK

The following is a more complete XML fragment for a seed request, including parameter filters:

<?xml version="1.0" encoding="UTF-8"?>
<seedRequest>
  <name>topp:states</name>
  <bounds>
    <coords>
      <double>-2495667.977678598</double>
      <double>-2223677.196231552</double>
      <double>3291070.6104286816</double>
      <double>959189.3312465074</double>
    </coords>
  </bounds>

  <!-- These are listed on http://localhost:8080/geoserver/gwc/demo -->
  <gridSetId>EPSG:2163</gridSetId>
  <zoomStart>0</zoomStart>
  <zoomStop>2</zoomStop>
  <format>image/png</format>

  <!-- type can be seed, reseed, or truncate -->
  <type>truncate</type> 

  <!-- Number of seeding threads to run in parallel. 
       If type == truncate only one thread will be used
       regardless of this parameter -->
  <threadCount>1</threadCount>
  <!-- Parameter filters -->
  <parameters>
    <entry>
      <string>STYLES</string>
      <string>pophatch</string>
    </entry>
    <entry>
      <string>CQL_FILTER</string>
      <string>TOTPOP > 10000</string>
    </entry>
  </parameters>
</seedRequest>

Truncating

The following XML request initiates a truncating task:

curl -v -u admin:geoserver -XPOST -H "Content-type: application/json" -d "{'seedRequest':{'name':'topp:states','bounds':{'coords':{ 'double':['-124.0','22.0','66.0','72.0']}},'srs':{'number':4326},'zoomStart':1,'zoomStop':12,'format':'image\/png','type':'truncate','threadCount':4}}}"  "http://localhost:8080/geoserver/gwc/rest/seed/nurc:Arc_Sample.json"

* About to connect() to localhost port 8080 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
* Server auth using Basic with user 'admin'
> POST /geoserver/gwc/rest/seed/nurc:Arc_Sample.json HTTP/1.1
> Authorization: Basic YWRtaW46Z2Vvc2VydmVy
> User-Agent: curl/7.21.3 (x86_64-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: localhost:8080
> Accept: */*
> Content-type: application/json
> Content-Length: 205
> 
< HTTP/1.1 200 OK
< Date: Fri, 14 Oct 2011 22:09:21 GMT
< Server: Noelios-Restlet-Engine/1.0..8
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Querying running tasks

URL: /gwc/rest/seed[/<layer>].json

Method	Action	Return Code	Formats
GET	Get the global or per layer state of running and pending tasks	200	JSON
POST		405
PUT		405
DELETE		405

Getting current state of the seeding threads

Sending a GET request to the /gwc/rest/seed.json resource returns a list of pending (scheduled) and running tasks for all the layers.

Sending a GET request to the /gwc/rest/seed/<layer name>.json resource returns a list of pending (scheduled) and running tasks for that specific layer.

The returned content is a JSON array of the form:

{"long-array-array":[[<long>,<long>,<long>,<long>,<long>],...]}

If there are no pending or running tasks, the returned array is empty:

{"long-array-array":[]}

The returned array of arrays contains one array per seeding/truncating task. The meaning of each long value in each thread array is:

[tiles processed, total number of tiles to process, estimated remaining time (in seconds), Task ID, Task status]

The returned Task Status value will be one of the following:

-1 = ABORTED 
 0 = PENDING
 1 = RUNNING
 2 = DONE

The example below returns the current state of tasks for the topp:states layer:

curl -u <user>:<password> -v -XGET http://localhost:8080/geoserver/gwc/rest/seed/topp:states.json

{"long-array-array":[[17888,44739250,18319,1,1],[17744,44739250,18468,2,1],[16608,44739250,19733,3,0],[0,1000,1000,4,0]]}

In the above response, tasks 1 and 2 for the topp:states layer are running, and tasks 3 and 4 are in a pending state waiting for an available thread.

The example below returns a list of tasks for all the layers.

curl -u <user>:<password> -XGET http://localhost:8080/geoserver/gwc/rest/seed.json

{"long-array-array":[[2240,327426,1564,2,1],[2368,327426,1477,3,1],[2272,327426,1541,4,1],[2176,327426,1611,5,1],[1056,15954794690,79320691,6,1],[1088,15954794690,76987729,7,1],[1040,15954794690,80541010,8,1],[1104,15954794690,75871965,9,1]]}

Terminating running tasks

URL: /gwc/rest/seed[/<layer>]

Method	Action	Return Code
GET		405
POST	Issue a kill running and/or pending tasks request	200
PUT		405
DELETE		405

A POST request to the /gwc/rest/seed resource terminates pending and/or running tasks for all layers. A POST request to the /gwc/rest/seed/<layername> resource terminates pending and/or running tasks for a specific layer.

It is possible to terminate individual or all pending and/or running tasks. Use the parameter kill_all with one of the following values: running, pending, or all.

Note

For backward compatibility, the kill_all parameter value 1 is also accepted and is equivalent to running.

The following request terminates all running seed and truncate tasks.

curl -v -u admin:geoserver -d "kill_all=all"  "http://localhost:8080/geoserver/gwc/rest/seed"

* About to connect() to localhost port 8080 (#0)
*   Trying 127.0.0.1... connected
< HTTP/1.1 200 OK
< Date: Fri, 14 Oct 2011 22:23:04 GMT
< Server: Noelios-Restlet-Engine/1.0..8
< Content-Type: text/html; charset=ISO-8859-1
< Content-Length: 426
< 
<html>
...
* Connection #0 to host localhost left intact
* Closing connection #0