Package org.odpi.openmetadata.accessservices.governanceengine.client

Class GovernanceEngineClient

java.lang.Object

org.odpi.openmetadata.commonservices.gaf.client.OpenMetadataStoreClientBase

org.odpi.openmetadata.accessservices.governanceengine.client.GovernanceEngineClient

All Implemented Interfaces:

GovernanceProcessingInterface, SpecialGovernanceActionInterface, org.odpi.openmetadata.commonservices.gaf.api.MetadataElementInterface, org.odpi.openmetadata.commonservices.gaf.api.MultiLanguageInterface, org.odpi.openmetadata.commonservices.gaf.api.StewardshipActionInterface, org.odpi.openmetadata.commonservices.gaf.api.ValidMetadataValuesInterface

public class GovernanceEngineClient
extends OpenMetadataStoreClientBase
implements GovernanceProcessingInterface, SpecialGovernanceActionInterface

GovernanceEngineClient sits in the governance context of a governance action service when it is running in the engine host OMAG server. It is however shared by all the governance action services running in an engine service so that we only need one connector to the topic listener for the watchdog governance services.

Field Summary

Fields inherited from class org.odpi.openmetadata.commonservices.gaf.client.OpenMetadataStoreClientBase

invalidParameterHandler, serverName, serverPlatformURLRoot

Constructor Summary

Constructors

Constructor	Description
GovernanceEngineClient(String serverName, String serverPlatformURLRoot)	Create a new client with no authentication embedded in the HTTP request.
GovernanceEngineClient(String serverName, String serverPlatformURLRoot, String serverUserId, String serverPassword)	Create a new client that passes userId and password in each HTTP request.
GovernanceEngineClient(String serverName, String serverPlatformURLRoot, GovernanceEngineRESTClient restClient, int maxPageSize)	Create a new client that passes userId and password in each HTTP request.

Method Summary

Modifier and Type	Method	Description
void	claimGovernanceAction(String userId, String governanceActionGUID)	Request that execution of a governance action is allocated to the caller.
List<GovernanceActionElement>	findGovernanceActions(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of governance action type metadata elements that contain the search string.
List<GovernanceActionElement>	getActiveClaimedGovernanceActions(String userId, String governanceEngineGUID, int startFrom, int pageSize)	Retrieve the governance actions that are still in process and that have been claimed by this caller's userId.
List<GovernanceActionElement>	getActiveGovernanceActions(String userId, int startFrom, int pageSize)	Retrieve the governance actions that are still in process.
GovernanceActionElement	getGovernanceAction(String userId, String governanceActionGUID)	Request the status of an executing governance action request.
List<GovernanceActionElement>	getGovernanceActions(String userId, int startFrom, int pageSize)	Retrieve the governance actions known to the server.
List<GovernanceActionElement>	getGovernanceActionsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of governance action type metadata elements with a matching qualified or display name.
String	initiateGovernanceAction(String userId, String qualifiedName, int domainIdentifier, String displayName, String description, List<String> requestSourceGUIDs, List<NewActionTarget> actionTargets, List<String> receivedGuards, Date startTime, String governanceEngineName, String requestType, Map<String,String> requestParameters, String processName, String requestSourceName, String originatorServiceName, String originatorEngineName)	Create a governance action in the metadata store which will trigger the governance action service associated with the supplied request type.
String	initiateGovernanceActionProcess(String userId, String processQualifiedName, List<String> requestSourceGUIDs, List<NewActionTarget> actionTargets, Date startTime, Map<String,String> requestParameters, String originatorServiceName, String originatorEngineName)	Using the named governance action process as a template, initiate a chain of governance actions.
void	linkConsolidatedDuplicate(String userId, String consolidatedElementGUID, int statusIdentifier, String steward, String stewardTypeName, String stewardPropertyName, String source, String notes, List<String> sourceElementGUIDs)	Identify an element that acts as a consolidated version for a set of duplicate elements.
void	linkElementsAsPeerDuplicates(String userId, String metadataElement1GUID, String metadataElement2GUID, int statusIdentifier, String steward, String stewardTypeName, String stewardPropertyName, String source, String notes, boolean setKnownDuplicate)	Link elements as peer duplicates.
void	recordCompletionStatus(String userId, String governanceActionGUID, Map<String,String> requestParameters, CompletionStatus status, List<String> outputGuards, List<NewActionTarget> newActionTargets, String completionMessage)	Declare that all the processing for the governance action service is finished and the status of the work.
void	updateActionTargetStatus(String userId, String actionTargetGUID, GovernanceActionStatus status, Date startDate, Date completionDate, String completionMessage)	Update the status of a specific action target.
void	updateGovernanceActionStatus(String userId, String governanceActionGUID, GovernanceActionStatus governanceActionStatus)	Update the status of the governance action - providing the caller is permitted.

Methods inherited from class org.odpi.openmetadata.commonservices.gaf.client.OpenMetadataStoreClientBase

classifyMetadataElementInStore, classifyMetadataElementInStore, clearTranslation, clearValidMetadataValue, createIncidentReport, createMetadataElementInStore, createMetadataElementInStore, createRelatedElementsInStore, createRelatedElementsInStore, deleteMetadataElementInStore, deleteMetadataElementInStore, deleteRelatedElementsInStore, deleteRelatedElementsInStore, findMetadataElements, findMetadataElementsWithString, findRelationshipsBetweenMetadataElements, getMetadataElementByGUID, getMetadataElementByUniqueName, getMetadataElementGUIDByUniqueName, getRelatedMetadataElements, getTranslation, getTranslations, getValidMetadataValue, getValidMetadataValues, openToDo, reclassifyMetadataElementInStore, reclassifyMetadataElementInStore, setTranslation, setUpValidMetadataValue, unclassifyMetadataElementInStore, unclassifyMetadataElementInStore, updateClassificationEffectivityInStore, updateClassificationEffectivityInStore, updateMetadataElementEffectivityInStore, updateMetadataElementEffectivityInStore, updateMetadataElementInStore, updateMetadataElementInStore, updateMetadataElementStatusInStore, updateMetadataElementStatusInStore, updateRelatedElementsEffectivityInStore, updateRelatedElementsEffectivityInStore, updateRelatedElementsInStore, updateRelatedElementsInStore, validateMetadataValue

Methods inherited from class java.lang.Object

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

Constructor Detail

GovernanceEngineClient

public GovernanceEngineClient(String serverName,
                              String serverPlatformURLRoot)
                       throws InvalidParameterException

Create a new client with no authentication embedded in the HTTP request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST servers

Throws:

InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

GovernanceEngineClient

public GovernanceEngineClient(String serverName,
                              String serverPlatformURLRoot,
                              String serverUserId,
                              String serverPassword)
                       throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST servers

serverUserId - caller's userId embedded in all HTTP requests

serverPassword - caller's password embedded in all HTTP requests

Throws:

InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

GovernanceEngineClient

public GovernanceEngineClient(String serverName,
                              String serverPlatformURLRoot,
                              GovernanceEngineRESTClient restClient,
                              int maxPageSize)
                       throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST servers

restClient - pre-initialized REST client

maxPageSize - pre-initialized parameter limit

Throws:

InvalidParameterException - there is a problem with the information about the remote OMAS

Method Detail

updateActionTargetStatus

public void updateActionTargetStatus(String userId,
                                     String actionTargetGUID,
                                     GovernanceActionStatus status,
                                     Date startDate,
                                     Date completionDate,
                                     String completionMessage)
                              throws InvalidParameterException,
                                     UserNotAuthorizedException,
                                     PropertyServerException

Update the status of a specific action target. By default, these values are derived from the values for the governance action service. However, if the governance action service has to process name target elements, then setting the status on each individual target will show the progress of the governance action service.

Specified by:

updateActionTargetStatus in interface GovernanceProcessingInterface

Parameters:

userId - caller's userId

actionTargetGUID - unique identifier of the governance action service.

status - status enum to show its progress

startDate - date/time that the governance action service started processing the target

completionDate - date/time that the governance process completed processing this target.

completionMessage - message to describe completion results or reasons for failure

Throws:

InvalidParameterException - the action target GUID is not recognized

UserNotAuthorizedException - the governance action service is not authorized to update the action target properties

PropertyServerException - there is a problem connecting to the metadata store

updateGovernanceActionStatus

public void updateGovernanceActionStatus(String userId,
                                         String governanceActionGUID,
                                         GovernanceActionStatus governanceActionStatus)
                                  throws InvalidParameterException,
                                         UserNotAuthorizedException,
                                         PropertyServerException

Update the status of the governance action - providing the caller is permitted.

Specified by:

updateGovernanceActionStatus in interface GovernanceProcessingInterface

Parameters:

userId - identifier of calling user

governanceActionGUID - identifier of the governance action request

governanceActionStatus - new status enum

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

recordCompletionStatus

public void recordCompletionStatus(String userId,
                                   String governanceActionGUID,
                                   Map<String,String> requestParameters,
                                   CompletionStatus status,
                                   List<String> outputGuards,
                                   List<NewActionTarget> newActionTargets,
                                   String completionMessage)
                            throws InvalidParameterException,
                                   UserNotAuthorizedException,
                                   PropertyServerException

Declare that all the processing for the governance action service is finished and the status of the work.

Specified by:

recordCompletionStatus in interface GovernanceProcessingInterface

Parameters:

userId - caller's userId

governanceActionGUID - unique identifier of the governance action to update

requestParameters - request properties from the caller (will be passed onto any follow-on actions)

status - completion status enum value

outputGuards - optional guard strings for triggering subsequent action(s)

newActionTargets - list of action target names to GUIDs for the resulting governance action service

completionMessage - message to describe completion results or reasons for failure

Throws:

InvalidParameterException - the completion status is null

UserNotAuthorizedException - the governance action service is not authorized to update the governance action service status

PropertyServerException - there is a problem connecting to the metadata store

initiateGovernanceAction

public String initiateGovernanceAction(String userId,
                                       String qualifiedName,
                                       int domainIdentifier,
                                       String displayName,
                                       String description,
                                       List<String> requestSourceGUIDs,
                                       List<NewActionTarget> actionTargets,
                                       List<String> receivedGuards,
                                       Date startTime,
                                       String governanceEngineName,
                                       String requestType,
                                       Map<String,String> requestParameters,
                                       String processName,
                                       String requestSourceName,
                                       String originatorServiceName,
                                       String originatorEngineName)
                                throws InvalidParameterException,
                                       UserNotAuthorizedException,
                                       PropertyServerException

Create a governance action in the metadata store which will trigger the governance action service associated with the supplied request type. The governance action remains to act as a record of the actions taken for auditing.

Specified by:

initiateGovernanceAction in interface GovernanceProcessingInterface

Parameters:

userId - caller's userId

qualifiedName - unique identifier to give this governance action

domainIdentifier - governance domain associated with this action (0=ALL)

displayName - display name for this action

description - description for this action

requestSourceGUIDs - request source elements for the resulting governance action service

actionTargets - list of action target names to GUIDs for the resulting governance action service

receivedGuards - list of guards to initiate the governance action

startTime - future start time or null for "as soon as possible"

governanceEngineName - name of the governance engine that should execute the request

requestType - governance request type from the caller

requestParameters - properties to pass to the governance action service

processName - name of the process that this action is a part of

requestSourceName - source of the request

originatorServiceName - unique name of the requesting governance service (if initiated by a governance engine).

originatorEngineName - optional unique name of the requesting governance engine (if initiated by a governance engine).

Returns:

unique identifier of the governance action

Throws:

InvalidParameterException - null qualified name

UserNotAuthorizedException - this governance action service is not authorized to create a governance action

PropertyServerException - there is a problem with the metadata store

initiateGovernanceActionProcess

public String initiateGovernanceActionProcess(String userId,
                                              String processQualifiedName,
                                              List<String> requestSourceGUIDs,
                                              List<NewActionTarget> actionTargets,
                                              Date startTime,
                                              Map<String,String> requestParameters,
                                              String originatorServiceName,
                                              String originatorEngineName)
                                       throws InvalidParameterException,
                                              UserNotAuthorizedException,
                                              PropertyServerException

Using the named governance action process as a template, initiate a chain of governance actions.

Specified by:

initiateGovernanceActionProcess in interface GovernanceProcessingInterface

Parameters:

userId - caller's userId

processQualifiedName - unique name of the governance action process to use

requestSourceGUIDs - request source elements for the resulting governance action service

actionTargets - list of action target names to GUIDs for the resulting governance action service

startTime - future start time or null for "as soon as possible".

requestParameters - request properties to be passed to the first governance action

originatorServiceName - unique name of the requesting governance service (if initiated by a governance engine).

originatorEngineName - optional unique name of the governance engine (if initiated by a governance engine).

Returns:

unique identifier of the first governance action of the process

Throws:

InvalidParameterException - null or unrecognized qualified name of the process

UserNotAuthorizedException - this governance action service is not authorized to create a governance action process

PropertyServerException - there is a problem with the metadata store

getGovernanceAction

public GovernanceActionElement getGovernanceAction(String userId,
                                                   String governanceActionGUID)
                                            throws InvalidParameterException,
                                                   UserNotAuthorizedException,
                                                   PropertyServerException

Request the status of an executing governance action request.

Specified by:

getGovernanceAction in interface GovernanceProcessingInterface

Parameters:

userId - identifier of calling user

governanceActionGUID - identifier of the governance action request.

Returns:

status enum

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

claimGovernanceAction

public void claimGovernanceAction(String userId,
                                  String governanceActionGUID)
                           throws InvalidParameterException,
                                  UserNotAuthorizedException,
                                  PropertyServerException

Request that execution of a governance action is allocated to the caller.

Specified by:

claimGovernanceAction in interface GovernanceProcessingInterface

Parameters:

userId - identifier of calling user

governanceActionGUID - identifier of the governance action request.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

getGovernanceActions

public List<GovernanceActionElement> getGovernanceActions(String userId,
                                                          int startFrom,
                                                          int pageSize)
                                                   throws InvalidParameterException,
                                                          UserNotAuthorizedException,
                                                          PropertyServerException

Retrieve the governance actions known to the server.

Specified by:

getGovernanceActions in interface GovernanceProcessingInterface

Parameters:

userId - userId of caller

startFrom - starting from element

pageSize - maximum elements to return

Returns:

list of governance action elements

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

getActiveGovernanceActions

public List<GovernanceActionElement> getActiveGovernanceActions(String userId,
                                                                int startFrom,
                                                                int pageSize)
                                                         throws InvalidParameterException,
                                                                UserNotAuthorizedException,
                                                                PropertyServerException

Retrieve the governance actions that are still in process.

Specified by:

getActiveGovernanceActions in interface GovernanceProcessingInterface

Parameters:

userId - userId of caller

startFrom - starting from element

pageSize - maximum elements to return

Returns:

list of governance action elements

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

getActiveClaimedGovernanceActions

public List<GovernanceActionElement> getActiveClaimedGovernanceActions(String userId,
                                                                       String governanceEngineGUID,
                                                                       int startFrom,
                                                                       int pageSize)
                                                                throws InvalidParameterException,
                                                                       UserNotAuthorizedException,
                                                                       PropertyServerException

Retrieve the governance actions that are still in process and that have been claimed by this caller's userId. This call is used when the caller restarts.

Specified by:

getActiveClaimedGovernanceActions in interface GovernanceProcessingInterface

Parameters:

userId - userId of caller

governanceEngineGUID - unique identifier of governance engine

startFrom - starting from element

pageSize - maximum elements to return

Returns:

list of governance action elements

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem detected by the metadata store.

findGovernanceActions

public List<GovernanceActionElement> findGovernanceActions(String userId,
                                                           String searchString,
                                                           int startFrom,
                                                           int pageSize)
                                                    throws InvalidParameterException,
                                                           UserNotAuthorizedException,
                                                           PropertyServerException

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

Specified by:

findGovernanceActions in interface GovernanceProcessingInterface

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

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

getGovernanceActionsByName

public List<GovernanceActionElement> getGovernanceActionsByName(String userId,
                                                                String name,
                                                                int startFrom,
                                                                int pageSize)
                                                         throws InvalidParameterException,
                                                                UserNotAuthorizedException,
                                                                PropertyServerException

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

Specified by:

getGovernanceActionsByName in interface GovernanceProcessingInterface

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

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

linkElementsAsPeerDuplicates

public void linkElementsAsPeerDuplicates(String userId,
                                         String metadataElement1GUID,
                                         String metadataElement2GUID,
                                         int statusIdentifier,
                                         String steward,
                                         String stewardTypeName,
                                         String stewardPropertyName,
                                         String source,
                                         String notes,
                                         boolean setKnownDuplicate)
                                  throws InvalidParameterException,
                                         UserNotAuthorizedException,
                                         PropertyServerException

Link elements as peer duplicates. Create a simple relationship between two elements. If the relationship already exists, the properties are updated.

Specified by:

linkElementsAsPeerDuplicates in interface SpecialGovernanceActionInterface

Parameters:

userId - caller's userId

metadataElement1GUID - unique identifier of the metadata element at end 1 of the relationship

metadataElement2GUID - unique identifier of the metadata element at end 2 of the relationship

statusIdentifier - what is the status of this relationship (negative means untrusted, 0 means unverified and positive means trusted)

steward - identifier of the steward

stewardTypeName - type of element used to identify the steward

stewardPropertyName - property name used to identify steward

source - source of the duplicate detection processing

notes - notes for the steward

setKnownDuplicate - boolean flag indicating whether the KnownDuplicate classification should be set on the linked entities.

Throws:

InvalidParameterException - the unique identifier's of the metadata elements are null or invalid in some way; the properties are not valid for this type of relationship

UserNotAuthorizedException - the governance action service is not authorized to create this type of relationship

PropertyServerException - there is a problem with the metadata store

linkConsolidatedDuplicate

public void linkConsolidatedDuplicate(String userId,
                                      String consolidatedElementGUID,
                                      int statusIdentifier,
                                      String steward,
                                      String stewardTypeName,
                                      String stewardPropertyName,
                                      String source,
                                      String notes,
                                      List<String> sourceElementGUIDs)
                               throws InvalidParameterException,
                                      UserNotAuthorizedException,
                                      PropertyServerException

Identify an element that acts as a consolidated version for a set of duplicate elements. (The consolidated element is created using createMetadataElement.)

Specified by:

linkConsolidatedDuplicate in interface SpecialGovernanceActionInterface

Parameters:

userId - caller's userId

consolidatedElementGUID - unique identifier of the metadata element

statusIdentifier - what is the status of this relationship (negative means untrusted, 0 means unverified and positive means trusted)

steward - identifier of the steward

stewardTypeName - type of element used to identify the steward

stewardPropertyName - property name used to identify steward

source - source of the duplicate detection processing

notes - notes for the steward

sourceElementGUIDs - List of the source elements that must be linked to the consolidated element. It is assumed that they already have the KnownDuplicateClassification.

Throws:

InvalidParameterException - the unique identifier's of the metadata elements are null or invalid in some way; the properties are not valid for this type of relationship

UserNotAuthorizedException - the governance action service is not authorized to create this type of relationship

PropertyServerException - there is a problem with the metadata store