Difference between revisions of "GIS Interface"

From Gcube Wiki
Jump to: navigation, search
(→‎The library)
 
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- CATEGORIES -->
 
<!-- CATEGORIES -->
 
[[Category:Developer's Guide]]
 
[[Category:Developer's Guide]]
 +
[[Category: gCube Spatial Data Infrastructure]]
 +
[[Category: SDI components]]
 
<!-- END CATEGORIES -->
 
<!-- END CATEGORIES -->
−
The GIS-Interface is a java library which exposes methods to access / modify spatial data and related metadata.
+
The GIS-Interface is a java library which exposes methods to access / modify and publish spatial data and related metadata.
 
The library is designed to rely on GeoNetwork and GeoServer registered in the infrastructure.
 
The library is designed to rely on GeoNetwork and GeoServer registered in the infrastructure.
  
Line 9: Line 11:
  
 
=The library=
 
=The library=
 +
 +
==Module description==
  
 
The library is a maven artifact with the following coordinates :  
 
The library is a maven artifact with the following coordinates :  
Line 23: Line 27:
 
</source>
 
</source>
  
−
It basically :
+
==Key Features==
−
*Interacts with the infrastructure's '''IS''' to gather access information to both '''GeoServer''' and '''GeoNetwork''' instance(s)
+
;Transparent handling of multiple GeoServer instances;
−
*Wraps ''geoserver-manager'' functionalities for accessing/modifying data on a given '''Geoserver''' instance,
+
The library is designed to operate on a pool of GeoServer instances in order to provide load-balancing.
−
*Implements high level logic by coordinating publication of both data and metadata on the Spatial Data Infrastructure in the current scope.
+
;Automatic handling of SDI configuration and resources
 +
By interacting with both IS and registered GeoServer instances, the library is capable of managing this resources transparently to the caller application.
 +
;Contextual publication of metadata along with data publication
 +
Data publication is always performed along metadata publication, enriching such metadata with generated information (i.e. online resources)
  
−
The offered functionalities are accessible by instatiating the ''org.gcube.spatial.data.gis.GISInterface'' java class, via its static method  
+
=Interaction with the Spatial Data Infrastructure=
 +
 
 +
The library relies on the interfaces inside the package ''it.geosolutions.geoserver.rest'' to interact with the REST interface of a given '''GeoServer''' instance.
 +
While GET methods are offered to clients just by letting them access an instance of ''GeoServerRESTReader'' class, PUT (for creating, modifying and deleting purposes) methods are redefined and offered by the class ''GISInterface''.
 +
This lets the library coordinate the modification of both data/metadata thus granting consistency inside the '''SDI'''.
 +
 
 +
==GeoServer Pool==
 +
The library operates over a pool of ''GeoServer'' instances in order to:
 +
* balance load on instances
 +
* ensure coherence on SDI configuration
 +
 
 +
The pool can be either declared by the caller or automatically retrieved from the IS using caller's thread identity. See [[Instantiating the library]] for more information.
 +
 
 +
=Using the library=
 +
 
 +
==Instantiating the library==
 +
Functionalities of this library can be exploited using ''org.gcube.spatial.data.gis.GISInterface'' instance methods. At instantiation time, the caller decides the GeoServer pool that should be used by the library, either by declaring one or by using default behavior. This is done by calling the static method ''public static GISInterface get(AbstractGeoServerDescriptor... toUsePool)''.
 +
 
 +
Please note that default behavior should be preferred in order to correctly interact with the '''SDI''.
 +
 
 +
===Default Pool behavior===
 +
The default behavior of the library is to gather and cache SDI configuration from the IS. This is obtained by simply calling the static method ''public static GISInterface get(AbstractGeoServerDescriptor... toUsePool)'' with no arguments.
 +
See[Configuration] for cache configuration details.
 +
 
 +
===Explicit Pool behavior===
 +
In same cases, like test runs, caller might want to explicit the GeoServer pool in order to force the library to interact with a specific set of GeoServer instances. This is done by calling the static method ''public static GISInterface get(AbstractGeoServerDescriptor... toUsePool)'' with the set of wanted GeoServer instances. The library will avoid interacting with the IS in order to get instances, ensuring the solely use of declared pool.
 +
 
 +
===AbstractGeoServerDescriptor Class===
 +
Classes used by the GeoServer pool extend '''org.gcube.spatial.data.gis.is.AbstractGeoServerDescriptor''' class. It declares the base methods that describe a GeoServer instance, and leave its sublcasses to define how to retrieve these information.
 +
Expected information provided by this class and its implementations are :
 +
 
 +
* Set<String> workspaces
 +
* Map<String,String> dataStores By workspaces
 +
* Set<String> existing styles
 +
* Long hosted layers count
 +
 
 +
 
 +
The following 3 base classes are provided :
 +
 
 +
* '''GeoServerDescriptor''' : This class holds its information in memory as a simple bean;
 +
* '''LiveGeoServerDescriptor''' : This class returns information by directly invoking the related GeoServer instance.
 +
* '''CachedGeoServerDescriptor''' : Extending ''LiveGeoServerDescriptor'', it caches information in memory and invoke related GeoServer only if its cache is not valid.
 +
 
 +
The default class for the pool is CachedGeoServerDescriptor. To learn more about the pool configuration see [Configuration].
 +
 
 +
====Pool initialization examples====
 +
;Default pool initialization;
 +
The pool is initialized (if not yet present) with a set of ''CachedGeoServerDescriptor'' related to information retrieved from Information System in the current context.
 +
<source lang ="java">
 +
GISInterface gis=GISInterface.get();
 +
</source>
 +
 
 +
;In memory information pool;
 +
Here we specify all expected information in the declared beans, and tell the library to use this set as its GeoServer pool.
 +
 
 +
<source lang = "java">
 +
GeoServerDescriptor geo1=new GeoServerDescriptor("..", "..", "...", 0l);
 +
geo1.setDatastores(...);
 +
geo1.setWorkspaces(...);
 +
geo1.setStyles(...);
 +
GeoServerDescriptor geo2=new GeoServerDescriptor("..", "..", "...", 0l);
 +
 
 +
GISInterface gis=GISInterface.get(geo1,geo2);
 +
</source>
 +
 
 +
==Read API==
 +
 
 +
===Select a GeoServer from the pool===
 +
In order to get GeoServer descriptor from the library's pool one must use one of the following :
 
<source lang="java">
 
<source lang="java">
−
public static GISInterface get() throws Exception
+
// Returns the first descriptor of the cache according to default Research Method.
 +
AbstractGeoServerDescriptor getCurrentGeoServer();
 +
 
 +
// Returns the entire collection of the pool, prior refreshing its information (if forceUpdate == true)
 +
SortedSet<AbstractGeoServerDescriptor> getCurrentCacheElements(Boolean forceUpdate);
 +
 
 +
//Returns the first element of the pool according to specified method, prior refreshing its information (if forceUpdate == true)
 +
AbstractGeoServerDescriptor getGeoServerByMethod(ResearchMethod method, Boolean forceUpdate){
 
</source>
 
</source>
  
−
=Interaction with GeoServer=
+
===GeoServerRESTReader===
−
==GeoServer Get Methods==
+
''AbstractGeoServerDescriptor'' implementations offer methods to directly interact with related GeoServer instance via the use of classes provided by ''it.geosolutions.geoserver-manager'' libraries. More information provided on section [[#Raw Methods | Raw Methods]].
−
==GeoServer Put Methods==
+
 
−
==Advanced Publishing==
+
==Publish API==
 +
The library expose different ways to interact with the '''SDI'''.
 +
;Orchestrated methods;
 +
API exposed by the class ''org.gcube.spatial.data.gis.GISInterface''. By operating across the '''SDI''' they ensure coherency and integrity of published data and metadata.
 +
;RAW methods;
 +
API exposed by the underlying library ''it.geosolutions.geoserver-manager''. In order to achieve flexibility, the '''GIS Interface''' library allows programmers to directly use this API for use cases not yet covered by ''Orchestrated methods''. Since they directly interact with a specific instance of '''GeoServer''', their use is discouraged in most cases.
 +
 
 +
===Orchestrated Methods===
 +
To modify both data and metadata registered in the '''SDI''', one should use the instance methods exposed by the class ''GISInterface''. This grants the client a complete interaction with both '''GeoServer''' and '''GeoNetwork''' servers, assuring consistency between data and metadata.
 +
Following is a list of exposed methods (For more detailed information please refer to distributed javadoc maven artifact) :
 +
 
 +
*Publish data and metadata altogether
 +
**addGeoTIFF
 +
**publishDBTable
 +
*Configure '''GeoServer'''s (NB these methods operate on each '''GeoServer''' instance available in current context)
 +
**publishStyle
 +
**createDataStore
 +
**createWorkspace
 +
 
 +
 
 +
The following code shows how to publish a layer from a table already created on a postgis database.
 +
Please note that the Database must already be registered onto the '''GeoServer''' instance as a store inside the workspace the user is willing to publish the layer into.
 +
 
 +
<source lang="java">
 +
import it.geosolutions.geoserver.rest.encoder.GSLayerEncoder;
 +
import it.geosolutions.geoserver.rest.encoder.feature.GSFeatureTypeEncoder;
 +
 
 +
...
 +
 
 +
String scope="...";
 +
String toPublishTable="...";
 +
String datastore="...";
 +
 +
 +
String defaultStyle="...";
 +
String workspace="...";
 +
 +
//Setup geoserver publishing parameters
 +
GSFeatureTypeEncoder fte=new GSFeatureTypeEncoder();
 +
fte.setEnabled(true);
 +
fte.setLatLonBoundingBox(-180.0, -90.0, 180.0, 90.0, crs);
 +
fte.setName(toPublishTable);
 +
fte.setNativeCRS(crs);
 +
 +
GSLayerEncoder le=new GSLayerEncoder();
 +
le.setDefaultStyle(defaultStyle);
 +
le.setEnabled(true);
 +
 
 +
//GCubeISOMetadata class belongs to org.gcube.spatial.data.geonetwork. Please refer to metadata generation in this page for further information
 +
//Generate metadata for the layer to be published
 +
ScopeProvider.instance.set(scope);
 +
GcubeISOMetadata meta=new GcubeISOMetadata();
 +
meta.set..
 +
...
 +
 +
 +
GISInterface gis=GISInterface.get();
 +
 +
PublishResponse resp=gis.publishDBTable(workspace, datastore, fte, le, meta.getMetadata(), "datasets", "_none_", LoginLevel.DEFAULT);
 +
</source>
 +
 
 +
=== RAW Methods ===
 +
In some cases, the developer wants to interact directly to a '''GeoServer''' instance by exploiting underlying library ''it.geosolutions.geoserver-manager''.
 +
This can be done by using the following methods exposed by ''org.gcube.spatial.data.gis.is.AbstractGeoServerDescriptor'' described in section above.
 +
Exposed API methods are :
 +
<source lang="java">
 +
public GeoServerRESTReader getReader() throws MalformedURLException;
 +
public GeoServerRESTStoreManager getDataStoreManager() throws IllegalArgumentException, MalformedURLException;
 +
public GeoServerRESTPublisher getPublisher() throws IllegalArgumentException, MalformedURLException;
 +
</source>
 +
 
 +
 
 +
===GS Parameters===
 +
We decided not to override some parameter classes like ''GSLayerEncoder'' and ''GSFeatureTypeEncoder''. So please refer to the ''geoserver-manager'' library's official documentation.
 +
 
 +
===Metadata generation and publishing===
 +
Publishing of GIS metadata is made using ''org.gcube.spatial.data.geonetwork'' library. The library exposes facilities to help developers define layers metadata compliant with gCube SDI policies, especially the class ''org.gcube.spatial.data.geonetwork.iso.GcubeISOMetadata''. Please refer to [[GeoNetwork library]] for further details.
 +
 
 +
===Report classes===
 +
The results, status and contingent error messages of modifying operations are wrapped into the classes
 +
''org.gcube.spatial.data.gis.model.report.PublishResponse'' and ''org.gcube.spatial.data.gis.model.report.DeleteReponse'', both extending ''org.gcube.spatial.data.gis.model.report.Report'' class.
 +
Please refere to their javadoc pages for further information.

Latest revision as of 15:12, 2 February 2023

The GIS-Interface is a java library which exposes methods to access / modify and publish spatial data and related metadata. The library is designed to rely on GeoNetwork and GeoServer registered in the infrastructure.

The library relies on org.gcube.spatial-data.geonetwork (see GeoNetwork library) to interact with geonetwork. Interaction with GeoServer REST interface is based on functionalities exposed by geoserver-manager, developed by GeoSolutions under MIT License.

The library

Module description

The library is a maven artifact with the following coordinates : 

  <groupId>org.gcube.spatial.data</groupId>
  <artifactId>gis-interface</artifactId>

It relies on the GeoNetwork library for the interaction with GeoNetwork servers, and exploits functionalities implemented by geosolution's library : 

  <groupId>it.geosolutions</groupId>
  <artifactId>geoserver-manager</artifactId>
  <version>1.5.2</version>

Key Features

Transparent handling of multiple GeoServer instances;

The library is designed to operate on a pool of GeoServer instances in order to provide load-balancing.

Automatic handling of SDI configuration and resources

By interacting with both IS and registered GeoServer instances, the library is capable of managing this resources transparently to the caller application.

Contextual publication of metadata along with data publication

Data publication is always performed along metadata publication, enriching such metadata with generated information (i.e. online resources)

Interaction with the Spatial Data Infrastructure

The library relies on the interfaces inside the package it.geosolutions.geoserver.rest to interact with the REST interface of a given GeoServer instance. While GET methods are offered to clients just by letting them access an instance of GeoServerRESTReader class, PUT (for creating, modifying and deleting purposes) methods are redefined and offered by the class GISInterface. This lets the library coordinate the modification of both data/metadata thus granting consistency inside the SDI.

GeoServer Pool

The library operates over a pool of GeoServer instances in order to:

  • balance load on instances
  • ensure coherence on SDI configuration

The pool can be either declared by the caller or automatically retrieved from the IS using caller's thread identity. See Instantiating the library for more information.

Using the library

Instantiating the library

Functionalities of this library can be exploited using org.gcube.spatial.data.gis.GISInterface instance methods. At instantiation time, the caller decides the GeoServer pool that should be used by the library, either by declaring one or by using default behavior. This is done by calling the static method public static GISInterface get(AbstractGeoServerDescriptor... toUsePool).

Please note that default behavior should be preferred in order to correctly interact with the 'SDI.

Default Pool behavior

The default behavior of the library is to gather and cache SDI configuration from the IS. This is obtained by simply calling the static method public static GISInterface get(AbstractGeoServerDescriptor... toUsePool) with no arguments. See[Configuration] for cache configuration details.

Explicit Pool behavior

In same cases, like test runs, caller might want to explicit the GeoServer pool in order to force the library to interact with a specific set of GeoServer instances. This is done by calling the static method public static GISInterface get(AbstractGeoServerDescriptor... toUsePool) with the set of wanted GeoServer instances. The library will avoid interacting with the IS in order to get instances, ensuring the solely use of declared pool.

AbstractGeoServerDescriptor Class

Classes used by the GeoServer pool extend org.gcube.spatial.data.gis.is.AbstractGeoServerDescriptor class. It declares the base methods that describe a GeoServer instance, and leave its sublcasses to define how to retrieve these information. Expected information provided by this class and its implementations are :

  • Set<String> workspaces
  • Map<String,String> dataStores By workspaces
  • Set<String> existing styles
  • Long hosted layers count


The following 3 base classes are provided :

  • GeoServerDescriptor : This class holds its information in memory as a simple bean;
  • LiveGeoServerDescriptor : This class returns information by directly invoking the related GeoServer instance.
  • CachedGeoServerDescriptor : Extending LiveGeoServerDescriptor, it caches information in memory and invoke related GeoServer only if its cache is not valid.

The default class for the pool is CachedGeoServerDescriptor. To learn more about the pool configuration see [Configuration].

Pool initialization examples

Default pool initialization;

The pool is initialized (if not yet present) with a set of CachedGeoServerDescriptor related to information retrieved from Information System in the current context. 

GISInterface gis=GISInterface.get();
In memory information pool;

Here we specify all expected information in the declared beans, and tell the library to use this set as its GeoServer pool. 

GeoServerDescriptor geo1=new GeoServerDescriptor("..", "..", "...", 0l);
geo1.setDatastores(...);
geo1.setWorkspaces(...);
geo1.setStyles(...);
GeoServerDescriptor geo2=new GeoServerDescriptor("..", "..", "...", 0l);
 
GISInterface gis=GISInterface.get(geo1,geo2);

Read API

Select a GeoServer from the pool

In order to get GeoServer descriptor from the library's pool one must use one of the following : 

// Returns the first descriptor of the cache according to default Research Method.
AbstractGeoServerDescriptor getCurrentGeoServer();
 
// Returns the entire collection of the pool, prior refreshing its information (if forceUpdate == true)
SortedSet<AbstractGeoServerDescriptor> getCurrentCacheElements(Boolean forceUpdate);
 
//Returns the first element of the pool according to specified method, prior refreshing its information (if forceUpdate == true)
AbstractGeoServerDescriptor getGeoServerByMethod(ResearchMethod method, Boolean forceUpdate){

GeoServerRESTReader

AbstractGeoServerDescriptor implementations offer methods to directly interact with related GeoServer instance via the use of classes provided by it.geosolutions.geoserver-manager libraries. More information provided on section Raw Methods.

Publish API

The library expose different ways to interact with the SDI.

Orchestrated methods;

API exposed by the class org.gcube.spatial.data.gis.GISInterface. By operating across the SDI they ensure coherency and integrity of published data and metadata.

RAW methods;

API exposed by the underlying library it.geosolutions.geoserver-manager. In order to achieve flexibility, the GIS Interface library allows programmers to directly use this API for use cases not yet covered by Orchestrated methods. Since they directly interact with a specific instance of GeoServer, their use is discouraged in most cases.

Orchestrated Methods

To modify both data and metadata registered in the SDI, one should use the instance methods exposed by the class GISInterface. This grants the client a complete interaction with both GeoServer and GeoNetwork servers, assuring consistency between data and metadata. Following is a list of exposed methods (For more detailed information please refer to distributed javadoc maven artifact) :

  • Publish data and metadata altogether
    • addGeoTIFF
    • publishDBTable
  • Configure GeoServers (NB these methods operate on each GeoServer instance available in current context)
    • publishStyle
    • createDataStore
    • createWorkspace


The following code shows how to publish a layer from a table already created on a postgis database. Please note that the Database must already be registered onto the GeoServer instance as a store inside the workspace the user is willing to publish the layer into. 

import it.geosolutions.geoserver.rest.encoder.GSLayerEncoder;
import it.geosolutions.geoserver.rest.encoder.feature.GSFeatureTypeEncoder;
 
...
 
String scope="...";
String toPublishTable="...";
String datastore="...";
 
 
String defaultStyle="...";
String workspace="...";
 
//Setup geoserver publishing parameters
GSFeatureTypeEncoder fte=new GSFeatureTypeEncoder();
fte.setEnabled(true);
fte.setLatLonBoundingBox(-180.0, -90.0, 180.0, 90.0, crs);
fte.setName(toPublishTable);
fte.setNativeCRS(crs);
 
GSLayerEncoder le=new GSLayerEncoder();
le.setDefaultStyle(defaultStyle);
le.setEnabled(true);
 
//GCubeISOMetadata class belongs to org.gcube.spatial.data.geonetwork. Please refer to metadata generation in this page for further information
//Generate metadata for the layer to be published
ScopeProvider.instance.set(scope);
GcubeISOMetadata meta=new GcubeISOMetadata();
meta.set..
...
 
 
GISInterface gis=GISInterface.get();
 
PublishResponse resp=gis.publishDBTable(workspace, datastore, fte, le, meta.getMetadata(), "datasets", "_none_", LoginLevel.DEFAULT);

RAW Methods

In some cases, the developer wants to interact directly to a GeoServer instance by exploiting underlying library it.geosolutions.geoserver-manager. This can be done by using the following methods exposed by org.gcube.spatial.data.gis.is.AbstractGeoServerDescriptor described in section above. Exposed API methods are : 

public GeoServerRESTReader getReader() throws MalformedURLException;
public GeoServerRESTStoreManager getDataStoreManager() throws IllegalArgumentException, MalformedURLException;
public GeoServerRESTPublisher getPublisher() throws IllegalArgumentException, MalformedURLException;


GS Parameters

We decided not to override some parameter classes like GSLayerEncoder and GSFeatureTypeEncoder. So please refer to the geoserver-manager library's official documentation.

Metadata generation and publishing

Publishing of GIS metadata is made using org.gcube.spatial.data.geonetwork library. The library exposes facilities to help developers define layers metadata compliant with gCube SDI policies, especially the class org.gcube.spatial.data.geonetwork.iso.GcubeISOMetadata. Please refer to GeoNetwork library for further details.

Report classes

The results, status and contingent error messages of modifying operations are wrapped into the classes org.gcube.spatial.data.gis.model.report.PublishResponse and org.gcube.spatial.data.gis.model.report.DeleteReponse, both extending org.gcube.spatial.data.gis.model.report.Report class. Please refere to their javadoc pages for further information.

Retrieved from "https://gcube.wiki.gcube-system.org/index.php?title=GIS_Interface&oldid=35042"