Class DiscoveryEngineClient

  • All Implemented Interfaces:
    ConnectorFactoryInterface

    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).
    • Constructor Summary

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

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

      • DiscoveryEngineClient

        public DiscoveryEngineClient​(java.lang.String serverName,
                                     java.lang.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​(java.lang.String serverName,
                                     java.lang.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​(java.lang.String serverName,
                                     java.lang.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​(java.lang.String serverName,
                                     java.lang.String serverPlatformURLRoot,
                                     java.lang.String userId,
                                     java.lang.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​(java.lang.String serverName,
                                     java.lang.String serverPlatformURLRoot,
                                     java.lang.String userId,
                                     java.lang.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​(java.lang.String serverName,
                                     java.lang.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

      • getAssetsByQualifiedName

        public java.util.List<java.lang.String> getAssetsByQualifiedName​(java.lang.String userId,
                                                                         java.lang.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 java.util.List<java.lang.String> getAssetsByName​(java.lang.String userId,
                                                                java.lang.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 java.util.List<java.lang.String> findAssets​(java.lang.String userId,
                                                           java.lang.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 java.util.List<java.lang.String> findAssetsByEndpoint​(java.lang.String userId,
                                                                     java.lang.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.
      • logAssetAuditMessage

        public void logAssetAuditMessage​(java.lang.String userId,
                                         java.lang.String assetGUID,
                                         java.lang.String discoveryService,
                                         java.lang.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 java.lang.String createDiscoveryAnalysisReport​(java.lang.String userId,
                                                              java.lang.String qualifiedName,
                                                              java.lang.String displayName,
                                                              java.lang.String description,
                                                              java.util.Date creationDate,
                                                              java.util.Map<java.lang.String,​java.lang.String> analysisParameters,
                                                              java.lang.String analysisStep,
                                                              DiscoveryRequestStatus discoveryRequestStatus,
                                                              java.lang.String assetGUID,
                                                              java.lang.String discoveryEngineGUID,
                                                              java.lang.String discoveryServiceGUID,
                                                              java.util.Map<java.lang.String,​java.lang.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.
      • getDiscoveryReportAnnotations

        public java.util.List<Annotation> getDiscoveryReportAnnotations​(java.lang.String userId,
                                                                        java.lang.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 java.util.List<Annotation> getExtendedAnnotations​(java.lang.String userId,
                                                                 java.lang.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.