Difference between revisions of "URI Resolver"

Revision as of 17:08, 5 December 2018

The URI Resolver is a RESTful service which gives access via HTTP(s) to different gCube Resolver services and gCube Applications (like GisViewer) used into the D4Science Infrastructure.

Maven

The artifact is available on Nexus with the following coordinates:

  <groupId>org.gcube.data.transfer</groupId>
  <artifactId>uri-resolver</artifactId>
  <version>LATEST</version>
  <type>war</type>

Runtime Resource

The address and the configuration information of the servlet are registered on the gCube Information System as Runtime Resource (RR).

You can see the configuration through Monitor service (https://services.d4science.org/infrastructure-monitor) searching in the root scope the RR with following:

<Type>RuntimeResource</Type>
<Category>Service</Category>
<Name>HTTP-URI-Resolver</Name>

You must copy such runtime resource in VRE scope if it is need to work at VRE level

Query

The following code snippet can be used to retrieve from the gCube Information System the info to configure the resolver

 
        ScopeProvider.instance.set(<scope>);
 
	XQuery query = queryFor(ServiceEndpoint.class);
 
	query.addCondition("$resource/Profile/Name/text() eq 'HTTP-URI-Resolver'").setResult("$resource/Profile/AccessPoint");
 
	DiscoveryClient<AccessPoint> client = clientFor(AccessPoint.class);
 
	List<AccessPoint> endpoints = client.submit(query);
 
	if (endpoints.size() == 0)
		throw new Exception("No Resolver available");
 
	//Base Address
        System.out.println(endpoints.get(0).address());
        //Query URL parameter
	System.out.println(endpoints.get(0).propertyMap().get("SMP_URI_parameter").value());

Retrieve web service endpoint

The service endpoint URL [URI_RESOLVER_SERVICE_ENDPOINT] of Resolver services is:

for the development environment

http://data-d.d4science.org

for the production environment

http://data.d4science.org

Resolvers

SMP Resolver

The first version of the component is able to give HTTP resolution to SMP protocol URIs [1].

Once deployed in a SmartGear container as Tomcat, the service can be used to resolve SMP URIs as follows:

URL url = new URL("http://<hostname>:<port>/uri-resolver/smp?smp-uri=smp://.....);

The HTTP URI can be also used to retrieve files using wget or trough a Web Browser:

[URI_RESOLVER_SERVICE_ENDPOINT]/smp?smp-uri=[STORAGE_URI]&fileName=[FILENAME]&contentType=[CONTENT_TYPE]

Apart from the smp-uri mandatory parameter, two optional paramters can be used:

• fileName : to specify the output file name ( default: fromStorageManager)
• contentType : to specify the output file content-type ( default: unknown/unknown)

SMP-ID Resolver

The resolver is able to give HTTP resolution to storage resource by ID [2].

[URI_RESOLVER_SERVICE_ENDPOINT]/id?smp-id=[STORAGE_SMP_ID]&fileName=[FILENAME]&contentType=[CONTENT_TYPE]

For instance, in the development environment you can download the following file with WGET command or through a Web Browser by using the link:

http://data-d.d4science.org/id?smp-id=553f9265e4b0567b75021fce&fileName=dog&contentType=image%2Fjpg

Apart from the smp-id mandatory parameter, SMP-ID Resolver uses two optional parameters (in the query string):

• fileName : to specify the output file name (default: fromStorageManager)
• contentType : to specify the output file content-type (default: unknown/unknown)

The two default cases above will be used if and only if the file name and content-type (mime type) cannot be read from metadata of the file saved in the Storage.

Therefore, in this order:

- Either fileName is read from query string or is read from storage metadata otherwise is default: "fromStorageManager"

- Either contentype is read from query string or is read from storage metadata otherwise is default: "unknown/unknown"

STORAGE-ID Resolver

This works as #SMP-ID Resolver using links having the format:

[URI_RESOLVER_SERVICE_ENDPOINT]/[STORAGE_ID]

HEAD HTTP

STORAGE-ID Resolver implements the HTTP doHead operation. It performs a payload validation (checking if it exists in the storage area) for the resource ID required:

- if the payload exists: it returns status 200 the content-type and content-disposition of the file in the HTTP response;

- if the payload does not exist: it returns status 404 in the HTTP response.

STORAGE-HUB Resolver

The StorageHub Resolver is reachable at the following:

[URI_RESOLVER_SERVICE_ENDPOINT]/shub/[STORAGE_HUB_FILE_ID]

It provides the HTTP GET method to allow the download of the gCube Workspace file with ID [STORAGE_HUB_FILE_ID] via the StorageHub facility.

GIS Resolver

The first version of the component is able to give HTTP resolution (as redirect to Gis Viewer Application) to display and navigate on map the gis layers stored in iMarine Geonetwork #iMarine_GeoNetwork

The Gis Resolver can be used to resolve Gis Layer using a Web Browser link as follows:

[URI_RESOLVER_SERVICE_ENDPOINT]/gis?gis-UUID=[UUID]&scope=[SCOPE]

The link must include two mandatory parameters:

• gis-UUID : to specify the Metadata Universally Unique Identifier (UUID - used in iMarine Geonetwork). The UUID identifies the gis layer which you want to show in Gis Viewer Application
• scope : to specify the "scope" for discovering the iMarine GeoNetwork service (e.g. scope=/gcube/devsec/devVRE)

Runtime Resource

In order to work, it is necessary to copy from Root scope (/d4science.research-infrastructures.eu) to the VRE where Gis-Resolver must work, the runtime resource with following coordinates:

<Type>RuntimeResource</Type>
<Category>Service</Category>
<Name>Gis-Resolver</Name>

Generic Resource for Gis Viewer Application

It is necessary to edit the generic resource "Gis Viewer Application" in the Root scope (/d4science.research-infrastructures.eu) adding the VRE scope where the GisViewerApplication must work.

The Generic Resource "Gis Viewer Application" coordiantes are:

<Type>GenericResource</Type>
<SecondaryType>ApplicationProfile</SecondaryType>
<Name>Gis Viewer Application</Name>

CATALOGUE Resolver

This works as an HTTP Resolver to get/resolve a link to a "Catalogue Entity" stored in one of the instances of gCube Data Catalogue

A Catalogue Entity is either a "group" or an "organization" or a "product" of gCube Data Catalogue.

HTTP POST: Create an Item URL

The resolver provides HTTP POST operation to build a link to a "Catalogue Entity" stored into a specific gCube Data Catalogue.

In order to give a catalogue link for a catalogue entity is needed to pass in the body of the POST request a JSON with the fields:

• gcube_scope as mandatory field. It is the gcube scope where to search the gCube Catalogue Portlet;
• entity_context as mandatory field. It can be: "dataset" or "product", "group", "organization";
• entity_name as mandatory field. It is the entity name, that is its CKAN URL.

Where the JSON format is the following one:

{
"gcube_scope" : "[gcube_scope value]",
"entity_context" : "[entity_context value]",
"entity_name" : "[entity_name value]"
}

How to create the Catalogue Link

You need to perform a POST request to the resolver

[URI_RESOLVER_SERVICE_ENDPOINT]/catalogue

by using:

- the header parameter Content-Type: application/json;

- the body with the JSON format as above specified (the response returns an HTTP link).

An instance of body could be [ex. 1]:

{
"gcube_scope" : "/gcube/devsec/devVRE",
"entity_context" : "dataset",
"entity_name" : "sarda-sarda"
}

The HTTP Response returned:

The response returns in the body a "brief URL" in clear of kind:

[URI_RESOLVER_SERVICE_ENDPOINT]/[ctlg|ctlg-p|ctlg-d|ctlg-o|ctlg-g]/[VRE_NAME]/[entity_name value]

Where:

ctlg | ctlg-p | ctlg-d | ctlg-o | ctlg-g are codes to resolve the couple "catalogue"-"entity_context_value", in detail:

ctlg -> this one is default value to refer a 'product'|'dataset'

ctlg-p|d -> to refer respectively a 'product'|'dataset'

ctlg-o -> to refer an 'organization'

ctlg-g -> to refer a 'group'

For instance, using the request of [ex. 1] in the development environment, the HTTP response returns in the body the URL:

http://data-d.d4science.org/ctlg/devVRE/sarda-sarda

HTTP GET: Resolve an Item URL

The resolver provides HTTP GET operation to give HTTP resolution (as HTTP redirect) for displaying the 'entity_name' through an instance of "gCube Data Catalogue Portlet" (this last one is resolved by the 'gcube_scope' used to generate the catalogue link)

Geonetwork Resolver

The 'Geonetwork Resolver' is a "middle tier" (like a Proxy) to perform queries on gCube Geonetwork services. It uses the 'Geonetwork Manager library' to discovery Geonetwork configurations like: Geonetwork service end-point, Geonetwork accounts and so on. Using the Geonetwork configurations discovered the resolver performs authentication on Geonetwork (if needed) and then forward the requests received to harvesting metadata on that Geonetwork. Authentication is needed to get layers stored as private on Geonetwork.

The resolver is reachable at the following:

[URI_RESOLVER_SERVICE_ENDPOINT]/geonetwork

later referred like "GEONETWORK_RESOLVER_BASE_URL".

The 'Geonetwork Resolver' provides the HTTP GET method that supports the following protocol:

http[s]://[GEONETWORK_RESOLVER_BASE_URL]/[SCOPE]/[MODE]/[VISIBILITY]/[FILTER_KEY]/[FILTER_VALUE]/$$

In detail, the protocol parameters are:

• SCOPE (mandatory): the gCube scope used via 'Geonetwork Manager library' to discovery the Geonetwork service end-point and other configurations (like Geonetwork accounts and so on). It must be separated by character pipe '|'. i.e. gcube|devNext|NextNext;
• MODE (mandatory): must be 'VRE' or 'HARVEST'. To harvest at VRE level or External GEONETWORK level;
• VISIBILITY (mandatory): must be 'PUB' or 'PRV'. When PUB: only public layer/s is/are returned. When PRV: only private layer/s is/are returned;
• FILTER_KEY/FILTER_VALUE (mandatory): couple key/value passed in the path to filter on one of geonetwork:info field returned by ISO19139 schema. Only layer/s complying the filter criteria are returned (i.e. The filter category/interactiveResources returns only the layers belonging to GN category "Interactive resources"). The default value must be null/null if you don't want to apply any filter;

• REQUEST DELIMITER (mandatory). must be '$$'. It is the delimiter to specify the end of the path.

i.e. CKAN harvester configured to retrieve metadata by the URL: https://data.d4science.org/geonetwork/d4science.research-infrastructures.eu%7CgCubeApps%7CRPrototypingLab/VRE/PRV/null/null/$$

Where:

• GEONETWORK_RESOLVER_BASE_URL has value: https://data.d4science.org, so the Geonetwork Resolver service endepoint is: https://data.d4science.org/geonetwork;
• SCOPE has value: 'd4science.research-infrastructures.eu|gCubeApps|RPrototypingLab';
• MODE has value: 'VRE';
• FILTER_KEY has value: null and FILTER_VALUE has value: null;
• VISIBILITY has value: 'PRV';

It retrieves all private layers of the VRE RPrototypingLab.

Parthenos URL Resolver

(DRAFT) This resolver is reachable at:

[URI_RESOLVER_SERVICE_ENDPOINT]/parthenos_registry

It exposes the HTTP methods:

• GET - to resolve an "item" from a Parthenos URL stored in the Parthenos Catalogue at https://ckan-parthenos.d4science.org/
• POST - to get a normalized item name from a Parthenos URL. It applies a normalization function to get from an input Parthenos URL an item name that is catalogue compliant.

HTTP POST: Get normalized Item Name

The resolver provides HTTP POST operation to request a normalized item name for an input Parthenos URL.

It reads the input Parthenos URL (from the 'entity_name' field of a JSON object) and returns its normalized name (as plaintext) to the Parthenos Catalogue URL.

You need to perform a POST request to the resolver parthenos_registry by adding the HTTP header Content-Type: application/json and passing in the body a JSON object with the following format:

{
"entity_name" : "[PARTHENOS entity_name value]"
}

An instance of body could be:

{ "entity_name": "/Culturalitalia/unknown/Dataset/oai%3Aculturaitalia.it%3Aoai%3Aculturaitalia.it%3Amuseiditalia-mus_11953" }

and in this case the POST response returns:

- as plaintext in the body: culturalitalia_unknown_dataset_oaiculturaitaliaitoaiculturaitaliaitmuseiditalia_mus_11953

- as Location parameter (in the HTTP header): https://parthenos.d4science.org/group/parthenos_registry/catalogue?path=/dataset/culturalitalia_unknown_dataset_oaiculturaitaliaitoaiculturaitaliaitmuseiditalia_mus_11953

HTTP GET: Resolve a Parthenos URL

The resolver provides HTTP GET operation to return the Parthenos Catalogue URL of an "item" stored as Parthenos URL in the (Parthenos) Catalogue

You simply by resolving via browser the HTTP link of a Parthenos URL (stored in the Parthenos Catalogue), you are performing a GET request to the resolver parthenos_registry to get its Parthenos Catalogue URL.

Analitycs Resolver

(In progess)

The resolver provides a method to get the Analitycs URLs (that are simply URLs) by which is possible to invoke through the DataMiner App the run of an algorithm stored in a certain VRE. By the DataMiner App then the user is able to monitoring the algorithm execution.

The DataMiner Resolver is reachable at:

[URI_RESOLVER_SERVICE_ENDPOINT]/analytics

It exposes the HTTP methods:

• GET - to resolve an Analitycs URL (created by POST method) that invokes the "run" operation for an algorithm stored in a VRE;
• POST - to generate an Analitycs URL (then resolved by GET method) for a certain algorithm of a VRE.

HTTP POST: Create an Analitycs URL

This resolver is reachable at the following:

[URI_RESOLVER_SERVICE_ENDPOINT]/analytics/create

It provides the HTTP POST method to create Analitycs URLs. In order to obtain an Analitycs URL, you need to know the scope (that is the VRE) the identifier and the parameters to call the algorithm/operator in the VRE.

If you know these things, you can perform a POST request to the resolver /analytics/create by adding the HTTP header Content-Type: application/json and passing in the body a JSON object with the following format:

{
  "scope": "[scope_value]",
  "operatorId": "[operator_identifier]",
  "parameters": {
    "param1": "value1",
    "param2": "value2",
    .....
    "paramN": "valueN"
  }
}

An instance of the body could be:

{
   "scope":"/gcube/preprod/preVRE",
   "operatorId":"org.gcube.dataanalysis.wps.statisticalmanager.synchserver.mappedclasses.transducerers.MPA_INTERSECT",
   "parameters":{
      "mpaIdentifier":"1"
   }
}

and in this case the POST response returns as plaintext in the body (and as value of header parameter Location) the following Analitycs URL [ex.1]:

http://data1-d.d4science.net/dataminer/preVRE/org.gcube.dataanalysis.wps.statisticalmanager.synchserver.mappedclasses.transducerers.MPA_INTERSECT?mpaIdentifier=1

HTTP GET: Resolve an Analitycs URL

This resolver is reachable at

[URI_RESOLVER_SERVICE_ENDPOINT]/analytics/get

It provides the HTTP GET method to resolve an Analitycs URL.

For instance, by calling the GET method on the previous Analitycs URL [see ex.1] it will be resolved as:

https://pre.d4science.org/group/prevre/dataminer-manager?OperatorId=org.gcube.dataanalysis.wps.statisticalmanager.synchserver.mappedclasses.transducerers.MPA_INTERSECT&mpaIdentifier=1

KNIME Resolver

(In progess)

Uri Resolver Manager

The Uri Resolver Manager is a library to get a public link of a resource reachable from a (Gcube) Http Resolver

At moment, the resource types are GIS or SMP reachable from Uri-Resolver and Gis-Resolver.

The Uri Resolver Manager look up the (Generic Resource) "Uri-Resolver-Map" to read the mapping: Application Type -> (Runtime Resource of its) Resolver, e.g. GIS -> Gis-Resolver, SMP -> HTTP-URI-Resolver

The mandatory parameters to forward correctly the HTTP request to Resolver are dynamically read from Runtime Resource

Maven

The artifact is available on Nexus with the following coordinates:

   <groupId>org.gcube.portlets.user</groupId>
   <artifactId>uri-resolver-manager</artifactId>
   <version>LATEST</version>

A simple java How-to:

public static void main(String[] args) {
 
		try {
                        ScopeProvider.instance.set("/gcube/devsec/devVRE");
			UriResolverManager resolver = new UriResolverManager("GIS");
			Map<String, String> params = new HashMap<String, String>();
			params.put("gis-UUID", "eb1a1b63-f324-47ee-9522-b8f5803e19ec");
			params.put("scope", "/gcube/devsec/devVRE");
			String shortLink = resolver.getLink(params, true); //true, link is shorted otherwise none
			System.out.println(shortLink);
		} catch (UriResolverMapException e) {
			e.printStackTrace();
		} catch (IllegalArgumentException e) {
			e.printStackTrace();
		}catch (Exception e) {
			e.printStackTrace();
		}
	}

Generic Resource

In order to work, it is necessary to copy from Root scope (/d4science.research-infrastructures.eu) to the VRE where Uri Resolver Manager must work, the generic resource with following coordinates:

<Type>GenericResource</Type>
<SecondaryType>UriResolverMap</SecondaryType>
<Name>Uri-Resolver-Map</Name>