GeoPortal Service

GeoPortal Service is a new REST service designed to manage complex space-temporal Documents defined by metadata Profiles. It has been released as a component of the gCube framework, and SmartGears powers it. It has been designed to manage publication lifecycle of complex space-temporal Documents, supporting their materialization & Indexing in different platforms (Databases, Catalogues, OGC Services..) and maximising reusability.

Overview

Users can define their model as a Profile in the VRE and then manage their Documents publication lifecycle both via gateway’s GUIs and by interacting with the service’s API (both JAVA and/or REST). The service provides a set of Handlers which can be declared and configured in the Profile (defaults apply) in order to be invoked in the different phases of the publication lifecycle. The set of Event Handlers is dynamically loaded by the service allowing support for custom implementation of Event Handlers. The provided java client library allows for dynamic model Serialization / Deserialization of custom provided Java model classes, allowing for easy integration of different systems.

Its main features are :

Documents Publication Management

CRUD (Create, Read, Update, Delete) operations, publication lifecycle, Profiles-based validation;

Role-based access to resources and metadata sections;

Cooperative workflow;

Automatic Indexing & aggregation based on Profiles annotations

GIS indexes (both centroids & multi-polygon), with dynamic aggregation based on zoom level;

Text indexes;

Time indexes and aggregation;

Extensible Document model

Generic meta-model Profile;

Custom extensions of the model;

Extensible behaviour

Core engine based on a meta-model;

Publication management implemented by an extendable set of Event Handlers;

Behaviour configured in Profiles by declaring Event Handlers call in cascade;

Please refer to GeoPortal for conceptual informations.

Architecture

GeoPortal Service Architecture

The service receives documents and stores them as Project linked to a Use Case Descriptor UCD which contains :

- Schemata - Workflow Management Configurations - GUIs Configurations

Configurations are then used to : - Perform management operations on Projects - Materialization and indexing of Projects related resources (files) - Access Project's data and metadata

Project Management

Every operation that changes the Phase of the document is called a STEP. Steps are implemented in handlers plugins and can be executed in cascade depending on implementation and configuration.

The following diagram shows the execution of a STEP. The plugin is only requested to implement the "Perform Step" operation.

The outcome of such operations is reported in Project section Lifecycle Information schematized in the diagram below.

Projects Lifecycle Management

API

REST Interface

This section describes the HTTP methods and interfaces exposed by the service. Base relative PATH for all interfaces (BASE_PATH) is "geoportal-service/srv/".

Projects

NB : This section is still in development and should be intended as blueprint. HTTP Interface for Project objects management.

All exposed methods are listed in the tables below with path relative to BASE_PATH/projects. NB : In the following tables UCID refers to UseCaseID

Access and search Methods

Method Name	HTTP Method	Sub Path	Parameters	Description
List	GET	<UCID>		List al registered projects related to specified UCID
Get By Id	GET	<UCID>/<ID>	Path : UCID,ID	Returns the corresponding project if any
Search	POST	search/<UCID>	Path : UCID Body : Filter	Returns all projects related to UCID and matching the Filter
Query	POST	query/<UCID>	Path : UCID Body : QueryRequest	Returns all projects related to UCID and matching the QueryRequest

Projects lifecycle

Method Name	HTTP Method	Sub Path	Parameters	Description
Create New	POST	<UCID>	Path : UCID Body : Document	Creates a new project
Delete By ID	DELETE	<UCID>/<ID>	Path : UCID,ID	Deletes the corresponding project if any
Update By ID	PUT	<UCID>/<ID>	Path : UCID,ID Body : Updated Project Document	Updates the corresponding project if any
Register FileSet By ID	POST	registerFiles/<UCID>/<ID>	Path : UCID,ID Body : FileSet	Registers the FileSet into the corresponding project if any
Delete FileSet By ID	POST	deleteFiles/<UCID>/<ID>	Path : UCID,ID Body : Path	Deletes the FileSet at Path in the corresponding project if any
Step By ID	PUT	step/<UCID>/<ID>	Path : UCID,ID	Advances the corresponding project status according to workflow

Management

Method Name	HTTP Method	Sub Path	Parameters	Description
Get Configuration	GET			Returns the current environment generated Informations

Concessioni

Custom prototype interface for GNA case study (See GNA Usecase). All exposed methods are listed in the tables below with path relative to BASE_PATH/mongo-concessioni.

Caption: Access and search Methods

Method Name	HTTP Method	Sub Path	Parameters	Description
List	GET			List al registered records
Get By Id	GET	<ID>	Path : ID	Returns the corresponding record if any
Search	POST	search	Body : Filter	Returns all records matching the Filter
Query	POST	query	Body : QueryRequest	Returns all records matching the QueryRequest

Caption: Concessioni lifecycle

Method Name	HTTP Method	Sub Path	Parameters	Description
Create New	POST		Body Concessioni record	Creates a new record
Delete By ID	DELETE	<ID>	Path : ID	Deletes the corresponding record if any
Update By ID	PUT	<ID>	Path : ID	Updates the corresponding record if any
Publish By ID	PUT	publish/<ID>	Path : ID	Publishes the corresponding record if any
Unpublish By ID	DELETE	publish/<ID>	Path : ID	Unpublishes the corresponding record if any
Register FileSet By ID	POST	registerFiles/<ID>	Path : ID,</br>Body : FileSet	Registers the FileSet into the corresponding record if any	Unregister FileSet By ID	POST	deleteFiles/<ID>	Path : ID,</br>Body : Path	Deletes the FileSet in the corresponding record/path if any

Caption: Management

Method Name	HTTP Method	Sub Path	Parameters	Description
Get Configuration	HEAD			Returns the current environment configuration
Replace	PUT		Body : Concessioni record	Replaces any existing record with the same ID (if any) as passed parameter's

Search and Query Methods

Search and Query methods allows refined access to registered records by exploiting the underlying Document Store DB (MongoDB).

Search method allows to specify filters just like with a MongoDB instance, like in the following examples (HTTP Request Body):

//Get validated
{"report.status": {$eq : "PASSED"}}
//All but fabio.sinibaldi's records
{"creationUser" : {$ne : "fabio.sinibaldi"}}

While Search methods accept Filters as directly supported by the underlying engine, the Query method introduces a proprietary JSON object allowing for:

• Filtering
• Ordering
• Paging
• Projection

//Get last registered record
{
  "paging" : {
    "offset" : 0,
    "limit" : 1
  },
  "ordering" : {
    "direction" : "DESCENDING",
    "fields" : ["creationTime","nome"]
  }
}
 
//Get last registerd record by fabio.sinibaldi
{
  "paging" : {
    "offset" : 0,
    "limit" : 1
  },
  "ordering" : {
    "direction" : "DESCENDING",
    "fields" : ["creationTime","nome"]
  }
  "filter" : {"creationUser" : {$eq : "fabio.sinibaldi"}}
}

Client Library

Java client library to interact with the service is distributed as maven artifact

<groupId>org.gcube.application</groupId>
<artifactId>geoportal-client</artifactId>

The library offers various wrappings of the REST interface, allowing for :

• Both Custom & Generic management of Profiled Documents ;
• Both Custom & Generic automatic parsing of JSON communications over REST interface;
• Transparent authentication and service discovery, thanks to gCube Framework;

Generic Profiled Documents Managers

• ProfiledDocumentsManagerI : JAVA interface for the management of Profiled Documents.

Custom Concessioni Managers

The library provides the following customized versions of the generic clients in order to manage Concessioni Documents :

MongoConcessioni

Interface for the stateless management of Concessioni Documents. It reflects the contract of the generic REST API. Following snippet shows typical usage :

import static org.gcube.application.geoportal.client.GeoportalAbstractPlugin.mongoConcessioni;
...
 
Concessione c=...
 
//Register New Concessione
c=client.createNew(c);
 
// Upload files to Concessione Section by Path (e.g. Relazione)
String mongoId=c.getMongo_id();	
List<TempFile> files=...
AddSectionToConcessioneRequest request=	new AddSectionToConcessioneRequest(Paths.RELAZIONE, files);
 
client.registerFile(mongoId, request);
 
 
// Publish
 
client.publish(mongoId);

ConcessioniManagerI

Interface for the statefull creation of Concessioni Documents. Stateful logic helps client to manage the management of the last loaded/registered Concessione, offering dedicated methods for adding FileSets (e.g. RelazioneScavo) to the current Document.

Following snippet shows typical usage :

import org.gcube.application.geoportal.client.GeoportalAbstractPlugin.statefulMongoConcessioni;
....
 
//Obtain the client
ConcessioniManagerI manager=statefulMongoConcessioni().build();
...
 
//Create a new Document from scratch
Concessione c = ...
...
manager.createNew(c);
 
//Adds an UploadedImage to the current document
 
UploadedImage toRegisterImg= ...
TempFile toUpload=....
 
manager.addImmagineRappresentativa(toRegisterImg, toUpload);
 
 
//Publishes current object
manager.publish();

Utility Classes

StorageUtils

In order to transfer FileSets to the REST service, an utility class is provided, allowing for the management of infrastructure's TempFiles. Following snippet is a typical usage :

StorageUtils storage=new StorageUtils();
 
InputStream myPayload=...
String payloadName=...
 
TempFile toUpload=storage.putOntoStorage(myPayload, payloadName);

Configuration

Mongo DB

The service uses a mongo DB instance for its internal archive. It looks for a Service Endpoint with the following characteristics :

• Category : Database
• Platform Name : mongodb

And uses the Access Point with the following parameter (older versions):

• Key : GNA_DB
• Value : internal-db

UCD

Current UCD provider implementation relies on the following Generic Resource in order to assess the available UCDs in a VRE :

• Secondary Type : "CMS"
• Name : "UCDs"

It is expected to declare links to UCD documents, which they are then loaded into the application. It's body format must like in the following example :

<UCDs>   
    <record label=.. ucdUrl=... />
    <record label=.. ucdUrl=... />
    ...
</UCDs>

Plugin Requirements

SDI Plugins

SDI plugins rely on the presence of Geoserver for materialization purposes. SDI Indexer expects a postgis DB registered in the gCube IS as Service Endpoint with the following characteristics :

• Category : Database
• Platform Name : postgis

And uses the Access Point with the following parameter (older versions):

• Key : GNA_DB
• Value : Concessioni