java.lang.Object
- org.odpi.openmetadata.accessservices.assetmanager.handlers.ExternalReferenceExchangeHandler

```
public class ExternalReferenceExchangeHandler
extends Object
```
ExternalReferenceExchangeHandler is the server side handler for managing externalReference content.

Constructor Summary

Constructors
Constructor	Description
`ExternalReferenceExchangeHandler(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 externalReference exchange handler with information needed to work with externalReference related objects for Asset Manager OMAS.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`String`	`createExternalReference(String userId, boolean assetManagerIsHome, MetadataCorrelationProperties correlationProperties, ExternalReferenceProperties externalReferenceProperties, String anchorGUID, String methodName)`	Create a new metadata element to represent the root of a externalReference.
`List<ExternalReferenceElement>`	`findExternalReferences(String userId, String assetManagerGUID, String assetManagerName, String searchString, String searchStringParameterName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of externalReference metadata elements that contain the search string.
`ExternalReferenceElement`	`getExternalReferenceByGUID(String userId, String assetManagerGUID, String assetManagerName, String guid, String guidParameterName, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the externalReference metadata element with the supplied unique identifier.
`List<ExternalReferenceElement>`	`getExternalReferences(String userId, String assetManagerGUID, String assetManagerName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of externalReference metadata elements that contain the search string.
`List<ExternalReferenceElement>`	`getExternalReferencesById(String userId, String assetManagerGUID, String assetManagerName, String referenceId, String referenceIdParameterName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of externalReference metadata elements with a matching qualified or display referenceId.
`List<ExternalReferenceElement>`	`getExternalReferencesByName(String userId, String assetManagerGUID, String assetManagerName, String name, String nameParameterName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of externalReference metadata elements with a matching qualified or display name.
`List<ExternalReferenceElement>`	`getExternalReferencesByURL(String userId, String assetManagerGUID, String assetManagerName, String url, String urlParameterName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of externalReference metadata elements with a matching qualified or display url.
`List<ExternalReferenceElement>`	`getExternalReferencesForAssetManager(String userId, String assetManagerGUID, String assetManagerName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of external references created by this caller.
`String`	`linkExternalReferenceToElement(String userId, String assetManagerGUID, String assetManagerName, String attachedToGUID, String attachedToGUIDParameterName, String externalReferenceGUID, String externalReferenceGUIDParameterName, ExternalReferenceLinkProperties linkProperties, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Link an external reference to an object.
`void`	`removeExternalReference(String userId, MetadataCorrelationProperties correlationProperties, String externalReferenceGUID, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Remove the metadata element representing a externalReference.
`List<ExternalReferenceLinkElement>`	`retrieveAttachedExternalReferences(String userId, String assetManagerGUID, String assetManagerName, String attachedToGUID, String attachedToGUIDParameterName, int startFrom, int pageSize, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Retrieve the list of external references attached to the supplied object.
`void`	`unlinkExternalReferenceFromElement(String userId, String assetManagerGUID, String assetManagerName, String externalReferenceLinkGUID, String externalReferenceGUIDParameterName, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Remove the link between an external reference and an element.
`void`	`updateExternalReference(String userId, MetadataCorrelationProperties correlationProperties, String externalReferenceGUID, boolean isMergeUpdate, ExternalReferenceProperties externalReferenceProperties, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Update the metadata element representing an external reference.
`void`	`updateExternalReferenceToElementLink(String userId, String assetManagerGUID, String assetManagerName, String externalReferenceLinkGUID, String externalReferenceGUIDParameterName, ExternalReferenceLinkProperties linkProperties, boolean forLineage, boolean forDuplicateProcessing, Date effectiveTime, String methodName)`	Update the link between an external reference to an object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExternalReferenceExchangeHandler

public ExternalReferenceExchangeHandler(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 externalReference exchange handler with information needed to work with externalReference related objects for Asset Manager OMAS.

Parameters:: 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 instances from.; defaultZones - list of zones that the access service should set in all new instances.; publishZones - list of zones that the access service sets up in published instances.; auditLog - destination for audit log events.

Method Detail

createExternalReference
```
public String createExternalReference(String userId,
                                      boolean assetManagerIsHome,
                                      MetadataCorrelationProperties correlationProperties,
                                      ExternalReferenceProperties externalReferenceProperties,
                                      String anchorGUID,
                                      String methodName)
                               throws InvalidParameterException,
                                      UserNotAuthorizedException,
                                      PropertyServerException
```
Create a new metadata element to represent the root of a externalReference. All categories and terms are linked to a single externalReference. They are owned by this externalReference and if the externalReference is deleted, any linked terms and categories are deleted as well.

Parameters:

userId - calling user

assetManagerIsHome - ensure that only the asset manager can update this asset

correlationProperties - properties to help with the mapping of the elements in the external asset manager and open metadata

externalReferenceProperties - properties to store

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

methodName - calling method

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

updateExternalReference

public void updateExternalReference(String userId,
                                    MetadataCorrelationProperties correlationProperties,
                                    String externalReferenceGUID,
                                    boolean isMergeUpdate,
                                    ExternalReferenceProperties externalReferenceProperties,
                                    boolean forLineage,
                                    boolean forDuplicateProcessing,
                                    Date effectiveTime,
                                    String methodName)
                             throws InvalidParameterException,
                                    UserNotAuthorizedException,
                                    PropertyServerException

Update the metadata element representing an external reference.

Parameters:: userId - calling user; correlationProperties - properties to help with the mapping of the elements in the external asset manager and open metadata; externalReferenceGUID - unique identifier of the metadata element to update; isMergeUpdate - are unspecified properties unchanged (true) or replaced with null?; externalReferenceProperties - new properties for this element; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is 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)

removeExternalReference
```
public void removeExternalReference(String userId,
                                    MetadataCorrelationProperties correlationProperties,
                                    String externalReferenceGUID,
                                    boolean forLineage,
                                    boolean forDuplicateProcessing,
                                    Date effectiveTime,
                                    String methodName)
                             throws InvalidParameterException,
                                    UserNotAuthorizedException,
                                    PropertyServerException
```
Remove the metadata element representing a externalReference. This will delete the externalReference and all categories and terms because the Anchors classifications are set up in these elements.

Parameters:

userId - calling user

correlationProperties - properties to help with the mapping of the elements in the external asset manager and open metadata

externalReferenceGUID - unique identifier of the metadata element to remove

forLineage - return elements marked with the Memento classification?

forDuplicateProcessing - do not merge elements marked as duplicates?

effectiveTime - when should the elements be effected for - null is anytime; new Date() is 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)

linkExternalReferenceToElement

public String linkExternalReferenceToElement(String userId,
                                             String assetManagerGUID,
                                             String assetManagerName,
                                             String attachedToGUID,
                                             String attachedToGUIDParameterName,
                                             String externalReferenceGUID,
                                             String externalReferenceGUIDParameterName,
                                             ExternalReferenceLinkProperties linkProperties,
                                             boolean forLineage,
                                             boolean forDuplicateProcessing,
                                             Date effectiveTime,
                                             String methodName)
                                      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; attachedToGUID - object linked to external references; attachedToGUIDParameterName - parameter name; externalReferenceGUID - unique identifier (guid) of the external reference details; externalReferenceGUIDParameterName - parameter name; linkProperties - description for the reference from the perspective of the object that the reference is being attached to.; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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

public void updateExternalReferenceToElementLink(String userId,
                                                 String assetManagerGUID,
                                                 String assetManagerName,
                                                 String externalReferenceLinkGUID,
                                                 String externalReferenceGUIDParameterName,
                                                 ExternalReferenceLinkProperties linkProperties,
                                                 boolean forLineage,
                                                 boolean forDuplicateProcessing,
                                                 Date effectiveTime,
                                                 String methodName)
                                          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; externalReferenceLinkGUID - unique identifier (guid) of the external reference details; externalReferenceGUIDParameterName - parameter name; linkProperties - description for the reference from the perspective of the object that the reference is being attached to; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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

public void unlinkExternalReferenceFromElement(String userId,
                                               String assetManagerGUID,
                                               String assetManagerName,
                                               String externalReferenceLinkGUID,
                                               String externalReferenceGUIDParameterName,
                                               boolean forLineage,
                                               boolean forDuplicateProcessing,
                                               Date effectiveTime,
                                               String methodName)
                                        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 server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; externalReferenceLinkGUID - identifier of the external reference relationship; externalReferenceGUIDParameterName - parameter name; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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

public List<ExternalReferenceElement> getExternalReferences(String userId,
                                                            String assetManagerGUID,
                                                            String assetManagerName,
                                                            int startFrom,
                                                            int pageSize,
                                                            boolean forLineage,
                                                            boolean forDuplicateProcessing,
                                                            Date effectiveTime,
                                                            String methodName)
                                                     throws InvalidParameterException,
                                                            UserNotAuthorizedException,
                                                            PropertyServerException

Retrieve the list of externalReference metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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

public List<ExternalReferenceElement> findExternalReferences(String userId,
                                                             String assetManagerGUID,
                                                             String assetManagerName,
                                                             String searchString,
                                                             String searchStringParameterName,
                                                             int startFrom,
                                                             int pageSize,
                                                             boolean forLineage,
                                                             boolean forDuplicateProcessing,
                                                             Date effectiveTime,
                                                             String methodName)
                                                      throws InvalidParameterException,
                                                             UserNotAuthorizedException,
                                                             PropertyServerException

Retrieve the list of externalReference metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; searchString - string to find in the properties; searchStringParameterName - name of parameter for search string; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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)

getExternalReferencesByName

public List<ExternalReferenceElement> getExternalReferencesByName(String userId,
                                                                  String assetManagerGUID,
                                                                  String assetManagerName,
                                                                  String name,
                                                                  String nameParameterName,
                                                                  int startFrom,
                                                                  int pageSize,
                                                                  boolean forLineage,
                                                                  boolean forDuplicateProcessing,
                                                                  Date effectiveTime,
                                                                  String methodName)
                                                           throws InvalidParameterException,
                                                                  UserNotAuthorizedException,
                                                                  PropertyServerException

Retrieve the list of externalReference metadata elements with a matching qualified or display name. There are no wildcards supported on this request.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; name - name to search for; nameParameterName - name of parameter supplying name value; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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)

getExternalReferencesById

public List<ExternalReferenceElement> getExternalReferencesById(String userId,
                                                                String assetManagerGUID,
                                                                String assetManagerName,
                                                                String referenceId,
                                                                String referenceIdParameterName,
                                                                int startFrom,
                                                                int pageSize,
                                                                boolean forLineage,
                                                                boolean forDuplicateProcessing,
                                                                Date effectiveTime,
                                                                String methodName)
                                                         throws InvalidParameterException,
                                                                UserNotAuthorizedException,
                                                                PropertyServerException

Retrieve the list of externalReference metadata elements with a matching qualified or display referenceId. There are no wildcards supported on this request.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique referenceId of software server capability representing the caller; referenceId - referenceId to search for; referenceIdParameterName - name of parameter supplying referenceId value; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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)

getExternalReferencesByURL

public List<ExternalReferenceElement> getExternalReferencesByURL(String userId,
                                                                 String assetManagerGUID,
                                                                 String assetManagerName,
                                                                 String url,
                                                                 String urlParameterName,
                                                                 int startFrom,
                                                                 int pageSize,
                                                                 boolean forLineage,
                                                                 boolean forDuplicateProcessing,
                                                                 Date effectiveTime,
                                                                 String methodName)
                                                          throws InvalidParameterException,
                                                                 UserNotAuthorizedException,
                                                                 PropertyServerException

Retrieve the list of externalReference metadata elements with a matching qualified or display url. There are no wildcards supported on this request.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique url of software server capability representing the caller; url - url to search for; urlParameterName - name of parameter supplying url value; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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)

getExternalReferencesForAssetManager

public List<ExternalReferenceElement> getExternalReferencesForAssetManager(String userId,
                                                                           String assetManagerGUID,
                                                                           String assetManagerName,
                                                                           int startFrom,
                                                                           int pageSize,
                                                                           boolean forLineage,
                                                                           boolean forDuplicateProcessing,
                                                                           Date effectiveTime,
                                                                           String methodName)
                                                                    throws InvalidParameterException,
                                                                           UserNotAuthorizedException,
                                                                           PropertyServerException

Retrieve the list of external references created by this caller.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; startFrom - paging start point; pageSize - maximum results that can be returned; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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)

retrieveAttachedExternalReferences

public List<ExternalReferenceLinkElement> retrieveAttachedExternalReferences(String userId,
                                                                             String assetManagerGUID,
                                                                             String assetManagerName,
                                                                             String attachedToGUID,
                                                                             String attachedToGUIDParameterName,
                                                                             int startFrom,
                                                                             int pageSize,
                                                                             boolean forLineage,
                                                                             boolean forDuplicateProcessing,
                                                                             Date effectiveTime,
                                                                             String methodName)
                                                                      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; attachedToGUIDParameterName - name of attachedToGUID parameter; startFrom - index of the list to start from (0 for start); pageSize - maximum number of elements to return; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
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

public ExternalReferenceElement getExternalReferenceByGUID(String userId,
                                                           String assetManagerGUID,
                                                           String assetManagerName,
                                                           String guid,
                                                           String guidParameterName,
                                                           boolean forLineage,
                                                           boolean forDuplicateProcessing,
                                                           Date effectiveTime,
                                                           String methodName)
                                                    throws InvalidParameterException,
                                                           UserNotAuthorizedException,
                                                           PropertyServerException

Retrieve the externalReference metadata element with the supplied unique identifier.

Parameters:: userId - calling user; assetManagerGUID - unique identifier of software server capability representing the caller; assetManagerName - unique name of software server capability representing the caller; guid - unique identifier of the requested metadata element; guidParameterName - name of parameter for guid; forLineage - return elements marked with the Memento classification?; forDuplicateProcessing - do not merge elements marked as duplicates?; effectiveTime - when should the elements be effected for - null is anytime; new Date() is now; methodName - calling method
Returns:: matching metadata element
Throws:: InvalidParameterException - one of the parameters is invalid; UserNotAuthorizedException - the user is not authorized to issue this request; PropertyServerException - there is a problem reported in the open metadata server(s)

Class ExternalReferenceExchangeHandler