org.apache.uima.aae.client

## Interface UimaAsynchronousEngine

- All Known Implementing Classes:
    BaseUIMAAsynchronousEngine_impl, org.apache.uima.adapter.jms.client.BaseUIMAAsynchronousEngineCommon_impl

      public interface UimaAsynchronousEngine

  A `UimaAsynchronousEngine` enables an application to send CASes for analysis to remote UIMA AS service. It provides a high level API and hides the detail of the transport implementation. The UIMA AS Client implementation uses JMS as its transport mechanism. Both synchronous and asynchronous processing is supported. For synchronous processing an application should call `sendAndReceiveCAS(CAS)` method. For asynchronous processing the application should call `sendCAS(CAS)` method. Additionally, processing with a client side `CollectionReader` is supported as well. The application first instantiates and initializes the `CollectionReader` and registers it via `setCollectionReader(CollectionReader)` method. Once the `CollectionReader` is registered, and `initialize(Map)` method is called, the application may call `process()` method. This API enables the application to dynamically deploy UIMA AS services that it intends to use for processing. These services are deployed in a container and are collocated in the same JVM as the application. The services are considered private and used exclusively by the application. To deploy "private" services the application calls either `deploy(String, Map)` `deploy(String[], Map)` method, where the first parameter is either a single AS deployment descriptor or an array thereof. The application must deploy its "private" services *before* calling `initialize(Map)` method. The application may stop the UIMA AS client in the middle of processing by calling `stop()` method. Listeners can register with the `UimaAsynchronousEngine` by calling the `addStatusCallbackListener(UimaAsBaseCallbackListener)` method. These listeners receive status callbacks during the processing. An exception to that is the synchronous processing via `sendAndReceiveCAS(CAS)` method. This method returns either a CAS containing results of analysis or an exception. No callbacks are made while processing CASes synchronously. An application may choose to implement parallelization of the processing, calling either `sendAndReceiveCAS(CAS)` or `sendCAS(CAS)` methods from multiple threads.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ApplicationContext` Deprecated.
    `static String` | `ApplicationName` Name of an application that uses Uima AS client.
    `static String` | `CasPoolSize` Size of Cas pool to create.
    `static String` | `CpcTimeout` Collection Processing Complete timeout.
    `static String` | `DD2SpringXsltFilePath` Path to the XSLT processor to use when processing a deployment descriptor.
    `static String` | `Endpoint` Deprecated. use ENDPOINT instead
    `static String` | `ENDPOINT` Name of a queue where the Uima AS client sends JMS requests.
    `static String` | `GetMetaTimeout` GetMeta timeout.
    `static String` | `password` The password for Message queuing connection if needed
    `static String` | `ReplyWindow` Deprecated.
    `static String` | `SaxonClasspath` Saxon classpath to use when processing a deployment descriptor.
    `static String` | `SERIALIZATION_STRATEGY` Type of serialization to use when serializing CASes to remote Uima AS service.
    `static String` | `SerializationStrategy` Deprecated.
    `static String` | `ServerUri` Broker URL the Uima AS client will use to communicate with Uima AS service.
    `static String` | `ShadowCasPoolSize` Deprecated.
    `static String` | `SharedConnection` Deprecated.
    `static String` | `TargetSelectorProperty`
    `static String` | `Timeout` CAS process timeout.
    `static String` | `TimerPerCAS` Flag to indicate whether or not the uima-as client should use timer per CAS.
    `static String` | `UimaEeDebug` Debug flag to use when processing a deployment descriptor.
    `static String` | `userName` The userName for Message queuing connection if needed

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addStatusCallbackListener(UimaAsBaseCallbackListener aListener)` Registers application specific listener.
    `void` | `collectionProcessingComplete()` Sends a Collection Processing Complete (CPC) request to a UIMA AS Service and blocks waiting for a reply.
    `String` | `deploy(String[] aDeploymentDescriptorList, Map anApplicationContext)` Deploys a single UIMA AS container and all services defined in provided deployment descriptors.
    `String` | `deploy(String aDeploymentDescriptor, Map anApplicationContext)` Deploys a UIMA AS container and all services defined in the provided deployment descriptor.
    `CAS` | `getCAS()` Requests new CAS instance from a CAS pool.
    `ProcessingResourceMetaData` | `getMetaData()` Returns a `ProcessingResourceMetadata` received from the UIMA AS Service.
    `String` | `getPerformanceReport()` Not implemented
    `SerialFormat` | `getSerialFormat()` Returns serialization strategy for the remote service.
    `void` | `initialize(Map anApplicationContext)` Initializes UIMA asynchronous client using configuration parameters provided in a Map object.
    `void` | `process()` Initiates processing of a collection.
    `void` | `removeStatusCallbackListener(UimaAsBaseCallbackListener aListener)` Unregisters named application listener.
    `String` | `sendAndReceiveCAS(CAS aCAS)` This synchronous method sends a given CAS to a UIMA AS service and waits for response.
    `String` | `sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList)` This synchronous method sends a given CAS to a UIMA AS service and waits for response.
    `String` | `sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList, String targetServiceId)` This synchronous method sends a given CAS to a UIMA AS service and waits for response.
    `String` | `sendCAS(CAS aCAS)` Sends a given CAS for analysis to UIMA AS Service.
    `String` | `sendCAS(CAS aCAS, String targetServiceId)` Sends a given CAS for analysis to a specific instance of UIMA AS Service.
    `void` | `setCollectionReader(CollectionReader aCollectionReader)` Registers a `CollectionReader` instance to process a Collection.
    `void` | `stop()` Stops the asynchronous client.
    `void` | `stopProducingCases()` Request Uima AS client to initiate sending Stop requests to a service for all outstanding CASes awaiting reply.
    `void` | `stopProducingCases(String aCasReferenceId)` Request Uima AS client to initiate sending Stop request to a service for a given CAS id If the service is a Cas Multiplier, it will stop producing new CASes, will wait until all child CASes finish and finally returns the input CAS.
    `void` | `undeploy(String aSpringContainerId)` Undeploys specified UIMA AS container and all services running within it.
    `void` | `undeploy(String aSpringContainerId, int stop_level)` Undeploys specified UIMA AS container and all services running within it.

- - ### Field Detail

    - #### ApplicationContext

          static final String ApplicationContext

      Deprecated.
      See Also:
        Constant Field Values

    - #### ApplicationName

          static final String ApplicationName

      Name of an application that uses Uima AS client. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)` .This name is used to register Uima AS client MBean with JMX. To make the name unique, provided string is prepended to a UUID to form ApplicationName_www_xxxx_yyyy_zzzz
      See Also:
        Constant Field Values

    - #### ServerUri

          static final String ServerUri

      Broker URL the Uima AS client will use to communicate with Uima AS service. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Required. If omitted, the Uima AS client throws `ResourceInitializationException`
      See Also:
        Constant Field Values

    - #### ENDPOINT

          static final String ENDPOINT

      Name of a queue where the Uima AS client sends JMS requests. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Required. If omitted, the Uima AS client throws `ResourceInitializationException`
      See Also:
        Constant Field Values

    - #### Endpoint

          static final String Endpoint

      Deprecated. use ENDPOINT instead
      See Also:
        Constant Field Values

    - #### CasPoolSize

          static final String CasPoolSize

      Size of Cas pool to create. This parameter determines how many CASes can be processed concurrently. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Optional. If omitted, the Uima AS client will use 1 as a default.
      See Also:
        Constant Field Values

    - #### ShadowCasPoolSize

          static final String ShadowCasPoolSize

      Deprecated.
      See Also:
        Constant Field Values

    - #### ReplyWindow

          static final String ReplyWindow

      Deprecated.
      See Also:
        Constant Field Values

    - #### Timeout

          static final String Timeout

      CAS process timeout. The max amount of time allowed to process a CAS. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Optional. If omitted, the Uima AS client defaults to no timeout.
      See Also:
        Constant Field Values

    - #### CpcTimeout

          static final String CpcTimeout

      Collection Processing Complete timeout. The max amount of time allowed to process CPC request.The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Optional. If omitted, the Uima AS client defaults to no timeout.
      See Also:
        Constant Field Values

    - #### GetMetaTimeout

          static final String GetMetaTimeout

      GetMeta timeout. The max amount of time allowed to process GetMeta request.The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`. Optional. If omitted, the Uima AS client defaults to 60 seconds.
      See Also:
        Constant Field Values

    - #### DD2SpringXsltFilePath

          static final String DD2SpringXsltFilePath

      Path to the XSLT processor to use when processing a deployment descriptor. The application provides it to the Uima AS client via System property, either on a command line using -D, or explicitly by using java's System.setProperty(DD2SpringXsltFilePath,value). This path is required only if the Uima AS Client is used to deploy Uima AS service.
      See Also:
        Constant Field Values

    - #### SaxonClasspath

          static final String SaxonClasspath

      Saxon classpath to use when processing a deployment descriptor. The application provides it to the Uima AS client via System property, either on a command line using -D, or explicitly by using java's System.setProperty(SaxonClasspath,value). This path is required only if the Uima AS Client is used to deploy Uima AS service.
      See Also:
        Constant Field Values

    - #### UimaEeDebug

          static final String UimaEeDebug

      Debug flag to use when processing a deployment descriptor. If set, the dd2spring processor will not remove generated spring configuration file on client exit. The application provides it to the Uima AS client via System property, either on a command line using -D, or explicitly by using java's System.setProperty(UimaEeDebug,value). This setting is only relevant if the Uima AS Client is used to deploy Uima AS service.
      See Also:
        Constant Field Values

    - #### SERIALIZATION_STRATEGY

          static final String SERIALIZATION_STRATEGY

      Type of serialization to use when serializing CASes to remote Uima AS service. Valid serialization types are the string "xmi" (any case) or other (taken to be binary). If this setting is omitted, the Uima AS client uses XMI as a default. The application provides it to the Uima AS client in a Map which is an argument in `initialize(Map)`
      See Also:
        Constant Field Values

    - #### SerializationStrategy

          static final String SerializationStrategy

      Deprecated.
      See Also:
        Constant Field Values

    - #### userName

          static final String userName

      The userName for Message queuing connection if needed

    - #### password

          static final String password

      The password for Message queuing connection if needed

    - #### SharedConnection

          static final String SharedConnection

      Deprecated.
      See Also:
        Constant Field Values

    - #### TimerPerCAS

          static final String TimerPerCAS

      Flag to indicate whether or not the uima-as client should use timer per CAS. The default is single timer for all outstanding CASes.
      See Also:
        Constant Field Values

    - #### TargetSelectorProperty

          static final String TargetSelectorProperty

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### initialize

          void initialize(Map anApplicationContext)
                   throws ResourceInitializationException

      Initializes UIMA asynchronous client using configuration parameters provided in a Map object. It creates a connection to a service queue managed by a Broker as specified in the parameters. A temporary reply queue is also created with a JMS listener attached to it. Once the connections are made and the listener is started the method sends getMeta request to the UIMA AS service and waits for a response. When the reply to getMeta is received the UIMA AS client is fully initialized and notifies an application by calling `UimaASStatusCallbackListener.initializationComplete(EntityProcessStatus)` on the application listener.
      Parameters:
        `anApplicationContext` - - configuration containing UIMA EE Service Broker URI, service queue name, timeout value, reply window size, and CAS Pool size.
      Throws:
        `ResourceInitializationException` - init error

    - #### setCollectionReader

          void setCollectionReader(CollectionReader aCollectionReader)
                            throws ResourceInitializationException

      Registers a `CollectionReader` instance to process a Collection. This method must be called first, before calling `process()` method.
      Parameters:
        `aCollectionReader` - - instance of a `CollectionReader`
      Throws:
        `ResourceInitializationException` - init error

    - #### addStatusCallbackListener

          void addStatusCallbackListener(UimaAsBaseCallbackListener aListener)

      Registers application specific listener. Via this listener the application receives call-backs. More than one listener can be added.
      Parameters:
        `aListener` - - application listener object to add

    - #### removeStatusCallbackListener

          void removeStatusCallbackListener(UimaAsBaseCallbackListener aListener)

      Unregisters named application listener.
      Parameters:
        `aListener` - - application listener to remove

    - #### stop

          void stop()
             throws Exception

      Stops the asynchronous client. Cleans up resources, drops connection to UIMA AS service queue and stops listening on a response queue.
      Throws:
        `Exception` - error

    - #### getPerformanceReport

          String getPerformanceReport()

      Not implemented
      Returns:
        performance report

    - #### process

          void process()
                throws ResourceProcessException

      Initiates processing of a collection. This method should be only called after initialize() has been called and an instance of a `CollectionReader` is provided via `setCollectionReader(CollectionReader)`. This method blocks until the `CollectionReader` finishes processing the entire collection. Status of the processing can be obtained by registering a listener with the `addStatusCallbackListener(UimaAsBaseCallbackListener)` method.

      The method is synchronized to allow processing of only one collection at a time. The application must wait with processing another collection until it receives notification via a listener `UimaASStatusCallbackListener.collectionProcessComplete(EntityProcessStatus aStatus)`

      Throws:
        `ResourceProcessException` - - if there is a problem processing the Collection

    - #### sendCAS

          String sendCAS(CAS aCAS)
                  throws ResourceProcessException

      Sends a given CAS for analysis to UIMA AS Service. This method may block if the client is configured to use a reply window which prevents sending too many CASes to the service. Assuming the window is large enough to send the CAS, this method returns as soon as the CAS is sent. Before sending the CAS, a timer starts that will expire if a reply doesn't arrive in a given interval.
      Parameters:
        `aCAS` - - a CAS to analyze.
      Returns:
        - returns a unique identifier associated with the sent CAS
      Throws:
        `ResourceProcessException` - error

    - #### sendCAS

          String sendCAS(CAS aCAS,
                         String targetServiceId)
                  throws ResourceProcessException

      Sends a given CAS for analysis to a specific instance of UIMA AS Service. This method may block if the client is configured to use a reply window which prevents sending too many CASes to the service. Assuming the window is large enough to send the CAS, this method returns as soon as the CAS is sent. Before sending the CAS, a timer starts that will expire if a reply doesn't arrive in a given interval.
      Parameters:
        `aCAS` - - a CAS to analyze.
        `targetServiceId` - - Id of a service which should process the CAS
      Returns:
        - returns a unique identifier associated with the sent CAS
      Throws:
        `ResourceProcessException` - error

    - #### getCAS

          CAS getCAS()
              throws Exception

      Requests new CAS instance from a CAS pool. This method blocks until a free instance of CAS is available in a CAS pool.
      Returns:
        - new CAS instance fetched from the CAS pool
      Throws:
        `Exception` - error

    - #### collectionProcessingComplete

          void collectionProcessingComplete()
                                     throws ResourceProcessException

      Sends a Collection Processing Complete (CPC) request to a UIMA AS Service and blocks waiting for a reply. The method blocks until the service replies or a timeout occurs. Before returning, this method will notify an application of completing the Collection Processing Complete request using registered listener
      Throws:
        `ResourceProcessException` - error

    - #### getMetaData

          ProcessingResourceMetaData getMetaData()
                                          throws ResourceInitializationException

      Returns a `ProcessingResourceMetadata` received from the UIMA AS Service. The metadata is obtained from the service during initialization. returns - an ProcessingResourceMetadata received from an asynchronous Analysis Engine service, or null if initialize() has not yet been called.
      Returns:
        ProcessingResourceMetaData metadata
      Throws:
        `ResourceInitializationException` - error

    - #### sendAndReceiveCAS

          String sendAndReceiveCAS(CAS aCAS)
                            throws ResourceProcessException

      This synchronous method sends a given CAS to a UIMA AS service and waits for response. The method either returns a CAS with the result of analysis or throws an exception. It doesn't use call-backs through a registered application listener.
      Parameters:
        `aCAS` - - a CAS to analyze.
      Returns:
        - a unique id assigned to the CAS
      Throws:
        `ResourceProcessException` - error

    - #### sendAndReceiveCAS

          String sendAndReceiveCAS(CAS aCAS,
                                   List<AnalysisEnginePerformanceMetrics> componentMetricsList)
                            throws ResourceProcessException

      This synchronous method sends a given CAS to a UIMA AS service and waits for response. The method either returns a CAS with the result of analysis or throws an exception. It doesn't use call-backs through a registered application listener. If there is no exception, the method also returns per Analysis Engine performance breakdown for the CAS. This breakdown can be used to identify how much time each AE took to process the CAS.
      Parameters:
        `aCAS` - - a CAS to analyze.
        `componentMetricsList` - - empty list to be filled with per AE performance metrics
      Returns:
        - a unique id assigned to the CAS
      Throws:
        `ResourceProcessException` - error

    - #### sendAndReceiveCAS

          String sendAndReceiveCAS(CAS aCAS,
                                   List<AnalysisEnginePerformanceMetrics> componentMetricsList,
                                   String targetServiceId)
                            throws ResourceProcessException

      This synchronous method sends a given CAS to a UIMA AS service and waits for response. The method either returns a CAS with the result of analysis or throws an exception. It doesn't use call-backs through a registered application listener. If there is no exception, the method also returns per Analysis Engine performance breakdown for the CAS. This breakdown can be used to identify how much time each AE took to process the CAS.
      Parameters:
        `aCAS` - - a CAS to analyze.
        `componentMetricsList` - - empty list to be filled with per AE performance metrics
        `targetServiceId` - - Id of a specific service which should process the CAS
      Returns:
        - a unique id assigned to the CAS
      Throws:
        `ResourceProcessException` - error

    - #### deploy

          String deploy(String aDeploymentDescriptor,
                        Map anApplicationContext)
                 throws Exception

      Deploys a UIMA AS container and all services defined in the provided deployment descriptor. The deployment is within the same JVM. Each deployment descriptor contains an assembly of related UIMA AS services. This method is synchronous and will block until all UIMA AS services are completely deployed and initialized. If there is a problem deploying any of the UIMA AS services the container is destroyed and exception thrown.
      Parameters:
        `aDeploymentDescriptor` - - a deployment descriptor to deploy in a container.
        `anApplicationContext` - - initialization parameters needed to configure the client and services
      Returns:
        - the id of the container in which the UIMA AS services were deployed
      Throws:
        `Exception` - - if there was a problem deploying the container or UIMA AS services.

    - #### deploy

          String deploy(String[] aDeploymentDescriptorList,
                        Map anApplicationContext)
                 throws Exception

      Deploys a single UIMA AS container and all services defined in provided deployment descriptors. The deployment is within the same JVM. Each deployment descriptor contains an assembly of related UIMA AS services. This method is synchronous and will block until all UIMA AS services are completely deployed and initialized. If there is a problem deploying any of the UIMA AS services the container is destroyed and exception thrown.
      Parameters:
        `aDeploymentDescriptorList` - - a list of deployment descriptors to deploy in a container.
        `anApplicationContext` - - initialization parameters needed to configure the client and services
      Returns:
        - the id of the container in which the UIMA AS services were deployed
      Throws:
        `Exception` - - if there was a problem deploying the container or UIMA AS services.

    - #### undeploy

          void undeploy(String aSpringContainerId)
                 throws Exception

      Undeploys specified UIMA AS container and all services running within it. Each UIMA AS container has a unique id assigned to it during the deploy phase. This method is synchronous and will block until the container (and all services contained within it) is destroyed.
      Parameters:
        `aSpringContainerId` - - an id of the container to be destroyed.
      Throws:
        `Exception` - error

    - #### undeploy

          void undeploy(String aSpringContainerId,
                        int stop_level)
                 throws Exception

      Undeploys specified UIMA AS container and all services running within it. Each UIMA AS container has a unique id assigned to it during the deploy phase. This method is synchronous and will block until the container (and all services contained within it) is destroyed.
      Parameters:
        `aSpringContainerId` - - an id of the container to be destroyed.
        `stop_level` - stop
      Throws:
        `Exception` - error

    - #### getSerialFormat

          SerialFormat getSerialFormat()

      Returns serialization strategy for the remote service. All CASes will be serialized according to the specified serialization. Either XMI or BINARY or COMPRESSED_BINARY_6
      Returns:
        String type of serialization for CASes

    - #### stopProducingCases

          void stopProducingCases()

      Request Uima AS client to initiate sending Stop requests to a service for all outstanding CASes awaiting reply.

    - #### stopProducingCases

          void stopProducingCases(String aCasReferenceId)

      Request Uima AS client to initiate sending Stop request to a service for a given CAS id If the service is a Cas Multiplier, it will stop producing new CASes, will wait until all child CASes finish and finally returns the input CAS.
      Parameters:
        `aCasReferenceId` - cas id

Copyright © 2006–2018 The Apache Software Foundation. All rights reserved.