org.odpi.openmetadata.accessservices.discoveryengine.server

Class DiscoveryEngineRESTServices

java.lang.Object

org.odpi.openmetadata.accessservices.discoveryengine.server.DiscoveryEngineRESTServices

public class DiscoveryEngineRESTServices
extends Object

The DiscoveryEngineRESTServices provides the server-side implementation of the services used by the discovery engine as it is managing requests to execute open discovery services in the discovery server. These services align with the interface definitions from the Open Discovery Framework (ODF).

Constructor Summary

Constructors

Constructor and Description
DiscoveryEngineRESTServices() Default constructor

Method Summary

Modifier and Type	Method and Description
GUIDResponse	addAnnotationToAnnotation(String serverName, String userId, String parentAnnotationGUID, Annotation requestBody) Add a new annotation and link it to an existing annotation.
GUIDResponse	addAnnotationToDataField(String serverName, String userId, String parentDataFieldGUID, Annotation annotation) Add a new annotation and link it to an existing data field.
GUIDResponse	addAnnotationToDiscoveryReport(String serverName, String userId, String discoveryReportGUID, Annotation requestBody) Add a new annotation to the annotation store as a top level annotation linked directly off of the report.
GUIDResponse	addDataFieldToDataField(String serverName, String userId, String parentDataFieldGUID, DataField dataField) Add a new data field and link it to an existing data field.
GUIDResponse	addDataFieldToDiscoveryReport(String serverName, String userId, String annotationGUID, DataField dataField) Add a new data field to the Annotation store linked off of an annotation (typically SchemaAnalysisAnnotation).
GUIDResponse	createDiscoveryAnalysisReport(String serverName, String userId, String assetGUID, DiscoveryAnalysisReportRequestBody requestBody) Create a new discovery analysis report and chain it to its asset, discovery engine and discovery service.
VoidResponse	deleteAnnotation(String serverName, String userId, String annotationGUID, NullRequestBody requestBody) Remove an annotation from the annotation store.
VoidResponse	deleteDataField(String serverName, String userId, String dataFieldGUID, NullRequestBody requestBody) Remove a data field from the annotation store.
GUIDListResponse	findAssets(String serverName, 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.
GUIDListResponse	findAssetsByEndpoint(String serverName, String userId, String networkAddress, int startFrom, int pageSize) Return the list of assets that have the same endpoint address.
AnnotationResponse	getAnnotation(String serverName, String userId, String annotationGUID) Retrieve a single annotation by unique identifier.
AnnotationListResponse	getAnnotationsForAssetByStatus(String serverName, String userId, String assetGUID, int startingFrom, int maximumResults, StatusRequestBody requestBody) Return the list of annotations from previous runs of the discovery service that are set to a specific status.
GUIDListResponse	getAssets(String serverName, String userId, int startFrom, int pageSize) Return the next set of assets to process.
GUIDListResponse	getAssetsByName(String serverName, 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.
GUIDListResponse	getAssetsByQualifiedName(String serverName, String userId, String name, int startFrom, int pageSize) Return the assets with the same qualified name.
DataFieldResponse	getDataField(String serverName, String userId, String dataFieldGUID) Return a specific data field stored in the annotation store (previous or new).
DiscoveryAnalysisReportResponse	getDiscoveryAnalysisReport(String serverName, String userId, String discoveryReportGUID) Request the discovery report for a discovery request that has completed.
AnnotationListResponse	getDiscoveryReportAnnotations(String serverName, String userId, String discoveryReportGUID, int startingFrom, int maximumResults) Return the annotations linked directly to the report.
AnnotationListResponse	getExtendedAnnotations(String serverName, String userId, String annotationGUID, int startingFrom, int maximumResults) Return any annotations attached to this annotation.
DataFieldListResponse	getNestedDataFields(String serverName, String userId, String parentDataFieldGUID, int startingFrom, int maximumResults) Return any annotations attached to this annotation.
DataFieldListResponse	getNewDataFieldsForAsset(String serverName, String userId, String discoveryReportGUID, int startingFrom, int maximumResults) Return the current list of data fields for this discovery run.
DataFieldListResponse	getPreviousDataFieldsForAsset(String serverName, String userId, String discoveryReportGUID, int startingFrom, int maximumResults) Return the list of data fields from previous runs of the discovery service.
NameListResponse	getTypesOfAnnotation(String serverName, String userId) Return the annotation subtype names.
StringMapResponse	getTypesOfAnnotationWithDescriptions(String serverName, String userId) Return the annotation subtype names mapped to their descriptions.
VoidResponse	logAssetAuditMessage(String serverName, String userId, String assetGUID, String discoveryService, String message) Log an audit message about this asset.
VoidResponse	updateAnnotation(String serverName, String userId, String annotationGUID, Annotation requestBody) Replace the current properties of an annotation.
VoidResponse	updateDataField(String serverName, String userId, String dataFieldGUID, DataField dataField) Replace the current properties of a data field.
VoidResponse	updateDiscoveryAnalysisReport(String serverName, String userId, String discoveryReportGUID, DiscoveryAnalysisReport requestBody) Update the properties of the discovery analysis report.

Methods inherited from class java.lang.Object

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

Constructor Detail

DiscoveryEngineRESTServices

public DiscoveryEngineRESTServices()

Default constructor

Method Detail

getAssets

public GUIDListResponse getAssets(String serverName,
                                  String userId,
                                  int startFrom,
                                  int pageSize)

Return the next set of assets to process.

Parameters:

serverName - name of server instance to route request to

userId - calling user

startFrom - starting point of the query

pageSize - maximum number of results to return

Returns:

list of unique identifiers for located assets or 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.

getAssetsByQualifiedName

public GUIDListResponse getAssetsByQualifiedName(String serverName,
                                                 String userId,
                                                 String name,
                                                 int startFrom,
                                                 int pageSize)

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

Parameters:

serverName - name of server instance to route request to

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

getAssetsByName

public GUIDListResponse getAssetsByName(String serverName,
                                        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. This is an exact match retrieval.

Parameters:

serverName - name of server instance to route request to

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

findAssets

public GUIDListResponse findAssets(String serverName,
                                   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. The search string is interpreted as a regular expression (RegEx).

Parameters:

serverName - name of server instance to route request to

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

findAssetsByEndpoint

public GUIDListResponse findAssetsByEndpoint(String serverName,
                                             String userId,
                                             String networkAddress,
                                             int startFrom,
                                             int pageSize)

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

Parameters:

serverName - name of server instance to route request to

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

logAssetAuditMessage

public VoidResponse logAssetAuditMessage(String serverName,
                                         String userId,
                                         String assetGUID,
                                         String discoveryService,
                                         String message)

Log an audit message about this asset.

Parameters:

serverName - name of server instance to route request to

userId - userId of user making request.

assetGUID - unique identifier for asset.

discoveryService - name of discovery service

message - message to log

Returns:

void or 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.

createDiscoveryAnalysisReport

public GUIDResponse createDiscoveryAnalysisReport(String serverName,
                                                  String userId,
                                                  String assetGUID,
                                                  DiscoveryAnalysisReportRequestBody requestBody)

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

Parameters:

serverName - name of server instance to route request to

userId - calling user

assetGUID - unique identifier of the asset being analysed

requestBody - all of the other parameters

Returns:

The unique identifier of the new discovery report or InvalidParameterException one of the parameters is invalid or UserNotAuthorizedException the user is not authorized to access the asset and/or report or PropertyServerException there was a problem in the store whether the asset/report properties are kept.

updateDiscoveryAnalysisReport

public VoidResponse updateDiscoveryAnalysisReport(String serverName,
                                                  String userId,
                                                  String discoveryReportGUID,
                                                  DiscoveryAnalysisReport requestBody)

Update the properties of the discovery analysis report.

Parameters:

serverName - name of server instance to route request to

userId - calling user

discoveryReportGUID - unique identifier of the report to update

requestBody - updated report - this will replace what was previous stored

Returns:

void or 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 DiscoveryAnalysisReportResponse getDiscoveryAnalysisReport(String serverName,
                                                                  String userId,
                                                                  String discoveryReportGUID)

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

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

discoveryReportGUID - identifier of the discovery request.

Returns:

discovery report or 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.

getTypesOfAnnotation

public NameListResponse getTypesOfAnnotation(String serverName,
                                             String userId)

Return the annotation subtype names.

Parameters:

serverName - name of the server instance to connect to

userId - calling user

Returns:

list of type names that are subtypes of annotation or throws InvalidParameterException full path or userId is null or throws PropertyServerException problem accessing property server or throws UserNotAuthorizedException security access problem.

getTypesOfAnnotationWithDescriptions

public StringMapResponse getTypesOfAnnotationWithDescriptions(String serverName,
                                                              String userId)

Return the annotation subtype names mapped to their descriptions.

Parameters:

serverName - name of the server instance to connect to

userId - calling user

Returns:

list of type names that are subtypes of annotation or throws InvalidParameterException full path or userId is null or throws PropertyServerException problem accessing property server or throws UserNotAuthorizedException security access problem.

getAnnotationsForAssetByStatus

public AnnotationListResponse getAnnotationsForAssetByStatus(String serverName,
                                                             String userId,
                                                             String assetGUID,
                                                             int startingFrom,
                                                             int maximumResults,
                                                             StatusRequestBody requestBody)

Return the list of annotations from previous runs of the discovery service that are set to a specific status. If status is null then annotations that have been reviewed, approved and/or actioned are returned from discovery reports that are not waiting or in progress.

Parameters:

serverName - name of server instance to route request to

userId - calling user

assetGUID - unique identifier of the asset

startingFrom - starting position in the list.

maximumResults - maximum number of elements that can be returned

requestBody - status value to use on the query

Returns:

list of annotation (or null if none are registered) or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem retrieving annotations from the annotation store.

getDiscoveryReportAnnotations

public AnnotationListResponse getDiscoveryReportAnnotations(String serverName,
                                                            String userId,
                                                            String discoveryReportGUID,
                                                            int startingFrom,
                                                            int maximumResults)

Return the annotations linked directly to the report.

Parameters:

serverName - name of server instance to route request to

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 or 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 AnnotationListResponse getExtendedAnnotations(String serverName,
                                                     String userId,
                                                     String annotationGUID,
                                                     int startingFrom,
                                                     int maximumResults)

Return any annotations attached to this annotation.

Parameters:

serverName - name of server instance to route request to

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 or 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 AnnotationResponse getAnnotation(String serverName,
                                        String userId,
                                        String annotationGUID)

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

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

annotationGUID - unique identifier of the annotation

Returns:

Annotation object or 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.

addAnnotationToDiscoveryReport

public GUIDResponse addAnnotationToDiscoveryReport(String serverName,
                                                   String userId,
                                                   String discoveryReportGUID,
                                                   Annotation requestBody)

Add a new annotation to the annotation store as a top level annotation linked directly off of the report.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

discoveryReportGUID - unique identifier of the discovery analysis report

requestBody - annotation object

Returns:

unique identifier of new annotation or InvalidParameterException the annotation is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem retrieving adding the annotation to the annotation store.

addAnnotationToAnnotation

public GUIDResponse addAnnotationToAnnotation(String serverName,
                                              String userId,
                                              String parentAnnotationGUID,
                                              Annotation requestBody)

Add a new annotation and link it to an existing annotation.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

parentAnnotationGUID - unique identifier of the annotation that this new one os to be attached to

requestBody - annotation object

Returns:

unique identifier of new annotation or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem saving annotations in the annotation store.

updateAnnotation

public VoidResponse updateAnnotation(String serverName,
                                     String userId,
                                     String annotationGUID,
                                     Annotation requestBody)

Replace the current properties of an annotation.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

annotationGUID - identifier of the annotation to change

requestBody - new properties

Returns:

fully filled out annotation or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem updating the annotation in the annotation store.

deleteAnnotation

public VoidResponse deleteAnnotation(String serverName,
                                     String userId,
                                     String annotationGUID,
                                     NullRequestBody requestBody)

Remove an annotation from the annotation store.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

annotationGUID - unique identifier of the annotation

requestBody - null request body to satisfy POST semantics

Returns:

void or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem deleting the annotation from the annotation store.

getPreviousDataFieldsForAsset

public DataFieldListResponse getPreviousDataFieldsForAsset(String serverName,
                                                           String userId,
                                                           String discoveryReportGUID,
                                                           int startingFrom,
                                                           int maximumResults)

Return the list of data fields from previous runs of the discovery service.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

discoveryReportGUID - unique identifier of the discovery analysis report

startingFrom - starting position in the list.

maximumResults - maximum number of elements that can be returned

Returns:

list of data fields (or null if none are registered) or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem retrieving data fields from the annotation store.

getNewDataFieldsForAsset

public DataFieldListResponse getNewDataFieldsForAsset(String serverName,
                                                      String userId,
                                                      String discoveryReportGUID,
                                                      int startingFrom,
                                                      int maximumResults)

Return the current list of data fields for this discovery run.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

discoveryReportGUID - unique identifier of the discovery analysis report

startingFrom - starting position in the list.

maximumResults - maximum number of elements that can be returned

Returns:

list of data fields (or null if none are registered) or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem retrieving data fields from the annotation store.

getNestedDataFields

public DataFieldListResponse getNestedDataFields(String serverName,
                                                 String userId,
                                                 String parentDataFieldGUID,
                                                 int startingFrom,
                                                 int maximumResults)

Return any annotations attached to this annotation.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

parentDataFieldGUID - parent data field identifier

startingFrom - starting position in the list

maximumResults - maximum number of annotations that can be returned.

Returns:

list of DataField objects or 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.

getDataField

public DataFieldResponse getDataField(String serverName,
                                      String userId,
                                      String dataFieldGUID)

Return a specific data field stored in the annotation store (previous or new).

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

dataFieldGUID - unique identifier of the data field

Returns:

data field object or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem retrieving the data field from the annotation store.

addDataFieldToDiscoveryReport

public GUIDResponse addDataFieldToDiscoveryReport(String serverName,
                                                  String userId,
                                                  String annotationGUID,
                                                  DataField dataField)

Add a new data field to the Annotation store linked off of an annotation (typically SchemaAnalysisAnnotation).

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

annotationGUID - unique identifier of the annotation that the data field is to be linked to

dataField - dataField object

Returns:

unique identifier of new data field or InvalidParameterException the dataField is invalid or the annotation GUID points to an annotation that can not be associated with a data field. UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem adding the data field to the Annotation store.

addDataFieldToDataField

public GUIDResponse addDataFieldToDataField(String serverName,
                                            String userId,
                                            String parentDataFieldGUID,
                                            DataField dataField)

Add a new data field and link it to an existing data field.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

parentDataFieldGUID - unique identifier of the data field that this new one is to be attached to

dataField - data field object

Returns:

unique identifier of new data field or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem saving data fields in the annotation store.

addAnnotationToDataField

public GUIDResponse addAnnotationToDataField(String serverName,
                                             String userId,
                                             String parentDataFieldGUID,
                                             Annotation annotation)

Add a new annotation and link it to an existing data field.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

parentDataFieldGUID - unique identifier of the data field that this new one is to be attached to

annotation - data field object

Returns:

unique identifier of new annotation or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem saving data fields in the annotation store.

updateDataField

public VoidResponse updateDataField(String serverName,
                                    String userId,
                                    String dataFieldGUID,
                                    DataField dataField)

Replace the current properties of a data field.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

dataFieldGUID - unique identifier of the data field

dataField - new properties

Returns:

fully filled out data field or InvalidParameterException one of the parameters is invalid UserNotAuthorizedException the user id not authorized to issue this request PropertyServerException there was a problem updating the data field in the annotation store.

deleteDataField

public VoidResponse deleteDataField(String serverName,
                                    String userId,
                                    String dataFieldGUID,
                                    NullRequestBody requestBody)

Remove a data field from the annotation store.

Parameters:

serverName - name of server instance to route request to

userId - identifier of calling user

dataFieldGUID - unique identifier of the data field

requestBody - null request body

Returns:

void or InvalidParameterException one of the parameters is invalid or UserNotAuthorizedException the user id not authorized to issue this request or PropertyServerException there was a problem deleting the data field from the annotation store.