Package org.odpi.openmetadata.frameworks.openmetadata.handlers

Class ExternalReferenceHandler

java.lang.Object

org.odpi.openmetadata.frameworks.openmetadata.handlers.OpenMetadataHandlerBase

org.odpi.openmetadata.frameworks.openmetadata.handlers.ExternalReferenceHandler

public class ExternalReferenceHandler
extends OpenMetadataHandlerBase

ExternalReferenceHandler provides methods to define external references and their relationships.

Field Summary

Fields inherited from class org.odpi.openmetadata.frameworks.openmetadata.handlers.OpenMetadataHandlerBase

auditLog, classificationBuilder, elementBuilder, localServerName, localServiceName, metadataElementTypeName, openMetadataClient, propertyHelper, relationshipBuilder

Constructor Summary

Constructors

Constructor	Description
ExternalReferenceHandler(String localServerName, AuditLog auditLog, String localServiceName, OpenMetadataClient openMetadataClient)	Create a new handler.

Method Summary

Modifier and Type	Method	Description
String	createExternalReference(String userId, NewElementOptions newElementOptions, Map<String,ClassificationProperties> initialClassifications, ExternalReferenceProperties properties, RelationshipProperties parentRelationshipProperties)	Create a new external reference.
String	createExternalReferenceFromTemplate(String userId, TemplateOptions templateOptions, String templateGUID, EntityProperties replacementProperties, Map<String,ClassificationProperties> replacementClassifications, Map<String,String> placeholderProperties, RelationshipProperties parentRelationshipProperties)	Create a new metadata element to represent an external reference using an existing element as a template.
void	deleteExternalReference(String userId, String externalReferenceGUID, DeleteOptions deleteOptions)	Delete an external reference.
void	detachCitedDocumentReference(String userId, String elementGUID, String externalReferenceGUID, DeleteOptions deleteOptions)	Detach an element from its external document reference.
void	detachCitedDocumentReference(String userId, String citedDocumentLinkRelationshipGUID, DeleteOptions deleteOptions)	Remove a cited document link relationship.
void	detachExternalReference(String userId, String elementGUID, String externalReferenceGUID, DeleteOptions deleteOptions)	Detach an external reference from an element.
void	detachExternalReference(String userId, String externalReferenceLinkRelationshipGUID, DeleteOptions deleteOptions)	Remove a external reference link relationship.
void	detachMediaReference(String userId, String elementGUID, String externalReferenceGUID, DeleteOptions deleteOptions)	Detach an external media reference from an element.
void	detachMediaReference(String userId, String mediaReferenceRelationshipGUID, DeleteOptions deleteOptions)	Remove a media reference relationship.
List<OpenMetadataRootElement>	findExternalReferences(String userId, String searchString, SearchOptions searchOptions)	Retrieve the list of external references metadata elements that contain the search string and show which solution components (if any) are attached to it.
OpenMetadataRootElement	getExternalReferenceByGUID(String userId, String externalReferenceGUID, GetOptions getOptions)	Return the properties of a specific external reference.
List<OpenMetadataRootElement>	getExternalReferencesByName(String userId, String name, QueryOptions queryOptions)	Returns the list of external references with a particular name.
String	linkCitedDocumentReference(String userId, String elementGUID, String externalReferenceGUID, MakeAnchorOptions makeAnchorOptions, CitedDocumentLinkProperties relationshipProperties)	Attach an element to its external document reference.
String	linkExternalReference(String userId, String elementGUID, String externalReferenceGUID, MakeAnchorOptions makeAnchorOptions, ExternalReferenceLinkProperties relationshipProperties)	Attach an external reference to an element.
String	linkMediaReference(String userId, String elementGUID, String externalReferenceGUID, MakeAnchorOptions makeAnchorOptions, MediaReferenceProperties relationshipProperties)	Attach an external media reference to an element.
void	updateCitedDocumentReference(String userId, String citedDocumentLinkRelationshipGUID, UpdateOptions updateOptions, CitedDocumentLinkProperties relationshipProperties)	Update the properties of a cited document link relationship.
boolean	updateExternalReference(String userId, String externalReferenceGUID, UpdateOptions updateOptions, ExternalReferenceProperties properties)	Update the properties of an external reference.
void	updateExternalReferenceLink(String userId, String externalReferenceLinkRelationshipGUID, UpdateOptions updateOptions, ExternalReferenceLinkProperties relationshipProperties)	Update the properties of a external reference link relationship.
void	updateMediaReference(String userId, String mediaReferenceRelationshipGUID, UpdateOptions updateOptions, MediaReferenceProperties relationshipProperties)	Update the properties of a media reference relationship.

Methods inherited from class org.odpi.openmetadata.frameworks.openmetadata.handlers.OpenMetadataHandlerBase

addDefaultType, addDefaultType, addDefaultType, addMermaidToRootElement, convertRootElement, convertRootElement, convertRootElements, createElementFromTemplate, createNewElement, findRootElements, getClassificationSearch, getDeletedElementByUniqueName, getElementHierarchies, getElementHierarchies, getElementHierarchy, getElementRelatedElements, getElementsByClassification, getFullParentContext, getLineageElementByUniqueName, getMermaidGraph, getMermaidGraph, getQueryOptions, getQueryOptions, getQueryOptions, getRelatedRootElements, getRootElementByGUID, getRootElementByUniqueName, getRootElementByUniqueName, getRootElementsByName, getRootElementsByUniqueName, populateRootElement, updateElement

Methods inherited from class java.lang.Object

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

Constructor Details

ExternalReferenceHandler

public ExternalReferenceHandler(String localServerName,
 AuditLog auditLog,
 String localServiceName,
 OpenMetadataClient openMetadataClient)

Create a new handler.

Parameters:

localServerName - name of this server (view server)

auditLog - logging destination

localServiceName - local service name

openMetadataClient - access to open metadata

Method Details

createExternalReference

public String createExternalReference(String userId,
 NewElementOptions newElementOptions,
 Map<String,ClassificationProperties> initialClassifications,
 ExternalReferenceProperties properties,
 RelationshipProperties parentRelationshipProperties)
                               throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Create a new external reference.

Parameters:

userId - userId of the user making the request.

newElementOptions - details of the element to create

initialClassifications - map of classification names to classification properties to include in the entity creation request

properties - properties for the new element.

parentRelationshipProperties - properties to include in parent relationship

Returns:

unique identifier of the newly created element

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

createExternalReferenceFromTemplate

public String createExternalReferenceFromTemplate(String userId,
 TemplateOptions templateOptions,
 String templateGUID,
 EntityProperties replacementProperties,
 Map<String,ClassificationProperties> replacementClassifications,
 Map<String,String> placeholderProperties,
 RelationshipProperties parentRelationshipProperties)
                                           throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent an external reference using an existing element as a template. The template defines additional classifications and relationships that should be added to the new external reference.

Parameters:

userId - calling user

templateOptions - details of the element to create

templateGUID - the unique identifier of the existing element to copy

replacementProperties - properties of the new metadata element. These override the template values

replacementClassifications - map of classification names to classification properties to include in the entity creation request. These override the template values.

placeholderProperties - property name-to-property value map to replace any placeholder values in the template element - and their anchored elements, which are also copied as part of this operation.

parentRelationshipProperties - properties to include in parent relationship

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 - a problem reported in the open metadata server(s)

updateExternalReference

public boolean updateExternalReference(String userId,
 String externalReferenceGUID,
 UpdateOptions updateOptions,
 ExternalReferenceProperties properties)
                                throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of an external reference.

Parameters:

userId - userId of the user making the request.

externalReferenceGUID - unique identifier of the external reference (returned from create)

updateOptions - provides a structure for the additional options when updating an element.

properties - properties for the element.

Returns:

boolean - true if an update occurred

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

linkExternalReference

public String linkExternalReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 MakeAnchorOptions makeAnchorOptions,
 ExternalReferenceLinkProperties relationshipProperties)
                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Attach an external reference to an element.

Parameters:

userId - userId of the user making the request

elementGUID - unique identifier of the element

externalReferenceGUID - unique identifier of the external reference

makeAnchorOptions - options to control access to open metadata

relationshipProperties - description of the relationship.

Returns:

unique identifier of the new relationship

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateExternalReferenceLink

public void updateExternalReferenceLink(String userId,
 String externalReferenceLinkRelationshipGUID,
 UpdateOptions updateOptions,
 ExternalReferenceLinkProperties relationshipProperties)
                                 throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of a external reference link relationship.

Parameters:

userId - userId of the user making the request

externalReferenceLinkRelationshipGUID - unique identifier of the relationship

updateOptions - provides a structure for the additional options when updating a relationship.

relationshipProperties - description of the relationship.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

detachExternalReference

public void detachExternalReference(String userId,
 String externalReferenceLinkRelationshipGUID,
 DeleteOptions deleteOptions)
                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Remove a external reference link relationship.

Parameters:

userId - userId of the user making the request.

externalReferenceLinkRelationshipGUID - unique identifier of the relationship

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

linkMediaReference

public String linkMediaReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 MakeAnchorOptions makeAnchorOptions,
 MediaReferenceProperties relationshipProperties)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Attach an external media reference to an element.

Parameters:

userId - userId of the user making the request

elementGUID - unique identifier of the first external reference

externalReferenceGUID - unique identifier of the second external reference

makeAnchorOptions - options to control access to open metadata

relationshipProperties - description of the relationship.

Returns:

unique identifier of the new relationship

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateMediaReference

public void updateMediaReference(String userId,
 String mediaReferenceRelationshipGUID,
 UpdateOptions updateOptions,
 MediaReferenceProperties relationshipProperties)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of a media reference relationship.

Parameters:

userId - userId of the user making the request

mediaReferenceRelationshipGUID - unique identifier of the relationship

updateOptions - provides a structure for the additional options when updating a relationship.

relationshipProperties - description of the relationship.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

detachMediaReference

public void detachMediaReference(String userId,
 String mediaReferenceRelationshipGUID,
 DeleteOptions deleteOptions)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Remove a media reference relationship.

Parameters:

userId - userId of the user making the request.

mediaReferenceRelationshipGUID - unique identifier of the relationship

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

linkCitedDocumentReference

public String linkCitedDocumentReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 MakeAnchorOptions makeAnchorOptions,
 CitedDocumentLinkProperties relationshipProperties)
                                  throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Attach an element to its external document reference.

Parameters:

userId - userId of the user making the request

elementGUID - unique identifier of the element to connect

externalReferenceGUID - unique identifier of the external reference

makeAnchorOptions - options to control access to open metadata

relationshipProperties - description of the relationship.

Returns:

unique identifier of the new relationship

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateCitedDocumentReference

public void updateCitedDocumentReference(String userId,
 String citedDocumentLinkRelationshipGUID,
 UpdateOptions updateOptions,
 CitedDocumentLinkProperties relationshipProperties)
                                  throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of a cited document link relationship.

Parameters:

userId - userId of the user making the request

citedDocumentLinkRelationshipGUID - unique identifier of the relationship

updateOptions - provides a structure for the additional options when updating a relationship.

relationshipProperties - description of the relationship.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

detachCitedDocumentReference

public void detachCitedDocumentReference(String userId,
 String citedDocumentLinkRelationshipGUID,
 DeleteOptions deleteOptions)
                                  throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Remove a cited document link relationship.

Parameters:

userId - userId of the user making the request.

citedDocumentLinkRelationshipGUID - unique identifier of the relationship

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

deleteExternalReference

public void deleteExternalReference(String userId,
 String externalReferenceGUID,
 DeleteOptions deleteOptions)
                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Delete an external reference.

Parameters:

userId - userId of the user making the request.

externalReferenceGUID - unique identifier of the element

deleteOptions - options for a delete request

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getExternalReferencesByName

public List<OpenMetadataRootElement> getExternalReferencesByName(String userId,
 String name,
 QueryOptions queryOptions)
                                                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of external references with a particular name.

Parameters:

userId - userId of the user making the request

name - name of the element to return - match is full text match in qualifiedName or name

queryOptions - multiple options to control the query

Returns:

a list of elements

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getExternalReferenceByGUID

public OpenMetadataRootElement getExternalReferenceByGUID(String userId,
 String externalReferenceGUID,
 GetOptions getOptions)
                                                   throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Return the properties of a specific external reference.

Parameters:

userId - userId of the user making the request

externalReferenceGUID - unique identifier of the required element

getOptions - multiple options to control the query

Returns:

retrieved properties

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

findExternalReferences

public List<OpenMetadataRootElement> findExternalReferences(String userId,
 String searchString,
 SearchOptions searchOptions)
                                                     throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of external references metadata elements that contain the search string and show which solution components (if any) are attached to it. The returned external references include a list of the components that are associated with it.

Parameters:

userId - calling user

searchString - string to find in the properties

searchOptions - multiple options to control the query

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 - a problem reported in the open metadata server(s)

detachCitedDocumentReference

public void detachCitedDocumentReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 DeleteOptions deleteOptions)
                                  throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Detach an element from its external document reference.

Parameters:

userId - userId of the user making the request.

elementGUID - unique identifier of the element

externalReferenceGUID - unique identifier of the external reference

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request. This is a multi-link relationship, so this request removes every cited document link relationship between the two elements. Use the request that takes the relationship's own unique identifier to remove just one of them.

detachExternalReference

public void detachExternalReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 DeleteOptions deleteOptions)
                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Detach an external reference from an element.

Parameters:

userId - userId of the user making the request.

elementGUID - unique identifier of the first external reference

externalReferenceGUID - unique identifier of the second external reference

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request. This is a multi-link relationship, so this request removes every external reference link relationship between the two elements. Use the request that takes the relationship's own unique identifier to remove just one of them.

detachMediaReference

public void detachMediaReference(String userId,
 String elementGUID,
 String externalReferenceGUID,
 DeleteOptions deleteOptions)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Detach an external media reference from an element.

Parameters:

userId - userId of the user making the request.

elementGUID - unique identifier of the first external reference

externalReferenceGUID - unique identifier of the second external reference

deleteOptions - options to control access to open metadata

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request. This is a multi-link relationship, so this request removes every media reference relationship between the two elements. Use the request that takes the relationship's own unique identifier to remove just one of them.