Difference between revisions of "GeoPortal Service"
(→Configuration) |
|||
(25 intermediate revisions by the same user not shown) | |||
Line 25: | Line 25: | ||
:Publication management implemented by an extendable set of Event Handlers; | :Publication management implemented by an extendable set of Event Handlers; | ||
:Behaviour configured in Profiles by declaring Event Handlers call in cascade; | :Behaviour configured in Profiles by declaring Event Handlers call in cascade; | ||
+ | |||
+ | Please refer to [[GeoPortal]] for conceptual informations. | ||
== Architecture == | == Architecture == | ||
− | === | + | [[Image:DataCube.png|frame|center|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. | ||
+ | |||
+ | [[Image:LC Management.png|frame|center|Projects Lifecycle Management]] | ||
== API == | == API == | ||
=== REST Interface === | === 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/". | ||
+ | |||
+ | ==== Profiles ==== | ||
+ | ==== 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 | ||
+ | |||
+ | |||
+ | {|class="wikitable" | ||
+ | |+ 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<br>Body : Filter || Returns all projects related to UCID and matching the Filter | ||
+ | |- | ||
+ | !Query | ||
+ | | POST ||query/<UCID>||Path : UCID<br>Body : QueryRequest || Returns all projects related to UCID and matching the QueryRequest | ||
+ | |} | ||
+ | |||
+ | {|class="wikitable" | ||
+ | |+ Projects lifecycle | ||
+ | !Method Name!!HTTP Method!!Sub Path!!Parameters!!Description | ||
+ | |- | ||
+ | !Create New | ||
+ | |POST|| <UCID>||Path : UCID<br>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<br>Body : ''Updated Project Document'' || Updates the corresponding project if any | ||
+ | |- | ||
+ | !Register FileSet By ID | ||
+ | | POST ||registerFiles/<UCID>/<ID>||Path : UCID,ID<br>Body : FileSet || Registers the FileSet into the corresponding project if any | ||
+ | |- | ||
+ | !Delete FileSet By ID | ||
+ | | POST ||deleteFiles/<UCID>/<ID>||Path : UCID,ID<br>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 | ||
+ | |} | ||
+ | |||
+ | {|class="wikitable" | ||
+ | |+ 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|GNA Usecase]]). | ||
+ | All exposed methods are listed in the tables below with path relative to BASE_PATH/'''mongo-concessioni'''. | ||
+ | {|class="wikitable" | ||
+ | |+ 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 | ||
+ | |} | ||
+ | |||
+ | {|class="wikitable" | ||
+ | |+ 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 | ||
+ | |} | ||
+ | |||
+ | {|class="wikitable" | ||
+ | |+ 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 ([https://docs.mongodb.com/v3.6/tutorial/query-documents/ MongoDB]). | ||
+ | |||
+ | '''Search''' method allows to specify filters just like with a MongoDB instance, like in the following examples (HTTP Request Body): | ||
+ | |||
+ | <syntaxhighlight lang="javascript" > | ||
+ | //Get validated | ||
+ | {"report.status": {$eq : "PASSED"}} | ||
+ | //All but fabio.sinibaldi's records | ||
+ | {"creationUser" : {$ne : "fabio.sinibaldi"}} | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | 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 | ||
+ | |||
+ | <syntaxhighlight lang="javascript" > | ||
+ | //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"}} | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
=== Client Library === | === Client Library === | ||
Java client library to interact with the service is distributed as maven artifact | Java client library to interact with the service is distributed as maven artifact | ||
Line 55: | Line 242: | ||
Following snippet shows typical usage : | Following snippet shows typical usage : | ||
− | < | + | <syntaxhighlight lang="java"> |
import static org.gcube.application.geoportal.client.GeoportalAbstractPlugin.mongoConcessioni; | import static org.gcube.application.geoportal.client.GeoportalAbstractPlugin.mongoConcessioni; | ||
Line 77: | Line 264: | ||
client.publish(mongoId); | client.publish(mongoId); | ||
− | </ | + | </syntaxhighlight> |
===== ConcessioniManagerI ===== | ===== ConcessioniManagerI ===== | ||
Line 84: | Line 271: | ||
Following snippet shows typical usage : | Following snippet shows typical usage : | ||
− | < | + | <syntaxhighlight lang="java"> |
import org.gcube.application.geoportal.client.GeoportalAbstractPlugin.statefulMongoConcessioni; | import org.gcube.application.geoportal.client.GeoportalAbstractPlugin.statefulMongoConcessioni; | ||
.... | .... | ||
Line 108: | Line 295: | ||
manager.publish(); | manager.publish(); | ||
− | </ | + | </syntaxhighlight> |
==== Utility Classes ==== | ==== Utility Classes ==== | ||
Line 115: | Line 302: | ||
Following snippet is a typical usage : | Following snippet is a typical usage : | ||
− | < | + | <syntaxhighlight lang="java"> |
StorageUtils storage=new StorageUtils(); | StorageUtils storage=new StorageUtils(); | ||
Line 122: | Line 309: | ||
TempFile toUpload=storage.putOntoStorage(myPayload, payloadName); | TempFile toUpload=storage.putOntoStorage(myPayload, payloadName); | ||
− | </ | + | </syntaxhighlight> |
− | == | + | == Configuration == |
+ | IS configuration for both the service and service plugins is reported at [[ServiceManager_Guide#Geoportal | here]]. |
Latest revision as of 12:40, 16 February 2023
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.
Contents
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
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.
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/".
Profiles
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
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 |
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 |
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.
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 |
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 |
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
IS configuration for both the service and service plugins is reported at here.