Interface UimaAsynchronousEngine
-
- All Known Implementing Classes:
BaseUIMAAsynchronousEngine_impl
,BaseUIMAAsynchronousEngineCommon_impl
public interface UimaAsynchronousEngine
AUimaAsynchronousEngine
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 callsendAndReceiveCAS(CAS)
method. For asynchronous processing the application should callsendCAS(CAS)
method. Additionally, processing with a client sideCollectionReader
is supported as well. The application first instantiates and initializes theCollectionReader
and registers it viasetCollectionReader(CollectionReader)
method. Once theCollectionReader
is registered, andinitialize(Map)
method is called, the application may callprocess()
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* callinginitialize(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 theaddStatusCallbackListener(UimaAsBaseCallbackListener)
method. These listeners receive status callbacks during the processing. An exception to that is the synchronous processing viasendAndReceiveCAS(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)
orsendCAS(CAS)
methods from multiple threads.
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
ApplicationContext
Deprecated.static java.lang.String
ApplicationName
Name of an application that uses Uima AS client.static java.lang.String
CasPoolSize
Size of Cas pool to create.static java.lang.String
CpcTimeout
Collection Processing Complete timeout.static java.lang.String
DD2SpringXsltFilePath
Path to the XSLT processor to use when processing a deployment descriptor.static java.lang.String
Endpoint
Name of a queue where the Uima AS client sends JMS requests.static java.lang.String
GetMetaTimeout
GetMeta timeout.static java.lang.String
ReplyWindow
Deprecated.static java.lang.String
SaxonClasspath
Saxon classpath to use when processing a deployment descriptor.static java.lang.String
SerializationStrategy
Type of serialization to use when serializing CASes to remote Uima AS service.static java.lang.String
ServerUri
Broker URL the Uima AS client will use to communicate with Uima AS service.static java.lang.String
ShadowCasPoolSize
Deprecated.static java.lang.String
SharedConnection
Deprecated.static java.lang.String
Timeout
CAS process timeout.static java.lang.String
UimaEeDebug
Debug flag to use when processing a deployment descriptor.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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.java.lang.String
deploy(java.lang.String[] aDeploymentDescriptorList, java.util.Map anApplicationContext)
Deploys a single UIMA AS container and all services defined in provided deployment descriptors.java.lang.String
deploy(java.lang.String aDeploymentDescriptor, java.util.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 aProcessingResourceMetadata
received from the UIMA AS Service.java.lang.String
getPerformanceReport()
Not implementedjava.lang.String
getSerializationStrategy()
Returns serialization strategy for the remote service.void
initialize(java.util.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.java.lang.String
sendAndReceiveCAS(org.apache.uima.cas.CAS aCAS)
This synchronous method sends a given CAS to a UIMA AS service and waits for response.java.lang.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 aCollectionReader
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(java.lang.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(java.lang.String aSpringContainerId)
Undeploys specified UIMA AS container and all services running within it.void
undeploy(java.lang.String aSpringContainerId, int stop_level)
Undeploys specified UIMA AS container and all services running within it.
-
-
-
Field Detail
-
ApplicationContext
static final java.lang.String ApplicationContext
Deprecated.- See Also:
- Constant Field Values
-
ApplicationName
static final java.lang.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 ininitialize(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_www_xxxx_yyyy_zzzz - See Also:
- Constant Field Values
-
ServerUri
static final java.lang.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 ininitialize(Map)
. Required. If omitted, the Uima AS client throwsResourceInitializationException
- See Also:
- Constant Field Values
-
Endpoint
static final java.lang.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 ininitialize(Map)
. Required. If omitted, the Uima AS client throwsResourceInitializationException
- See Also:
- Constant Field Values
-
CasPoolSize
static final java.lang.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 ininitialize(Map)
. Optional. If omitted, the Uima AS client will use 1 as a default.- See Also:
- Constant Field Values
-
ShadowCasPoolSize
static final java.lang.String ShadowCasPoolSize
Deprecated.- See Also:
- Constant Field Values
-
ReplyWindow
static final java.lang.String ReplyWindow
Deprecated.- See Also:
- Constant Field Values
-
Timeout
static final java.lang.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 ininitialize(Map)
. Optional. If omitted, the Uima AS client defaults to no timeout.- See Also:
- Constant Field Values
-
CpcTimeout
static final java.lang.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 ininitialize(Map)
. Optional. If omitted, the Uima AS client defaults to no timeout.- See Also:
- Constant Field Values
-
GetMetaTimeout
static final java.lang.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 ininitialize(Map)
. Optional. If omitted, the Uima AS client defaults to 60 seconds.- See Also:
- Constant Field Values
-
DD2SpringXsltFilePath
static final java.lang.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,). 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 java.lang.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,). 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 java.lang.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,). This setting is only relevant if the Uima AS Client is used to deploy Uima AS service. - See Also:
- Constant Field Values
-
SerializationStrategy
static final java.lang.String SerializationStrategy
Type of serialization to use when serializing CASes to remote Uima AS service. Valid serialization types are: xmi or 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 ininitialize(Map)
- See Also:
- Constant Field Values
-
SharedConnection
static final java.lang.String SharedConnection
Deprecated.- See Also:
- Constant Field Values
-
-
Method Detail
-
initialize
void initialize(java.util.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 callingUimaASStatusCallbackListener.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:
org.apache.uima.resource.ResourceInitializationException
-
setCollectionReader
void setCollectionReader(org.apache.uima.collection.CollectionReader aCollectionReader) throws org.apache.uima.resource.ResourceInitializationException
Registers aCollectionReader
instance to process a Collection. This method must be called first, before callingprocess()
method.- Parameters:
aCollectionReader
- - instance of aCollectionReader
- Throws:
org.apache.uima.resource.ResourceInitializationException
-
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 java.lang.Exception
Stops the asynchronous client. Cleans up resources, drops connection to UIMA AS service queue and stops listening on a response queue.- Throws:
java.lang.Exception
-
getPerformanceReport
java.lang.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 aCollectionReader
is provided viasetCollectionReader(CollectionReader)
. This method blocks until theCollectionReader
finishes processing the entire collection. Status of the processing can be obtained by registering a listener with theaddStatusCallbackListener(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:
org.apache.uima.resource.ResourceProcessException
- - if there is a problem processing the Collection
-
sendCAS
java.lang.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 java.lang.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:
java.lang.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 aProcessingResourceMetadata
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
java.lang.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
java.lang.String deploy(java.lang.String aDeploymentDescriptor, java.util.Map anApplicationContext) throws java.lang.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:
java.lang.Exception
- - if there was a problem deploying the container or UIMA AS services.
-
deploy
java.lang.String deploy(java.lang.String[] aDeploymentDescriptorList, java.util.Map anApplicationContext) throws java.lang.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:
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:
java.lang.Exception
- - if there was a problem deploying the container or UIMA AS services.
-
undeploy
void undeploy(java.lang.String aSpringContainerId) throws java.lang.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:
java.lang.Exception
-
undeploy
void undeploy(java.lang.String aSpringContainerId, int stop_level) throws java.lang.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:
java.lang.Exception
-
getSerializationStrategy
java.lang.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(java.lang.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.
-
-