Package org.odpi.openmetadata.commonservices.generichandlers

Class ExternalIdentifierHandler<EXTERNAL_ID,​OPEN_METADATA_ELEMENT_HEADER>

  • Type Parameters:
    EXTERNAL_ID - bean that returns an external identifier
    OPEN_METADATA_ELEMENT_HEADER - bean that returns the elements tied to this external identifier
    public class ExternalIdentifierHandler<EXTERNAL_ID,​OPEN_METADATA_ELEMENT_HEADER>
extends ReferenceableHandler<EXTERNAL_ID>
    ExternalIdentifierHandler manages ExternalIdentifier objects. These entities represent the identifiers used for metadata in third party technology. It runs server-side in the OMAG Server Platform and manages ExternalId entities through the OMRSRepositoryConnector via the repository handler. The ExternalIdentifier is linked to the SoftwareServerCapability that represents the third party technology that generated the external identifier. This is referred to as the scope. It is also linked to the element (or elements) in open metadata that are equivalent to the metadata element(s) in the third party technology. The correlation may be many-to-many.

    • Constructor Detail

      • ExternalIdentifierHandler

        public ExternalIdentifierHandler​(OpenMetadataAPIGenericConverter<EXTERNAL_ID> converter,
                                 Class<EXTERNAL_ID> beanClass,
                                 OpenMetadataAPIGenericConverter<OPEN_METADATA_ELEMENT_HEADER> elementConverter,
                                 Class<OPEN_METADATA_ELEMENT_HEADER> elementBeanClass,
                                 String serviceName,
                                 String serverName,
                                 InvalidParameterHandler invalidParameterHandler,
                                 RepositoryHandler repositoryHandler,
                                 OMRSRepositoryHelper repositoryHelper,
                                 String localServerUserId,
                                 OpenMetadataServerSecurityVerifier securityVerifier,
                                 List<String> supportedZones,
                                 List<String> defaultZones,
                                 List<String> publishZones,
                                 AuditLog auditLog)
        Construct the handler information needed to interact with the repository services
        Parameters:
        converter - specific converter for the EXTERNAL_ID bean class
        beanClass - name of bean class that is represented by the generic class EXTERNAL_ID
        elementConverter - specific converter for the OPEN_METADATA_ELEMENT_HEADER bean class
        elementBeanClass - name of bean class that is represented by the generic class OPEN_METADATA_ELEMENT_HEADER
        serviceName - name of this service
        serverName - name of the local server
        invalidParameterHandler - handler for managing parameter errors
        repositoryHandler - manages calls to the repository services
        repositoryHelper - provides utilities for manipulating the repository services objects
        localServerUserId - userId for this server
        securityVerifier - open metadata security services verifier
        supportedZones - list of zones that the access service is allowed to serve Asset instances from.
        defaultZones - list of zones that the access service should set in all new Asset instances.
        publishZones - list of zones that the access service sets up in published Asset instances.
        auditLog - destination for audit log events.

    • Method Detail

      • setUpExternalIdentifier

        public void setUpExternalIdentifier​(String userId,
                                    String elementGUID,
                                    String elementGUIDParameterName,
                                    String elementTypeName,
                                    String identifier,
                                    String identifierParameterName,
                                    int identifierKeyPattern,
                                    String identifierDescription,
                                    String identifierUsage,
                                    String identifierSource,
                                    Map<String,​String> identifierMappingProperties,
                                    String scopeGUID,
                                    String scopeGUIDParameterName,
                                    String scopeQualifiedName,
                                    String scopeTypeName,
                                    int permittedSynchronization,
                                    String synchronizationDescription,
                                    Date effectiveTime,
                                    String methodName)
                             throws InvalidParameterException,
                                    UserNotAuthorizedException,
                                    PropertyServerException
        Set up the ExternalIdentifier for the supplied element. This external identifier may already exist for the requested scope if multiple open metadata entities are needed to represent the metadata element(s) in the third party metadata source that is identified by this ExternalIdentifier.
        Parameters:
        userId - calling userId
        elementGUID - unique identifier of the open metadata element to link to the external identifier
        elementGUIDParameterName - parameter supplying elementGUID
        elementTypeName - type of the element
        identifier - identifier from the third party technology (scope)
        identifierParameterName - name of parameter supplying identifier
        identifierKeyPattern - type of key pattern used in the third party technology (typically local key)
        identifierDescription - name of the identifier in the third party technology
        identifierUsage - usage information from the connector/client supplying the identifier
        identifierSource - name of the connector/client supplying the identifier
        identifierMappingProperties - additional properties to help with the synchronization
        scopeGUID - unique identifier of the software server capability that represents the third metadata source
        scopeGUIDParameterName - parameter supplying scopeGUID
        scopeQualifiedName - qualified name from the entity that
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        permittedSynchronization - direction of synchronization
        synchronizationDescription - optional description of the synchronization in progress (augments the description in the permitted synchronization enum)
        effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
        methodName - calling method
        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)

      • logRelationshipCreation

        public void logRelationshipCreation​(String scopeGUID,
                                    String scopeQualifiedName,
                                    String relationshipType,
                                    String end1GUID,
                                    String end1TypeName,
                                    String end2GUID,
                                    String end2TypeName,
                                    String methodName)
        Create an audit log record to document that an external metadata source has created a relationship.
        Parameters:
        scopeGUID - unique identifier of the element representing the scope
        scopeQualifiedName - unique name of the element representing the scope
        relationshipType - type of relationship
        end1GUID - unique identifier for the entity at end 1 of the relationship
        end1TypeName - type of the entity at end 1 of the relationship
        end2GUID - unique identifier for the entity at end 2 of the relationship
        end2TypeName - type of the entity at end 2 of the relationship
        methodName - calling method

      • logRelationshipUpdate

        public void logRelationshipUpdate​(String scopeGUID,
                                  String scopeQualifiedName,
                                  String relationshipType,
                                  String relationshipGUID,
                                  String methodName)
        Create an audit log record to document that an external metadata source has created a relationship.
        Parameters:
        scopeGUID - unique identifier of the element representing the scope
        scopeQualifiedName - unique name of the element representing the scope
        relationshipType - type of relationship
        relationshipGUID - unique identifier for the relationship
        methodName - calling method

      • logRelationshipRemoval

        public void logRelationshipRemoval​(String scopeGUID,
                                   String scopeQualifiedName,
                                   String relationshipType,
                                   String end1GUID,
                                   String end1TypeName,
                                   String end2GUID,
                                   String end2TypeName,
                                   String methodName)
        Create an audit log record to document that an external metadata source has created a relationship.
        Parameters:
        scopeGUID - unique identifier of the element representing the scope
        scopeQualifiedName - unique name of the element representing the scope
        relationshipType - type of relationship
        end1GUID - unique identifier for the entity at end 1 of the relationship
        end1TypeName - type of the entity at end 1 of the relationship
        end2GUID - unique identifier for the entity at end 2 of the relationship
        end2TypeName - type of the entity at end 2 of the relationship
        methodName - calling method

      • removeExternalIdentifier

        public void removeExternalIdentifier​(String userId,
                                     String elementGUID,
                                     String elementGUIDParameterName,
                                     String elementTypeName,
                                     String identifier,
                                     String identifierParameterName,
                                     int identifierKeyPattern,
                                     String identifierDescription,
                                     String identifierUsage,
                                     String identifierSource,
                                     Map<String,​String> identifierMappingProperties,
                                     String scopeGUID,
                                     String scopeGUIDParameterName,
                                     String scopeQualifiedName,
                                     String scopeTypeName,
                                     int permittedSynchronization,
                                     String synchronizationDescription,
                                     String methodName)
                              throws InvalidParameterException,
                                     UserNotAuthorizedException,
                                     PropertyServerException
        Remove the ExternalIdentifier for the supplied element. The open metadata element is not affected.
        Parameters:
        userId - calling userId
        elementGUID - unique identifier of the open metadata element to link to the external identifier
        elementGUIDParameterName - parameter supplying elementGUID
        elementTypeName - type of the element
        identifier - identifier from the third party technology (scope)
        identifierParameterName - name of parameter supplying identifier
        identifierKeyPattern - type of key pattern used in the third party technology (typically local key)
        identifierDescription - name of the identifier in the third party technology
        identifierUsage - usage information from the connector/client supplying the identifier
        identifierSource - name of the connector/client supplying the identifier
        identifierMappingProperties - additional properties to help with the synchronization
        scopeGUID - unique identifier of the software server capability that represents the third metadata source
        scopeGUIDParameterName - parameter supplying scopeGUID
        scopeQualifiedName - qualified name from the entity that
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        permittedSynchronization - direction of synchronization
        synchronizationDescription - optional description of the synchronization in progress (augments the description in the permitted synchronization enum)
        methodName - calling method
        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)

      • confirmSynchronization

        public EntityDetail confirmSynchronization​(String userId,
                                           String elementGUID,
                                           String elementGUIDParameterName,
                                           String elementTypeName,
                                           String identifier,
                                           String identifierParameterName,
                                           String scopeGUID,
                                           String scopeGUIDParameterName,
                                           String scopeQualifiedName,
                                           String scopeTypeName,
                                           Date effectiveTime,
                                           String methodName)
                                    throws InvalidParameterException,
                                           UserNotAuthorizedException,
                                           PropertyServerException
        Confirm that the values of a particular metadata element have been synchronized. This is important from an audit points of view, and to allow bidirectional updates of metadata using optimistic locking.
        Parameters:
        userId - calling user
        elementGUID - unique identifier (GUID) of this element in open metadata
        elementGUIDParameterName - parameter supplying elementGUID
        elementTypeName - type of element being mapped
        identifier - unique identifier of this element in the external asset manager
        identifierParameterName - parameter supplying identifier
        scopeGUID - unique identifier of software server capability representing the caller
        scopeGUIDParameterName - parameter name supplying scopeGUID
        scopeQualifiedName - unique name of the scope
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        effectiveTime - the time that the retrieved elements must be effective for (null for any time, new Date() for now)
        methodName - calling method
        Returns:
        the identifier's entity
        Throws:
        InvalidParameterException - one of the parameters is invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server

      • getExternalIdentifiersForElement

        public List<EXTERNAL_ID> getExternalIdentifiersForElement​(String userId,
                                                          String elementGUID,
                                                          String elementGUIDParameterName,
                                                          String elementTypeName,
                                                          List<String> serviceSupportedZones,
                                                          int startingFrom,
                                                          int pageSize,
                                                          Date effectiveTime,
                                                          String methodName)
                                                   throws InvalidParameterException,
                                                          PropertyServerException,
                                                          UserNotAuthorizedException
        Return the external identifiers attached to a referenceable by the ExternalIdLink.
        Parameters:
        userId - calling user
        elementGUID - identifier for the entity that the identifier is attached to
        elementGUIDParameterName - name of parameter supplying the GUID
        elementTypeName - name of the type of object being attached to
        serviceSupportedZones - supported zones for calling service
        startingFrom - where to start from in the list
        pageSize - maximum number of results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        methodName - calling method
        Returns:
        list of retrieved objects or null if none found
        Throws:
        InvalidParameterException - the input properties are invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server

      • getExternalIdentifiersForScope

        public List<EXTERNAL_ID> getExternalIdentifiersForScope​(String userId,
                                                        String elementGUID,
                                                        String elementGUIDParameterName,
                                                        String elementTypeName,
                                                        String scopeGUID,
                                                        String scopeTypeName,
                                                        String scopeQualifiedName,
                                                        int startingFrom,
                                                        int pageSize,
                                                        Date effectiveTime,
                                                        String methodName)
                                                 throws InvalidParameterException,
                                                        PropertyServerException,
                                                        UserNotAuthorizedException
        Return the external identifiers attached to a referenceable by the ExternalIdLink.
        Parameters:
        userId - calling user
        elementGUID - identifier for the entity that the identifier is attached to
        elementGUIDParameterName - name of parameter supplying the GUID
        elementTypeName - name of the type of object being attached to
        scopeGUID - unique identifier of the software server capability that represents the third metadata source
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        scopeQualifiedName - unique name of the software server capability that represents the third metadata source
        startingFrom - where to start from in the list
        pageSize - maximum number of results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        methodName - calling method
        Returns:
        list of retrieved objects or null if none found
        Throws:
        InvalidParameterException - the input properties are invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server

      • getExternalIdentifiersForScope

        public List<EXTERNAL_ID> getExternalIdentifiersForScope​(String userId,
                                                        String elementGUID,
                                                        String elementGUIDParameterName,
                                                        String elementTypeName,
                                                        List<String> serviceSupportedZones,
                                                        String scopeGUID,
                                                        String scopeTypeName,
                                                        String scopeQualifiedName,
                                                        int startingFrom,
                                                        int pageSize,
                                                        Date effectiveTime,
                                                        String methodName)
                                                 throws InvalidParameterException,
                                                        PropertyServerException,
                                                        UserNotAuthorizedException
        Return the external identifiers attached to a referenceable by the ExternalIdLink.
        Parameters:
        userId - calling user
        elementGUID - identifier for the entity that the identifier is attached to
        elementGUIDParameterName - name of parameter supplying the GUID
        elementTypeName - name of the type of object being attached to
        serviceSupportedZones - supported zones for calling service
        scopeGUID - unique identifier of the software server capability that represents the third metadata source
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        scopeQualifiedName - unique name name of the software server capability that represents the third party metadata source
        startingFrom - where to start from in the list
        pageSize - maximum number of results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        methodName - calling method
        Returns:
        list of retrieved objects or null if none found
        Throws:
        InvalidParameterException - the input properties are invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server

      • getElementEntitiesForScope

        public List<EntityDetail> getElementEntitiesForScope​(String userId,
                                                     String scopeGUID,
                                                     String scopeParameterName,
                                                     String scopeTypeName,
                                                     String requestedTypeName,
                                                     int startingFrom,
                                                     int pageSize,
                                                     Date effectiveTime,
                                                     String methodName)
                                              throws InvalidParameterException,
                                                     UserNotAuthorizedException,
                                                     PropertyServerException
        Return the list of entities for open metadata elements of an open metadata type that are associated with an external identifier in a particular scope.
        Parameters:
        userId - calling user
        scopeGUID - unique identifier of software server capability representing the caller
        scopeParameterName - unique name of software server capability representing the caller
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        requestedTypeName - unique type name of the elements in the external asset manager
        startingFrom - where to start from in the list
        pageSize - maximum number of results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        methodName - calling method
        Returns:
        list of element headers
        Throws:
        InvalidParameterException - one of the parameters is invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server

      • getElementsForExternalIdentifier

        public List<OPEN_METADATA_ELEMENT_HEADER> getElementsForExternalIdentifier​(String userId,
                                                                           String scopeGUID,
                                                                           String scopeParameterName,
                                                                           String scopeTypeName,
                                                                           String scopeQualifiedName,
                                                                           String externalIdentifier,
                                                                           int startingFrom,
                                                                           int pageSize,
                                                                           Date effectiveTime,
                                                                           String methodName)
                                                                    throws InvalidParameterException,
                                                                           UserNotAuthorizedException,
                                                                           PropertyServerException
        Return the list of headers for open metadata elements that are associated with a particular external identifier. It is necessary to navigate to the externalIdentifier from the scope.
        Parameters:
        userId - calling user
        scopeGUID - unique identifier of software server capability representing the caller
        scopeParameterName - unique name of software server capability representing the caller
        scopeTypeName - specific type name of the software server capability that represents the third party metadata source
        scopeQualifiedName - unique name name of the software server capability that represents the third party metadata source
        externalIdentifier - unique identifier of this element in the external asset manager
        startingFrom - where to start from in the list
        pageSize - maximum number of results that can be returned
        effectiveTime - the time that the retrieved elements must be effective for
        methodName - calling method
        Returns:
        list of element headers
        Throws:
        InvalidParameterException - one of the parameters is invalid
        UserNotAuthorizedException - user not authorized to issue this request
        PropertyServerException - problem accessing the property server