2016-06-07 16:00:05 +02:00
|
|
|
package org.gcube.datacatalogue.ckanutillibrary;
|
|
|
|
|
|
|
|
import java.util.List;
|
|
|
|
import java.util.Map;
|
|
|
|
|
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.models.CKanUserWrapper;
|
2016-08-04 18:24:39 +02:00
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.models.CkanDatasetRelationship;
|
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.models.DatasetRelationships;
|
2016-06-14 12:31:19 +02:00
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.models.ResourceBean;
|
2016-06-14 17:05:24 +02:00
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.models.RolesIntoOrganization;
|
2016-06-07 16:00:05 +02:00
|
|
|
|
2016-07-13 16:21:24 +02:00
|
|
|
import eu.trentorise.opendata.jackan.model.CkanLicense;
|
2016-06-07 16:00:05 +02:00
|
|
|
import eu.trentorise.opendata.jackan.model.CkanOrganization;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* This is the ckan-util-library interface that shows the utility methods.
|
|
|
|
* @author Costantino Perciante at ISTI-CNR (costantino.perciante@isti.cnr.it)
|
|
|
|
*/
|
2016-07-02 23:57:46 +02:00
|
|
|
public interface CKanUtils {
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
2016-06-14 17:05:24 +02:00
|
|
|
* Retrieve the API_KEY given the username (only if it is active).
|
2016-06-07 16:00:05 +02:00
|
|
|
* @param username
|
2016-06-14 17:05:24 +02:00
|
|
|
* @return an API_KEY string on success, null otherwise
|
2016-06-07 16:00:05 +02:00
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
String getApiKeyFromUsername(String username);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
|
|
|
* Retrieve the user given the API_KEY (the user is retrieved if it is active).
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param the user api key
|
2016-06-07 16:00:05 +02:00
|
|
|
* @return an API_KEY string
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
CKanUserWrapper getUserFromApiKey(String apiKey);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
2016-06-18 16:59:07 +02:00
|
|
|
* Returns the list of organizations to whom the user belongs (with any role)
|
2016-06-07 16:00:05 +02:00
|
|
|
* @param username
|
|
|
|
* @return a list of organizations
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
List<CkanOrganization> getOrganizationsByUser(String username);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
2016-06-18 16:59:07 +02:00
|
|
|
* Returns the list of organizations' names to whom the user belongs (with any role)
|
2016-06-07 16:00:05 +02:00
|
|
|
* @param username
|
|
|
|
* @return a list of organizations
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
List<String> getOrganizationsNamesByUser(String username);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
2016-06-14 17:05:24 +02:00
|
|
|
* Given a username and a list of roles to be matched, find the organizations in which the user has these roles.
|
2016-06-18 16:59:07 +02:00
|
|
|
* Please note that the role SYSADMIN is infra-organizations, so won't be considered (use the method isSysAdmin(String username, String apiKey))
|
2016-06-07 16:00:05 +02:00
|
|
|
* @param username
|
|
|
|
* @param rolesToMatch
|
2016-06-18 16:59:07 +02:00
|
|
|
* @return a list (orgsName, roles in this organization), null on error
|
2016-06-07 16:00:05 +02:00
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
Map<String, List<RolesIntoOrganization>> getGroupsAndRolesByUser(String username, List<RolesIntoOrganization> rolesToMatch);
|
2016-06-07 16:00:05 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return the ckan catalogue url in this scope.
|
2016-06-16 18:09:26 +02:00
|
|
|
* @return the catalogue url
|
2016-06-07 16:00:05 +02:00
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
String getCatalogueUrl();
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
|
|
|
* Get the list of licenses' titles.
|
2016-06-08 18:31:25 +02:00
|
|
|
* @return the list of licenses' titles
|
2016-06-07 16:00:05 +02:00
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
List<String> getLicenseTitles();
|
2016-08-04 18:24:39 +02:00
|
|
|
|
2016-07-13 16:21:24 +02:00
|
|
|
/**
|
|
|
|
* Retrieve ckan licenses
|
|
|
|
* @return
|
|
|
|
*/
|
|
|
|
List<CkanLicense> getLicenses();
|
2016-08-04 18:24:39 +02:00
|
|
|
|
2016-06-18 10:12:47 +02:00
|
|
|
/**
|
|
|
|
* Retrieve the list of organizations ids
|
|
|
|
* @return
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
List<String> getOrganizationsIds();
|
2016-06-18 16:59:07 +02:00
|
|
|
|
2016-06-18 10:12:47 +02:00
|
|
|
/**
|
|
|
|
* Retrieve the list of organizations names
|
|
|
|
* @return
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
List<String> getOrganizationsNames();
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
/**
|
|
|
|
* Finds the id associated to the chosen license
|
|
|
|
* @param chosenLicense
|
2016-06-08 18:31:25 +02:00
|
|
|
* @return the id on success, null otherwise
|
2016-06-07 16:00:05 +02:00
|
|
|
*/
|
2016-09-12 10:39:49 +02:00
|
|
|
String findLicenseIdByLicenseTitle(String chosenLicense);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Set dataset private
|
|
|
|
* @param priv
|
2016-09-09 16:38:05 +02:00
|
|
|
* @param organizationId (NOTE: The ID, not the name!)
|
|
|
|
* @param datasetId (NOTE: The ID, not the name!)
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey the user's api key
|
2016-06-10 16:26:01 +02:00
|
|
|
* @return true on success, false otherwise
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
boolean setDatasetPrivate(boolean priv, String organizationId, String datasetId, String apiKey);
|
2016-06-10 16:26:01 +02:00
|
|
|
|
2016-06-14 12:31:19 +02:00
|
|
|
/**
|
|
|
|
* Add a resource described by the bean to the dataset id into resource.datasetId
|
|
|
|
* @param resource
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey the user api key
|
2016-06-14 12:31:19 +02:00
|
|
|
* @return String the id of the resource on success, null otherwise
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
String addResourceToDataset(ResourceBean resource, String apiKey);
|
2016-06-14 12:31:19 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Remove the resource with id resourceId from the dataset in which it is.
|
|
|
|
* @param resourceId
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey the user's api key
|
2016-06-14 12:31:19 +02:00
|
|
|
* @return true on success, false otherwise.
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
boolean deleteResourceFromDataset(String resourceId, String apiKey);
|
2016-06-14 12:31:19 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Create a dataset with those information.
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey
|
2016-06-14 12:31:19 +02:00
|
|
|
* @param title
|
|
|
|
* @param organizationNameOrId
|
|
|
|
* @param author
|
|
|
|
* @param authorMail
|
|
|
|
* @param maintainer
|
|
|
|
* @param maintainerMail
|
|
|
|
* @param version
|
|
|
|
* @param description
|
|
|
|
* @param licenseId
|
|
|
|
* @param tags
|
|
|
|
* @param customFields
|
|
|
|
* @param resources
|
2016-09-09 16:38:05 +02:00
|
|
|
* @param setPublic (manage visibility: Admin role is needed)
|
2016-06-14 12:31:19 +02:00
|
|
|
* @return the id of the dataset on success, null otherwise
|
|
|
|
*/
|
2016-07-14 10:45:24 +02:00
|
|
|
String createCKanDataset(String apiKey, String title, String organizationNameOrId, String author,
|
2016-06-14 12:31:19 +02:00
|
|
|
String authorMail, String maintainer, String maintainerMail, long version, String description, String licenseId,
|
|
|
|
List<String> tags, Map<String, String> customFields, List<ResourceBean> resources, boolean setPublic);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Given the id or the name of the dataset it returns its current url (e.g., http://ckan-catalogue-address.org/dataset/dataset-name)
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey
|
2016-06-14 12:31:19 +02:00
|
|
|
* @param datasetId
|
2016-06-29 11:58:11 +02:00
|
|
|
* @param withoutHost if the host part is not needed (e.g. it returns only /dataset/dataset-name)
|
2016-06-14 12:31:19 +02:00
|
|
|
* @return The url of the dataset on success, null otherwise
|
|
|
|
*/
|
2016-06-29 11:17:23 +02:00
|
|
|
String getUrlFromDatasetIdOrName(String apiKey, String datasetIdOrName, boolean withoutHost);
|
2016-06-18 16:59:07 +02:00
|
|
|
|
2016-06-14 17:05:24 +02:00
|
|
|
/**
|
2016-06-16 18:09:26 +02:00
|
|
|
* Check if this user is a sysadmin. The api key is used to authorize this call.
|
2016-06-14 17:05:24 +02:00
|
|
|
* @param username
|
2016-06-16 18:09:26 +02:00
|
|
|
* @param apiKey the current user's api key
|
2016-06-14 17:05:24 +02:00
|
|
|
* @return true on success, false otherwise
|
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
boolean isSysAdmin(String username, String apiKey);
|
2016-06-14 17:05:24 +02:00
|
|
|
|
|
|
|
/**
|
2016-09-09 16:38:05 +02:00
|
|
|
* Check if this role is present for this user in that organization. If it is not present we need to add it with the given role.
|
2016-06-14 17:05:24 +02:00
|
|
|
* @param username
|
|
|
|
* @param organizationName
|
|
|
|
* @param correspondentRoleToCheck
|
2016-06-18 10:05:10 +02:00
|
|
|
* @return true if the role can be set, false if it cannot
|
2016-06-14 17:05:24 +02:00
|
|
|
*/
|
2016-06-28 17:19:45 +02:00
|
|
|
boolean checkRole(String username, String organizationName,
|
2016-06-14 17:05:24 +02:00
|
|
|
RolesIntoOrganization correspondentRoleToCheck);
|
2016-06-26 21:59:26 +02:00
|
|
|
|
2016-06-29 11:44:24 +02:00
|
|
|
/**
|
2016-08-04 18:24:39 +02:00
|
|
|
* Return the catalogue portlet for this context(i.e. scope)
|
2016-06-29 11:44:24 +02:00
|
|
|
* @return
|
|
|
|
*/
|
|
|
|
String getPortletUrl();
|
2016-08-04 18:24:39 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a relationship between a "subject" dataset and an "object" dataset
|
|
|
|
* Please note that according to ckan apis the following must be valid:
|
|
|
|
* <blockquote>To create a relationship between two datasets (packages),
|
|
|
|
* You must be authorized to edit both the subject and the object datasets.</blockquote>
|
2016-09-01 16:57:01 +02:00
|
|
|
* The relationship can be one of the following:
|
2016-08-04 18:24:39 +02:00
|
|
|
* <ul>
|
|
|
|
* <li> depends_on
|
|
|
|
* <li> dependency_of
|
|
|
|
* <li> derives_from
|
|
|
|
* <li> has_derivation
|
|
|
|
* <li> child_of
|
|
|
|
* <li> parent_of
|
|
|
|
* <li> links_to
|
|
|
|
* <li> linked_from
|
|
|
|
* </ul>
|
|
|
|
* @param datasetIdSubject
|
|
|
|
* @param datasetIdObject
|
|
|
|
* @param relation
|
|
|
|
* @param relationComment a comment about the relation
|
|
|
|
* @param apiKey the user api key
|
|
|
|
* @return <b>true</b> on success, <b>false</b> otherwise.
|
|
|
|
*/
|
|
|
|
boolean createDatasetRelationship(String datasetIdSubject, String datasetIdObject, DatasetRelationships relation, String relationComment, String apiKey);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Deletes a relationship between a "subject" dataset and an "object" dataset
|
|
|
|
* Please note that according to ckan apis the following must be valid:
|
|
|
|
* <blockquote>You must be authorised to delete dataset relationships, and to edit both the subject and the object datasets.</blockquote>
|
2016-09-01 16:57:01 +02:00
|
|
|
* The relationship can be one of the following:
|
2016-08-04 18:24:39 +02:00
|
|
|
* <ul>
|
|
|
|
* <li> depends_on
|
|
|
|
* <li> dependency_of
|
|
|
|
* <li> derives_from
|
|
|
|
* <li> has_derivation
|
|
|
|
* <li> child_of
|
|
|
|
* <li> parent_of
|
|
|
|
* <li> links_to
|
|
|
|
* <li> linked_from
|
|
|
|
* </ul>
|
|
|
|
* @param datasetIdSubject
|
|
|
|
* @param datasetIdObject
|
|
|
|
* @param relation
|
|
|
|
* @param apiKey the user api key
|
|
|
|
* @return <b>true</b> on success, <b>false</b> otherwise.
|
|
|
|
*/
|
|
|
|
boolean deleteDatasetRelationship(String datasetIdSubject, String datasetIdObject, DatasetRelationships relation, String apiKey);
|
|
|
|
|
|
|
|
/**
|
2016-09-02 11:18:11 +02:00
|
|
|
* Returns the list of relationships between dataset datasetIdSubject and dataset datasetIdObject. If datasetIdObject is missing, the whole list of
|
|
|
|
* relationships for dataset datasetIdSubject is returned.
|
2016-08-04 18:24:39 +02:00
|
|
|
* @param datasetIdSubject
|
|
|
|
* @param datasetIdObject
|
|
|
|
* @param apiKey
|
|
|
|
* @return list of CkanDatasetRelationship objects or null if an error occurs
|
|
|
|
*/
|
|
|
|
List<CkanDatasetRelationship> getRelationshipDatasets(String datasetIdSubject, String datasetIdObject, String apiKey);
|
2016-09-12 15:00:30 +02:00
|
|
|
|
2016-06-07 16:00:05 +02:00
|
|
|
}
|