Package org.odpi.openmetadata.accessservices.discoveryengine.client

Class DiscoveryEngineClient

java.lang.Object

org.odpi.openmetadata.commonservices.ocf.metadatamanagement.client.ConnectedAssetClientBase

org.odpi.openmetadata.accessservices.discoveryengine.client.DiscoveryEngineClient

public class DiscoveryEngineClient
extends ConnectedAssetClientBase

DiscoveryEngineClient provides the client-side operational REST APIs for a running Discovery Engine. The discovery engine embeds this client in each of the special store clients defined by the Open Discovery Framework (ODF).

Field Summary

Fields inherited from class org.odpi.openmetadata.commonservices.ocf.metadatamanagement.client.ConnectedAssetClientBase

auditLog, invalidParameterHandler, nullRequestBody, serverName, serverPlatformURLRoot

Constructor Summary

Constructors

Constructor	Description
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot)	Create a new client with no authentication embedded in the HTTP request.
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot, String userId, String password)	Create a new client that passes userId and password in each HTTP request.
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot, String userId, String password, AuditLog auditLog)	Create a new client that passes userId and password in each HTTP request.
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot, ODFRESTClient restClient, int maxPageSize, AuditLog auditLog)	Create a new client that is to be used within an OMAG Server.
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot, ODFRESTClient restClient, AuditLog auditLog)	Create a client-side object for calling a discovery engine within a discovery server.
DiscoveryEngineClient(String serverName, String serverPlatformURLRoot, AuditLog auditLog)	Create a new client with no authentication embedded in the HTTP request.

Method Summary

Modifier and Type	Method	Description
String	createDiscoveryAnalysisReport(String userId, String qualifiedName, String displayName, String description, Date creationDate, Map<String,String> analysisParameters, String analysisStep, DiscoveryRequestStatus discoveryRequestStatus, String assetGUID, String discoveryEngineGUID, String discoveryServiceGUID, Map<String,String> additionalProperties)	Create a new discovery analysis report and chain it to its asset, discovery engine and discovery service.
List<String>	findAssets(String userId, String searchString, int startFrom, int pageSize)	Return a list of assets with the requested search string in their name, qualified name or description.
List<String>	findAssetsByEndpoint(String userId, String networkAddress, int startFrom, int pageSize)	Return the list of assets that have the same endpoint address.
Annotation	getAnnotation(String userId, String annotationGUID)	Retrieve a single annotation by unique identifier.
List<String>	getAssets(String userId, int startFrom, int pageSize)	Return the next set of assets to process.
List<String>	getAssetsByName(String userId, String name, int startFrom, int pageSize)	Return the list of matching assets that have the supplied name as either the qualified name or display name.
List<String>	getAssetsByQualifiedName(String userId, String name, int startFrom, int pageSize)	Return the assets with the same qualified name.
Connector	getConnectorForConnection(String userId, Connection connection)	Returns the connector corresponding to the supplied connection.
DiscoveryAnalysisReport	getDiscoveryAnalysisReport(String userId, String discoveryReportGUID)	Request the discovery report for a discovery request that has completed.
List<Annotation>	getDiscoveryReportAnnotations(String userId, String discoveryReportGUID, int startingFrom, int maximumResults)	Return the annotations linked directly to the report.
DiscoveryRequestStatus	getDiscoveryStatus(String userId, String discoveryReportGUID)	Request the status of an executing discovery request.
List<Annotation>	getExtendedAnnotations(String userId, String annotationGUID, int startingFrom, int maximumResults)	Return any annotations attached to this annotation.
void	logAssetAuditMessage(String userId, String assetGUID, String discoveryService, String message)	Log an audit message about this asset.
void	setDiscoveryStatus(String userId, String discoveryReportGUID, DiscoveryRequestStatus newStatus)	Request the status of an executing discovery request.
void	updateDiscoveryAnalysisReport(String userId, DiscoveryAnalysisReport updatedReport)	Update the properties of the discovery analysis report.

Methods inherited from class org.odpi.openmetadata.commonservices.ocf.metadatamanagement.client.ConnectedAssetClientBase

getAssetForConnection, getAssetProperties, getAssetSummary, getConnectionByGUID, getConnectionByName, getConnectionForAsset, getConnectorForConnection

Methods inherited from class java.lang.Object

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

Constructor Detail

DiscoveryEngineClient

public DiscoveryEngineClient(String serverName,
                             String serverPlatformURLRoot,
                             ODFRESTClient restClient,
                             AuditLog auditLog)
                      throws InvalidParameterException

Create a client-side object for calling a discovery engine within a discovery server.

Parameters:

serverPlatformURLRoot - the root url of the platform where the discovery engine is running.

serverName - the name of the discovery server where the discovery engine is running

restClient - pre-built client

auditLog - logging destination

Throws:

InvalidParameterException - one of the parameters is null or invalid.

DiscoveryEngineClient

public DiscoveryEngineClient(String serverName,
                             String serverPlatformURLRoot,
                             AuditLog auditLog)
                      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

auditLog - logging destination

Throws:

InvalidParameterException - null URL or server name

DiscoveryEngineClient

public DiscoveryEngineClient(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 - null URL or server name

DiscoveryEngineClient

public DiscoveryEngineClient(String serverName,
                             String serverPlatformURLRoot,
                             String userId,
                             String password,
                             AuditLog auditLog)
                      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

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

auditLog - logging destination

Throws:

InvalidParameterException - null URL or server name

DiscoveryEngineClient

public DiscoveryEngineClient(String serverName,
                             String serverPlatformURLRoot,
                             String userId,
                             String password)
                      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

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

Throws:

InvalidParameterException - null URL or server name

DiscoveryEngineClient

public DiscoveryEngineClient(String serverName,
                             String serverPlatformURLRoot,
                             ODFRESTClient restClient,
                             int maxPageSize,
                             AuditLog auditLog)
                      throws InvalidParameterException

Create a new client that is to be used within an OMAG Server.

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

auditLog - logging destination

Throws:

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

Method Detail

getAssets

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

Return the next set of assets to process.

Parameters:

userId - calling user

startFrom - starting point of the query

pageSize - maximum number of results to return

Returns:

list of unique identifiers for located assets

Throws:

InvalidParameterException - one of the parameters is not recognized

UserNotAuthorizedException - the user is not authorized to access the asset and/or connection

PropertyServerException - there was a problem in the store whether the asset/connection properties are kept.

getAssetsByQualifiedName

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

Return the assets with the same qualified name. If all is well there should be only one returned.

Parameters:

userId - calling user

name - the qualified name to query on

startFrom - place to start in query

pageSize - number of results to return

Returns:

list of unique identifiers for matching assets

Throws:

InvalidParameterException - one of the parameters is not recognized

UserNotAuthorizedException - the user is not authorized to access the asset and/or connection

PropertyServerException - there was a problem in the store whether the asset/connection properties are kept.

getAssetsByName

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

Return the list of matching assets that have the supplied name as either the qualified name or display name. This is an exact match retrieval.

Parameters:

userId - calling user

name - name to query for

startFrom - place to start in query

pageSize - number of results to return

Returns:

list of unique identifiers for matching assets

Throws:

InvalidParameterException - one of the parameters is not recognized

UserNotAuthorizedException - the user is not authorized to access the asset and/or connection

PropertyServerException - there was a problem in the store whether the asset/connection properties are kept.

findAssets

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

Return a list of assets with the requested search string in their name, qualified name or description. The search string is interpreted as a regular expression (RegEx).

Parameters:

userId - calling user

searchString - string to search for in text

startFrom - starting element (used in paging through large result sets)

pageSize - maximum number of results to return

Returns:

list of assets that match the search string.

Throws:

InvalidParameterException - the searchString is invalid

PropertyServerException - there is a problem access in the property server

UserNotAuthorizedException - the user does not have access to the properties

findAssetsByEndpoint

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

Return the list of assets that have the same endpoint address.

Parameters:

userId - calling user

networkAddress - address to query on

startFrom - place to start in query

pageSize - number of results to return

Returns:

list of unique identifiers for matching assets

Throws:

InvalidParameterException - one of the parameters is not recognized

UserNotAuthorizedException - the user is not authorized to access the asset and/or connection

PropertyServerException - there was a problem in the store whether the asset/connection properties are kept.

getConnectorForConnection

public Connector getConnectorForConnection(String userId,
                                           Connection connection)
                                    throws InvalidParameterException,
                                           ConnectionCheckedException,
                                           ConnectorCheckedException

Returns the connector corresponding to the supplied connection.

Parameters:

userId - userId of user making request.

connection - the connection object that contains the properties needed to create the connection.

Returns:

Connector connector instance

Throws:

InvalidParameterException - one of the parameters is null or invalid.

ConnectionCheckedException - there are errors in the configuration of the connection which is preventing the creation of a connector.

ConnectorCheckedException - there are errors in the initialization of the connector.

logAssetAuditMessage

public void logAssetAuditMessage(String userId,
                                 String assetGUID,
                                 String discoveryService,
                                 String message)
                          throws InvalidParameterException,
                                 PropertyServerException,
                                 UserNotAuthorizedException

Log an audit message about this asset.

Parameters:

userId - userId of user making request.

assetGUID - unique identifier for asset.

discoveryService - unique name for discoveryService.

message - message to log

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving the asset properties from the property servers).

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

createDiscoveryAnalysisReport

public String createDiscoveryAnalysisReport(String userId,
                                            String qualifiedName,
                                            String displayName,
                                            String description,
                                            Date creationDate,
                                            Map<String,String> analysisParameters,
                                            String analysisStep,
                                            DiscoveryRequestStatus discoveryRequestStatus,
                                            String assetGUID,
                                            String discoveryEngineGUID,
                                            String discoveryServiceGUID,
                                            Map<String,String> additionalProperties)
                                     throws InvalidParameterException,
                                            UserNotAuthorizedException,
                                            PropertyServerException

Create a new discovery analysis report and chain it to its asset, discovery engine and discovery service.

Parameters:

userId - calling user

qualifiedName - unique name for the report

displayName - short name for the report

description - description of the report

creationDate - date of the report

analysisParameters - analysis parameters passed to the discovery service

analysisStep - name of the first analysis step

discoveryRequestStatus - current status of the discovery processing

assetGUID - unique identifier of the asset being analysed

discoveryEngineGUID - unique identifier of the discovery engine that is running the discovery service

discoveryServiceGUID - unique identifier of the discovery service creating the report

additionalProperties - additional properties for the report

Returns:

unique identifier of new discovery report.

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to access the asset and/or report

PropertyServerException - there was a problem in the store whether the asset/report properties are kept.

updateDiscoveryAnalysisReport

public void updateDiscoveryAnalysisReport(String userId,
                                          DiscoveryAnalysisReport updatedReport)
                                   throws InvalidParameterException,
                                          UserNotAuthorizedException,
                                          PropertyServerException

Update the properties of the discovery analysis report.

Parameters:

userId - calling user.

updatedReport - updated report - this will replace what was previous stored.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem that occurred within the property server.

getDiscoveryStatus

public DiscoveryRequestStatus getDiscoveryStatus(String userId,
                                                 String discoveryReportGUID)
                                          throws InvalidParameterException,
                                                 UserNotAuthorizedException,
                                                 PropertyServerException

Request the status of an executing discovery request.

Parameters:

userId - identifier of calling user

discoveryReportGUID - identifier of the discovery 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 that occurred within the property server.

setDiscoveryStatus

public void setDiscoveryStatus(String userId,
                               String discoveryReportGUID,
                               DiscoveryRequestStatus newStatus)
                        throws InvalidParameterException,
                               UserNotAuthorizedException,
                               PropertyServerException

Request the status of an executing discovery request.

Parameters:

userId - identifier of calling user

discoveryReportGUID - identifier of the discovery request.

newStatus - 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 that occurred within the property server.

getDiscoveryAnalysisReport

public DiscoveryAnalysisReport getDiscoveryAnalysisReport(String userId,
                                                          String discoveryReportGUID)
                                                   throws InvalidParameterException,
                                                          UserNotAuthorizedException,
                                                          PropertyServerException

Request the discovery report for a discovery request that has completed.

Parameters:

userId - identifier of calling user

discoveryReportGUID - identifier of the discovery report.

Returns:

discovery report

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem that occurred within the property server.

getDiscoveryReportAnnotations

public List<Annotation> getDiscoveryReportAnnotations(String userId,
                                                      String discoveryReportGUID,
                                                      int startingFrom,
                                                      int maximumResults)
                                               throws InvalidParameterException,
                                                      UserNotAuthorizedException,
                                                      PropertyServerException

Return the annotations linked directly to the report.

Parameters:

userId - identifier of calling user

discoveryReportGUID - identifier of the discovery request.

startingFrom - initial position in the stored list.

maximumResults - maximum number of definitions to return on this call.

Returns:

list of annotations

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem that occurred within the property server.

getExtendedAnnotations

public List<Annotation> getExtendedAnnotations(String userId,
                                               String annotationGUID,
                                               int startingFrom,
                                               int maximumResults)
                                        throws InvalidParameterException,
                                               UserNotAuthorizedException,
                                               PropertyServerException

Return any annotations attached to this annotation.

Parameters:

userId - identifier of calling user

annotationGUID - parent annotation

startingFrom - starting position in the list

maximumResults - maximum number of annotations that can be returned.

Returns:

list of Annotation objects

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem that occurred within the property server.

getAnnotation

public Annotation getAnnotation(String userId,
                                String annotationGUID)
                         throws InvalidParameterException,
                                UserNotAuthorizedException,
                                PropertyServerException

Retrieve a single annotation by unique identifier. This call is typically used to retrieve the latest values for an annotation.

Parameters:

userId - identifier of calling user

annotationGUID - unique identifier of the annotation

Returns:

Annotation object

Throws:

InvalidParameterException - one of the parameters is null or invalid.

UserNotAuthorizedException - user not authorized to issue this request.

PropertyServerException - there was a problem that occurred within the property server.