Package org.odpi.openmetadata.accessservices.digitalservice.client

Class CollectionsClient

java.lang.Object
org.odpi.openmetadata.accessservices.digitalservice.client.OpenMetadataBaseClient
org.odpi.openmetadata.accessservices.digitalservice.client.CollectionsClient
All Implemented Interfaces:
CollectionsInterface
public class CollectionsClient extends OpenMetadataBaseClient implements CollectionsInterface
The CollectionsClient supports requests related to collections.

  • Constructor Details

    • CollectionsClient

      public CollectionsClient(String serverName, String serverPlatformURLRoot, int maxPageSize) throws InvalidParameterException
      Create a new client with no authentication embedded in the HTTP request.
      Parameters:
      serverName - name of the server to connect to
      serverPlatformURLRoot - the network address of the server running the OMAS REST services
      maxPageSize - number of elements that can be returned on a call
      Throws:
      InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

    • CollectionsClient

      public CollectionsClient(String serverName, String serverPlatformURLRoot, String userId, String password, int maxPageSize) throws InvalidParameterException
      Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.
      Parameters:
      serverName - name of the server to connect to
      serverPlatformURLRoot - the network address of the server running the OMAS REST services
      userId - caller's userId embedded in all HTTP requests
      password - caller's userId embedded in all HTTP requests
      maxPageSize - number of elements that can be returned on a call
      Throws:
      InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

  • Method Details

    • getAttachedCollections

      public List<CollectionElement> getAttachedCollections(String userId, String parentGUID, String collectionType, TemplateFilter templateFilter, 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 that are linked off of the supplied element.
      Specified by:
      getAttachedCollections in interface CollectionsInterface
      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
      templateFilter - should templates be returned?
      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.

    • getClassifiedCollections

      public List<CollectionElement> getClassifiedCollections(String userId, String classificationName, TemplateFilter templateFilter, 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 classification.
      Specified by:
      getClassifiedCollections in interface CollectionsInterface
      Parameters:
      userId - userId of user making request
      classificationName - name of the classification - if null, all collections are returned
      templateFilter - should templates be returned?
      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.

    • findCollections

      public List<CollectionElement> findCollections(String userId, String classificationName, String searchString, TemplateFilter templateFilter, 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.
      Specified by:
      findCollections in interface CollectionsInterface
      Parameters:
      userId - userId of user making request
      classificationName - option name of a collection classification
      searchString - string to search for
      templateFilter - should templates be returned?
      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

      public List<CollectionElement> getCollectionsByName(String userId, String classificationName, String name, TemplateFilter templateFilter, 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.
      Specified by:
      getCollectionsByName in interface CollectionsInterface
      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.
      templateFilter - should templates be returned?
      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

      public List<CollectionElement> getCollectionsByType(String userId, String classificationName, String collectionType, TemplateFilter templateFilter, 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 collectionType. This is an optional text field in the collection element.
      Specified by:
      getCollectionsByType in interface CollectionsInterface
      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
      templateFilter - should templates be returned?
      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.

    • getCollection

      public 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.
      Specified by:
      getCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      createCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      createCollectionFromTemplate in interface CollectionsInterface
      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

      public 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.
      Specified by:
      createDigitalProduct in interface CollectionsInterface
      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

      public void updateCollection(String userId, String collectionGUID, boolean replaceAllProperties, CollectionProperties properties, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Update the properties of a collection.
      Specified by:
      updateCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      updateDigitalProduct in interface CollectionsInterface
      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

      public 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).
      Specified by:
      attachCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      detachCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      deleteCollection in interface CollectionsInterface
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection
      cascadedDelete - should any 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

      public List<CollectionMember> getCollectionMembers(String userId, String collectionGUID, List<ElementStatus> limitResultsByStatus, Date asOfTime, String sequencingProperty, SequencingOrder sequencingOrder, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, int startFrom, int pageSize) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return a list of elements that are a member of a collection.
      Specified by:
      getCollectionMembers in interface CollectionsInterface
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      limitResultsByStatus - By default, relationships in all statuses (other than DELETE) are returned. However, it is possible to specify a list of statuses (for example ACTIVE) to restrict the results to. Null means all status values.
      asOfTime - Requests a historical query of the entity. Null means return the present values.
      sequencingProperty - String name of the property that is to be used to sequence the results. Null means do not sequence on a property name (see SequencingOrder).
      sequencingOrder - Enum defining how the results should be ordered.
      forLineage - the retrieved element is 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 the element if it is effective at this time. Null means anytime. Use "new Date()" for now.
      startFrom - paging start point
      pageSize - maximum results that can be returned
      Returns:
      list of member 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.

    • getCollectionGraph

      public CollectionGraph getCollectionGraph(String userId, String collectionGUID, List<ElementStatus> limitResultsByStatus, Date asOfTime, String sequencingProperty, SequencingOrder sequencingOrder, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, int startFrom, int pageSize) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return a graph of elements that are the nested members of a collection along with elements immediately connected to the starting collection. The result includes a mermaid graph of the returned elements.
      Specified by:
      getCollectionGraph in interface CollectionsInterface
      Parameters:
      userId - userId of user making request.
      collectionGUID - unique identifier of the collection.
      limitResultsByStatus - By default, relationships in all statuses (other than DELETE) are returned. However, it is possible to specify a list of statuses (for example ACTIVE) to restrict the results to. Null means all status values.
      asOfTime - Requests a historical query of the entity. Null means return the present values.
      sequencingProperty - String name of the property that is to be used to sequence the results. Null means do not sequence on a property name (see SequencingOrder).
      sequencingOrder - Enum defining how the results should be ordered.
      forLineage - the retrieved element is 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 the element if it is effective at this time. Null means anytime. Use "new Date()" for now.
      startFrom - paging start point
      pageSize - maximum results that can be returned
      Returns:
      list of member 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

      public void addToCollection(String userId, String collectionGUID, CollectionMembershipProperties membershipProperties, String elementGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Add an element to a collection.
      Specified by:
      addToCollection in interface CollectionsInterface
      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

      public 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.
      Specified by:
      updateCollectionMembership in interface CollectionsInterface
      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

      public void removeFromCollection(String userId, String collectionGUID, String elementGUID, Date effectiveTime) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Remove an element from a collection.
      Specified by:
      removeFromCollection in interface CollectionsInterface
      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.