Improving documentation for configuration
This commit is contained in:
parent
673a6fadeb
commit
151783e813
|
|
@ -96,13 +96,12 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
|
||||
/**
|
||||
* Creates the catalogue configuration for the current context using the json
|
||||
* provided as request body.
|
||||
* Only a Catalogue-Manager can invoke this API.
|
||||
* This API allows to create the catalogue configuration for the
|
||||
* context of the request (i.e. the context where the token has been generated)
|
||||
* using the json provided as request body.
|
||||
* Only a <a href="../docs/index.html#roles">Catalogue-Manager</a> can invoke this API.
|
||||
* The configuration will be persisted in the infrastructure
|
||||
* Information System (IS) in the context of the request
|
||||
* (i.e. the context where the token has been generated).
|
||||
*
|
||||
* Information System (IS) in the context of the request.
|
||||
*
|
||||
* Let consider the following example:
|
||||
*
|
||||
|
|
@ -224,6 +223,41 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* This API allows to read the catalogue configuration for the
|
||||
* current context (i.e. the context where the token has been generated).
|
||||
*
|
||||
* Please refers to <a href="#resource_Configuration_create_json_POST">Create Configuration API</a>
|
||||
* for the list of configuration properties and their meaning.
|
||||
*
|
||||
* This API can be invoked by any user with at least
|
||||
* <a href="../docs/index.html#roles">Catalogue-Editor</a> role.
|
||||
*
|
||||
* For any non <a href="../docs/index.html#roles">Catalogue-Manager</a> user the configuration
|
||||
* will contain only a subset of the properties of the configuration. *
|
||||
* Here is an example:
|
||||
*
|
||||
* <pre>
|
||||
* {
|
||||
* "context": "/gcube/devsec/devVRE",
|
||||
* "defaultOrganization": "devvre",
|
||||
* "supportedOrganizations": [ "devvre" "nextnext" ],
|
||||
* "ckanURL": "https://ckan-d-d4s.d4science.org",
|
||||
* "solrURL": "https://ckan-d-d4s.d4science.org/solr/",
|
||||
* "socialPostEnabled": false,
|
||||
* "notificationToUsersEnabled": true,
|
||||
* "moderationEnabled": true
|
||||
* }
|
||||
* </pre>
|
||||
*
|
||||
* @param context must contains the context of the request
|
||||
* or the placeholder <code>CURRENT_CONTEXT</code>.<br/>
|
||||
* Please note that the context must be URL encoded,
|
||||
* e.g. /gcube/devsec/devVRE -> %2Fgcube%2Fdevsec%2FdevVRE
|
||||
*
|
||||
* @pathExample /configurations/CURRENT_CONTEXT
|
||||
* @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/configuration/read-configuration-response.json
|
||||
*/
|
||||
@GET
|
||||
@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
|
||||
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
|
|
@ -267,6 +301,112 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* This API allows to create/update the catalogue configuration for the
|
||||
* context of the request (i.e. the context where the token has been generated)
|
||||
* using the json provided as request body.
|
||||
* Only a <a href="../docs/index.html#roles">Catalogue-Manager</a> can invoke this API.
|
||||
* The configuration will be persisted in the infrastructure
|
||||
* Information System (IS) in the context of the request.
|
||||
*
|
||||
* Let consider the following 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>
|
||||
*
|
||||
* We have the following properties:
|
||||
*
|
||||
* <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>
|
||||
*
|
||||
* @param context must contains the context of the request
|
||||
* or the placeholder <code>CURRENT_CONTEXT</code>.<br/>
|
||||
* Please note that the context must be URL encoded,
|
||||
* e.g. /gcube/devsec/devVRE -> %2Fgcube%2Fdevsec%2FdevVRE
|
||||
* @param json the configuration representation
|
||||
* @return the updated/created configuration
|
||||
* @throws WebServiceException when the request fails
|
||||
*
|
||||
* @pathExample /configurations/CURRENT_CONTEXT
|
||||
* @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/configuration/create-configuration-request.json
|
||||
* @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/configuration/create-configuration-response.json
|
||||
*/
|
||||
@PUT
|
||||
@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
|
||||
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
|
|
@ -309,6 +449,31 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* This API allows to patch the catalogue configuration for the
|
||||
* context of the request (i.e. the context where the token has been generated)
|
||||
* using the json provided as request body.
|
||||
* Only a <a href="../docs/index.html#roles">Catalogue-Manager</a> can invoke this API.
|
||||
* The configuration will be persisted in the infrastructure
|
||||
* Information System (IS) in the context of the request.
|
||||
*
|
||||
*
|
||||
*
|
||||
* Please refers to <a href="#resource_Configuration_create_json_POST">Create Configuration API</a>
|
||||
* for the list of configuration properties and their meaning.
|
||||
*
|
||||
* @param context must contains the context of the request
|
||||
* or the placeholder <code>CURRENT_CONTEXT</code>.<br/>
|
||||
* Please note that the context must be URL encoded,
|
||||
* e.g. /gcube/devsec/devVRE -> %2Fgcube%2Fdevsec%2FdevVRE
|
||||
* @param json must contains only the properties of the configuratoin the user wants to change.
|
||||
* @return the patched configuration.
|
||||
* @throws WebServiceException when the request fails
|
||||
*
|
||||
* @pathExample /configurations/CURRENT_CONTEXT
|
||||
* @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/configuration/create-configuration-request.json
|
||||
* @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/configuration/create-configuration-response.json
|
||||
*/
|
||||
@PATCH
|
||||
@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
|
||||
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
|
|
@ -370,6 +535,27 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* It removes from the cache the configuration for the
|
||||
* context of the request (i.e. the context where the token has been generated).
|
||||
*
|
||||
* This API forces the service to read again from the Information System (IS)
|
||||
* the catalogue configuration for the context of the request.
|
||||
*
|
||||
* If the user specifies the <code>purge</code> query parameter this API
|
||||
* remove the configuration from the IS. Please note that this implies that
|
||||
* the catalogue is no more configured for the context of the request.
|
||||
*
|
||||
*
|
||||
* @param context context must contains the context of the request
|
||||
* or the placeholder <code>CURRENT_CONTEXT</code>.<br/>
|
||||
* Please note that the context must be URL encoded,
|
||||
* e.g. /gcube/devsec/devVRE -> %2Fgcube%2Fdevsec%2FdevVRE
|
||||
* @param purge indicates to the service to remvoe the configuration from the IS
|
||||
* @throws WebServiceException
|
||||
*
|
||||
* @pathExample /configurations/CURRENT_CONTEXT
|
||||
*/
|
||||
@DELETE
|
||||
@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
|
||||
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
|
||||
|
|
@ -407,6 +593,21 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* It removes remove the configuration from the IS for the
|
||||
* context of the request (i.e. the context where the token has been generated).
|
||||
*
|
||||
* Please note that this implies that
|
||||
* the catalogue is no more configured for the context of the request.
|
||||
*
|
||||
* @param context context must contains the context of the request
|
||||
* or the placeholder <code>CURRENT_CONTEXT</code>.<br/>
|
||||
* Please note that the context must be URL encoded,
|
||||
* e.g. /gcube/devsec/devVRE -> %2Fgcube%2Fdevsec%2FdevVRE
|
||||
* @throws WebServiceException
|
||||
*
|
||||
* @pathExample /configurations/CURRENT_CONTEXT
|
||||
*/
|
||||
@PURGE
|
||||
@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
|
||||
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
{
|
||||
"id": "584b8503-a490-4a89-8372-e21830fa716c",
|
||||
"context": "/gcube/devsec/devVRE",
|
||||
"defaultOrganization": "devvre",
|
||||
"supportedOrganizations": [
|
||||
"nextnext",
|
||||
"devvre"
|
||||
],
|
||||
"ckanURL": "https://ckan-d-d4s.d4science.org",
|
||||
"solrURL": "https://ckan-d-d4s.d4science.org/solr/",
|
||||
"socialPostEnabled": false,
|
||||
"notificationToUsersEnabled": true,
|
||||
"moderationEnabled": false
|
||||
}
|
||||
Loading…
Reference in New Issue