gcat/src/main/java/org/gcube/gcat/rest/Item.java

451 lines
18 KiB
Java
Raw Normal View History

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;
2022-09-16 16:21:36 +02:00
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;
2020-11-30 19:44:15 +01:00
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;
2021-12-03 17:41:38 +01:00
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* @author Luca Frosini (ISTI - CNR)
*/
@Path(Item.ITEMS)
2019-09-16 14:48:18 +02:00
public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interfaces.Item<Response,Response> {
2021-12-03 17:41:38 +01:00
private final Logger logger = LoggerFactory.getLogger(Item.class);
public static final String ITEM_ID_PARAMETER = "ITEM_ID";
2021-11-19 16:49:43 +01:00
protected String moderationMessage;
public Item() {
super(ITEMS, ITEM_ID_PARAMETER, CKANPackage.class);
}
2022-09-16 11:27:06 +02:00
/**
* <p>
* The listing API provides paginated results by using the query parameters limit and offset.<br/>
* It returns an array list of string containing the ids (i.e. names) of the items.<br/>
2022-09-16 16:21:36 +02:00
* Each name can be used as <code>{ITEM_ID}</code> path parameter to manage such item.
2022-09-16 11:27:06 +02:00
* </p>
*
2022-09-16 16:21:36 +02:00
* <h3>Filtering options</h3>
2022-09-16 11:27:06 +02:00
* <p>
* The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).<br/>
* </p>
2022-09-16 16:21:36 +02:00
*
* <h4>Basic Filtering options</h4>
2022-09-16 11:27:06 +02:00
* <dl>
* <dt>include_private (bool)</dt>
* <dd>
2022-09-16 12:37:06 +02:00
* <em>Optional</em>.<em>Default:false</em>.<br/>
* If True, private datasets will be included in the results.<br/>
2022-09-16 16:21:36 +02:00
* Only private datasets from the users organizations will be returned. For the sysadmins will be returned all private datasets.<br/>
2022-09-16 11:27:06 +02:00
* E.g. <code>/items?include_private=true</code>
* </dd>
2022-09-16 12:42:58 +02:00
*
2022-09-16 16:21:36 +02:00
* <dt style="margin-top: 5px;">ext_bbox</dt>
2022-09-16 11:27:06 +02:00
* <dd>
2022-09-16 12:37:06 +02:00
* <em>Optional</em>.<em>Default:null</em>.<br/>
2022-09-16 11:27:06 +02:00
* The coordinates of the upper-right and bottom-left angle of a rectangular to query for.
2022-09-16 12:37:06 +02:00
* The form is <code>Lat,Long,Lat,Long</code><br/>
2022-09-16 11:27:06 +02:00
* E.g. <code>/items?limit=10&offset=0&q=Pollution&ext_bbox=-7.535093,49.208494,3.890688,57.372349</code>
* returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box.
* </dd>
2022-09-16 12:37:06 +02:00
*
2022-09-16 16:21:36 +02:00
* <dt style="margin-top: 5px;">own_only (bool)</dt>
2022-09-16 12:37:06 +02:00
* <dd>
* <em>Optional</em>.<em>Default:false</em>.<br/>
* If True, only the items of the requester user will be included in the result.<br/>
2022-09-16 16:21:36 +02:00
* E.g. <code>/items?limit=10&offset=0&own_only=true</code>
2022-09-16 12:37:06 +02:00
* </dd>
2022-09-16 11:27:06 +02:00
* </dl>
*
2022-09-16 16:21:36 +02:00
* <h4>Filtering options based on Solr query parameters</h4>
2022-09-16 12:42:58 +02:00
* <p>
* It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax):
* </p>
* <dl>
* <dt>q (string)</dt>
* <dd>
* <em>Optional</em>.<em>Default:"*:*"</em><br/>
* The solr query.<br/>
* E.g. <code>/items?q=title:foo</code> returns the items with word "foo" in the title.<br/>
* E.g. <code>/items?q=extras_systemtype:MyProfile</code> returns the items having the profile <em>MyProfile</em>
* </dd>
*
2022-09-16 16:21:36 +02:00
* <dt style="margin-top: 5px;">fq (string)</dt>
2022-09-16 12:42:58 +02:00
* <dd>
* <em>Optional</em>.<em>Default:null</em>.<br/>
* Filter query. A query string that limits the query results without influencing their scores.<br/>
* E.g. <code>/items?q=title:foo&fq=notes:bar</code> returns with word "foo" in the 'title' and the word "bar" in the 'notes'.
* </dd>
*
2022-09-16 16:21:36 +02:00
* <dt style="margin-top: 5px;">fq_list (list of strings)</dt>
2022-09-16 12:42:58 +02:00
* <dd>
* <em>Optional</em>.<em>Default:null</em>.<br/>
* Additional filter queries to apply.<br/>
* E.g. <code>/items?q=title:foo&fq_list=...</code> returns the items with word "foo" in the 'title'.
* </dd>
*
2022-09-16 16:21:36 +02:00
* <dt style="margin-top: 5px;">sort (string)</dt>
2022-09-16 12:42:58 +02:00
* <dd>
* <em>Optional</em>.<em>Default:"relevance asc, metadata_modified desc"</em>.<br/>
* Sorting of the search results.<br/>
* As per the solr documentation, this is a comma-separated string of field names and sort-orderings.<br/>
* E.g. <code>/items?q=title:foo&sort=name+asc</code> returns the items with word "foo" in the 'title'
* sorting the results by name ascending.
* </dd>
* <dl>
2022-09-16 12:37:06 +02:00
*
2022-09-16 16:35:17 +02:00
* <h4>Moderated Catalogue filtering options</h4>
2022-09-16 16:21:36 +02:00
* <dl>
* <dt>status (enum)</dt>
* <dd>
* <em>Optional</em>.<em>Default:null</em>.<br/>
*
2022-09-16 16:35:17 +02:00
* <span style="font-weight:bold;">It has sense only for moderated catalogues</span>.<br/>
2022-09-16 16:21:36 +02:00
* 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 <code>approved</code> after the moderation activation.
*
* It can assume the following values:
* <ul>
2022-09-16 18:00:38 +02:00
* <li><code>pending</code>: it returns only the pending items, i.e. the item published by any allowed users and still not <span style="font-weight:bold;">Catalogue-Moderator</span>;</li>
* <li><code>rejected</code>: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a <span style="font-weight:bold;">Catalogue-Moderator</span>;</li>
* <li><code>approved</code>: it returns only the approved items, i.e. the item published by any allowed users and approved by a <span style="font-weight:bold;">Catalogue-Moderator</span>.</li>
2022-09-16 16:21:36 +02:00
* </ul>
*
* <p>
2022-09-20 17:59:14 +02:00
* Please note that only Catalogue-Moderators can filter all items by status.<br />
2022-09-16 16:21:36 +02:00
* Other users using this query parameter will get only its own items with such a status in the results.
* </p>
* </dd>
* </dl>
*
*
* <h3>Query results options</h3>
* <p>
* 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.
* </p>
* <dl>
* <dt>count (bool)</dt>
* <dd>
* <em>Optional</em>.<em>Default:false</em>.<br/>
* If True, it indicates that the result must contains only the total number of items of the query.<br/>
* E.g. <code>/items?limit=10&offset=0&count=true</code>
* </dd>
*
* <dt style="margin-top: 5px;">all_fields (bool)</dt>
* <dd>
* <em>Optional</em>.<em>Default:false</em>.
* If True, the returned array list contains the whole item representation and not only the id (i.e. the name).</br/>
* E.g. <code>/items?limit=10&offset=0&all_fields=true</code>
* </dd>
* </dl>
* <p>
* Please note that, <code>count</code> query parameter has priority over <code>all_fields</code> query parameter.
* In other words, <code>all_fields</code> query parameter is not considered is <code>count</code> query parameter is true.
* </p>
*
2022-09-16 12:37:06 +02:00
*
2022-09-19 12:45:30 +02:00
* @param limit (<em>Default:10</em>) To get unlimited results the limit query parameters must be set to -1.
2022-09-16 11:27:06 +02:00
* If the results are too much the operation could fail.
* It is recommended to request no more than 1000 results.
2022-09-19 12:45:30 +02:00
* @param offset <em>Default:0</em>) The offset parameter indicates the starting position of the result.
2022-09-16 12:37:06 +02:00
* @return It returns an array list of string containing the ids (i.e. names) of the items.
2022-09-16 11:27:06 +02:00
* E.g.<pre>["item0","items1",...,"item10"]</pre>
*
* In the case the query parameter <code>count=true</code> it returns the total number of items of the query.
* E.g. <pre>{"count":148}</pre>
2022-09-16 16:21:36 +02:00
*
* In the case the query parameter <code>all_fields=true</code> each element of the resulting array contains the item representation:
* E.g.
* <pre>
* [
* {
* "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"
* }
*
* ]</pre>
2022-09-16 11:27:06 +02:00
*/
@GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
2022-04-01 18:37:45 +02:00
/* 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)
*/
2022-09-16 16:21:36 +02:00
@Override
2022-07-26 12:05:37 +02:00
public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit,
2022-09-16 16:21:36 +02:00
@QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) {
Boolean countOnly = false;
MultivaluedMap<String,String> queryParameters = uriInfo.getQueryParameters();
if(queryParameters.containsKey(GCatConstants.COUNT_QUERY_PARAMETER)) {
countOnly = Boolean.parseBoolean(queryParameters.get(GCatConstants.ALL_FIELDS_QUERY_PARAMETER).get(0));
}
if(countOnly) {
2021-12-03 17:41:38 +01:00
CKANPackage ckan = getInstance();
2022-09-16 11:27:06 +02:00
int size = ckan.count();
return createCountJson(size);
2021-02-03 16:48:42 +01:00
}else {
return list(limit, offset);
2021-02-03 16:48:42 +01:00
}
}
2022-09-16 16:21:36 +02:00
@POST
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public Response create(String json) {
return super.create(json);
}
@GET
@Path("/{" + ITEM_ID_PARAMETER + "}")
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Override
2022-04-01 18:37:45 +02:00
/* 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);
}
@PUT
@Path("/{" + ITEM_ID_PARAMETER + "}")
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@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);
}
@PATCH
@Path("/{" + ITEM_ID_PARAMETER + "}")
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@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);
}
@DELETE
@Path("/{" + ITEM_ID_PARAMETER + "}")
@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);
}
@PURGE
@Path("/{" + ITEM_ID_PARAMETER + "}")
@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);
}
2019-09-16 14:48:18 +02:00
@Override
public Response delete(String name, boolean purge) throws WebServiceException {
return delete(name, new Boolean(purge));
}
2021-11-19 16:49:43 +01:00
2021-12-03 17:41:38 +01:00
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();
}
2022-09-19 12:45:30 +02:00
/**
2022-09-20 15:26:20 +02:00
* <p>
* 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.
* </p>
2022-09-19 12:45:30 +02:00
*
2022-09-20 15:26:20 +02:00
* <p>
* When invoked with no arguments, it deletes all the items of the invoking user in the default
* CKAN organization for the current context.
* </p>
2022-09-19 12:45:30 +02:00
*
2022-09-20 15:26:20 +02:00
* <p>
* If a Catalogue-Admin or above specifies the query parameter <em>own_only=false</em>
* it deletes all the items of all users for the CKAN organization for the current context.
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
* Catalogue-Admin or above.
* </p>
2022-09-19 12:45:30 +02:00
*
* <p style="font-weight:bold;">
* Please check the result using the items listing APIs to verify what you will delete.
* </p>
*
* <p>
* 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 <em>purge=true</em>.
* <span style="font-weight:bold;">Please note that the purge action is not reversible.</span>
* </p>
*
* <p>
* By indicating the query parameter <em>purge=true</em> has the same result of using the bulk
* purge API using the <code>PURGE</code> HTTP Method.
* </p>
*
* @param purge <em>Default:false</em>) it completely removes all the items in the default CKAN organization.
* @return <code>202 Accepted</code> 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.
*/
2021-12-03 17:41:38 +01:00
@DELETE
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
2021-12-03 17:41:38 +01:00
@Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
2021-12-03 17:41:38 +01:00
public Response bulkDelete(@QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") boolean purge) {
deleteAll(purge);
return Response.status(Status.ACCEPTED).build();
}
2022-09-19 12:45:30 +02:00
/**
2022-09-20 15:26:20 +02:00
* <p>
* 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.
* </p>
2022-09-19 12:45:30 +02:00
*
2022-09-20 15:26:20 +02:00
* <p>
* When invoked with no arguments, it purges all the items of the invoking user in the default
* CKAN organization for the current context.
* </p>
2022-09-19 12:45:30 +02:00
*
2022-09-20 15:26:20 +02:00
* <p>
* If a Catalogue-Admin or above specifies the query parameter <em>own_only=false</em>,
* it purges all the items of all users for the CKAN organization for the current context.
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
* Catalogue-Admin or above.
* </p>
2022-09-19 12:45:30 +02:00
*
* <p style="font-weight:bold;">
* Please check the result using the items listing APIs to verify what you will purge.
* </p>
*
* <p>
* Invoking this API has the same result of using the bulk delete API using the <code>DELETE</code> HTTP Method
* with the query parameters <em>purge=true</em>.
* </p>
*
2022-09-20 15:26:20 +02:00
* @return <code>202 Accepted</code> HTTP Status to indicate that the request has been
* properly taken in charge.<br />
2022-09-19 12:45:30 +02:00
* The operation will continue in background.
2022-09-20 15:26:20 +02:00
*
2022-09-19 12:45:30 +02:00
* @throws WebServiceException if an error occurs.
*/
2021-12-03 17:41:38 +01:00
@PURGE
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
2021-12-03 17:41:38 +01:00
@Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
2021-12-03 17:41:38 +01:00
public Response bulkPurge() {
return bulkDelete(true);
}
2022-09-20 15:26:20 +02:00
/**
*
* @param id the name of the item to moderate
* @param json It contains the moderation action to perform on the item.
*
* <p>The format is the following</p>
*
* <pre>
* {
* "system:cm_item_status":"approved",
* "message": "..."
* }
* </pre>
*
* <p>
* The field <code>system:cm_item_status</code> can have
* the following values: <code>approved</code> or <code>rejected</code>, indicating the
* item's new status.<br />
* It is possible to send an optional message together with the new status by adding
* the field <code>message</code>.<br />
* This operation is available for Catalogue-Moderator only.
* </p>
*
* <p>
* Catalogue-Moderator and item author can send just a message to discuss
* the approval of the item by indicating the field <code>message</code> only.
* </p>
*
* @return <code>202 Accepted</code> HTTP Status to indicate that the request has been
* properly taken in charge.<br />
* The operation will continue in background.
*/
@POST
@Path("/{" + ITEM_ID_PARAMETER + "}")
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
// @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();
2021-11-19 16:49:43 +01:00
}
2021-12-03 17:41:38 +01:00
}