Package org.odpi.openmetadata.accessservices.assetmanager.api

Interface ExternalReferencesInterface

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

    • Method Detail

      • createExternalReference

        String createExternalReference​(String userId,
                               String assetManagerGUID,
                               String assetManagerName,
                               boolean assetManagerIsHome,
                               String referenceExternalIdentifier,
                               String referenceExternalIdentifierName,
                               String referenceExternalIdentifierUsage,
                               String referenceExternalIdentifierSource,
                               KeyPattern referenceExternalIdentifierKeyPattern,
                               Map<String,​String> mappingProperties,
                               String anchorGUID,
                               ExternalReferenceProperties properties)
                        throws InvalidParameterException,
                               UserNotAuthorizedException,
                               PropertyServerException
        Create a definition of a external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        assetManagerIsHome - ensure that only the asset manager can update this asset
        referenceExternalIdentifier - unique identifier of the external reference in the external asset manager
        referenceExternalIdentifierName - name of property for the external identifier in the external asset manager
        referenceExternalIdentifierUsage - optional usage description for the external identifier when calling the external asset manager
        referenceExternalIdentifierSource - component that issuing this request.
        referenceExternalIdentifierKeyPattern - pattern for the external identifier within the external asset manager (default is LOCAL_KEY)
        mappingProperties - additional properties to help with the mapping of the elements in the external asset manager and open metadata
        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 a 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​(String userId,
                             String assetManagerGUID,
                             String assetManagerName,
                             String externalReferenceGUID,
                             String referenceExternalIdentifier,
                             boolean isMergeUpdate,
                             ExternalReferenceProperties properties)
                      throws InvalidParameterException,
                             UserNotAuthorizedException,
                             PropertyServerException
        Update the definition of a external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software server capability representing the caller
        assetManagerName - unique name of software server 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
        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​(String userId,
                             String assetManagerGUID,
                             String assetManagerName,
                             String externalReferenceGUID,
                             String referenceExternalIdentifier)
                      throws InvalidParameterException,
                             UserNotAuthorizedException,
                             PropertyServerException
        Remove the definition of a external reference.
        Parameters:
        userId - calling user
        assetManagerGUID - unique identifier of software server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        externalReferenceGUID - unique identifier of external reference
        referenceExternalIdentifier - unique identifier of the external reference in the external asset manager
        Throws:
        InvalidParameterException - guid or userId is null; guid is not known
        PropertyServerException - problem accessing property server
        UserNotAuthorizedException - security access problem

      • linkExternalReferenceToElement

        String linkExternalReferenceToElement​(String userId,
                                      String assetManagerGUID,
                                      String assetManagerName,
                                      boolean assetManagerIsHome,
                                      String attachedToGUID,
                                      String externalReferenceGUID,
                                      ExternalReferenceLinkProperties linkProperties)
                               throws InvalidParameterException,
                                      PropertyServerException,
                                      UserNotAuthorizedException
        Link an external reference to an object.
        Parameters:
        userId - the name of the calling user.
        assetManagerGUID - unique identifier of software server capability representing the caller
        assetManagerName - unique name of software server 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.
        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​(String userId,
                                          String assetManagerGUID,
                                          String assetManagerName,
                                          String externalReferenceLinkGUID,
                                          ExternalReferenceLinkProperties linkProperties)
                                   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 server capability representing the caller
        assetManagerName - unique name of software server 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.
        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​(String userId,
                                        String assetManagerGUID,
                                        String assetManagerName,
                                        String externalReferenceLinkGUID)
                                 throws InvalidParameterException,
                                        PropertyServerException,
                                        UserNotAuthorizedException
        Remove the link between a 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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        externalReferenceLinkGUID - identifier of the external reference 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.

      • getExternalReferences

        List<ExternalReferenceElement> getExternalReferences​(String userId,
                                                     String assetManagerGUID,
                                                     String assetManagerName,
                                                     Date effectiveTime,
                                                     int startFrom,
                                                     int pageSize)
                                              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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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

        List<ExternalReferenceElement> getExternalReferencesById​(String userId,
                                                         String assetManagerGUID,
                                                         String assetManagerName,
                                                         String resourceId,
                                                         Date effectiveTime,
                                                         int startFrom,
                                                         int pageSize)
                                                  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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        resourceId - unique reference id assigned by the resource owner (supports wildcards). This is the qualified name of the entity
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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

        List<ExternalReferenceElement> getExternalReferencesByURL​(String userId,
                                                          String assetManagerGUID,
                                                          String assetManagerName,
                                                          String url,
                                                          Date effectiveTime,
                                                          int startFrom,
                                                          int pageSize)
                                                   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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        url - URL of the external resource.
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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

        List<ExternalReferenceElement> getExternalReferencesByName​(String userId,
                                                           String assetManagerGUID,
                                                           String assetManagerName,
                                                           String name,
                                                           Date effectiveTime,
                                                           int startFrom,
                                                           int pageSize)
                                                    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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        name - qualifiedName or displayNAme of the external resource
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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

        List<ExternalReferenceElement> getExternalReferencesForAssetManager​(String userId,
                                                                    String assetManagerGUID,
                                                                    String assetManagerName,
                                                                    Date effectiveTime,
                                                                    int startFrom,
                                                                    int pageSize)
                                                             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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - paging start point
        pageSize - maximum results that can be returned
        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

        List<ExternalReferenceElement> findExternalReferences​(String userId,
                                                      String assetManagerGUID,
                                                      String assetManagerName,
                                                      String searchString,
                                                      Date effectiveTime,
                                                      int startFrom,
                                                      int pageSize)
                                               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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        searchString - regular expression (RegEx) to search for
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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

        List<ExternalReferenceLinkElement> retrieveAttachedExternalReferences​(String userId,
                                                                      String assetManagerGUID,
                                                                      String assetManagerName,
                                                                      String attachedToGUID,
                                                                      Date effectiveTime,
                                                                      int startFrom,
                                                                      int pageSize)
                                                               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 server capability representing the caller
        assetManagerName - unique name of software server capability representing the caller
        attachedToGUID - object linked to external reference.
        effectiveTime - the time that the retrieved elements must be effective for
        startFrom - index of the list to start from (0 for start)
        pageSize - maximum number of elements to return.
        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.