Difference between revisions of "SDI Library"

From Gcube Wiki
Jump to: navigation, search
(Philosophy)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:gCube Features]]
 
[[Category:gCube Features]]
SDI Library is a java library designed to help developers interact with gCube SDI. It is the main entry point for developpers wanting to exploits client implementations towards the SDI subsystems (i.e. SDI-Service, GeoNetwork, GeoServer ).  
+
SDI Library is a java library designed to help developers interact with gCube SDI.It is part of the [[gCube-SDI-Suite]], and it is the main entry point for developpers wanting to exploits client implementations towards the SDI subsystems (i.e. SDI-Service, GeoNetwork, GeoServer ).  
 
It offers static gCube-fw-clients that communicate with [[SDI-Service]] for the management of gCube SDI and common publication features. It also manages client implementation for third-parties SDI technologies, allowing for direct communication with these subsystems.
 
It offers static gCube-fw-clients that communicate with [[SDI-Service]] for the management of gCube SDI and common publication features. It also manages client implementation for third-parties SDI technologies, allowing for direct communication with these subsystems.
  
Line 6: Line 6:
 
Following diagram illustrate the relations between the various clients components in '''gcube-sdi-suite'''.
 
Following diagram illustrate the relations between the various clients components in '''gcube-sdi-suite'''.
 
[[Image:SDI_clients.png|frame|center|SDI Clients]]
 
[[Image:SDI_clients.png|frame|center|SDI Clients]]
 
  
 
To external users, the main component of interest is '''sdi-library''', built on top of the ''sdi-interface'' which contains common classes definition.  
 
To external users, the main component of interest is '''sdi-library''', built on top of the ''sdi-interface'' which contains common classes definition.  
''SDI Library'' exposes basic gCube clients towards [[[SDI-Service]]] REST interfaces.  
+
'''SDI Library''' exposes basic gCube clients towards [[SDI-Service]] REST interfaces.  
''SDI Library'' also exposes means to dynamically load and instantiate client implementations for specific SDI subsystems (e.g. GeoServer, GeoNetwork).  
+
'''SDI Library''' also exposes means to dynamically load and instantiate client implementations for specific SDI subsystems (e.g. GeoServer, GeoNetwork).
 +
 
 +
Each client imeplementation exposes :
 +
* Information on internal implementation
 +
* Information on the ''target engine''
 +
* '''Range''' of supported version for the declared target engine.
  
 
=== Philosophy===
 
=== Philosophy===
 
The library has been designed to maximize isolation of dependencies : common complex logic is supported on services and client implementations are discovered at runtime.
 
The library has been designed to maximize isolation of dependencies : common complex logic is supported on services and client implementations are discovered at runtime.
  
The main library ''sdi-ibrary'' offers ways to obtain specific client implementation based on :  
+
The main library '''sdi-ibrary''' offers ways to obtain specific client implementation based on :  
  
 
* Information System Configuration : accessible third-parties services, configuration and version
 
* Information System Configuration : accessible third-parties services, configuration and version
Line 22: Line 26:
 
== Static Clients ==
 
== Static Clients ==
 
Static clients are directly defined in '''sdi-library''', so no dynamic loading is needed.  
 
Static clients are directly defined in '''sdi-library''', so no dynamic loading is needed.  
They are implemented as gCube-fw-clients towards [[[SDI Sevice]]] REST interfaces and cover most common use cases such as :  
+
They are implemented as gCube-fw-clients towards [[SDI Sevice]] REST interfaces and cover most common use cases such as :  
  
 
* Manage SDI configuration (instances, credentials, IS Resources)
 
* Manage SDI configuration (instances, credentials, IS Resources)
Line 30: Line 34:
  
 
=== SDI Management ===
 
=== SDI Management ===
 +
 +
SDI Management client communicates with [[SDI Service]] REST interface, and should be used for :
 +
 +
* Manage SDI Configuration
 +
* Inspect SDI-Health
 +
* Obtain specific client
 +
 +
Following sections describe common usage. Please, refere to [[SDI Service]] for further information.
 +
 +
==== Check current Scope Configuration ====
 +
Following example snippet shows how to printout current context's configuration
 +
 +
<source lang="java">
 +
import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
 +
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
 +
...
 +
 +
SDIManagement sdi=management().build();
 +
System.out.println(sdi.getConfiguration());
 +
</source>
 +
  
 
==== Instantiate specific client ====
 
==== Instantiate specific client ====
 
SDI Management should be used to dynamically instantiate client implementations against runtime configuration.  
 
SDI Management should be used to dynamically instantiate client implementations against runtime configuration.  
It deals with
+
 
 +
It automatically checks :
 +
* IS Configuration : in order to assess accessible subsystem and their configuration
 +
* CLASSPATH : in order to dynamically load available cients.
 +
* Supported engine version : REST API can drastically change from version, so specific plugins may be distributed.
 +
 
 +
Following example snippet shows how to obtain a client by its engineID and printout its exposed information.
 +
 
 +
<source lang="java">
 +
import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
 +
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
 +
...
 +
 
 +
String engineID=...
 +
System.out.println(management().build().getClientByEngineId(engineID).getInfo());
 +
</source>
  
 
== Dynamic Clients ==
 
== Dynamic Clients ==
=== GeoServer ===
+
Dynamic Clients are java components aimed at communicating with SDI subsystems (e.g. GeoServer, GeoNetwork..).
=== GeoNetwork ===
+
Available implementations are dynamically discovered through JAVA reflection, so beware that you have the wanted client in your CLASSPATH at runtime.
 +
 
 +
Each client exposes informations about :
 +
* Their internal implementation
 +
* Their Specific ID
 +
* The supported target Engine, identified by :
 +
** Engine ID : String representing the engine technology (e.g. "geonetwork")
 +
** Engine description : String describing the target engine and its developers.
 +
** Supported Version Range : Range of supported engine versions
 +
 
 +
Through [[#SDI Management]], Dynamic clients :
 +
* Are discovered in classpath at runtime
 +
* Their target engine is checked against current context configuration
 +
* They are automatically instantiated.
 +
 
 +
 
 +
Following sections described currently knows available implementations.
 +
 
 +
=== gCube GeoServer Client ===
 +
''gCube GeoServer Client'' is a java client over GeoServer REST API.
 +
 
 +
It is distributed as the following artifact :
 +
 
 +
<source lang="xml">
 +
<artifactId>gcube-geoserver-client</artifactId>
 +
<groupId>org.gcube.spatial.data</groupId>
 +
</source>
 +
 
 +
Following snippet illustrate how to instantiate the client and printout available workspaces:
 +
 
 +
<source lang="java">
 +
import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
 +
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
 +
import org.gcube.spatial.data.clients.model.engine.Engine;
 +
...
 +
 
 +
GSRESTClient gs=(GSRESTClient) management().build().getClientByEngineId(Engine.GS_ENGINE).getRESTClient();
 +
System.out.println(gs.getWorkspaces());
 +
</source>
 +
 
 +
=== gCube GeoNetwork Client  ===
  
 
== Use Cases ==
 
== Use Cases ==
 
=== Migrating from legacy GIS - Interface ===
 
=== Migrating from legacy GIS - Interface ===
 
=== Migrating from legacy Geonetwork library ===
 
=== Migrating from legacy Geonetwork library ===

Latest revision as of 15:22, 23 February 2021

SDI Library is a java library designed to help developers interact with gCube SDI.It is part of the gCube-SDI-Suite, and it is the main entry point for developpers wanting to exploits client implementations towards the SDI subsystems (i.e. SDI-Service, GeoNetwork, GeoServer ). It offers static gCube-fw-clients that communicate with SDI-Service for the management of gCube SDI and common publication features. It also manages client implementation for third-parties SDI technologies, allowing for direct communication with these subsystems.

Design

Following diagram illustrate the relations between the various clients components in gcube-sdi-suite.

SDI Clients

To external users, the main component of interest is sdi-library, built on top of the sdi-interface which contains common classes definition. SDI Library exposes basic gCube clients towards SDI-Service REST interfaces. SDI Library also exposes means to dynamically load and instantiate client implementations for specific SDI subsystems (e.g. GeoServer, GeoNetwork).

Each client imeplementation exposes :

  • Information on internal implementation
  • Information on the target engine
  • Range of supported version for the declared target engine.

Philosophy

The library has been designed to maximize isolation of dependencies : common complex logic is supported on services and client implementations are discovered at runtime.

The main library sdi-ibrary offers ways to obtain specific client implementation based on :

  • Information System Configuration : accessible third-parties services, configuration and version
  • Available implementations at runtime

Static Clients

Static clients are directly defined in sdi-library, so no dynamic loading is needed. They are implemented as gCube-fw-clients towards SDI Sevice REST interfaces and cover most common use cases such as :

  • Manage SDI configuration (instances, credentials, IS Resources)
  • Manage Application Profiles
  • Instantiate Dynamic clients
  • Common basic publish logic

SDI Management

SDI Management client communicates with SDI Service REST interface, and should be used for :

  • Manage SDI Configuration
  • Inspect SDI-Health
  • Obtain specific client

Following sections describe common usage. Please, refere to SDI Service for further information.

Check current Scope Configuration

Following example snippet shows how to printout current context's configuration

import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
...
 
SDIManagement sdi=management().build();
System.out.println(sdi.getConfiguration());


Instantiate specific client

SDI Management should be used to dynamically instantiate client implementations against runtime configuration.

It automatically checks :

  • IS Configuration : in order to assess accessible subsystem and their configuration
  • CLASSPATH : in order to dynamically load available cients.
  • Supported engine version : REST API can drastically change from version, so specific plugins may be distributed.

Following example snippet shows how to obtain a client by its engineID and printout its exposed information.

import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
...
 
String engineID=...
System.out.println(management().build().getClientByEngineId(engineID).getInfo());

Dynamic Clients

Dynamic Clients are java components aimed at communicating with SDI subsystems (e.g. GeoServer, GeoNetwork..). Available implementations are dynamically discovered through JAVA reflection, so beware that you have the wanted client in your CLASSPATH at runtime.

Each client exposes informations about :

  • Their internal implementation
  • Their Specific ID
  • The supported target Engine, identified by :
    • Engine ID : String representing the engine technology (e.g. "geonetwork")
    • Engine description : String describing the target engine and its developers.
    • Supported Version Range : Range of supported engine versions

Through #SDI Management, Dynamic clients :

  • Are discovered in classpath at runtime
  • Their target engine is checked against current context configuration
  • They are automatically instantiated.


Following sections described currently knows available implementations.

gCube GeoServer Client

gCube GeoServer Client is a java client over GeoServer REST API.

It is distributed as the following artifact :

<artifactId>gcube-geoserver-client</artifactId>
<groupId>org.gcube.spatial.data</groupId>

Following snippet illustrate how to instantiate the client and printout available workspaces:

import static org.gcube.spatial.data.sdi.plugins.SDIAbstractPlugin.management;
import org.gcube.spatial.data.sdi.interfaces.SDIManagement;
import org.gcube.spatial.data.clients.model.engine.Engine;
...
 
GSRESTClient gs=(GSRESTClient) management().build().getClientByEngineId(Engine.GS_ENGINE).getRESTClient();
System.out.println(gs.getWorkspaces());

gCube GeoNetwork Client

Use Cases

Migrating from legacy GIS - Interface

Migrating from legacy Geonetwork library