Difference between revisions of "GCube Data Catalogue for GRSF"

From Gcube Wiki
Jump to: navigation, search
(Metadata)
(GRSF Publication Web Service)
Line 550: Line 550:
  
 
== GRSF Publication Web Service ==
 
== GRSF Publication Web Service ==
Publication of products is performed by means of a RESTful web service. Almost every call to the service requires the security token of the user for the context in which he wish to publish or exploit the other functionalities. Please note that in case of product publication it is needed that the user has enough privileges. The list of roles and associated privileges for the catalogue users is reported [https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue#Users.2C_Roles_and_Groups here]. The VRE Manager assignes them.  
+
Publication of products is performed by means of a RESTful web service running over SmartGears. Almost every call to the service requires the security token of the user for the context in which he wish to publish or exploit the other functionalities. Please note that in case of product publication it is needed that the user has enough privileges. The list of roles and associated privileges for the catalogue users is reported [https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue#Users.2C_Roles_and_Groups here]. The VRE Manager assignes them.  
  
 
In order to retrieve your security token you can use the [https://wiki.gcube-system.org/gcube/Token_generator token generator] portlet.
 
In order to retrieve your security token you can use the [https://wiki.gcube-system.org/gcube/Token_generator token generator] portlet.
  
The right address for contacting the service in the GRSF context can be discovered by means of the Information System <ref name="ic-client"> Information System can be queried via ic-client [https://wiki.gcube-system.org/gcube/Ic-client read more]</ref>. You need the following parameters
+
The right address for contacting the GRSF service in a context can be discovered by means of the Information System <ref name="ic-client"> Information System can be queried via ic-client [https://wiki.gcube-system.org/gcube/Ic-client read more]</ref>. You need the following parameters
  
 
<source lang="xml">
 
<source lang="xml">
Line 567: Line 567:
  
 
<source lang="xml">
 
<source lang="xml">
https://next.d4science.org/grsf-publisher-ws/rest/  [GRSF_PUBLISHER_WS_BASE_URL]
+
https://smart-grsf-d-d4s.d4science.org/grsf-publisher-ws/rest/  [GRSF_PUBLISHER_WS_BASE_URL]
 
</source>
 
</source>
  
The token for testing purpose can be retrieved from the VRE at this url https://next.d4science.org/group/nextnext/home (register yourself if needed)
+
The token for testing purpose can be retrieved from the VRE at this url https://next.d4science.org/group/nextnext/home (register yourself if needed).
 +
In the following, every time you perform a request you must specify the type of record for which it will be valid, i.e., in the request path you need to specify a value among:
 +
* grsf;
 +
* fishsource;
 +
* ram;
 +
* firms.
  
 
=== Check Service Availability ===
 
=== Check Service Availability ===
Line 577: Line 582:
  
 
<source lang="xml">
 
<source lang="xml">
[GRSF_PUBLISHER_WS_BASE_URL]/fishery/hello
+
[GRSF_PUBLISHER_WS_BASE_URL]/{...}/fishery/hello
 
</source>
 
</source>
  
and the response should look like
+
Specify the record type by replacing {...}. The response should look like
  
 
<source lang="xml">
 
<source lang="xml">
Line 589: Line 594:
  
 
<source lang="xml">
 
<source lang="xml">
[GRSF_PUBLISHER_WS_BASE_URL]/stock/hello
+
[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/hello
 
</source>
 
</source>
  
Line 603: Line 608:
  
 
<source lang="xml">
 
<source lang="xml">
[GRSF_PUBLISHER_WS_BASE_URL]/fishery/get-licenses?gcube-token=YOUR_TOKEN
+
[GRSF_PUBLISHER_WS_BASE_URL]/{...}/fishery/get-licenses?gcube-token=YOUR_TOKEN
 
</source>
 
</source>
  
Line 609: Line 614:
  
 
<source lang="xml">
 
<source lang="xml">
[GRSF_PUBLISHER_WS_BASE_URL]/stock/get-licenses?gcube-token=YOUR_TOKEN
+
[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/get-licenses?gcube-token=YOUR_TOKEN
 
</source>
 
</source>
  
Line 631: Line 636:
 
=== Stock Publication Example ===
 
=== Stock Publication Example ===
  
The publish method to invoke to publish a stock is the following
+
The publish method to invoke to publish a stock for rams, grsf, fishsource or ram is the following
  
 
<source lang="xml">
 
<source lang="xml">
[GRSF_PUBLISHER_WS_BASE_URL]/stock/publish-product?gcube-token=YOUR_TOKEN
+
[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/publish-product?gcube-token=YOUR_TOKEN
 
</source>
 
</source>
  
Line 673: Line 678:
 
<source lang="xml">
 
<source lang="xml">
 
{
 
{
   "id": ... , // identifier of the created product
+
   "id": ... , // identifier of the created product in the catalogue
   "dataset_url": ..., // url of the created product
+
   "knowledge_base_id" : .... // identifier of the product in the knowledge base
 +
  "product_url": ..., // url of the created product
 
   "error": ... // in case of error, check this field
 
   "error": ... // in case of error, check this field
 
}
 
}

Revision as of 17:08, 3 December 2016

** THIS PAGE IS UNDER CONSTRUCTION **

GCube Data Catalogue: support for GRSF

In this page are reported the relevant information about the GRSF Data Catalogue, which is available here. This page is somehow an extension of the main gCube Data Catalogue guide, you are suggested to read before continue.

The GRFS Data Catalogue stores, as well as allows the publication of products of two types: Stock and Fishery. Apart from the default set of metadata, each type of product will also have specific fields. Some of them will also become automatically tags of the product. The same reasoning applies for group associations. In fact a set of groups was already available and each product will be automatically associated to them during publication, if that is the case. Fields that fire tags creation or groups association are documented below.

The publication phase is performed by means of a RESTful service whose publish methods accept JSON objects. The service allows also to publish records belonging to the original source records (i.e., "RAM", "FishSource" and "FIRMS") on which the aggregated GRSF records are build.

Metadata

Common Metadata

The following table shows the set of core metadata, that is the ones shared by both Stock and Fishery types. Some of them are automatically filled. The values given to some fields are automatically used to tag the product. Check the 'Is Tag' column of the table below. Other fields have a controlled vocabulary (that is, they can assume values selected from a defined set), and the value assigned to these fields allow to automatically determine to which group assign the product. Check the 'Is Group' column below.

The table also reports the column Type that shows how the field is mapped into the product, once it is published within the catalogue, i.e. as a simple field (key/value pair, possibly repeatable) or a resource (an object with a mandatory name, an optional description and a mandatory url).

IMPORTANT: Any other field that doesn't match one of the below ones will be managed as an object having a key and a value, both of String type, and attached to the product as a simple field.

Name Api Name (JSON) Mandatory (No, Aggregated, All) * Is Tag (Aggregated records only) Is Group Type Example Guidelines/Comments
Title stock_name or fishery_name All No No Field
Description description No No No Field This product contains attributes of ... A brief description of the dataset written in plain language. It should provide a sufficiently comprehensive overview of the resource for anyone to understand its content origins and any continuing work on it.
License license_id All No No Field CC-BY-SA-4.0 The list of licenses' ids can be retrieved by using the service (see below). By default the CC-BY-SA-4.0 will be used.
Author author No No No Field Bloggs, Joe This field is automatically compiled by using the information of the caller entity.
Author contact author_contact No No No Field joe.blogg@example.com This field is automatically compiled by using the information of the caller entity
Maintainer maintainer No No No Field A person: Bloggs, Joe. An authority: D4Science Mantainer of the dataset
Maintainer Contact maintainer_contact No No No Field joe@example.com Contact details of the resource maintainer.
Version version No No No Field 1.0 Increase manually after editing
Extra Fields extras_fields No No No Field(s) {"extras_fields":{"other_key":[{"value1", "value2", ...}], "other_keyN": [{"valueN" "valueM"}]}} It is a map of objects <key, list of values> that allow to dynamically add extra fields if the list of recognized fields by the service doesn't fit some needs.
Extra Resources extras_resources No No No Resources(s) {"extras_resources":[{"url": "http:// .....", "name": "...", "description":"...."}, ....]} It is a list of objects of the type {"url": ..., "name": ...., "description": ...} that allow to dynamically add extra resources if the list of recognized resources by the service doesn't fit some needs. Please note that "url" and "name" are mandatory.

* specifies if an attribute is not mandatory (No), mandatory for GRSF aggregated records (Aggregated) or is mandatory for every record (All)

Besides the above common metadata, there is the following set of attributes that are captured for both Stock and Fishery objects.

Name Api Name (JSON) Mandatory (No, Aggregated, All) * Is Tag (Aggregated records only) Is Group Type Example Guidelines/Comments
Product type All Yes No Field Fishery or Stock Automatically compiled
Record type All No No Field Aggregated (i.e. a GRSF record) or Original (i.e. a record among a "FIRMS", "RAMS" or "FishSource" one) Automatically compiled
Status status Aggregated Yes Yes Field Pending Controlled vocabulary: Pending, Rejected, Confirmed.
Database Sources database_sources Aggregated Yes No Resource [{"name":"FIRMS", "description": "unknown", "url":"http://....."}, ...] A list of elements of the type {"name": "a name", "description": "a description", "url": "http://...."}. Name and url are mandatory.

For the attribute name there is a controlled vocabulary: FIRMS, RAM, FishSource.

Source of Information source_of_information No No No Resource [{"name":"...", "description": "...", "url":"http://....."},...] A list of elements of the type {"name": "a name", "description": "a description", "url": "http://...."}. Name and url are mandatory.
uuid uuid_knowledge_base All No No Field The id of this Stock/Fishery object into the Knowledge Base
Traceability Flag traceability_flag Aggregated No No Field A boolean value
Short title short_title Aggregated No No Field A short title for this product
Data owner data_owner No No No Field IATTC
Refers To refers_to Aggregated No No Resource A list of objects of the format {"url": "http://", "id": "..."} that allows the aggregated GRSF records to point to their source records within the catalogue. The url and the id are both mandatory and are the ones returned by the services when a source record is published.
Reporting year reporting_year No No No Field 2005

* specifies if an attribute is not mandatory (No), mandatory for GRSF aggregated records (Aggregated) or is mandatory for every record (All)

Stock Metadata

The Stock product type also supports the following list of fields.

Name API Name Mandatory (No, Aggregated, All) * Is Tag Is Group Type Example Guidelines/Comments
Stock Name stock_name All No No Field Skipjack tuna - Eastern Pacific The title of the product. It is expected to be a unique name.
Stock ID stock_id No No No Field SKJ- EPO
Water Area water_area No No No Field (repeatable) ["SEAFO division B.1","SEAFO division D.0", "Indian Ocean, East/57.6", "SEAFO division D.1", "Cape of Good Hope", "Indian Ocean, West/51.6", "Indian Ocean, West/51.7"] A list of water areas. The multiple fields are mapped as multiple key/value pair fields.
Stock URI stock_uri No No No Field
Type type No Yes Yes Field Assessment Unit Controlled vocabulary: Assessment Unit, Resource
Species species Aggregated Yes No Field (repeatable) ["Katsuwonus pelamis", ....]
Assessment distribution area assessment_distribution_area No No No Field (repeatable) East Pacific Ocean
Exploiting Fishery exploiting_fishery No No No Field (repeatable) ["Tunas and billfishes fishery", ....]
Management entity management_entity No No No Field DFO
Assessment methods assessment_methods No No No Field Analytical assessment
State of marine resources state_of_marine_resource No No No Field
Exploitation Rate (Standard) standard_exploitation_rate No Yes (only the most five recent years) No Resource [{"year":2014, "value":"moderate fishing mortality"}, {"year":2015, "value":"high fishing mortality"}, ...] Controlled vocabulary for "value": Moderate fishing mortality, High fishing mortality, No or low fishing mortality
Exploitation Rate exploitation_rate No No No Resource [{"year":2014, "value":"moderate fishing mortality", "unit" : "..."}, {"year":2015, "value":"high fishing mortality", "unit" : "..."}, ....]
Abundance level (Standard) standard_abundance_level No Yes (only the most five recent years) No Resource [{"year":2014, "value":"low abundance"}, {"year":2015, "value":"intermediate abundance"}, ...] Controlled vocabulary for "value": Intermediate abundance, Low abundance, Uncertain/Not assessed
Abundance level abundance_level No No No Resource [{"year":2014, "value":"low abundance", "unit": "..."}, {"year":2015, "value":"intermediate abundance", "unit": "..."}, ...]
Narrative state and trend narrative_state_and_trend No No No Field Stock size and fishing pressure are considered to be close to their value at MSY. A textual description
Scientific advice scientific_advice No No No Field The indices of abundance from two longline fleets available for this stock present divergent trends over the last few years, the differences observed in targeting are not fully explained. A textual description
Reporting entity reporting_entity No No No Field GRP3

* specifies if an attribute is not mandatory (No), mandatory for GRSF aggregated records (Aggregated) or is mandatory for every record (All)

Fishery Metadata

The Fishery product type also supports the following list of fields.

Name API Name Mandatory (No, Aggregated, All) * Is Tag Is Group Type Example Guidelines/Comments
Fishery Name fishery_name All No No Field NAFO Flemish Cap groundfish fisheries This will be the title of the product and a unique name will be generated starting from this.
Fishery ID fishery_id No No No Field COD - 21.3.M - NAFO - OTB - CAN - Industrial
Type type No Yes Yes Field Fishery Activity Controlled vocabulary: Fishery Activity, Fishing Description
Scientific Name scientific_name No Yes No Field Caribbean spiny lobster
Fishing area fishing_area No No No Field (repeatable) ["North Atlantic", .... ] A list of values. If missing then Jurisdiction Area cannot be null
Exploited stocks exploited_stocks No No No Field (repeatable) ["Capelin - Southern Grand Bank" , ...]
Management entity management_entity No Yes No Field European Union
Jurisdiction Area jurisdiction_area No No No Field (repeatable) ["Senegal", "..."] If missing then Fishing Area cannot be null
Production system type production_system_type No Yes Yes Field Industrial Controlled vocabulary: Subsistence, Recreational, Commercial, Artisanal, Semi-industrial, Industrial, Exploratory_fishery, Unspecified
Flag state flag_state No Yes No Field ESP
Fishing gear fishing_gear No Yes No Field PUN
Environment environment No No No Field
Catches or landings catches_or_landings No No No Resource [{"unit" : "...", "value": "...", "year": "..."}, ...] A time series of value, unit and date

* specifies if an attribute is not mandatory (No), mandatory for GRSF aggregated records (Aggregated) or is mandatory for every record (All)

GRSF Publication Web Service

Publication of products is performed by means of a RESTful web service running over SmartGears. Almost every call to the service requires the security token of the user for the context in which he wish to publish or exploit the other functionalities. Please note that in case of product publication it is needed that the user has enough privileges. The list of roles and associated privileges for the catalogue users is reported here. The VRE Manager assignes them.

In order to retrieve your security token you can use the token generator portlet.

The right address for contacting the GRSF service in a context can be discovered by means of the Information System [1]. You need the following parameters

Service Name = GRSFPublisher
Service Class = Data-Catalogue
Entry Name = jersey-servlet

For testing purpose, a running instance can be contacted at the following address

https://smart-grsf-d-d4s.d4science.org/grsf-publisher-ws/rest/  [GRSF_PUBLISHER_WS_BASE_URL]

The token for testing purpose can be retrieved from the VRE at this url https://next.d4science.org/group/nextnext/home (register yourself if needed). In the following, every time you perform a request you must specify the type of record for which it will be valid, i.e., in the request path you need to specify a value among:

  • grsf;
  • fishsource;
  • ram;
  • firms.

Check Service Availability

To check that the stock/fishery service is up and running, just put the url below in your browser

[GRSF_PUBLISHER_WS_BASE_URL]/{...}/fishery/hello

Specify the record type by replacing {...}. The response should look like

Hello.. Fishery service is here

or

[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/hello

and the response should look like

Hello.. Stock service is here

Retrieve the licenses list

The default license that will be associated to the products, if not specified, is the CC-BY-SA-4.0 one. However, if it doesn't feet your needs, you can use one of the others available and retrievable by contacting the service(s) this way

[GRSF_PUBLISHER_WS_BASE_URL]/{...}/fishery/get-licenses?gcube-token=YOUR_TOKEN

or, for stock

[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/get-licenses?gcube-token=YOUR_TOKEN

The response is a JSON object, containing couples <license key, license name>, which looks like

{
    "AFL-3.0": "Academic Free License 3.0",
    "RPSL-1.0": "RealNetworks Public Source License 1.0",
    "ODC-BY-1.0": "Open Data Commons Attribution License 1.0",
    "IPL-1.0": "IBM Public License 1.0",
    "ODbL-1.0": "Open Data Commons Open Database License 1.0",
    "PostgreSQL": "PostgreSQL License",
    "W3C": "W3C License",
    ....
}

During the publication phase, the identifier of the license chosen should be provided.

Stock Publication Example

The publish method to invoke to publish a stock for rams, grsf, fishsource or ram is the following

[GRSF_PUBLISHER_WS_BASE_URL]/{...}/stock/publish-product?gcube-token=YOUR_TOKEN

The JSON object you must provide in input has the following structure (of course, not all fields are mandatory)

{
   "description": ...,
   "license_id": ...,
   "version": ...,
   "maintainer": ...,
   "maintainer_contact": ...,
   "catches_or_landings": ...,
   "database_sources": [{...}, ...],
   "source_of_information": [{...}, ...],
   "data_owner": ...,
   "type": ...,
   "stock_name": ...,
   "stock_id": ...,
   "species_scientific_name": ...,
   "assessment_distribution_area": ...,
   "exploiting_fishery": ...,
   "management_entity": ...,
   "assessment_methods": ...,
   "state_of_marine_resource": ...,
   "exploitation_rate": ...,
   "abundance_level": ...,
   "narrative_state_and_trend": ...,
   "scientific_advice": ...,
   "reporting_entity": ...,
   "reporting_year": ...,
   "status": ...
}

The response of the method is a JSON object of this kind

{
   "id": ... , // identifier of the created product in the catalogue
   "knowledge_base_id" : .... // identifier of the product in the knowledge base
   "product_url": ..., // url of the created product
   "error": ... // in case of error, check this field
}

In case of success the HTTP code is 201 (CREATED) and the response contains the url and the unique identifier assigned to the product. In case of errors (BAD_REQUEST, INTERNAL_SERVER_ERROR, FORBIDDEN ... ) the "error" message of the above object reports what was wrong.

Example

A valid JSON, for example, is the following one

{
   "description":"This stock product was generated for testing purposes, to show how publication works. Please refer to https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue_for_GRSF for more information",
   "license_id":"CC-BY-SA-4.0",
   "version":1,
   "maintainer":"Costantino Perciante",
   "maintainer_contact":"costantino.perciante@isti.cnr.it",
   "catches_or_landings":"unknown",
   "database_sources":[
      {
         "name":"FIRMS",
         "url":"test url"
      }
   ],
   "source_of_information":[
      {
         "name":"source of information",
         "url":"http://www.iattc.org/PDFFiles2/FisheryStatusReports/FisheryStatusReport13.pdf"
      }
   ],
   "data_owner":"IATTC",
   "type":"Assessment Unit",
   "stock_name":"Skipjack tuna - Eastern Pacific",
   "stock_id":"SKJ - EPO",
   "species_scientific_name":"SKJ",
   "assessment_distribution_area":"East Pacific Ocean",
   "exploiting_fishery":"Tunas and billfishes fishery",
   "management_entity":"DFO",
   "assessment_methods":"Analytical assessment",
   "state_of_marine_resource":null,
   "exploitation_rate":"Moderate fishing mortality",
   "abundance_level":"Intermediate abundance",
   "narrative_state_and_trend":"Stock size and fishing pressure are considered to be close to their value at MSY.",
   "scientific_advice":"The indices of abundance from two longline fleets available for this stock present divergent trends over the last few years, the differences observed in targeting are not fully explained.",
   "reporting_entity":"GRP3",
   "reporting_year":2016,
   "status":"pending"
}

the response obtained from the service is

{
   "id":"6d44b6b2-af80-4aa4-860a-a17db27b40df",
   "dataset_url":"https://next.d4science.org/group/nextnext/data-catalogue/?path=/dataset/skipjack_tuna_-_eastern_pacific",
   "error":null
}

Fishery Publication Example

The publish method to invoke to publish a fishery product is the following

[GRSF_PUBLISHER_WS_BASE_URL]/fishery/publish-product?gcube-token=YOUR_TOKEN

The JSON object you must provide in input has the following structure (of course, not all fields are mandatory)

{
   "description": ...,
   "license_id": ...,
   "version": ...,
   "maintainer": ...,
   "maintainer_contact": ...,
   "catches_or_landings": ...,
   "database_sources": [{...}, ...],
   "source_of_information": [{...}, ...],
   "data_owner": ...,
   "type": ...,
   "fishery_name": ...,
   "fishery_id": ...,
   "scientific_name": ...,
   "fishing_area": ...,
   "exploited_stocks": ...,
   "management_entity": ...,
   "jurisdiction_area": ...,
   "production_system_type": ...,
   "flag_state": ...,
   "fishing_gear": ...,
   "status":...,
   "environment":..
}

The response of the method is a JSON object of this kind

{
   "id": ... , // identifier of the created product
   "dataset_url": ..., // url of the created product
   "error": ... // in case of error, check this field
}

In case of success the HTTP code is 201 (CREATED) and the response contains the url and the unique identifier assigned to the product. In case of errors (BAD_REQUEST, INTERNAL_SERVER_ERROR, FORBIDDEN ... ) the "error" message of the above object reports what was wrong.

Example

A valid JSON, for example, is the following one

{
   "description":"This fishery product was generated for testing purposes, to show how publication works. Please refer to https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue_for_GRSF for more information",
   "license_id":"CC-BY-SA-4.0",
   "version":1,
   "maintainer":"Costantino Perciante",
   "maintainer_contact":"costantino.perciante@isti.cnr.it",
   "catches_or_landings":"unknown",
   "database_sources":[
      {
         "name":"FishSource",
         "url":"url"
      }
   ],
   "source_of_information":[
      {
         "name":"source of information",
         "url":"test url for source of information"
      }
   ],
   "data_owner":"IATTC",
   "type":"Fishery Activity",
   "fishery_name":"NAFO Flemish Cap groundfish fisheries ",
   "fishery_id":"COD - 21.3.M - NAFO - OTB - CAN - Industrial",
   "scientific_name":"Caribbean spiny lobster",
   "fishing_area":"North Atlantic",
   "exploited_stocks":"Capelin - Southern Grand Bank",
   "management_entity":"European Union",
   "jurisdiction_area":"Senegal",
   "production_system_type":"Industrial",
   "flag_state":"ESP",
   "fishing_gear":"PUN",
   "status":"Pending",
   "environment":null
}

the response obtained from the service is

{
   "id":"7b2989fc-cc4f-4b67-b7ff-42cc044881b1",
   "dataset_url":"https://next.d4science.org/group/nextnext/data-catalogue?path=/dataset/nafo_flemish_cap_groundfish_fisheries",
   "error":null
}

Delete a published product

If for some reason you need to delete a published product, you can invoke the following delete http methods. For fishery it is

[GRSF_PUBLISHER_WS_BASE_URL]/fishery/delete-product?gcube-token=YOUR_TOKEN

whereas for stock

[GRSF_PUBLISHER_WS_BASE_URL]/stock/delete-product?gcube-token=YOUR_TOKEN

You must provide the identifier (returned back at creation time) of the product, in a JSON that looks like

{"id", "identifier-deleted-product"}

The response status of the service, in case of success is 200 (OK)

How To Publish a GRSF product using JAVA

Below you find a simple Java application publishing a GRSF product (i.e. a stock).

package [YOUR PACKAGE];

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.MultiThreadedHttpConnectionManager;
import org.apache.commons.httpclient.methods.ByteArrayRequestEntity;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.http.HttpStatus;
import org.apache.log4j.Logger;

/**
 * The Class GRSFPublishMetadata.
 *
 * @author Francesco Mangiacrapa francesco.mangiacrapa@isti.cnr.it
 * Oct 13, 2016
 */
public class GRSFPublishMetadata {

	public static final Logger logger = Logger.getLogger(GRSFPublishMetadata.class);
	private static final String GRSF_PUBLISHER_REST_SERVICE_BASE_URL = "https://next.d4science.org/grsf-publisher-ws/rest/";

	/**
	 * The Enum PRODUCT_TYPE.
	 *
	 * @author Francesco Mangiacrapa francesco.mangiacrapa@isti.cnr.it
	 * Oct 13, 2016
	 */
	private static enum PRODUCT_TYPE{stock, fishery}
	private static final String PUBLISH_PRODUCT_REQUEST = "publish-product";
	private static final String GCUBE_TOKEN_PARAMETER = "gcube-token";
	private static final String GCUBE_TOKEN_VALUE = [YOUR TOKEN]; //***********SET YOUR TOKEN************
	private static final String CONTENTTYPE = "application/json";
	private HttpClient httpClient = null;
	public static final int TIME_OUT_REQUESTS = 5000; //5 sec

	/**
	 * Instantiates a new GRSF publish metadata.
	 */
	public GRSFPublishMetadata() {
		MultiThreadedHttpConnectionManager connectionManager = new MultiThreadedHttpConnectionManager();
		connectionManager.getParams().setSoTimeout(TIME_OUT_REQUESTS);
		this.httpClient = new HttpClient(connectionManager);

	}

	/**
	 * Publish product.
	 *
	 * @param type the type
	 * @param body the body
	 * @return the string
	 * @throws Exception the exception
	 */
	public String publishProduct(PRODUCT_TYPE type, String body) throws Exception {
		// Create a method instance.
		String buildURL = GRSF_PUBLISHER_REST_SERVICE_BASE_URL + "/" + type.toString() +"/"+PUBLISH_PRODUCT_REQUEST +"?"+GCUBE_TOKEN_PARAMETER +"="+GCUBE_TOKEN_VALUE;
		PostMethod method = new PostMethod(buildURL);
		method.setRequestHeader("Content-type", CONTENTTYPE);
		logger.debug("call post to URI .... " + method.getURI());
		logger.debug("	the body is..." + body);
		method.setRequestEntity(new ByteArrayRequestEntity(body.getBytes()));
		byte[] responseBody = null;
		try {
			// Execute the method.
			int statusCode = httpClient.executeMethod(method);

			if (statusCode != HttpStatus.SC_OK && statusCode != HttpStatus.SC_CREATED) {
				logger.error("Method failed: " + method.getStatusLine()+"; Response bpdy: "+method.getResponseBody());
				method.releaseConnection();
				throw new Exception("Method failed: " + method.getStatusLine()+"; Response body: "+new String(method.getResponseBody()));
			}
			// Read the response body.
			responseBody = method.getResponseBody();

		} catch (HttpException e) {
			logger.error("Fatal protocol violation: ", e);
			method.releaseConnection();
			throw new Exception("Fatal protocol violation: " + e.getMessage());
		} catch (Exception e) {
			logger.error("Fatal transport error: ", e);
			method.releaseConnection();
			throw new Exception("Fatal transport error: " + e.getMessage());
		}
		method.releaseConnection();
		return new String(responseBody);
	}

	/**
	 * The main method.
	 *
	 * @param args the arguments
	 */
	public static void main(String[] args) {
		try {
		GRSFPublishMetadata grsfP = new GRSFPublishMetadata();
			String minimal_json_stock =
			   "{\"description\":\"This stock product was generated for testing purposes, to show how publication works. Please refer to https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue_for_GRSF for more information\"," +
			   "\"license_id\":\"CC-BY-SA-4.0\"," +
			   "\"version\":1," +
			   "\"maintainer\":\"Francesco Mangiacrapa\","+
			   "\"maintainer_contact\":\"francesco.mangiacrapa@isti.cnr.it\","+
			   "\"catches_or_landings\":\"unknown\","+
			   "\"database_sources\":["+
			      "{\"name\":\"RAM\",\"url\":\"test url\"}" +
			      "]" +
			    ",\"source_of_information\":[{\"name\":\"the source of information\",\"url\":\"http://www.google.com\"}" +
			    "]," +
			   "\"data_owner\":\"IATTC\","+
			   "\"type\":\"Assessment Unit\","+
			   "\"stock_name\":\"Skipjack tuna - Western Pacific\","+ //YOU MUST CHANGE THE STOCK NAME FOR TESTING
			   "\"stock_id\":\"SKJ - EPO - TESTING\","+
			   "\"species_scientific_name\":\"SKJ\","+
			   "\"assessment_distribution_area\":\"Western Pacific\","+
			   "\"exploiting_fishery\":\"Tunas and billfishes fishery\","+
			   "\"management_entity\":\"DFO\","+
			   "\"assessment_methods\":\"Analytical assessment\","+
			   "\"state_of_marine_resource\":null,"+
			   "\"exploitation_rate\":\"High fishing mortality\","+
			   "\"abundance_level\":\"Intermediate abundance\","+
			   "\"narrative_state_and_trend\":\"Stock size and fishing pressure are considered to be close to their value at MSY.\","+
			   "\"scientific_advice\":\"The indices of abundance from two longline fleets available for this stock present divergent trends over the last few years, the differences observed in targeting are not fully explained.\","+
			   "\"reporting_entity\":\"GRP3\","+
			   "\"reporting_year\":2016,"+
			   "\"status\":\"pending\"}";

			String response = grsfP.publishProduct(PRODUCT_TYPE.stock, minimal_json_stock);
			logger.info("The Response: "+response);
		}catch (Exception e) {
			e.printStackTrace();
		}
	}

}

The response should look like:


call post to URI .... https://next.d4science.org/grsf-publisher-ws/rest/stock/publish-product?gcube-token=[YOUR TOKEN]
the body is...{"description":"This stock product was generated for testing purposes, to show how publication works. Please refer to https://wiki.gcube-system.org/gcube/GCube_Data_Catalogue_for_GRSF for more information","license_id":"CC-BY-SA-4.0","version":1,"maintainer":"Francesco Mangiacrapa","maintainer_contact":"francesco.mangiacrapa@isti.cnr.it","catches_or_landings":"unknown","database_sources":[{"name":"RAM","url":"test url"}],"source_of_information":[{"name":"the source of information","url":"http://www.google.com"}],"data_owner":"IATTC","type":"Assessment Unit","stock_name":"Skipjack tuna - Western Pacific Ocean 4","stock_id":"SKJ - EPO - TESTING","species_scientific_name":"SKJ","assessment_distribution_area":"Western Pacific Ocean 4","exploiting_fishery":"Tunas and billfishes fishery","management_entity":"DFO","assessment_methods":"Analytical assessment","state_of_marine_resource":null,"exploitation_rate":"High fishing mortality","abundance_level":"Intermediate abundance","narrative_state_and_trend":"Stock size and fishing pressure are considered to be close to their value at MSY.","scientific_advice":"The indices of abundance from two longline fleets available for this stock present divergent trends over the last few years, the differences observed in targeting are not fully explained.","reporting_entity":"GRP3","reporting_year":2016,"status":"pending"}
The Response: {"id":"8426bce9-15b9-4c4a-a526-e829882b91ec","dataset_url":"https://next.d4science.org/group/nextnext/data-catalogue?path=/dataset/skipjack_tuna_-_western_pacific_ocean_4","error":null}

You must use the following dependencies (if you are using Maven):

<!-- COMMONS HTTP -->
<dependency>
    <groupId>commons-httpclient</groupId>
    <artifactId>commons-httpclient</artifactId>
    <version>3.1</version>
</dependency>
<!-- LOGS -->
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.16</version>
</dependency>
  1. Information System can be queried via ic-client read more