Interface ExternalReferencesInterface

  • All Known Implementing Classes:
    ExternalReferenceExchangeClient

    public interface ExternalReferencesInterface
    The ExternalReferencesInterface is used by the governance team to define external references to elements within the governance program.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String createExternalReference​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, boolean assetManagerIsHome, ExternalIdentifierProperties externalIdentifierProperties, java.lang.String anchorGUID, ExternalReferenceProperties properties)
      Create a definition of an external reference.
      void deleteExternalReference​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String externalReferenceGUID, java.lang.String referenceExternalIdentifier, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Remove the definition of an external reference.
      java.util.List<ExternalReferenceElement> findExternalReferences​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String searchString, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Find the external references that contain the search string - which may contain wildcards.
      ExternalReferenceElement getExternalReferenceByGUID​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String externalReferenceGUID, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Return information about a specific external reference.
      java.util.List<ExternalReferenceElement> getExternalReferences​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external references sorted in open metadata.
      java.util.List<ExternalReferenceElement> getExternalReferencesById​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String resourceId, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external references for this resourceId.
      java.util.List<ExternalReferenceElement> getExternalReferencesByName​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String name, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external references for this name.
      java.util.List<ExternalReferenceElement> getExternalReferencesByURL​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String url, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external references for this URL.
      java.util.List<ExternalReferenceElement> getExternalReferencesForAssetManager​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external reference created on behalf of the named asset manager.
      java.lang.String linkExternalReferenceToElement​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, boolean assetManagerIsHome, java.lang.String attachedToGUID, java.lang.String externalReferenceGUID, ExternalReferenceLinkProperties linkProperties, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Link an external reference to an object.
      java.util.List<ExternalReferenceLinkElement> retrieveAttachedExternalReferences​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String attachedToGUID, int startFrom, int pageSize, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Retrieve the list of external references attached to the supplied object.
      void unlinkExternalReferenceFromElement​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String externalReferenceLinkGUID, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Remove the link between an external reference and an element.
      void updateExternalReference​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String externalReferenceGUID, java.lang.String referenceExternalIdentifier, boolean isMergeUpdate, ExternalReferenceProperties properties, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Update the definition of an external reference.
      void updateExternalReferenceToElementLink​(java.lang.String userId, java.lang.String assetManagerGUID, java.lang.String assetManagerName, java.lang.String externalReferenceLinkGUID, ExternalReferenceLinkProperties linkProperties, java.util.Date effectiveTime, boolean forLineage, boolean forDuplicateProcessing)
      Update the link between an external reference to an object.
    • Method Detail

      • createExternalReference

        java.lang.String createExternalReference​(java.lang.String userId,
                                                 java.lang.String assetManagerGUID,
                                                 java.lang.String assetManagerName,
                                                 boolean assetManagerIsHome,
                                                 ExternalIdentifierProperties externalIdentifierProperties,
                                                 java.lang.String anchorGUID,
                                                 ExternalReferenceProperties properties)
                                          throws InvalidParameterException,
                                                 UserNotAuthorizedException,
                                                 PropertyServerException
        Create a definition of an external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        assetManagerIsHome - ensure that only the asset manager can update this asset
        externalIdentifierProperties - optional properties used to define an external identifier
        anchorGUID - optional element to link the external reference to that will act as an anchor - that is, this external reference will be deleted when the element is deleted (once the external reference is linked to the anchor).
        properties - properties for an external reference
        Returns:
        unique identifier of the external reference
        Throws:
        InvalidParameterException - qualifiedName or userId is null; qualifiedName is not unique
        PropertyServerException - problem accessing property server
        UserNotAuthorizedException - security access problem
      • updateExternalReference

        void updateExternalReference​(java.lang.String userId,
                                     java.lang.String assetManagerGUID,
                                     java.lang.String assetManagerName,
                                     java.lang.String externalReferenceGUID,
                                     java.lang.String referenceExternalIdentifier,
                                     boolean isMergeUpdate,
                                     ExternalReferenceProperties properties,
                                     java.util.Date effectiveTime,
                                     boolean forLineage,
                                     boolean forDuplicateProcessing)
                              throws InvalidParameterException,
                                     UserNotAuthorizedException,
                                     PropertyServerException
        Update the definition of an external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        externalReferenceGUID - unique identifier of external reference
        referenceExternalIdentifier - unique identifier of the external reference in the external asset manager
        isMergeUpdate - are unspecified properties unchanged (true) or replaced with null?
        properties - properties to change
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Throws:
        InvalidParameterException - guid, qualifiedName or userId is null; qualifiedName is not unique; guid is not known
        PropertyServerException - problem accessing property server
        UserNotAuthorizedException - security access problem
      • deleteExternalReference

        void deleteExternalReference​(java.lang.String userId,
                                     java.lang.String assetManagerGUID,
                                     java.lang.String assetManagerName,
                                     java.lang.String externalReferenceGUID,
                                     java.lang.String referenceExternalIdentifier,
                                     java.util.Date effectiveTime,
                                     boolean forLineage,
                                     boolean forDuplicateProcessing)
                              throws InvalidParameterException,
                                     UserNotAuthorizedException,
                                     PropertyServerException
        Remove the definition of an external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        externalReferenceGUID - unique identifier of external reference
        referenceExternalIdentifier - unique identifier of the external reference in the external asset manager
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Throws:
        InvalidParameterException - guid or userId is null; guid is not known
        PropertyServerException - problem accessing property server
        UserNotAuthorizedException - security access problem
      • linkExternalReferenceToElement

        java.lang.String linkExternalReferenceToElement​(java.lang.String userId,
                                                        java.lang.String assetManagerGUID,
                                                        java.lang.String assetManagerName,
                                                        boolean assetManagerIsHome,
                                                        java.lang.String attachedToGUID,
                                                        java.lang.String externalReferenceGUID,
                                                        ExternalReferenceLinkProperties linkProperties,
                                                        java.util.Date effectiveTime,
                                                        boolean forLineage,
                                                        boolean forDuplicateProcessing)
                                                 throws InvalidParameterException,
                                                        PropertyServerException,
                                                        UserNotAuthorizedException
        Link an external reference to an object.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        assetManagerIsHome - ensure that only the asset manager can update this asset
        attachedToGUID - object linked to external references.
        linkProperties - description for the reference from the perspective of the object that the reference is being attached to.
        externalReferenceGUID - unique identifier (guid) of the external reference details.
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        Unique identifier for new relationship
        Throws:
        InvalidParameterException - problem with the GUID or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • updateExternalReferenceToElementLink

        void updateExternalReferenceToElementLink​(java.lang.String userId,
                                                  java.lang.String assetManagerGUID,
                                                  java.lang.String assetManagerName,
                                                  java.lang.String externalReferenceLinkGUID,
                                                  ExternalReferenceLinkProperties linkProperties,
                                                  java.util.Date effectiveTime,
                                                  boolean forLineage,
                                                  boolean forDuplicateProcessing)
                                           throws InvalidParameterException,
                                                  PropertyServerException,
                                                  UserNotAuthorizedException
        Update the link between an external reference to an object.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        linkProperties - description for the reference from the perspective of the object that the reference is being attached to.
        externalReferenceLinkGUID - unique identifier (guid) of the external reference details.
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Throws:
        InvalidParameterException - problem with the GUID or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • unlinkExternalReferenceFromElement

        void unlinkExternalReferenceFromElement​(java.lang.String userId,
                                                java.lang.String assetManagerGUID,
                                                java.lang.String assetManagerName,
                                                java.lang.String externalReferenceLinkGUID,
                                                java.util.Date effectiveTime,
                                                boolean forLineage,
                                                boolean forDuplicateProcessing)
                                         throws InvalidParameterException,
                                                PropertyServerException,
                                                UserNotAuthorizedException
        Remove the link between an external reference and an element. If the element is its anchor, the external reference is removed.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        externalReferenceLinkGUID - identifier of the external reference relationship.
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Throws:
        InvalidParameterException - problem with the GUID or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferences

        java.util.List<ExternalReferenceElement> getExternalReferences​(java.lang.String userId,
                                                                       java.lang.String assetManagerGUID,
                                                                       java.lang.String assetManagerName,
                                                                       int startFrom,
                                                                       int pageSize,
                                                                       java.util.Date effectiveTime,
                                                                       boolean forLineage,
                                                                       boolean forDuplicateProcessing)
                                                                throws InvalidParameterException,
                                                                       PropertyServerException,
                                                                       UserNotAuthorizedException
        Retrieve the list of external references sorted in open metadata.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferencesById

        java.util.List<ExternalReferenceElement> getExternalReferencesById​(java.lang.String userId,
                                                                           java.lang.String assetManagerGUID,
                                                                           java.lang.String assetManagerName,
                                                                           java.lang.String resourceId,
                                                                           int startFrom,
                                                                           int pageSize,
                                                                           java.util.Date effectiveTime,
                                                                           boolean forLineage,
                                                                           boolean forDuplicateProcessing)
                                                                    throws InvalidParameterException,
                                                                           PropertyServerException,
                                                                           UserNotAuthorizedException
        Retrieve the list of external references for this resourceId.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        resourceId - unique reference id assigned by the resource owner (supports wildcards). This is the qualified name of the entity
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferencesByURL

        java.util.List<ExternalReferenceElement> getExternalReferencesByURL​(java.lang.String userId,
                                                                            java.lang.String assetManagerGUID,
                                                                            java.lang.String assetManagerName,
                                                                            java.lang.String url,
                                                                            int startFrom,
                                                                            int pageSize,
                                                                            java.util.Date effectiveTime,
                                                                            boolean forLineage,
                                                                            boolean forDuplicateProcessing)
                                                                     throws InvalidParameterException,
                                                                            PropertyServerException,
                                                                            UserNotAuthorizedException
        Retrieve the list of external references for this URL.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        url - URL of the external resource.
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferencesByName

        java.util.List<ExternalReferenceElement> getExternalReferencesByName​(java.lang.String userId,
                                                                             java.lang.String assetManagerGUID,
                                                                             java.lang.String assetManagerName,
                                                                             java.lang.String name,
                                                                             int startFrom,
                                                                             int pageSize,
                                                                             java.util.Date effectiveTime,
                                                                             boolean forLineage,
                                                                             boolean forDuplicateProcessing)
                                                                      throws InvalidParameterException,
                                                                             PropertyServerException,
                                                                             UserNotAuthorizedException
        Retrieve the list of external references for this name.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        name - qualifiedName or displayNAme of the external resource
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferencesForAssetManager

        java.util.List<ExternalReferenceElement> getExternalReferencesForAssetManager​(java.lang.String userId,
                                                                                      java.lang.String assetManagerGUID,
                                                                                      java.lang.String assetManagerName,
                                                                                      int startFrom,
                                                                                      int pageSize,
                                                                                      java.util.Date effectiveTime,
                                                                                      boolean forLineage,
                                                                                      boolean forDuplicateProcessing)
                                                                               throws InvalidParameterException,
                                                                                      UserNotAuthorizedException,
                                                                                      PropertyServerException
        Retrieve the list of external reference created on behalf of the named asset manager.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        startFrom - paging start point
        pageSize - maximum results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        list of matching metadata elements
        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)
      • findExternalReferences

        java.util.List<ExternalReferenceElement> findExternalReferences​(java.lang.String userId,
                                                                        java.lang.String assetManagerGUID,
                                                                        java.lang.String assetManagerName,
                                                                        java.lang.String searchString,
                                                                        int startFrom,
                                                                        int pageSize,
                                                                        java.util.Date effectiveTime,
                                                                        boolean forLineage,
                                                                        boolean forDuplicateProcessing)
                                                                 throws InvalidParameterException,
                                                                        PropertyServerException,
                                                                        UserNotAuthorizedException
        Find the external references that contain the search string - which may contain wildcards.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        searchString - regular expression (RegEx) to search for
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • retrieveAttachedExternalReferences

        java.util.List<ExternalReferenceLinkElement> retrieveAttachedExternalReferences​(java.lang.String userId,
                                                                                        java.lang.String assetManagerGUID,
                                                                                        java.lang.String assetManagerName,
                                                                                        java.lang.String attachedToGUID,
                                                                                        int startFrom,
                                                                                        int pageSize,
                                                                                        java.util.Date effectiveTime,
                                                                                        boolean forLineage,
                                                                                        boolean forDuplicateProcessing)
                                                                                 throws InvalidParameterException,
                                                                                        PropertyServerException,
                                                                                        UserNotAuthorizedException
        Retrieve the list of external references attached to the supplied object.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        attachedToGUID - object linked to external reference.
        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
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        links to addition information.
        Throws:
        InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.
        PropertyServerException - the server is not available.
        UserNotAuthorizedException - the calling user is not authorized to issue the call.
      • getExternalReferenceByGUID

        ExternalReferenceElement getExternalReferenceByGUID​(java.lang.String userId,
                                                            java.lang.String assetManagerGUID,
                                                            java.lang.String assetManagerName,
                                                            java.lang.String externalReferenceGUID,
                                                            java.util.Date effectiveTime,
                                                            boolean forLineage,
                                                            boolean forDuplicateProcessing)
                                                     throws InvalidParameterException,
                                                            UserNotAuthorizedException,
                                                            PropertyServerException
        Return information about a specific external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software capability representing the caller
        assetManagerName - unique name of software capability representing the caller
        externalReferenceGUID - unique identifier for the external reference
        effectiveTime - the time that the retrieved elements must be effective for
        forLineage - return elements marked with the Memento classification?
        forDuplicateProcessing - do not merge elements marked as duplicates?
        Returns:
        properties of the external reference
        Throws:
        InvalidParameterException - externalReferenceGUID or userId is null
        PropertyServerException - problem accessing property server
        UserNotAuthorizedException - security access problem