org.odpi.openmetadata.commonservices.generichandlers

Class ExternalIdentifierHandler<EXTERNAL_ID,OPEN_METADATA_ELEMENT_HEADER>

java.lang.Object

org.odpi.openmetadata.commonservices.generichandlers.OpenMetadataAPIGenericHandler<B>

org.odpi.openmetadata.commonservices.generichandlers.ReferenceableHandler<EXTERNAL_ID>

org.odpi.openmetadata.commonservices.generichandlers.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.

Field Summary

Fields inherited from class org.odpi.openmetadata.commonservices.generichandlers.OpenMetadataAPIGenericHandler

auditLog, beanClass, converter, defaultZones, errorHandler, invalidParameterHandler, localServerUserId, publishZones, repositoryHandler, repositoryHelper, securityVerifier, serverName, serviceName, supportedZones

Constructor Summary

Constructors

Constructor and Description

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

Method Summary

Modifier and Type	Method and Description
EntityDetail	confirmSynchronization(String userId, String elementGUID, String elementGUIDParameterName, String elementTypeName, String identifier, String identifierParameterName, String scopeGUID, String scopeGUIDParameterName, String scopeQualifiedName, String scopeTypeName, String methodName) Confirm that the values of a particular metadata element have been synchronized.
int	countExternalIdentifiers(String userId, String elementGUID, String methodName) Count the number of external identifiers attached to an anchor entity.
List<EntityDetail>	getElementEntitiesForScope(String userId, String scopeGUID, String scopeParameterName, String scopeTypeName, String requestedTypeName, int startingFrom, int pageSize, String methodName) 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.
List<OPEN_METADATA_ELEMENT_HEADER>	getElementsForExternalIdentifier(String userId, String scopeGUID, String scopeParameterName, String scopeTypeName, String scopeQualifiedName, String externalIdentifier, int startingFrom, int pageSize, String methodName) Return the list of headers for open metadata elements that are associated with a particular external identifier.
List<EXTERNAL_ID>	getExternalIdentifiersForElement(String userId, String elementGUID, String elementGUIDParameterName, String elementTypeName, List<String> serviceSupportedZones, int startingFrom, int pageSize, String methodName) Return the external identifiers attached to a referenceable by the ExternalIdLink.
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, String methodName) Return the external identifiers attached to a referenceable by the ExternalIdLink.
List<EXTERNAL_ID>	getExternalIdentifiersForScope(String userId, String elementGUID, String elementGUIDParameterName, String elementTypeName, String scopeGUID, String scopeTypeName, String scopeQualifiedName, int startingFrom, int pageSize, String methodName) Return the external identifiers attached to a referenceable by the ExternalIdLink.
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.
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.
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) Remove the ExternalIdentifier for the supplied element.
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, String methodName) Set up the ExternalIdentifier for the supplied element.

Methods inherited from class org.odpi.openmetadata.commonservices.generichandlers.ReferenceableHandler

addSecurityTags, findBeanGUIDsByQualifiedName, findBeanGUIDsByQualifiedName, findBeansByQualifiedName, findBeansByQualifiedName, getBeanByQualifiedName, getBeanByQualifiedName, getBeanGUIDByQualifiedName, getBeanGUIDByQualifiedName, getBeanGUIDsByQualifiedName, getBeanGUIDsByQualifiedName, getBeansByQualifiedName, getBeansByQualifiedName, getMoreInformation, getMoreInformation, getVendorProperties, removeSecurityTags, removeSemanticAssignment, saveSemanticAssignment, saveSemanticAssignment

Methods inherited from class org.odpi.openmetadata.commonservices.generichandlers.OpenMetadataAPIGenericHandler

countAttachments, createBeanFromTemplate, createBeanInRepository, deleteBeanInRepository, deleteBeanInRepository, findBeanGUIDs, findBeans, findBeans, findBeans, findEntities, getAllAttachmentLinks, getAnchorsForAttachedElements, getAttachedElement, getAttachedElement, getAttachedElementGUID, getAttachedElementGUID, getAttachedElementGUIDs, getAttachedElementGUIDs, getAttachedElements, getAttachedElements, getAttachedElements, getAttachedElements, getAttachedEntities, getAttachedEntities, getAttachedEntities, getAttachedEntity, getAttachedEntity, getAttachmentLinks, getAttachmentLinks, getAttachmentLinks, getBeanByUniqueName, getBeanByUniqueName, getBeanByValue, getBeanFromEntity, getBeanFromRepository, getBeanFromRepository, getBeanGUIDByUniqueName, getBeanGUIDsByClassification, getBeanGUIDsByType, getBeanGUIDsByType, getBeanGUIDsByValue, getBeansByClassification, getBeansByCreator, getBeansByType, getBeansByType, getBeansByValue, getBeansByValue, getBeansByValue, getBeansByValue, getEntitiesByType, getEntitiesByValue, getEntitiesByValue, getEntityByValue, getEntityFromRepository, getEntityFromRepository, getEntityFromRepository, getEntityGUIDByValue, getRepositoryHelper, getServiceName, getUniqueAttachmentLink, getUniqueAttachmentLink, linkElementToElement, linkElementToElement, maintainSupplementaryProperties, relinkElementToNewElement, relinkElementToNewElement, setSecurityVerifier, unlinkAllElements, unlinkConnectedElement, unlinkElementFromElement, unlinkElementFromElement, updateBeanInRepository, updateBeanInRepository, updateBeanPropertyInRepository, updateBeanStatusInRepository, updateElementToElementLink, updateElementToElementLink, validateAnchorEntity, validateAnchorEntity, verifyExternalSourceIdentity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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,
                                    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)

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

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,
                                           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

methodName - calling method

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - user not authorized to issue this request

PropertyServerException - problem accessing the property server

countExternalIdentifiers

public int countExternalIdentifiers(String userId,
                                    String elementGUID,
                                    String methodName)
                             throws InvalidParameterException,
                                    PropertyServerException,
                                    UserNotAuthorizedException

Count the number of external identifiers attached to an anchor entity.

Parameters:

userId - calling user

elementGUID - identifier for the entity that the object is attached to

methodName - calling method

Returns:

count of attached objects

Throws:

InvalidParameterException - the parameters are invalid

UserNotAuthorizedException - user not authorized to issue this request

PropertyServerException - problem detected in the repository services

getExternalIdentifiersForElement

public List<EXTERNAL_ID> getExternalIdentifiersForElement(String userId,
                                                          String elementGUID,
                                                          String elementGUIDParameterName,
                                                          String elementTypeName,
                                                          List<String> serviceSupportedZones,
                                                          int startingFrom,
                                                          int pageSize,
                                                          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

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,
                                                        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

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,
                                                        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

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,
                                                     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

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,
                                                                           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

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