package org.gcube.gcat.rest; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; //import javax.ws.rs.NotAuthorizedException; import javax.ws.rs.POST; import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.QueryParam; import javax.ws.rs.core.MultivaluedMap; import javax.ws.rs.core.Response; import javax.ws.rs.core.Response.ResponseBuilder; import javax.ws.rs.core.Response.Status; import javax.xml.ws.WebServiceException; //import org.gcube.common.authorization.control.annotations.AuthorizationControl; import org.gcube.gcat.annotation.PATCH; import org.gcube.gcat.annotation.PURGE; import org.gcube.gcat.api.GCatConstants; //import org.gcube.gcat.api.moderation.Moderated; //import org.gcube.gcat.api.roles.Role; import org.gcube.gcat.persistence.ckan.CKANPackage; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import com.webcohesion.enunciate.metadata.rs.ResourceGroup; import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * Item is a set of metadata to describe a concept. * An Item can has one or more Resource attached. * * @author Luca Frosini (ISTI - CNR) */ @Path(Item.ITEMS) @ResourceGroup("Item APIs") @ResourceLabel("Item APIs") public class Item extends REST implements org.gcube.gcat.api.interfaces.Item { private final Logger logger = LoggerFactory.getLogger(Item.class); public static final String ITEM_ID_PARAMETER = "ITEM_ID"; protected String moderationMessage; public Item() { super(ITEMS, ITEM_ID_PARAMETER, CKANPackage.class); } /** *

* The listing API provides paginated results by using the query parameters limit and offset.
* It returns an array list of string containing the ids (i.e. names) of the items.
* Each name can be used as {ITEM_ID} path parameter to manage such item. *

* *

Filtering options

*

* The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).
*

* *

Basic Filtering options

*
*
include_private (bool)
*
* Optional.Default:false.
* If True, private datasets will be included in the results.
* Only private datasets from the user’s organizations will be returned. * For the sysadmins will be returned all private datasets.
* E.g. /items?include_private=true *
* *
ext_bbox
*
* Optional.Default:null.
* The coordinates of the upper-right and bottom-left angle of a rectangular to query for. * The form is Lat,Long,Lat,Long
* E.g. /items?limit=10&offset=0&q=Pollution&ext_bbox=-7.535093,49.208494,3.890688,57.372349 * returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box. *
* *
own_only (bool)
*
* Optional.Default:false.
* If True, only the items of the requester user will be included in the result.
* E.g. /items?limit=10&offset=0&own_only=true *
*
* *

Filtering options based on Solr query parameters

*

* It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax): *

*
*
q (string)
*
* Optional.Default:"*:*"
* The solr query.
* E.g. /items?q=title:foo returns the items with word "foo" in the title.
* E.g. /items?q=extras_systemtype:MyProfile returns the items having the profile MyProfile *
* *
fq (string)
*
* Optional.Default:null.
* Filter query. A query string that limits the query results without influencing their scores.
* E.g. /items?q=title:foo&fq=notes:bar returns with word "foo" in the 'title' and the word "bar" in the 'notes'. *
* *
fq_list (list of strings)
*
* Optional.Default:null.
* Additional filter queries to apply.
* E.g. /items?q=title:foo&fq_list=... returns the items with word "foo" in the 'title'. *
* *
sort (string)
*
* Optional.Default:"relevance asc, metadata_modified desc".
* Sorting of the search results.
* As per the solr documentation, this is a comma-separated string of field names and sort-orderings.
* E.g. /items?q=title:foo&sort=name+asc returns the items with word "foo" in the 'title' * sorting the results by name ascending. *
*
* *

Moderated Catalogue filtering options

*
*
status (enum)
*
* Optional.Default:null.
* * It has sense only for moderated catalogues.
* When no value is provided, it returns both the items which have been published before the activation of the moderation, * as weel as the items explicitly approved after the moderation activation. * * It can assume the following values: *
    *
  • pending: it returns only the pending items, i.e. the item published by any allowed users and still not Catalogue-Moderator;
    • *
  • rejected: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a Catalogue-Moderator;
    • *
  • approved: it returns only the approved items, i.e. the item published by any allowed users and approved by a Catalogue-Moderator.
    • *
* *

* Please note that only Catalogue-Moderators can filter all items by status.
* Other users using this query parameter will get only its own items with such a status in the results. *

*
*
* * *

Query results options

*

* The result is by default an array list of string containing the ids (i.e. names) of the items. * Anyway, there are two options to get a different results. *

*
*
count (bool)
*
* Optional.Default:false.
* If True, it indicates that the result must contains only the total number of items of the query.
* E.g. /items?limit=10&offset=0&count=true *
* *
all_fields (bool)
*
* Optional.Default:false. * If True, the returned array list contains the whole item representation and not only the id (i.e. the name).
* E.g. /items?limit=10&offset=0&all_fields=true *
*
*

* Please note that, count query parameter has priority over all_fields query parameter. * In other words, all_fields query parameter is not considered is count query parameter is true. *

* * * @param limit (Default:10) To get unlimited results the limit query parameters must be set to -1. * If the results are too much the operation could fail. * It is recommended to request no more than 1000 results. * @param offset (Default:0) The offset parameter indicates the starting position of the result. * @return It returns an array list of string containing the ids (i.e. names) of the items. * E.g.
["item0","items1",...,"item10"]
* * In the case the query parameter count=true it returns the total number of items of the query. * E.g. 
{"count":148}
* * In the case the query parameter all_fields=true each element of the resulting array contains the item representation: * E.g. * 
	 *  [
	 *  	{
	 *  		"name"="item0",
	 *  		...,
	 *  		"private": false,
	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
	 *  	},
	 *  	{
	 *  		"name"="item1",
	 *  		...,
	 *  		"private": true,
	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
	 *  	},
	 *  	...,
	 *  	{
	 *  		"name"="itemN",
	 *  		...,
	 *  		"private": false,
	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
	 *  	}
	 *  
	 *  ]
* * @pathExample /items?limit=10&offset=0 * @responseExample application/json;charset=UTF-8 ["item0","items1",...,"item10"] */ @GET @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The request succeeded.") }) /* Catalogue-Member is not added to VRE members and is assumed as the default role in the catalogue for the VRE members. So we can't enforce * @AuthorizationControl(allowedRoles={Role.CATALOGUE_MEMBER, Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) */ @Override public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit, @QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) { Boolean countOnly = false; MultivaluedMap queryParameters = uriInfo.getQueryParameters(); if(queryParameters.containsKey(GCatConstants.COUNT_QUERY_PARAMETER)) { countOnly = Boolean.parseBoolean(queryParameters.get(GCatConstants.ALL_FIELDS_QUERY_PARAMETER).get(0)); } if(countOnly) { CKANPackage ckan = getInstance(); int size = ckan.count(); return createCountJson(size); }else { return super.list(limit, offset); } } /** * * The create API allows to create an item. * An Item is mainly described by the following attributes (* indicate mandatory attributes): * *
*
name* (string)
*
* the name of the new item, must be between 2 and 100 characters long * and contain only lowercase alphanumeric characters, '-' and '_'; *
* * *
title (string)
*
* If not specified it assumes the same value of name attribute. * The title of the item; *
* *
maintainer (string)
*
the name of the item’s maintainer;
* *
maintainer_email (string)
*
the email address of the item’s maintainer;
* *
license_id* (string)
*
the id of the item’s license, use License listing API to get available values;
* *
notes (string)
*
a description of the item;
* *
url (string)
*
a URL for the item’s source;
* *
version (string)
*
must be between no longer than 100 characters
* *
state (string, default='active')
*
* the current state of the item, e.g. 'active' or 'deleted', only active items show up in search results and other lists of items, * this parameter will be ignored if you are not authorized to change the state of the item; *
* *
groups (list of dictionaries)
*
* the groups to which the item belongs, each group dictionary should have one or more of the * following keys which identify an existing group: * 'id' (the id of the group, string), or 'name' (the name of the group, string). * To see which groups exist use Group listing API.
* * *
tags (list of tag dictionaries)
*
* the item’s tags. The tag is a dictionary in the format: * name : the name for the tag, i.e. a string between 2 and 100 characters long containing only alphanumeric characters and '-', '_' and '.'. *
* * *
resources (list of resource dictionaries)
*
the item’s resources, see Resource collection for the format of resource dictionaries;
* * *
extras (list of item extra dictionaries)
*
the item’s extras, extras are arbitrary (key: value) metadata items that can be added to items, each extra dictionary should have keys 'key' (a string), 'value' (a string);
* *
owner_org (string)
*
* the id of the item’s owning organization, see supportedOrganizations property in * Read Configuration. * The defaultOrganization is used if the author does not specify the organization. *
* *
* * *

Parameter automatically managed:

*
* *
author (string)
*
the name of the item’s author (the owner of the gcube-token);
* *
author_email (string)
*
the email address of the item’s author (the email of the owner of gcube-token);
* *
* * *

Geo-Indexing your datasets:

*

* In order to make an Item searchable by location, it must have a special extra, with its key named ‘spatial’. * The value must be a valid GeoJSON geometry, for example: *

* 
	 * 	{
	 * 		"type":"Polygon",
	 * 		"coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]]
	 * 	}
	 *
* * or * * 
	 * 	{
	 * 		"type": "Point",
	 * 		"coordinates": [-3.145,53.078]
	 * 	}
	 *
* * *

Profile

*

* If at least one profile has been defined within this context, then you need to specify the profile's * type when creating the item. * You need to insert, among the extras of the JSON object describing the item, a system:type * property with one of the available profile, see List Profiles API. * The validation of the submitted request will be performed against the profile whose type has been specified. * The profile's properties need to be specified within the extras field as well. *

*

* If no profile has been defined, then no validation will be performed. * Thus you do not need to set any system:type property. *

* *

Social Post

*

* The user is going to crreate an item can indicate if he/she desires the creation of a social post * to inform all the users of the VRE that he/she has created the item.
* To request the social post he/she must indicate social_post=true query parameter.
* The social_post query parameter is optional and the default value is false.
* Please note that even the user indicates social_post=true the social post * is create only and only if the Catalogue-Manager enabled this feature, see socialPostEnabled property in * Read Configuration. * When the social post is created the a notification to the VRe user is sent if the property * notificationToUsersEnabled is true in the above mentioned configuration. * If false notificationToUsersEnabled=false the social post will not produce a notification * to the VRE user which will be only informed about the item pubblication by reading the generated * social post in the VRE. *

* * * @param json containing the item to be created * @return 201 Created HTTP Status to indicate that the item has been created. * Some operation could continue in background such as the social post creation. * * @pathExample /items?social_post=true * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/create-item-request.json * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/create-item-response.json * */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 201, condition = "The item has been created successfully.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public Response create(String json) { return super.create(json); } /** * @pathExample /items/my_test_item * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/read-item-response.json */ @GET @Path("/{" + ITEM_ID_PARAMETER + "}") @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The item exists.") }) @Override /* Catalogue-Member is not added to VRE members and is assumed as the default role in the catalogue for the VRE members. So we can't enforce * @AuthorizationControl(allowedRoles={Role.CATALOGUE_MEMBER, Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) */ public String read(@PathParam(ITEM_ID_PARAMETER) String id) { return super.read(id); } /** * Any Catalogue-Admins or above is capable of modifying the authorship of the item.
* The service does not perform any check on author information provided by the user. * * @pathExample /items/my_test_item * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/update-item-request.json * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/update-item-response.json */ @PUT @Path("/{" + ITEM_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The item has been updated successfully.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public String update(@PathParam(ITEM_ID_PARAMETER) String id, String json) { return super.update(id, json); } /** * @pathExample /items/my_test_item * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/patch-item-request.json * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/patch-item-response.json */ @PATCH @Path("/{" + ITEM_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The item has been patched successfully.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public String patch(@PathParam(ITEM_ID_PARAMETER) String id, String json) { return super.patch(id, json); } /** * @pathExample /items/my_test_item */ @DELETE @Path("/{" + ITEM_ID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The item has been deleted successfully."), @ResponseCode ( code = 404, condition = "The item was not found.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public Response delete(@PathParam(ITEM_ID_PARAMETER) String id, @QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") Boolean purge) { return super.delete(id, purge); } /** * @pathExample /items/my_test_item */ @PURGE @Path("/{" + ITEM_ID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The item has been purged successfully."), @ResponseCode ( code = 404, condition = "The item was not found.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public Response purge(@PathParam(ITEM_ID_PARAMETER) String id) { return super.purge(id); } @Override public Response delete(String name, boolean purge) throws WebServiceException { return delete(name, new Boolean(purge)); } protected void deleteAll(boolean purge) { Thread thread = new Thread(new Runnable() { @Override public void run() { CKANPackage ckan = getInstance(); String ret = ckan.deleteAll(purge); logger.info("Result of delete all is {}", ret); } }); thread.start(); } /** *

* The bulk delete API provides a way to delete all the items matching certain criteria * (see Filtering Listing options). * The operation returns immediately to the client and continues in background. * There is no way to monitor or stop the running operation. *

* *

* When invoked with no arguments, it deletes all the items of the invoking user in the default * CKAN organization for the current context. *

* *

* If a Catalogue-Admin or above specifies the query parameter own_only=false * it deletes all the items of all users for the CKAN organization for the current context. * The service ignores the query parameter own_only=false if the requesting user is not * Catalogue-Admin or above. *

* *

* Please check the result using the items listing APIs to verify what you will delete. *

* *

* The deleted items are moved to the thrash by default. * To completely remove the items (i.e. purge) the user can use the query parameter purge=true. * Please note that the purge action is not reversible. *

* *

* By indicating the query parameter purge=true has the same result of using the bulk * purge API using the PURGE HTTP Method. *

* * @param purge (Default:false) it completely removes all the items in the default CKAN organization. * @return 202 Accepted HTTP Status to indicate that the request has been properly take in charge. * The operation will continue in background. * @throws WebServiceException if an error occurs. * * @pathExample /items?purge=false * */ @DELETE @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 202, condition = "The bulk delete/purge has been accepted successfully.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public Response bulkDelete(@QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") boolean purge) { deleteAll(purge); return Response.status(Status.ACCEPTED).build(); } /** *

* The bulk purge API provides a way to completely remove all the items matching certain criteria * (see Filtering Listing options). Please note that this action is not reversible. * The operation returns immediately to the client and continues in background. * There is no way to monitor or stop the running operation. *

* *

* When invoked with no arguments, it purges all the items of the invoking user in the default * CKAN organization for the current context. *

* *

* If a Catalogue-Admin or above specifies the query parameter own_only=false, * it purges all the items of all users for the CKAN organization for the current context. * The service ignores the query parameter own_only=false if the requesting user is not * Catalogue-Admin or above. *

* *

* Please check the result using the items listing APIs to verify what you will purge. *

* *

* Invoking this API has the same result of using the bulk delete API using the DELETE HTTP Method * with the query parameters purge=true. *

* * @return 202 Accepted HTTP Status to indicate that the request has been * properly taken in charge.
* The operation will continue in background. * * @throws WebServiceException if an error occurs. * * @pathExample /items */ @PURGE @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 202, condition = "The bulk purge has been accepted successfully.") }) @Override // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) public Response bulkPurge() { return bulkDelete(true); } /** * * @param id the name of the item to moderate * @param json It contains the moderation action to perform on the item. * *

The format is the following

* * 
	 * 	{
	 * 		"system:cm_item_status":"approved",
	 * 		"message": "..."
	 * 	}
	 *
* *

* The field system:cm_item_status can have * the following values: approved or rejected, indicating the * item's new status.
* It is possible to send an optional message together with the new status by adding * the field message.
* This operation is available for Catalogue-Moderator only. *

* *

* Catalogue-Moderator and item author can send just a message to discuss * the approval of the item by indicating the field message only. *

* * @return 202 Accepted HTTP Status to indicate that the request has been * properly taken in charge.
* The operation will continue in background. * * @pathExample /items/my_test_item * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/reject.json */ @POST @Path("/{" + ITEM_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 202, condition = "The moderation operation has been accepted successfully.") }) // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER, Moderated.CATALOGUE_MODERATOR}, exception=NotAuthorizedException.class) public Response moderate(@PathParam(ITEM_ID_PARAMETER) String id, String json) { setCalledMethod("POST /" + COLLECTION_PARAMETER + "/{" + ID_PARAMETER + "}"); CKANPackage ckanPackage = getInstance(); ckanPackage.setName(id); String ret = ckanPackage.moderate(json); ResponseBuilder responseBuilder = Response.status(Status.ACCEPTED); if(ret!=null) { responseBuilder.entity(ret).type(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8); } return responseBuilder.build(); } }