Revision as of 09:01, 1 December 2016

GRSF-services

In this page we describe the components that are responsible for interacting with the gCube infrastructure for performing various activities about GRSF records. GRSF records are handled as dataset resources and are stored in the data catalogue. The following image depicts a high level view of the architecture of components that are exploited for constructing the GRSF KB, publishing GRSF records and updating them. In the sequel we will focus and describe the components grsf-services-core and grsf-services-updater.

grsf-services-core

This component is responsible for retrieving individual records from the GRSF KB and publish them in the GRSF data catalogue. For this reason it uses the particular service (which is described at GCube_Data_Catalogue_for_GRSF). Since the service is accepting incoming records (either for stocks or fisheries) as JSON objects, the main functionality of the grsf-services-core component is to act a a bridge between the GRSF KB and the GRSF data catalogue. The corresponding steps for publishing a set of records is described below (and in the corresponding part of the sequence diagram).

1. The grsf-services-core component fetches all the GRSF records and their corresponding information from the GRSF KB. Since the GRSF KB is a semantic warehouse, its contents are stored as a set of RDF triples; therefore in order to fetch them a particular SPARQL query has to be formulated and submitted to the GRSF KB.
2. After fetching all the GRSF records (in terms of RDF triples), they have to be transformed so that they can be published through the publishing service of the GRSF data catalogue. The services accepts JSON object, therefore the RDF triples are transformed accordingly with respect to the expected metadata (which are described here).
3. The grsf-services-core component publishes the transformed JSON objects and retrieves the results.

The component is being delivered as a software library. It is being triggered from MatWare after the construction of the GRSF KB.

grsf-services-updater

This component is responsible for updating the status of a record, when the users requires so. More specifically the component is delivered as a service, that accepts incoming requests containing the record that will be updated, with its accompanying information (the new status, a narrative text describing the status update). Once a request has been received the service will update the contents in the GRSF KB, and return a response message information the caller for the results. The communication messages for the service are formulated JSON objects. The steps that are followed are described in detail below (with the corresponding part of the sequence diagram).

1. a new incoming request for a record status update is being received from the grsf-services-updater.
2. grsf-services-updater validates that the request contains valid data
3. grsf-services-updater updates the corresponding component in the GRSF KB. For this reason the appropriate SPARQL update query is being formulated and submitted to GRSF KB
4. grsf-services-updater returns a response (as a JSON object) with the result of the update process.

Check service availability

In order to check that the service is up and running you can use the following url

[GRSF_SERVICES-CORE BASE_URL]/grsf-services-updater

This will show a landing page with instructions for using the service indicating that the service is up and running.

Service input

The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.

An indicative example of a JSON object that can be used as input is the following.

{
  "catalog_id" : "cat-1234-5678-90",
  "record_id" : "rec-1234-5678-90",
  "type" : "stock",
  "status" : "rejected"
  "annotation_msg" : "the corresponding values for exploitation rate are missing" 
}

Service response

The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.

An indicative example of a JSON object that can be used as input is the following.

{
  "catalog_id" : "cat-1234-5678-90",
  "record_id" : "rec-1234-5678-90",
  "type" : "stock",
  "status" : "rejected"
  "annotation_msg" : "the corresponding values for exploitation rate are missing" 
  "error" : "The record ID does not exist in the GRSF KB"
}

Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:

• 200: it is returned if the request has been processed successfully, and the status of the corresponding record has been updated
• 400: it is returned if any of the given parameters that are mandatory is missing or contains incorrect values (i.e. a wrong status value)
• 404: it is returned if the record to be updated does not exist (i.e. cannot find the record ID in the GRSF KB)
• 500: it is returned for any error that might occur when updating the records in the GRSF KB

Service usage

The following JAVA application can be used for contacting the grsf-services-updater service for updating the status of a GRSF record.

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.MultiThreadedHttpConnectionManager;
import org.apache.commons.httpclient.methods.ByteArrayRequestEntity;
import org.apache.commons.httpclient.methods.PostMethod;
import org.json.simple.JSONObject;
 
/**
 * @author Yannis Marketakis (marketak 'at' forth 'dot' ics 'dot' gr)
 */
public class Client {
    private static final String SERVICE_BASE_URL="http://localhost:8080/grsf-services-updater"; //the URL of the deployed service
    private static final String SERVICE_POST_METHOD="service/updater/post";
 
    public static void main(String[] args){
        MultiThreadedHttpConnectionManager connectionManager=new MultiThreadedHttpConnectionManager();
        connectionManager.getParams().setSoTimeout(15000);
        HttpClient httpClient=new HttpClient(connectionManager);
 
        PostMethod method=new PostMethod(SERVICE_BASE_URL+"/"+SERVICE_POST_METHOD);
        method.setRequestHeader("Content-type", "application/json");
 
        JSONObject json=new JSONObject();
        json.put("catalog_id", "cat-123");
        json.put("record_id", "SKJ+IOTC");
        json.put("type", "stock");
        json.put("status", "pending");
 
        method.setRequestEntity(new ByteArrayRequestEntity(json.toJSONString().getBytes()));
        byte[] responseBody=null;
 
        try{
            int statusCode = httpClient.executeMethod(method);
            if (statusCode != HttpStatus.SC_OK && statusCode != HttpStatus.SC_CREATED) {
                System.out.println("Method failed: " + method.getStatusLine()+
                             "; Response bpdy: "+method.getResponseBodyAsString());
                method.releaseConnection();
                throw new Exception("Method failed: " + method.getStatusLine()+
                                    "; Response body: "+new String(method.getResponseBody()));
            }
            responseBody = method.getResponseBody();
            System.out.println(new String(responseBody));
        }catch (HttpException ex) {
                System.out.println("Fatal protocol violation: "+ex);
                method.releaseConnection();
        }catch (Exception ex) {
                System.out.println("Fatal transport error: "+ex);
                method.releaseConnection();
        }
        method.releaseConnection();
    }
}

For maven projects you should also use the following maven dependencies

<dependency>
   <groupId>commons-httpclient</groupId>
   <artifactId>commons-httpclient</artifactId>
   <version>3.1</version>
</dependency>
<dependency>
   <groupId>com.googlecode.json-simple</groupId>
   <artifactId>json-simple</artifactId>
   <version>1.1.1</version>
</dependency>

Links

Related tickets

• https://support.d4science.org/issues/5600
• https://support.d4science.org/issues/5890