org.apache.uima.aae.client
Interface UimaAsynchronousEngine


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 #sendAndReceive(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(CollectionReads) 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(UimaASStatusCallbackListener) method. These listeners receive status callbacks during the processing. An exception to that is the synchronous processing via #sendAndReceive(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 #sendAndReceive(CAS) or #sendCASCAS) methods from multiple threads.


Field Summary
static String ApplicationContext
           
static String ApplicationName
           
static String CasPoolSize
           
static String CpcTimeout
           
static String DD2SpringXsltFilePath
           
static String Endpoint
           
static String GetMetaTimeout
           
static String ReplyWindow
           
static String SaxonClasspath
           
static String SerializationStrategy
           
static String ServerUri
           
static String ShadowCasPoolSize
           
static String SharedConnection
           
static String Timeout
           
static String UimaEeDebug
           
 
Method Summary
 void addStatusCallbackListener(org.apache.uima.aae.client.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 provided deployment descriptor.
 org.apache.uima.cas.CAS getCAS()
          Requests new CAS instance from a CAS pool.
 org.apache.uima.resource.metadata.ProcessingResourceMetaData getMetaData()
          Returns a ProcessingResourceMetadata received from the UIMA AS Service.
 String getPerformanceReport()
          Not implemented
 String getSerializationStrategy()
          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(org.apache.uima.aae.client.UimaAsBaseCallbackListener aListener)
          Unregisters named application listener.
 String sendAndReceiveCAS(org.apache.uima.cas.CAS aCAS)
          This synchronous method sends a given CAS to a UIMA AS service and waits for response.
 String sendCAS(org.apache.uima.cas.CAS aCAS)
          Sends a given CAS for analysis to UIMA AS Service.
 void setCollectionReader(org.apache.uima.collection.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
See Also:
Constant Field Values

ApplicationName

static final String ApplicationName
See Also:
Constant Field Values

ServerUri

static final String ServerUri
See Also:
Constant Field Values

Endpoint

static final String Endpoint
See Also:
Constant Field Values

CasPoolSize

static final String CasPoolSize
See Also:
Constant Field Values

ShadowCasPoolSize

static final String ShadowCasPoolSize
See Also:
Constant Field Values

ReplyWindow

static final String ReplyWindow
See Also:
Constant Field Values

Timeout

static final String Timeout
See Also:
Constant Field Values

CpcTimeout

static final String CpcTimeout
See Also:
Constant Field Values

GetMetaTimeout

static final String GetMetaTimeout
See Also:
Constant Field Values

DD2SpringXsltFilePath

static final String DD2SpringXsltFilePath
See Also:
Constant Field Values

SaxonClasspath

static final String SaxonClasspath
See Also:
Constant Field Values

UimaEeDebug

static final String UimaEeDebug
See Also:
Constant Field Values

SerializationStrategy

static final String SerializationStrategy
See Also:
Constant Field Values

SharedConnection

static final String SharedConnection
See Also:
Constant Field Values
Method Detail

initialize

void initialize(Map anApplicationContext)
                throws org.apache.uima.resource.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 #initializationComplete() 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:
org.apache.uima.resource.ResourceInitializationException

setCollectionReader

void setCollectionReader(org.apache.uima.collection.CollectionReader aCollectionReader)
                         throws org.apache.uima.resource.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:
org.apache.uima.resource.ResourceInitializationException

addStatusCallbackListener

void addStatusCallbackListener(org.apache.uima.aae.client.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(org.apache.uima.aae.client.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

getPerformanceReport

String getPerformanceReport()
Not implemented

Returns:
null

process

void process()
             throws org.apache.uima.resource.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(). 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(UimaASStatusCallbackListener) 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 #org.apache.uima.aae.clientcollectionProcessComplete(EntityProcessStatus aStatus)

Throws:
org.apache.uima.resource.ResourceProcessException - - if there is a problem processing the Collection

sendCAS

String sendCAS(org.apache.uima.cas.CAS aCAS)
               throws org.apache.uima.resource.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:
org.apache.uima.resource.ResourceProcessException

getCAS

org.apache.uima.cas.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

collectionProcessingComplete

void collectionProcessingComplete()
                                  throws org.apache.uima.resource.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:
org.apache.uima.resource.ResourceProcessException

getMetaData

org.apache.uima.resource.metadata.ProcessingResourceMetaData getMetaData()
                                                                         throws org.apache.uima.resource.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.

Throws:
org.apache.uima.resource.ResourceInitializationException

sendAndReceiveCAS

String sendAndReceiveCAS(org.apache.uima.cas.CAS aCAS)
                         throws org.apache.uima.resource.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:
org.apache.uima.resource.ResourceProcessException

deploy

String deploy(String aDeploymentDescriptor,
              Map anApplicationContext)
              throws Exception
Deploys a UIMA AS container and all services defined in provided deployment descriptor. 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. 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.

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

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.
Throws:
Exception

getSerializationStrategy

String getSerializationStrategy()
Returns serialization strategy for the remote service. All CASes will be serialized according to the specified serialization. Either xmi or binary

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.



Copyright © 2010 The Apache Software Foundation. All Rights Reserved.