514 lines
17 KiB
Java
514 lines
17 KiB
Java
package org.gcube.datacatalogue.ckanutillibrary.server;
|
|
|
|
import java.io.File;
|
|
import java.sql.SQLException;
|
|
import java.util.List;
|
|
import java.util.Map;
|
|
|
|
import org.gcube.datacatalogue.ckanutillibrary.server.models.CKanUserWrapper;
|
|
import org.gcube.datacatalogue.ckanutillibrary.server.models.CkanDatasetRelationship;
|
|
import org.gcube.datacatalogue.ckanutillibrary.server.models.DatasetRelationships;
|
|
import org.gcube.datacatalogue.ckanutillibrary.server.models.ResourceBean;
|
|
import org.gcube.datacatalogue.ckanutillibrary.shared.RolesCkanGroupOrOrg;
|
|
import org.json.simple.JSONObject;
|
|
|
|
import eu.trentorise.opendata.jackan.model.CkanDataset;
|
|
import eu.trentorise.opendata.jackan.model.CkanGroup;
|
|
import eu.trentorise.opendata.jackan.model.CkanLicense;
|
|
import eu.trentorise.opendata.jackan.model.CkanOrganization;
|
|
import eu.trentorise.opendata.jackan.model.CkanResource;
|
|
|
|
/**
|
|
* This is the data-catalogue-library interface that shows the utility methods.
|
|
* @author Costantino Perciante at ISTI-CNR (costantino.perciante@isti.cnr.it)
|
|
*/
|
|
public interface DataCatalogue {
|
|
|
|
/**
|
|
* Retrieve the API_KEY given the username (only if it is active).
|
|
* @param username
|
|
* @return an API_KEY string on success, null otherwise
|
|
*/
|
|
String getApiKeyFromUsername(String username);
|
|
|
|
/**
|
|
* Retrieve the user given the API_KEY (the user is retrieved if it is active).
|
|
* @param the user api key
|
|
* @return an API_KEY string
|
|
*/
|
|
CKanUserWrapper getUserFromApiKey(String apiKey);
|
|
|
|
/**
|
|
* Returns the list of organizations to whom the user belongs (with any role)
|
|
* @param username
|
|
* @return a list of organizations
|
|
*/
|
|
List<CkanOrganization> getOrganizationsByUser(String username);
|
|
|
|
/**
|
|
* Returns the list of groups to whom the user belongs (with any role)
|
|
* @param username
|
|
* @return a list of groups
|
|
*/
|
|
List<CkanGroup> getGroupsByUser(String username);
|
|
|
|
/**
|
|
* Returns the list of organizations' names to whom the user belongs (with any role)
|
|
* @param username
|
|
* @return a list of organizations
|
|
*/
|
|
List<String> getOrganizationsNamesByUser(String username);
|
|
|
|
/**
|
|
* Given a username and a list of roles to be matched, find the organizations in which the user has these roles.
|
|
* Please note that the role SYSADMIN is infra-organizations, so won't be considered (use the method isSysAdmin(String username, String apiKey))
|
|
* @param username
|
|
* @param rolesToMatch
|
|
* @return a list (orgsName, roles in this organization), null on error
|
|
*/
|
|
Map<String, List<RolesCkanGroupOrOrg>> getOrganizationsAndRolesByUser(String username, List<RolesCkanGroupOrOrg> rolesToMatch);
|
|
|
|
/**
|
|
* Return the ckan catalogue url in this scope.
|
|
* @return the catalogue url
|
|
*/
|
|
String getCatalogueUrl();
|
|
|
|
/**
|
|
* Return the manage product property
|
|
* @return the manage product property
|
|
*/
|
|
boolean isManageProductEnabled();
|
|
|
|
/**
|
|
* Get the list of licenses' titles.
|
|
* @return the list of licenses' titles
|
|
*/
|
|
List<String> getLicenseTitles();
|
|
|
|
/**
|
|
* Retrieve ckan licenses
|
|
* @return
|
|
*/
|
|
List<CkanLicense> getLicenses();
|
|
|
|
/**
|
|
* Retrieve the list of organizations ids
|
|
* @return
|
|
*/
|
|
List<String> getOrganizationsIds();
|
|
|
|
/**
|
|
* Retrieve the list of organizations names
|
|
* @return
|
|
*/
|
|
List<String> getOrganizationsNames();
|
|
|
|
/**
|
|
* Finds the id associated to the chosen license
|
|
* @param chosenLicense
|
|
* @return the id on success, null otherwise
|
|
*/
|
|
String findLicenseIdByLicenseTitle(String chosenLicense);
|
|
|
|
/**
|
|
* Add a resource described by the bean to the dataset id into resource.datasetId
|
|
* @param resource
|
|
* @param apiKey the user api key
|
|
* @return String the id of the resource on success, null otherwise
|
|
*/
|
|
String addResourceToDataset(ResourceBean resource, String apiKey);
|
|
|
|
/**
|
|
* Remove the resource with id resourceId from the dataset in which it is.
|
|
* @param resourceId
|
|
* @param apiKey the user's api key
|
|
* @return true on success, false otherwise.
|
|
*/
|
|
boolean deleteResourceFromDataset(String resourceId, String apiKey);
|
|
|
|
/**
|
|
* Create a dataset with those information.
|
|
* @param apiKey
|
|
* @param title
|
|
* @param name (unique identifier)
|
|
* @param organizationNameOrId
|
|
* @param author
|
|
* @param authorMail
|
|
* @param maintainer
|
|
* @param maintainerMail
|
|
* @param version
|
|
* @param description
|
|
* @param licenseId
|
|
* @param tags
|
|
* @param customFields
|
|
* @param resources
|
|
* @param setPublic (manage visibility: Admin role is needed)
|
|
* @return the id of the dataset on success, null otherwise
|
|
*/
|
|
String createCKanDataset(String apiKey, String title, String name, String organizationNameOrId, String author,
|
|
String authorMail, String maintainer, String maintainerMail, long version, String description, String licenseId,
|
|
List<String> tags, Map<String, String> customFields, List<ResourceBean> resources, boolean setPublic);
|
|
|
|
/**
|
|
* Create a dataset with those information. The method allows to have multiple values for the same custom field key.
|
|
* NOTE: unfortunately java doesn't support overload in java interface methods (that's way I cannot use the same name
|
|
* for the method)
|
|
* @param apiKey
|
|
* @param title
|
|
* @param name (unique identifier)
|
|
* @param organizationNameOrId
|
|
* @param author
|
|
* @param authorMail
|
|
* @param maintainer
|
|
* @param maintainerMail
|
|
* @param version
|
|
* @param description
|
|
* @param licenseId
|
|
* @param tags
|
|
* @param customFields
|
|
* @param resources
|
|
* @param setPublic (manage visibility: Admin role is needed)
|
|
* @return the id of the dataset on success, null otherwise
|
|
*/
|
|
String createCKanDatasetMultipleCustomFields(String apiKey, String title, String name, String organizationNameOrId, String author,
|
|
String authorMail, String maintainer, String maintainerMail, long version, String description, String licenseId,
|
|
List<String> tags, Map<String, List<String>> customFields, List<ResourceBean> resources, boolean setPublic);
|
|
|
|
/**
|
|
* Given the id or the name of the dataset it returns its current url by contacting the uri resolver.
|
|
* If no uri resolver is available, an url that is not guaranteed to be long term valid will be generated.
|
|
* The information are encoded in the url.
|
|
* @param datasetId
|
|
* @return The url of the dataset on success, null otherwise
|
|
*/
|
|
String getUrlFromDatasetIdOrName(String datasetIdOrName);
|
|
|
|
/**
|
|
* Given the id or the name of the dataset it returns its current url by contacting the uri resolver.
|
|
* If no uri resolver is available, an url that is not guaranteed to be long term valid will be generated.
|
|
* Information are not encrypted.
|
|
* @param datasetId
|
|
* @return The url of the dataset on success, null otherwise
|
|
*/
|
|
String getUnencryptedUrlFromDatasetIdOrName(String datasetIdOrName);
|
|
|
|
/**
|
|
* Check if this user is a sysadmin. The api key is used to authorize this call.
|
|
* @param username
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean isSysAdmin(String username);
|
|
|
|
/**
|
|
* Check if this role is present for this user in the organization. If he/she is not present we need to add it with the given role.
|
|
* @param username
|
|
* @param organizationName
|
|
* @param correspondentRoleToCheck
|
|
* @return true if the role can be set, false if it cannot
|
|
*/
|
|
boolean checkRoleIntoOrganization(String username, String organizationName, RolesCkanGroupOrOrg correspondentRoleToCheck);
|
|
|
|
/**
|
|
* Check if this role is present for this user in the group. If he/she is not present we need to add it with the given role.
|
|
* @param username
|
|
* @param organizationName
|
|
* @param correspondentRoleToCheck
|
|
* @return true if the role can be set, false if it cannot
|
|
*/
|
|
boolean checkRoleIntoGroup(String username, String groupName, RolesCkanGroupOrOrg correspondentRoleToCheck);
|
|
|
|
/**
|
|
* Return the catalogue portlet for this context(i.e. scope)
|
|
* @return
|
|
*/
|
|
String getPortletUrl();
|
|
|
|
/**
|
|
* 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>
|
|
* The relationship can be one of the following:
|
|
* <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>
|
|
* The relationship can be one of the following:
|
|
* <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);
|
|
|
|
/**
|
|
* 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.
|
|
* @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);
|
|
|
|
/**
|
|
* Checks if a product with such name already exists.
|
|
* Please remember that the name is unique.
|
|
* @param nameOrId the name or the id of the dataset to check
|
|
* @return
|
|
*/
|
|
boolean existProductWithNameOrId(String nameOrId);
|
|
|
|
/**
|
|
* Create a CkanGroup.
|
|
* @param nameOrId a unique id for the group
|
|
* @param title a title for the group
|
|
* @param description a description for the group
|
|
* @return the created CkanGroup on success, null otherwise
|
|
*/
|
|
CkanGroup createGroup(String nameOrId, String title, String description);
|
|
|
|
/**
|
|
* Associate a group with its parent.s
|
|
* @param parentName
|
|
* @param group
|
|
* @return
|
|
*/
|
|
boolean setGroupParent(String parentName, String groupName);
|
|
|
|
/**
|
|
* Returns a Map with key 'capacity' and as value a list of users with that capacity into the organization organizationName.
|
|
* @return
|
|
*/
|
|
Map<String, List<String>> getRolesAndUsersOrganization(String organizationName);
|
|
|
|
/**
|
|
* Returns a Map with key 'capacity' and as value a list of users with that capacity into the group groupNameOrTitle.
|
|
* @return
|
|
*/
|
|
Map<RolesCkanGroupOrOrg, List<String>> getRolesAndUsersGroup(String groupNameOrTitle);
|
|
|
|
/**
|
|
* Given the username and the organization name the method retrieves the role of the user (i.e. his/her 'capacity')
|
|
* @param username
|
|
* @param orgName
|
|
* @param apiKeyFromUsername
|
|
* @return the capacity of the user into this organization or null
|
|
*/
|
|
String getRoleOfUserInOrganization(String username, String orgName, String apiKeyFromUsername);
|
|
|
|
/**
|
|
* Given the username and the group name the method retrieves the role of the user (i.e. his/her 'capacity')
|
|
* @param username
|
|
* @param groupName
|
|
* @param apiKeyFromUsername
|
|
* @return the capacity of the user into this group or null
|
|
*/
|
|
String getRoleOfUserInGroup(String username, String groupName, String apiKey);
|
|
|
|
/**
|
|
* Assign a dataset to a group.
|
|
* @param groupNameOrId the id or the name of the destination group.
|
|
* @param datasetNameOrId the id or the name of the dataset
|
|
* @param apiKey (the apiKey should belong to someone that has the role of editor/admin of the organization in which
|
|
* the dataset is placed, plus the admin role into the destination group.
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean assignDatasetToGroup(String groupNameOrId, String datasetNameOrId,
|
|
String apiKey);
|
|
|
|
/**
|
|
* Remove a dataset from a group.
|
|
* @param groupNameOrId the id or the name of the group.
|
|
* @param datasetNameOrId the id or the name of the dataset
|
|
* @param apiKey (the apiKey should belong to someone that has the role of editor/admin of the organization in which
|
|
* the dataset is placed, plus the admin role into the destination group.
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean removeDatasetFromGroup(String groupNameOrId, String datasetNameOrId,
|
|
String apiKey);
|
|
|
|
/**
|
|
* Delete the dataset with id datasetId. If purge is true, the product will be purged too.
|
|
* @param datasetId
|
|
* @param apiKey
|
|
* @param purge
|
|
* @return
|
|
*/
|
|
boolean deleteProduct(String datasetId, String apiKey, boolean purge);
|
|
|
|
/**
|
|
* Retrieve a ckan dataset given its id
|
|
* @param datasetId
|
|
* @return
|
|
*/
|
|
CkanDataset getDataset(String datasetId, String apiKey);
|
|
|
|
/**
|
|
* Set searchable field
|
|
* The field, if set to true, allows organization's users to view private products also in groups
|
|
* @param datasetId the id of the dataset to update
|
|
* @param searchable the value to assign to the field
|
|
* @return true if the field is set, false otherwise
|
|
*/
|
|
boolean setSearchableField(String datasetId, boolean searchable);
|
|
|
|
/**
|
|
* Retrieve the list of groups in this instance
|
|
* @return a list of groups
|
|
*/
|
|
List<CkanGroup> getGroups();
|
|
|
|
/**
|
|
* Upload a file to ckan and attach it as resource.
|
|
* @param file
|
|
* @param packageId
|
|
* @param apiKey
|
|
* @param fileName
|
|
* @param description
|
|
* @return
|
|
*/
|
|
CkanResource uploadResourceFile(File file, String packageId, String apiKey, String fileName, String description);
|
|
|
|
/**
|
|
* Allows to change the url, the name and the description of a resource.
|
|
* @param resourceId
|
|
* @param url
|
|
* @param name
|
|
* @param description
|
|
* @param urlType
|
|
* @param apiKey
|
|
* @return
|
|
*/
|
|
boolean patchResource(String resourceId, String url, String name, String description, String urlType, String apiKey);
|
|
|
|
/**
|
|
* Patch a product with product id productId by using the couples in toChange.
|
|
* NOTE: only the specified custom fields will be changed. If a custom field with a given key
|
|
* already exists, the new values are added at the end of the list.
|
|
* @param productId
|
|
* @param apiKey
|
|
* @param toChange
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean patchProductCustomFields(String productId, String apiKey, Map<String, List<String>> customFieldsToChange);
|
|
|
|
/**
|
|
* Remove a custom field in the product that has a given key and value. If more than ones are present, the first one is removed.
|
|
* @return true on success, false otherwise.
|
|
*/
|
|
boolean removeCustomField(String productId, String key, String value, String apiKey);
|
|
|
|
/**
|
|
* Remove a tag from a product
|
|
* @param productId
|
|
* @param apiKey
|
|
* @param tagToRemove
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean removeTag(String productId, String apiKey, String tagToRemove);
|
|
|
|
/**
|
|
* Add a tag from a product
|
|
* @param productId
|
|
* @param apiKey
|
|
* @param tagToAdd
|
|
* @return true on success, false otherwise
|
|
*/
|
|
boolean addTag(String productId, String apiKey, String tagToAdd);
|
|
|
|
/**
|
|
* Get the parent groups of this group
|
|
* @return the group parent, if any
|
|
*/
|
|
List<CkanGroup> getParentGroups(String groupName, String apiKey);
|
|
|
|
/**
|
|
* Check if a dataset is into the given group
|
|
* @param groupName
|
|
* @param datasetId
|
|
* @return true if it belongs to the group, false otherwise
|
|
*/
|
|
boolean isDatasetInGroup(String groupName, String datasetId);
|
|
|
|
/**
|
|
* Retrieve products in a group. Please note that at most 1000 datasets are returned.
|
|
* @return a list of datasets in a group
|
|
*/
|
|
List<CkanDataset> getProductsInGroup(String groupName);
|
|
|
|
/**
|
|
* Retrieve the url of the uri resolver for this catalogue instance/scope
|
|
* @return
|
|
*/
|
|
String getUriResolverUrl();
|
|
|
|
/**
|
|
* Require to patch a product according to the content of the parameter jsonRequest
|
|
* @param productId
|
|
* @param jsonRequest
|
|
* @param apiKey
|
|
* @return error message if any, null otherwise
|
|
*/
|
|
String patchProductWithJSON(String productId, JSONObject jsonRequest, String apiKey);
|
|
|
|
/**
|
|
* Ckan APIs group_show and organization_show with the property "include_datasets=true"
|
|
* return at most 1000 products. This method, instead, let retrieve all the
|
|
* products (ids) in a group or organization.
|
|
* The query is performed against the solr index.
|
|
* Take a look
|
|
* <ul>
|
|
* <li>https://github.com/ckan/ckan/blob/master/ckan/lib/dictization/model_dictize.py
|
|
* <li>https://github.com/ckan/ckan/blob/master/ckan/lib/search/query.py
|
|
* </ul>
|
|
* @param orgOrGroupName
|
|
* @param isOrganization: true if the owner entity is an organization, false if it is a group
|
|
* @param start the initial row (e.g., 0)
|
|
* @param rows the number of rows from start (e.g., 10)
|
|
* @return
|
|
* @throws SQLException
|
|
* @throws ClassNotFoundException
|
|
*/
|
|
List<String> getProductsIdsInGroupOrOrg(String orgOrGroupName, boolean isOrganization, int start, int rows) throws ClassNotFoundException, SQLException;
|
|
|
|
/**
|
|
* Delete and purge (if purge is set to true) a group
|
|
* @param groupName
|
|
* @param purge
|
|
* @return
|
|
*/
|
|
boolean deleteGroup(String groupName, boolean purge);
|
|
}
|