Interacting with a StructuredGridCoverageReader

Since 1.6.x a new entity has been created to deal with StructuredGridCoverageReaders in GeoServer.

In this document we are going to describe how interacting via REST interface with such elements in GeoServer is possible using GeoServer-Manager library.

StructuredGridCoverageReader Manager

This is the base manager that interacts with a StructuredGridCoverageReader via REST calls.

Below you can find its constructor. The parameters are pretty much self-explaining.

public GeoServerRESTStructuredGridCoverageReaderManager(URL restURL, String username, String pw);

Here below an example of initialization to talk to a local instance of GeoServer.

        String RESTURL  = "http://localhost:8080/geoserver";
        String RESTUSER = "admin";
        String RESTPW   = "geoserver";
        
        GeoServerRESTStructuredGridCoverageReaderManager manager = 
              new GeoServerRESTStructuredGridCoverageReaderManager(new URL(RESTURL), RESTUSER, RESTPW);

We are now going to provide samples for the common operations to be performed when interacting with a StructuredGridCoverageReader using a GeoServerRESTStructuredGridCoverageReaderManager.

Creating a Mosaic by uploading the configuration files.

It is possible to upload a Zip file containing the configuration for the mosaic together with at least 1 branule (internal or external to the Zip itself) via the GeoServerRESTStructuredGridCoverageReaderManager (for more info you can check the GeoServer documentation here and here).

The following does an upload of a Zip file to create a mosaic for a certain number of GeoTiff files.

boolean create=manager.create("it.geosolutions", "mosaic","/path/to/mosaic.zip"));

The method returns true when it succeeds and false otherwise.

Accessing the Index Schema

To get access to the Index Schema for a certain StructuredCoverage, the following method can be used:

RESTStructuredCoverageIndexSchema indexFormat = manager.getGranuleIndexSchema("myWorkspace", "myCoverageStore", "myCoverage");

This is a sample XML REST schema representation for a certain index schema:

<Schema>
  <attributes>
    <Attribute>
      <name>the_geom</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>com.vividsolutions.jts.geom.Polygon</binding>
    </Attribute>
    <Attribute>
      <name>location</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.lang.String</binding>
    </Attribute>
    <Attribute>
      <name>imageindex</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.lang.Integer</binding>
    </Attribute>
    <Attribute>
      <name>time</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.sql.Timestamp</binding>
    </Attribute>
    <Attribute>
      <name>elevation</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.lang.Double</binding>
    </Attribute>
    <Attribute>
      <name>fileDate</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.sql.Timestamp</binding>
    </Attribute>
    <Attribute>
      <name>updated</name>
      <minOccurs>0</minOccurs>
      <maxOccurs>1</maxOccurs>
      <nillable>true</nillable>
      <binding>java.sql.Timestamp</binding>
    </Attribute>
  </attributes>
  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/workspaces/myWorkspace/coveragestores/myCoverageStore/coverages/myCoverage/index/granules.xml" type="application/xml"/>
</Schema>

If you want to further inspect the attributes that comprises the schema they are exposed as an iterable as follows:

Iterable<RESTStructuredCoverageIndexSchema.RESTStructuredCoverageIndexAttribute>

hence it is possible to iterate over each single RESTStructuredCoverageIndexAttribute.

See this example for some interesting code:

        Iterator<RESTStructuredCoverageIndexAttribute> iterator = indexFormat.iterator();
        while (iterator.hasNext()) {
            final RESTStructuredCoverageIndexAttribute element = iterator.next();
            final String elementName = element.getName();
            if (elementName.equals("location")) {
                assertEquals("0", element.getMinOccurs());
                assertEquals("1", element.getMaxOccurs());
                assertEquals("true", element.getNillable());
                assertEquals("java.lang.String", element.getBinding());
            } else if (elementName.equals("time")) {
                assertEquals("0", element.getMinOccurs());
                assertEquals("1", element.getMaxOccurs());
                assertEquals("true", element.getNillable());
                assertEquals("java.util.Date", element.getBinding());
            } else if (elementName.equals("date")) {
                assertEquals("0", element.getMinOccurs());
                assertEquals("1", element.getMaxOccurs());
                assertEquals("true", element.getNillable());
                assertEquals("java.lang.String", element.getBinding());
            } else if (elementName.equals("depth")) {
                assertEquals("0", element.getMinOccurs());
                assertEquals("1", element.getMaxOccurs());
                assertEquals("true", element.getNillable());
                assertEquals("java.lang.Integer", element.getBinding());
            }
        }

Creating or harvesting granules

To add a granule to an existing coverage store which refers to an ImageMosaic you need to do the following:

boolean added = manager.createOrHarvestExternal("it.geosolutions", "myCoverageStore", "imagemosaic", "/data/newSampleFile.nc");

Accessing granules information

To access granules information for a certain coverage you need to do the following:

RESTStructuredCoverageGranulesList granulesList = manager.getGranules("myWorkspace", "myCoverageStore", "myCoverage", null, null, null);

This method supports paged access to granule information. E.g., to access the first 10 granules from myCoverage, starting from an offset of 20 you need to do the following:

RESTStructuredCoverageGranulesList granulesList = manager.getGranules("myWorkspace", "myCoverageStore", "myCoverage", null, 20, 10);

This method also supports filtered access to granule information using CQL on granule index attributes. As an instance, to get only the granules from myCoverage, having depth = 100 and time = 20081101T0000000:

RESTStructuredCoverageGranulesList granulesList = manager.getGranules("myWorkspace", "myCoverageStore", "myCoverage", "depth = 100 AND time='20081101T0000000'", null, null);

Eventually To get a granule by ID (as an instance 43):

RESTStructuredCoverageGranulesList granulesList = manager.getGranuleById("myWorkspace", "myCoverageStore", "myCoverage", "43");

Removing Granules from the Index

It is possible not only to get information about granules but also to remove granules for the index.

To remove all granules from myCoverage, related to file having location = /data/sampleFile.tif, using a CQL filter.

final String fileLocation = "/data/sampleFile.tif";
boolean result = manager.removeGranulesByCQL("myWorkspace", "myCoverageStore", "myCoverage", "location = '" + fileLocation + "'");

To remove a specific granule from myCoverage, specified by ID (as an instance 43).

boolean result = manager.removeGranuleById("myWorkspace", "myCoverageStore", "myCoverage", "43");

Notice that currently this method does not delete the underlying file but simply removes it from the index, making it de-fact unaccessible from GeoServer