Improving documentation

This commit is contained in:
Luca Frosini 2022-09-30 17:28:30 +02:00
parent 8f88be604c
commit 73e7f67d7d
12 changed files with 1646 additions and 252 deletions

View File

@ -33,125 +33,9 @@ import com.webcohesion.enunciate.metadata.rs.ResponseCode;
import com.webcohesion.enunciate.metadata.rs.StatusCodes; import com.webcohesion.enunciate.metadata.rs.StatusCodes;
/** /**
* An Item is mainly described by the following attributes (* indicate mandatory attributes): * Item is a set of metadata to describe a concept.
* * An Item can has one or more <a href="./resource_Resource.html">Resource</a> attached.
* <dl>
* <dt>name* (string)</dt>
* <dd>
* the name of the new item, must be between 2 and 100 characters long
* and contain only lowercase alphanumeric characters, '-' and '_';
* </dd>
* *
*
* <dt style="margin-top: 5px;">title (string)</dt>
* <dd>
* If not specified it assumes the same value of <em>name</em> attribute.
* The title of the item;
* </dd>
*
* <dt style="margin-top: 5px;">maintainer (string)</dt>
* <dd>the name of the items maintainer;</dd>
*
* <dt style="margin-top: 5px;">maintainer_email (string)</dt>
* <dd>the email address of the items maintainer;</dd>
*
* <dt style="margin-top: 5px;">license_id* (string)</dt>
* <dd>the id of the items license, use <a href="resource_License.html">License listing</a> API to get available values;</dd>
*
* <dt style="margin-top: 5px;">notes (string)</dt>
* <dd>a description of the item;</dd>
*
* <dt style="margin-top: 5px;">url (string)</dt>
* <dd>a URL for the items source;</dd>
*
* <dt style="margin-top: 5px;">version (string)</dt>
* <dd>must be between no longer than 100 characters</dd>
*
* <dt style="margin-top: 5px;">state (string, default='active')</dt>
* <dd>
* 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;
* </dd>
*
* <dt style="margin-top: 5px;">groups (list of dictionaries)</dt>
* <dd>
* 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 <a href="resource_Group.html#resource_Group_list_limit_offset_countOnly_GET">Group listing</a> API.</dd>
* </dd>
*
* <dt style="margin-top: 5px;">tags (list of tag dictionaries)</dt>
* <dd>
* the items 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 '.'.
* </dd>
*
*
* <dt style="margin-top: 5px;">resources (list of resource dictionaries)</dt>
* <dd>the items resources, see <a href="resource_Resource.html">Resource collection</a> for the format of resource dictionaries;</dd>
*
*
* <dt style="margin-top: 5px;">extras (list of item extra dictionaries)</dt>
* <dd>the items 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);</dd>
*
* <dt style="margin-top: 5px;">owner_org (string)</dt>
* <dd>
* the id of the items owning organization, see <code>supportedOrganizations</code> property in
* <a href="resource_Configuration.html#resource_Configuration_read_context_GET">Read Configuration</a>.
* The <code>defaultOrganization</code> is used if the author does not specify the organization.
* </dd>
*
* </dl>
*
*
* <h3>Parameter automatically managed:</h3>
* <dl>
*
* <dt>author (string)</dt>
* <dd>the name of the items author (the owner of the gcube-token);</dd>
*
* <dt style="margin-top: 5px;">author_email (string)</dt>
* <dd>the email address of the items author (the email of the owner of gcube-token);</dd>
*
* </dl>
*
*
* <h3>Geo-Indexing your datasets:</h3>
* <p>
* 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:
* </p>
* <pre>
* {
* "type":"Polygon",
* "coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]]
* }
* </pre>
*
* or
*
* <pre>
* {
* "type": "Point",
* "coordinates": [-3.145,53.078]
* }
* </pre>
*
*
* <h3>Profile</h3>
* <p>
* 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 <code>system:type</code>
* property with one of the available profile, see <a href="resource_Profile.html#resource_Profile_listOrCount_countOnly_GET">List Profiles</a> 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.
* </p>
* <p>
* If no profile has been defined, then no validation will be performed.
* Thus you do not need to set any <code>system:type</code> property.
* </p>
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Item.ITEMS) @Path(Item.ITEMS)
@ -367,6 +251,125 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
/** /**
* *
* The create API allows to create an item. * The create API allows to create an item.
* An Item is mainly described by the following attributes (* indicate mandatory attributes):
*
* <dl>
* <dt>name* (string)</dt>
* <dd>
* the name of the new item, must be between 2 and 100 characters long
* and contain only lowercase alphanumeric characters, '-' and '_';
* </dd>
*
*
* <dt style="margin-top: 5px;">title (string)</dt>
* <dd>
* If not specified it assumes the same value of <em>name</em> attribute.
* The title of the item;
* </dd>
*
* <dt style="margin-top: 5px;">maintainer (string)</dt>
* <dd>the name of the items maintainer;</dd>
*
* <dt style="margin-top: 5px;">maintainer_email (string)</dt>
* <dd>the email address of the items maintainer;</dd>
*
* <dt style="margin-top: 5px;">license_id* (string)</dt>
* <dd>the id of the items license, use <a href="resource_License.html">License listing</a> API to get available values;</dd>
*
* <dt style="margin-top: 5px;">notes (string)</dt>
* <dd>a description of the item;</dd>
*
* <dt style="margin-top: 5px;">url (string)</dt>
* <dd>a URL for the items source;</dd>
*
* <dt style="margin-top: 5px;">version (string)</dt>
* <dd>must be between no longer than 100 characters</dd>
*
* <dt style="margin-top: 5px;">state (string, default='active')</dt>
* <dd>
* 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;
* </dd>
*
* <dt style="margin-top: 5px;">groups (list of dictionaries)</dt>
* <dd>
* 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 <a href="resource_Group.html#resource_Group_list_limit_offset_countOnly_GET">Group listing</a> API.</dd>
* </dd>
*
* <dt style="margin-top: 5px;">tags (list of tag dictionaries)</dt>
* <dd>
* the items 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 '.'.
* </dd>
*
*
* <dt style="margin-top: 5px;">resources (list of resource dictionaries)</dt>
* <dd>the items resources, see <a href="resource_Resource.html">Resource collection</a> for the format of resource dictionaries;</dd>
*
*
* <dt style="margin-top: 5px;">extras (list of item extra dictionaries)</dt>
* <dd>the items 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);</dd>
*
* <dt style="margin-top: 5px;">owner_org (string)</dt>
* <dd>
* the id of the items owning organization, see <code>supportedOrganizations</code> property in
* <a href="resource_Configuration.html#resource_Configuration_read_context_GET">Read Configuration</a>.
* The <code>defaultOrganization</code> is used if the author does not specify the organization.
* </dd>
*
* </dl>
*
*
* <h3>Parameter automatically managed:</h3>
* <dl>
*
* <dt>author (string)</dt>
* <dd>the name of the items author (the owner of the gcube-token);</dd>
*
* <dt style="margin-top: 5px;">author_email (string)</dt>
* <dd>the email address of the items author (the email of the owner of gcube-token);</dd>
*
* </dl>
*
*
* <h3>Geo-Indexing your datasets:</h3>
* <p>
* 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:
* </p>
* <pre>
* {
* "type":"Polygon",
* "coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]]
* }
* </pre>
*
* or
*
* <pre>
* {
* "type": "Point",
* "coordinates": [-3.145,53.078]
* }
* </pre>
*
*
* <h3>Profile</h3>
* <p>
* 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 <code>system:type</code>
* property with one of the available profile, see <a href="resource_Profile.html#resource_Profile_listOrCount_countOnly_GET">List Profiles</a> 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.
* </p>
* <p>
* If no profile has been defined, then no validation will be performed.
* Thus you do not need to set any <code>system:type</code> property.
* </p>
* *
* <h3>Social Post</h3> * <h3>Social Post</h3>
* <p> * <p>

View File

@ -3,14 +3,18 @@ package org.gcube.gcat.rest;
import javax.ws.rs.GET; import javax.ws.rs.GET;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.Produces; import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.gcube.gcat.api.GCatConstants;
import org.gcube.gcat.persistence.ckan.CKANLicense; import org.gcube.gcat.persistence.ckan.CKANLicense;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup; import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* A collection to interact with licenses that are available in the catalogue.
* A license is associated with items to define the legal right
* to use such an item.
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(License.LICENSES) @Path(License.LICENSES)
@ -22,8 +26,14 @@ public class License extends REST<CKANLicense> implements org.gcube.gcat.api.int
super(LICENSES, null, CKANLicense.class); super(LICENSES, null, CKANLicense.class);
} }
/**
* @return the json array containing the licenses available in the catalogue
*
* @pathExample /licenses
* @responseExample application/json classpath:/api-docs-examples/license/list-license-response.json
*/
@GET @GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(MediaType.APPLICATION_JSON)
public String list() { public String list() {
return super.list(-1, -1); return super.list(-1, -1);
} }

View File

@ -6,18 +6,20 @@ import javax.ws.rs.GET;
import javax.ws.rs.InternalServerErrorException; import javax.ws.rs.InternalServerErrorException;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.Produces; import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.gcube.com.fasterxml.jackson.databind.ObjectMapper; import org.gcube.com.fasterxml.jackson.databind.ObjectMapper;
import org.gcube.com.fasterxml.jackson.databind.node.ArrayNode; import org.gcube.com.fasterxml.jackson.databind.node.ArrayNode;
import org.gcube.com.fasterxml.jackson.databind.node.ObjectNode; import org.gcube.com.fasterxml.jackson.databind.node.ObjectNode;
import org.gcube.datacatalogue.metadatadiscovery.bean.jaxb.NamespaceCategory; import org.gcube.datacatalogue.metadatadiscovery.bean.jaxb.NamespaceCategory;
import org.gcube.gcat.api.GCatConstants;
import org.gcube.gcat.profile.MetadataUtility; import org.gcube.gcat.profile.MetadataUtility;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup; import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* A namespace defines a logical grouping for metadata contained in items.
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Namespace.NAMESPACES) @Path(Namespace.NAMESPACES)
@ -25,8 +27,14 @@ import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
@ResourceLabel("Namespace APIs") @ResourceLabel("Namespace APIs")
public class Namespace extends BaseREST implements org.gcube.gcat.api.interfaces.Namespace { public class Namespace extends BaseREST implements org.gcube.gcat.api.interfaces.Namespace {
/**
* @return the json array containing the licenses available in the catalogue
*
* @pathExample /namespaces
* @responseExample application/json classpath:/api-docs-examples/namespace/list-namespace-response.json
*/
@GET @GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(MediaType.APPLICATION_JSON)
public String list() { public String list() {
setCalledMethod("GET /" + NAMESPACES); setCalledMethod("GET /" + NAMESPACES);

View File

@ -34,11 +34,8 @@ import com.webcohesion.enunciate.metadata.rs.ResponseCode;
import com.webcohesion.enunciate.metadata.rs.StatusCodes; import com.webcohesion.enunciate.metadata.rs.StatusCodes;
/** /**
* A Profile must comply with the defined <a href="../profiles/SCHEMA">XSD schema</a> . * A profile defines a type and the schema any item of such a type must comply with.
* *
* Please find the documentation of profile schema at:
* at <a href="https://wiki.gcube-system.org/gcube/GCat_Background#Metadata_Profile_v.4">Metadata Profile</>
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Profile.PROFILES) @Path(Profile.PROFILES)
@ -87,10 +84,7 @@ public class Profile extends BaseREST implements org.gcube.gcat.api.interfaces.P
* @return a JSON Array. * @return a JSON Array.
* *
* @pathExample /profiles * @pathExample /profiles
* @responseExample application/json;charset=UTF-8 ["EmptyProfile","TestProfile",...,"ComplexProfile"] * @responseExample application/json ["EmptyProfile","TestProfile","ComplexProfile"]
*
* @pathExample /profiles?count=true
* @responseExample application/json;charset=UTF-8 {"count":5}
* *
*/ */
@GET @GET
@ -178,6 +172,16 @@ public class Profile extends BaseREST implements org.gcube.gcat.api.interfaces.P
} }
} }
/**
* A profile must comply with the defined <a href="../profiles/SCHEMA">XSD schema</a> .
*
* Please find the documentation of profile schema at:
* at <a href="https://wiki.gcube-system.org/gcube/GCat_Background#Metadata_Profile_v.4">Metadata Profile</>
*
* @param name
* @param xml
* @return
*/
@PUT @PUT
@Path("/{" + PROFILE_NAME_PARAMETER + "}") @Path("/{" + PROFILE_NAME_PARAMETER + "}")
@Consumes(MediaType.APPLICATION_XML) @Consumes(MediaType.APPLICATION_XML)

View File

@ -23,37 +23,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* An Resource is mainly described by the following attributes (* indicate mandatory attributes): * An Item's Resource is an URL (e.g. URL pointing to a file)
* * and can exists only attached to an <a href="./resource_Item.html">item</a>.
* <dl>
* <dt>name* (string)</dt>
* <dd>the name of the resource;</dd>
*
* <dt style="margin-top: 5px;">url* (string)</dt>
* <dd>url of resource;</dd>
*
* <dt style="margin-top: 5px;">package_id* (string)</dt>
* <dd>id of the item that the resource should be added to;</dd>
*
* <dt style="margin-top: 5px;">revision_id (string)</dt>
* <dd></dd>
*
* <dt style="margin-top: 5px;">description (string)</dt>
* <dd>a description for the resource;</dd>
*
* <dt style="margin-top: 5px;">format (string)</dt>
* <dd></dd>
*
* <dt style="margin-top: 5px;">mimetype (string)</dt>
* <dd>resource mimetype;</dd>
*
* <dt style="margin-top: 5px;">created (iso date string)</dt>
* <dd>resource creation time;</dd>
*
* <dt style="margin-top: 5px;">last_modified (iso date string)</dt>
* <dd>resource last update time;</dd>
*
* </dl>
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@ -79,6 +50,39 @@ public class Resource extends BaseREST implements org.gcube.gcat.api.interfaces.
return ckanResource.list(); return ckanResource.list();
} }
/**
* An Resource is mainly described by the following attributes (* indicate mandatory attributes):
*
* <dl>
* <dt>name* (string)</dt>
* <dd>the name of the resource;</dd>
*
* <dt style="margin-top: 5px;">url* (string)</dt>
* <dd>url of resource;</dd>
*
* <dt style="margin-top: 5px;">package_id* (string)</dt>
* <dd>id of the item that the resource should be added to;</dd>
*
* <dt style="margin-top: 5px;">revision_id (string)</dt>
* <dd></dd>
*
* <dt style="margin-top: 5px;">description (string)</dt>
* <dd>a description for the resource;</dd>
*
* <dt style="margin-top: 5px;">format (string)</dt>
* <dd></dd>
*
* <dt style="margin-top: 5px;">mimetype (string)</dt>
* <dd>resource mimetype;</dd>
*
* <dt style="margin-top: 5px;">created (iso date string)</dt>
* <dd>resource creation time;</dd>
*
* <dt style="margin-top: 5px;">last_modified (iso date string)</dt>
* <dd>resource last update time;</dd>
*
* </dl>
*/
@POST @POST
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)

View File

@ -7,6 +7,7 @@ import javax.ws.rs.GET;
import javax.ws.rs.Path; import javax.ws.rs.Path;
import javax.ws.rs.Produces; import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam; import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response; import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status; import javax.ws.rs.core.Response.Status;
import javax.xml.ws.WebServiceException; import javax.xml.ws.WebServiceException;
@ -19,8 +20,12 @@ import org.gcube.gcat.persistence.ckan.CKANPackageTrash;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup; import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
import com.webcohesion.enunciate.metadata.rs.ResponseCode;
import com.webcohesion.enunciate.metadata.rs.StatusCodes;
/** /**
* This collection allow to interact with thrashed items
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Trash.TRASH) @Path(Trash.TRASH)
@ -28,9 +33,29 @@ import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
@ResourceLabel("Trash APIs") @ResourceLabel("Trash APIs")
public class Trash extends BaseREST implements org.gcube.gcat.api.interfaces.Trash<Response> { public class Trash extends BaseREST implements org.gcube.gcat.api.interfaces.Trash<Response> {
/**
* List the thrashed items.<br/>
* By default, it lists only the trashed items of the requesting user.<br/>
*
* The listed items belong to the supported organizations for the
* context of the request (i.e. the context where the token has been generated).<br/>
*
* See <a href="./resource_Configuration.html">supportedOrganizations parameter in
* Configuration</a>.
*
* If the user specifies <code>own_only=false</code> and the user is
* <em>Catalogue-Admin</em> or above it return the thrashed items of all the
* users for all the supported organizations.
*
* @param ownOnly indicates that the user is interested only in its own items or the items of all the users.
* @return the json array containing the items in the trash
*
* @pathExample /trash
* @responseExample application/json ["item1","item54"]
*/
@GET @GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(MediaType.APPLICATION_JSON)
@Override @Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public String list(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException { public String list(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException {
@ -39,7 +64,34 @@ public class Trash extends BaseREST implements org.gcube.gcat.api.interfaces.Tra
return ckanPackageTrash.list(); return ckanPackageTrash.list();
} }
/**
* Delete in background all items in the trash.<br/>
* The operation returns immediately to the client and continues in background.<br/>
* There is no way to monitor or stop the running operation.<br/>
* The thrashed items cannot be recovered.</br/>
*
* By default, it empty only the trashed items of the requesting user.<br/>
*
* The listed items belong to the supported organizations for the
* context of the request (i.e. the context where the token has been generated).<br/>
*
* See <a href="./resource_Configuration.html">supportedOrganizations parameter in
* Configuration</a>.
*
* If the user specifies <code>own_only=false</code> and the user is
* <em>Catalogue-Admin</em> or above it empty the thrash of all the
* users for all the supported organizations.
*
* @param ownOnly indicates that the user is interested only in its own items or the items of all the users.
* @return 202 Accepted if the request has been accepted successfully
* @throws WebServiceException
*
* @pathExample /trash
*/
@DELETE @DELETE
@StatusCodes ({
@ResponseCode ( code = 202, condition = "The empty trash operation has been accepted successfully.")
})
@Override @Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public Response empty(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException { public Response empty(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException {
@ -55,7 +107,14 @@ public class Trash extends BaseREST implements org.gcube.gcat.api.interfaces.Tra
return Response.status(Status.ACCEPTED).build(); return Response.status(Status.ACCEPTED).build();
} }
/**
* It is the same of
* <a href="resource_Trash.html#resource_Trash_empty_ownOnly_DELETE">DELETE</a> operation
*/
@PURGE @PURGE
@StatusCodes ({
@ResponseCode ( code = 202, condition = "The empty trash operation has been accepted successfully.")
})
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) // @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public Response emptyViaPurge(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException { public Response emptyViaPurge(@QueryParam(GCatConstants.OWN_ONLY_QUERY_PARAMETER) @DefaultValue("true") Boolean ownOnly) throws WebServiceException {
return empty(ownOnly); return empty(ownOnly);

View File

@ -45,94 +45,8 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
import com.webcohesion.enunciate.metadata.swagger.OperationId; import com.webcohesion.enunciate.metadata.swagger.OperationId;
/** /**
* * The catalogue configuration for the context of the request
* A Configuration is described by the following attributes: * (i.e. the context where the token has been generated).
*
* <dl>
*
* <dt>context (string)</dt>
* <dd>it must contains the same value of requesting context;</dd>
*
* <dt style="margin-top: 5px;">defaultOrganization (string)</dt>
* <dd>
* the default ckan organization where an item is created for
* the context of the request;
* </dd>
*
* <dt style="margin-top: 5px;">supportedOrganizations (array of string)</dt>
* <dd>
* it defines the list of organization where an item can be created.
* All the organizations must be present in the catalogue of the VRE.
* It must contains at least the defaultOrganization value;
* </dd>
*
* <dt style="margin-top: 5px;">sysAdminToken (string)</dt>
* <dd>
* the token can be provided encrypted with the context key as well as plain.
* It any case it is persisted encrypted in IS;
* </dd>
*
* <dt style="margin-top: 5px;">ckanURL (string)</dt>
* <dd>
* the Ckan URL used for the catalogue of the VRE.
* </dd>
*
* <dt style="margin-top: 5px;">solrURL (string)</dt>
* <dd>
* the Solr URL used by the Ckan instance.
* This is normally, but not necessary, the same URL of Ckan plus the path <code>/solr</code>
* </dd>
*
* <dt style="margin-top: 5px;">socialPostEnabled (bool)</dt>
* <dd>
* it indicates if the social posts are enabled in the context of the request.
* The creation of a social post can be requested by a user when he/she creates
* an item;
* </dd>
*
* <dt style="margin-top: 5px;">notificationToUsersEnabled (bool)</dt>
* <dd>
* it indicates if a notification must be created when a social post
* is created. It is ignored if <code>socialPostEnabled=false</code>;
* </dd>
*
* <dt style="margin-top: 5px;">moderationEnabled (bool)</dt>
* <dd>
* it indicates if the catalogue is moderated.
* See <a href="../docs/index.html#moderated-catalogues">Moderated Catalogues</a>
* </dd>
*
* <dt style="margin-top: 5px;">ckanDB (object)</dt>
* <dd>
* it contains the url, username and password to contact the db used by the
* Ckan instance used for the catalogue of the VRE.
* The password can be provided encrypted with the context key as well as plain.
* It any case it is persisted encrypted in IS.
* </dd>
*
* </dl>
*
* Here is an example
*
* <pre>
* {
* "context": "/gcube/devsec/devVRE",
* "defaultOrganization": "devvre",
* "supportedOrganizations": [ "devvre" "nextnext" ],
* "sysAdminToken": "SYS_ADMIN_TOKEN_HERE",
* "ckanURL": "https://ckan-d-d4s.d4science.org",
* "solrURL": "https://ckan-d-d4s.d4science.org/solr/",
* "socialPostEnabled": false,
* "notificationToUsersEnabled": true,
* "moderationEnabled": true,
* "ckanDB": {
* "url": "jdbc:postgresql://ckan-d-d4s.d4science.org:5432/ckan_dev",
* "username": "ckan",
* "password": "PWD_HERE"
* }
* }
* </pre>
*
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@ -199,6 +113,92 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
* *
* The configuration will be persisted in the infrastructure * The configuration will be persisted in the infrastructure
* Information System (IS) in the context of the request.<br/> * Information System (IS) in the context of the request.<br/>
* * A Configuration is described by the following attributes:
*
* <dl>
*
* <dt>context (string)</dt>
* <dd>it must contains the same value of requesting context;</dd>
*
* <dt style="margin-top: 5px;">defaultOrganization (string)</dt>
* <dd>
* the default ckan organization where an item is created for
* the context of the request;
* </dd>
*
* <dt style="margin-top: 5px;">supportedOrganizations (array of string)</dt>
* <dd>
* it defines the list of organization where an item can be created.
* All the organizations must be present in the catalogue of the VRE.
* It must contains at least the defaultOrganization value;
* </dd>
*
* <dt style="margin-top: 5px;">sysAdminToken (string)</dt>
* <dd>
* the token can be provided encrypted with the context key as well as plain.
* It any case it is persisted encrypted in IS;
* </dd>
*
* <dt style="margin-top: 5px;">ckanURL (string)</dt>
* <dd>
* the Ckan URL used for the catalogue of the VRE.
* </dd>
*
* <dt style="margin-top: 5px;">solrURL (string)</dt>
* <dd>
* the Solr URL used by the Ckan instance.
* This is normally, but not necessary, the same URL of Ckan plus the path <code>/solr</code>
* </dd>
*
* <dt style="margin-top: 5px;">socialPostEnabled (bool)</dt>
* <dd>
* it indicates if the social posts are enabled in the context of the request.
* The creation of a social post can be requested by a user when he/she creates
* an item;
* </dd>
*
* <dt style="margin-top: 5px;">notificationToUsersEnabled (bool)</dt>
* <dd>
* it indicates if a notification must be created when a social post
* is created. It is ignored if <code>socialPostEnabled=false</code>;
* </dd>
*
* <dt style="margin-top: 5px;">moderationEnabled (bool)</dt>
* <dd>
* it indicates if the catalogue is moderated.
* See <a href="../docs/index.html#moderated-catalogues">Moderated Catalogues</a>
* </dd>
*
* <dt style="margin-top: 5px;">ckanDB (object)</dt>
* <dd>
* it contains the url, username and password to contact the db used by the
* Ckan instance used for the catalogue of the VRE.
* The password can be provided encrypted with the context key as well as plain.
* It any case it is persisted encrypted in IS.
* </dd>
*
* </dl>
*
* Here is an example
*
* <pre>
* {
* "context": "/gcube/devsec/devVRE",
* "defaultOrganization": "devvre",
* "supportedOrganizations": [ "devvre" "nextnext" ],
* "sysAdminToken": "SYS_ADMIN_TOKEN_HERE",
* "ckanURL": "https://ckan-d-d4s.d4science.org",
* "solrURL": "https://ckan-d-d4s.d4science.org/solr/",
* "socialPostEnabled": false,
* "notificationToUsersEnabled": true,
* "moderationEnabled": true,
* "ckanDB": {
* "url": "jdbc:postgresql://ckan-d-d4s.d4science.org:5432/ckan_dev",
* "username": "ckan",
* "password": "PWD_HERE"
* }
* }
* </pre>
* *
* *
* @param json the configuration representation * @param json the configuration representation

View File

@ -26,6 +26,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* This concept is mutated by Ckan which is used as underling technology to persist items.
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Group.GROUPS) @Path(Group.GROUPS)

View File

@ -26,6 +26,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* This concept is mutated by Ckan which is used as underling technology to persist items.
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(Organization.ORGANIZATIONS) @Path(Organization.ORGANIZATIONS)

View File

@ -28,6 +28,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
/** /**
* This collection allows to interact with the catalogue users.
*
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@Path(User.USERS) @Path(User.USERS)

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,32 @@
[
{
"id": "ClassificationInformation",
"title": "Classification Information",
"name": "ClassificationInformation",
"description": "Classification Information"
},
{
"id": "LocationInformation",
"title": "Location Information",
"name": "LocationInformation",
"description": "Location Information"
},
{
"id": "ContactInformation",
"title": "Contact Information",
"name": "ContactInformation",
"description": "Contact Information"
},
{
"id": "OtherInformation",
"title": "Other Information",
"name": "OtherInformation",
"description": "Other Information"
},
{
"id": "AvailabilityInformation",
"title": "Availability Information",
"name": "AvailabilityInformation",
"description": "Availability Information"
}
]