Package org.odpi.openmetadata.accessservices.digitalservice.api

Interface CollectionsInterface

All Known Implementing Classes:
CollectionsClient
public interface CollectionsInterface
The CollectionsInterface adds methods for managing collections. Collections are managed lists of elements. They can be used to create a folder type hierarchy for, say, assets and digital products. They are used to represent digital products and lists of favourites.

  • Method Details

    • getAttachedCollections

      List<CollectionElement> getAttachedCollections(String userId, String parentGUID, String collectionType, int startFrom, int pageSize) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Returns the list of collections that are linked off of the supplied element.
      Parameters:
      userId - userId of user making request
      parentGUID - unique identifier of referenceable object (typically a personal profile, project or community) that the collections hang off of
      collectionType - filter response by collection type - if null, any value will do
      startFrom - index of the list to start from (0 for start)
      pageSize - maximum number of elements to return
      Returns:
      a list of collections
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • getClassifiedCollections

      List<CollectionElement> getClassifiedCollections(String userId, String classificationName, int startFrom, int pageSize) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Returns the list of collections with a particular classification.
      Parameters:
      userId - userId of user making request
      classificationName - name of the classification - if null, all collections are returned
      startFrom - index of the list to start from (0 for start)
      pageSize - maximum number of elements to return
      Returns:
      a list of collections
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • findCollections

      List<CollectionElement> findCollections(String userId, String classificationName, String searchString, List<ElementStatus> limitResultsByStatus, Date asOfTime, SequencingOrder sequencingOrder, String sequencingProperty, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Returns the list of collections matching the search string - this is coded as a regular expression.
      Parameters:
      userId - userId of user making request
      classificationName - option name of a collection classification
      searchString - string to search for
      limitResultsByStatus - control the status of the elements to retrieve - default is everything but Deleted
      asOfTime - repository time to use
      sequencingOrder - order to retrieve results
      sequencingProperty - property to use for sequencing order
      startFrom - paging start point
      pageSize - maximum results that can be returned
      forLineage - the retrieved elements are for lineage processing so include archived elements
      forDuplicateProcessing - the retrieved element is for duplicate processing so do not combine results from known duplicates.
      effectiveTime - only return an element if it is effective at this time. Null means anytime. Use "new Date()" for now.
      Returns:
      a list of collections
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • getCollectionsByName

      List<CollectionElement> getCollectionsByName(String userId, String classificationName, String name, List<ElementStatus> limitResultsByStatus, Date asOfTime, SequencingOrder sequencingOrder, String sequencingProperty, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Returns the list of collections with a particular name.
      Parameters:
      userId - userId of user making request
      classificationName - option name of a collection classification
      name - name of the collections to return - match is full text match in qualifiedName or name
      limitResultsByStatus - control the status of the elements to retrieve - default is everything but Deleted
      asOfTime - repository time to use
      sequencingOrder - order to retrieve results
      sequencingProperty - property to use for sequencing order
      startFrom - paging start point
      pageSize - maximum results that can be returned
      forLineage - the retrieved elements are for lineage processing so include archived elements
      forDuplicateProcessing - the retrieved element is for duplicate processing so do not combine results from known duplicates.
      effectiveTime - only return an element if it is effective at this time. Null means anytime. Use "new Date()" for now.
      Returns:
      a list of collections
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • getCollectionsByType

      List<CollectionElement> getCollectionsByType(String userId, String classificationName, String collectionType, int startFrom, int pageSize) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Returns the list of collections with a particular collectionType. This is an optional text field in the collection element.
      Parameters:
      userId - userId of user making request
      classificationName - option name of a collection classification
      collectionType - the collection type value to match on. If it is null, all collections with a null collectionType are returned
      startFrom - index of the list to start from (0 for start)
      pageSize - maximum number of elements to return
      Returns:
      a list of collections
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • getCollection

      CollectionElement getCollection(String userId, String collectionGUID, Date asOfTime, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return the properties of a specific collection.
      Parameters:
      userId - userId of user making request
      collectionGUID - unique identifier of the required collection
      asOfTime - repository time to use
      forLineage - the retrieved elements are for lineage processing so include archived elements
      forDuplicateProcessing - the retrieved element is for duplicate processing so do not combine results from known duplicates.
      effectiveTime - only return an element if it is effective at this time. Null means anytime. Use "new Date()" for now.
      Returns:
      collection properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • createCollection

      String createCollection(String userId, String anchorGUID, boolean isOwnAnchor, String anchorScopeGUID, String optionalClassification, CollectionProperties properties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Create a new generic collection.
      Parameters:
      userId - userId of user making request.
      anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.
      isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.
      anchorScopeGUID - optional scope of the anchor
      optionalClassification - classification of the collections - typically RootCollection, Set or Folder
      properties - properties for the collection.
      parentGUID - unique identifier of optional parent entity
      parentRelationshipTypeName - type of relationship to connect the new element to the parent
      parentRelationshipProperties - properties to include in parent relationship
      parentAtEnd1 - which end should the parent GUID go in the relationship
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Returns:
      unique identifier of the newly created Collection
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • createCollectionFromTemplate

      String createCollectionFromTemplate(String userId, String anchorGUID, boolean isOwnAnchor, String anchorScopeGUID, Date effectiveFrom, Date effectiveTo, String templateGUID, ElementProperties replacementProperties, Map<String,String> placeholderProperties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1, Date effectiveTime) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Create a new metadata element to represent a collection using an existing metadata element as a template. The template defines additional classifications and relationships that should be added to the new collection.
      Parameters:
      userId - calling user
      anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.
      isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.
      anchorScopeGUID - optional scope of the anchor
      effectiveFrom - the date when this element is active - null for active on creation
      effectiveTo - the date when this element becomes inactive - null for active until deleted
      templateGUID - the unique identifier of the existing asset to copy (this will copy all the attachments such as nested content, schema connection etc)
      replacementProperties - properties of the new metadata element. These override the template values
      placeholderProperties - property name-to-property value map to replace any placeholder values in the template element - and their anchored elements, which are also copied as part of this operation.
      parentGUID - unique identifier of optional parent entity
      parentRelationshipTypeName - type of relationship to connect the new element to the parent
      parentRelationshipProperties - properties to include in parent relationship
      parentAtEnd1 - which end should the parent GUID go in the relationship
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Returns:
      unique identifier of the new metadata element
      Throws:
      InvalidParameterException - one of the parameters is invalid
      UserNotAuthorizedException - the user is not authorized to issue this request
      PropertyServerException - there is a problem reported in the open metadata server(s)

    • createDigitalProduct

      String createDigitalProduct(String userId, String anchorGUID, boolean isOwnAnchor, String anchorScopeGUID, CollectionProperties collectionProperties, DigitalProductProperties digitalProductProperties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Create a new collection that represents a digital product.
      Parameters:
      userId - userId of user making request.
      anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.
      isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.
      anchorScopeGUID - optional scope of the anchor
      collectionProperties - properties for the collection.
      digitalProductProperties - properties for the attached DigitalProduct classification
      parentGUID - unique identifier of optional parent entity
      parentRelationshipTypeName - type of relationship to connect the new element to the parent
      parentRelationshipProperties - properties to include in parent relationship
      parentAtEnd1 - which end should the parent GUID go in the relationship
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Returns:
      unique identifier of the newly created Collection
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.*

    • updateCollection

      void updateCollection(String userId, String collectionGUID, boolean replaceAllProperties, CollectionProperties properties, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Update the properties of a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection (returned from create)
      replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.
      properties - properties for the collection.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • updateDigitalProduct

      void updateDigitalProduct(String userId, String collectionGUID, boolean replaceAllProperties, DigitalProductProperties properties, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Update the properties of the DigitalProduct classification attached to a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection (returned from create)
      replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.
      properties - properties for the DigitalProduct classification.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • attachCollection

      void attachCollection(String userId, String collectionGUID, String parentGUID, ResourceListProperties collectionUse, boolean makeAnchor, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Connect an existing collection to an element using the ResourceList relationship (0019).
      Parameters:
      userId - userId of user making request
      collectionGUID - unique identifier of the collection
      parentGUID - unique identifier of referenceable object that the collection should be attached to
      collectionUse - description of how the collection will be used.
      makeAnchor - like the lifecycle of the collection to that of the parent so that if the parent is deleted, so is the collection
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • detachCollection

      void detachCollection(String userId, String collectionGUID, String parentGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Detach an existing collection from an element. If the collection is anchored to the element, it is deleted.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      parentGUID - unique identifier of referenceable object that the collection should be attached to.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • deleteCollection

      void deleteCollection(String userId, String collectionGUID, boolean cascadedDelete) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Delete a collection. It is detached from all parent elements. If members are anchored to the collection then they are also deleted.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection
      cascadedDelete - should nested collections be deleted? If false, the delete fails if there are nested collections. If true, nested collections are delete - but not member elements unless they are anchored to the collection
      Throws:
      InvalidParameterException - one of the parameters is null or invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • getCollectionMembers

      List<CollectionMember> getCollectionMembers(String userId, String collectionGUID, int startFrom, int pageSize, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return a list of elements that are a member of a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      startFrom - index of the list to start from (0 for start)
      pageSize - maximum number of elements to return.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Returns:
      list of asset details
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem retrieving information from the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • addToCollection

      void addToCollection(String userId, String collectionGUID, CollectionMembershipProperties membershipProperties, String elementGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Add an element to a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      membershipProperties - properties describing the membership characteristics.
      elementGUID - unique identifier of the element.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem updating information in the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • updateCollectionMembership

      void updateCollectionMembership(String userId, String collectionGUID, boolean replaceAllProperties, CollectionMembershipProperties membershipProperties, String elementGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Update an element's membership to a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.
      membershipProperties - properties describing the membership characteristics.
      elementGUID - unique identifier of the element.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem updating information in the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.

    • removeFromCollection

      void removeFromCollection(String userId, String collectionGUID, String elementGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Remove an element from a collection.
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      elementGUID - unique identifier of the element.
      effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
      Throws:
      InvalidParameterException - one of the parameters is invalid.
      PropertyServerException - there is a problem updating information in the property server(s).
      UserNotAuthorizedException - the requesting user is not authorized to issue this request.