You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2008/05/13 00:22:05 UTC
svn commit: r655671 [2/4] - in
/incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src:
docbook/uima_async_scaleout/ olink/uima_async_scaleout/
Modified: incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml?rev=655671&r1=655670&r2=655671&view=diff
==============================================================================
--- incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml (original)
+++ incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml Mon May 12 15:22:05 2008
@@ -1,10 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY imgroot "../images/uima_async_scaleout/async.overview/" >
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
- %uimaents;
- ]>
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -23,91 +19,45 @@
specific language governing permissions and limitations
under the License.
-->
-
<chapter id="ugr.async.ov">
- <title>Overview - Asynchronous Scaleout</title>
-
- <para>UIMA Asynchronous Scaleout (AS) is a set of capabilities supported in the UIMA
- Framework for achieving scaleout that is more general than the approaches provided for in
- the Collection Processing Manager (CPM). AS is a second generation design, replacing the
- CPM and Vinci Services. The CPM and Vinci are still available and are not being deprecated,
- but new designs are encouraged
- to use AS for scalability, and current designs reaching limitations want to
- move to AS.</para>
-
- <para>
- AS is integrated with the new flow controller architecture, and can be applied to
- both primitive and aggregate analysis engines.
- </para>
-
- <!--
+<title>Overview - Asynchronous Scaleout</title>
+<para>UIMA Asynchronous Scaleout (AS) is a set of capabilities supported in the UIMA Framework for achieving scaleout that is more general than the approaches provided for in the Collection Processing Manager (CPM). AS is a second generation design, replacing the CPM and Vinci Services. The CPM and Vinci are still available and are not being deprecated, but new designs are encouraged to use AS for scalability, and current designs reaching limitations want to move to AS.</para>
+<para>AS is integrated with the new flow controller architecture, and can be applied to both primitive and aggregate analysis engines. </para>
+<!--
<para>
AS comes in potentially several flavors, depending on which protocol and providers it is built upon.
This documentation describes the JMS-ActiveMQ variety.
</para>
-->
-
- <section id="ugr.async.ov.terminology">
- <title>Terminology</title>
- <para>
- Terms used in describing AS capabilities include:
- </para>
-
- <variablelist>
- <varlistentry><term><emphasis role="bold">
-
- AS
-
- </emphasis></term>
- <listitem>
- <para>Asynchronous Scaleout - a name given to the capability described here</para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><emphasis role="bold">
-
- AS-JMS/AMQ/Spring
-
- </emphasis></term>
- <listitem>
- <para>A variety of AS, based on JMS (Java Messaging Services), Active MQ,
- an Apache Open Source implementation of JMS, and the Spring framework. This
- variety is the one described in detail in this document.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><emphasis role="bold">
-
- Queue
-
- </emphasis></term>
- <listitem>
- <para>Queues are the basic mechanism of asynchronous communication. One or more "producers" send messages
- to a queue, and a queue can have one or more "consumers" that receive messages. Messages in UIMA AS
- are usually CASes, or references to CASes.
- Queues are identified by a 2 part name. The first part is the Queue Broker;
- the second part is a Queue Name.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><emphasis role="bold">
-
- AS Component
-
- </emphasis></term>
- <listitem>
- <para>An AS client or service. AS clients send requests to AS service queues and receive back responses
- on reply queues. AS services can be AS Primitives or AS aggregates (see following).</para>
- <!--
+<section id="ugr.async.ov.terminology">
+<title>Terminology</title>
+<para>Terms used in describing AS capabilities include: </para>
+<variablelist>
+<varlistentry>
+<term>
+<emphasis role="bold">AS </emphasis></term>
+<listitem>
+<para>Asynchronous Scaleout - a name given to the capability described here</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">AS-JMS/AMQ/Spring </emphasis></term>
+<listitem>
+<para>A variety of AS, based on JMS (Java Messaging Services), Active MQ, an Apache Open Source implementation of JMS, and the Spring framework. This variety is the one described in detail in this document. </para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">Queue </emphasis></term>
+<listitem>
+<para>Queues are the basic mechanism of asynchronous communication. One or more "producers" send messages to a queue, and a queue can have one or more "consumers" that receive messages. Messages in UIMA AS are usually CASes, or references to CASes. Queues are identified by a 2 part name. The first part is the Queue Broker; the second part is a Queue Name.</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">AS Component </emphasis></term>
+<listitem>
+<para>An AS client or service. AS clients send requests to AS service queues and receive back responses on reply queues. AS services can be AS Primitives or AS aggregates (see following).</para>
+<!--
<para>An Analysis Engine being managed by AS. All AS Components
have an input queue. AS Components can be AS Primitives or AS Aggregates (see following).</para>
- -->
- </listitem>
- </varlistentry>
-
-
- <!--
+ --></listitem></varlistentry>
+<!--
<varlistentry><term><emphasis role="bold">
AS Delegates
@@ -120,54 +70,29 @@
</listitem>
</varlistentry>
-->
-
- <varlistentry><term><emphasis role="bold">
-
- AS Primitive
-
- </emphasis></term>
- <listitem>
- <para>An AS service that is either a Primitive Analysis Engine <!-- or Service Client Proxy --> or
- an Aggregate AE whose Delegates are <emphasis role="bold">not</emphasis>
- AS-enabled</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry><term><emphasis role="bold">
-
- AS Aggregate
-
- </emphasis></term>
- <listitem>
- <para>An AS service that is an Aggregate Analysis Engine where the Delegates are also AS components.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry><term><emphasis role="bold">
-
- AS Client
-
- </emphasis></term>
- <listitem>
- <para>A component sending requests to AS services. An AS client is typically an application using the
- UIMA AS client API, a JMS Service Client Proxy, or an AS Aggregate.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><emphasis role="bold">
-
- co-located
-
- </emphasis></term>
- <listitem>
- <para>two running pieces of code are co-located if they run
- in the same JVM and share the same UIMA framework implementation and components.</para>
- </listitem>
- </varlistentry>
-
- <!-- *** This term is never used in the overview. Should be described in a separate section. ***
+<varlistentry>
+<term>
+<emphasis role="bold">AS Primitive </emphasis></term>
+<listitem>
+<para>An AS service that is either a Primitive Analysis Engine
+<!-- or Service Client Proxy --> or an Aggregate AE whose Delegates are
+<emphasis role="bold">not</emphasis> AS-enabled</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">AS Aggregate </emphasis></term>
+<listitem>
+<para>An AS service that is an Aggregate Analysis Engine where the Delegates are also AS components.</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">AS Client </emphasis></term>
+<listitem>
+<para>A component sending requests to AS services. An AS client is typically an application using the UIMA AS client API, a JMS Service Client Proxy, or an AS Aggregate.</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">co-located </emphasis></term>
+<listitem>
+<para>two running pieces of code are co-located if they run in the same JVM and share the same UIMA framework implementation and components.</para></listitem></varlistentry>
+<!-- *** This term is never used in the overview. Should be described in a separate section. ***
<varlistentry><term><emphasis role="bold">
AS remote service client
@@ -183,124 +108,76 @@
</listitem>
</varlistentry>
-->
-
-
- <varlistentry><term><emphasis role="bold">
-
- Queue Broker
-
- </emphasis></term>
- <listitem>
- <para>Queue brokers manage one or more named queues. The brokers are identified using
- a URL, representing where they are on the network. When the queue broker is co-located with
- the AS client and service, CASes are passed by reference, avoiding serialization / deserialization.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry><term><emphasis role="bold">
-
- Transport Connector
-
- </emphasis></term>
- <listitem>
- <para>AS components connect to queue brokers via transport connectors. UIMA AS will typically use "tcp"
- connectors. "http" connectors are useful for tunneling via an existing public web server.</para>
- </listitem>
- </varlistentry>
- <!--
+<varlistentry>
+<term>
+<emphasis role="bold">Queue Broker </emphasis></term>
+<listitem>
+<para>Queue brokers manage one or more named queues. The brokers are identified using a URL, representing where they are on the network. When the queue broker is co-located with the AS client and service, CASes are passed by reference, avoiding serialization / deserialization.</para></listitem></varlistentry>
+<varlistentry>
+<term>
+<emphasis role="bold">Transport Connector </emphasis></term>
+<listitem>
+<para>AS components connect to queue brokers via transport connectors. UIMA AS will typically use "tcp" connectors. "http" connectors are useful for tunneling via an existing public web server.</para></listitem></varlistentry>
+<!--
<varlistentry><term><emphasis role="bold"></emphasis></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
- -->
- </variablelist>
- </section>
- <section id="ugr.async.ov.as_vs_cpm">
- <title>AS versus CPM</title>
- <para> It is useful to compare and contrast the approaches and capabilities of AS and CPM.</para>
-
- <informaltable pgwide="1" colsep="1" frame="all" rowsep="1">
- <tgroup cols="3">
- <colspec colname="c1" colwidth="1*"/>
- <colspec colname="c2" colwidth="2.5*"/>
- <colspec colname="c3" colwidth="2.5*"/>
- <thead>
- <row>
- <entry align="center"></entry>
- <entry align="center">AS</entry>
- <entry align="center">CPM</entry>
- </row>
- </thead>
-
- <tbody valign="middle">
-
- <row>
- <entry>Putting components together</entry>
- <entry>
- <para>Aggregates are the only way to put components together. </para>
- </entry>
- <entry>
- <para> <emphasis role="bold">Two methods of putting components together</emphasis>
- <orderedlist spacing="compact">
- <listitem><para>CPE (Collection Processing Engine) descriptor, which has sections specifying a
- Collection Reader, and a set of CAS Processors</para></listitem>
- <listitem><para>Each CAS Processor can, as well, be an aggregate</para></listitem>
- </orderedlist></para>
- </entry>
- </row>
-
- <row>
- <entry>Kinds of Aggregates</entry>
- <entry>
- <para>An aggregate can be run <emphasis role="bold">asynchronously</emphasis>
- using the AS mechanism, with a queue in front of each
- delegate, or it can by run <emphasis role="bold">synchronously</emphasis>.
- When run asynchronously, <emphasis>all</emphasis> of the delegates will
- have queues in front of them, and AS Primitive delegates
- can be individually scaled out (replicated)
- as needed.
- </para>
- </entry>
- <entry>All aggregates are run synchronously. In an aggregate, only one component is
- running at a time.</entry>
- </row>
-
-
- <row>
- <entry>CAS flow</entry>
- <entry>Any, including custom user-defined sequence using user-provided flow controller.
- </entry>
- <entry>Fixed linear flow between CAS processors. A single CAS processor can be an aggregate,
- and within the aggregate, can have any flow including custom user-defined sequence
- using user-provided flow controller.</entry>
- </row>
-
- <row>
- <entry>Threading</entry>
-
- <entry>Each instance of a component runs in its own thread.</entry>
- <entry>One thread for the collection reader, one for the CAS Consumers, "n"
- threads for the main pipeline.</entry>
- </row>
-
- <!--row>
+ --></variablelist></section>
+<section id="ugr.async.ov.as_vs_cpm">
+<title>AS versus CPM</title>
+<para>It is useful to compare and contrast the approaches and capabilities of AS and CPM.</para>
+<informaltable pgwide="1" colsep="1" frame="all" rowsep="1">
+<tgroup cols="3">
+<colspec colname="c1" colwidth="1*"></colspec>
+<colspec colname="c2" colwidth="2.5*"></colspec>
+<colspec colname="c3" colwidth="2.5*"></colspec>
+<thead>
+<row>
+<entry align="center"></entry>
+<entry align="center">AS</entry>
+<entry align="center">CPM</entry></row></thead>
+<tbody valign="middle">
+<row>
+<entry>Putting components together</entry>
+<entry>
+<para>Aggregates are the only way to put components together. </para> </entry>
+<entry>
+<para>
+<emphasis role="bold">Two methods of putting components together</emphasis>
+<orderedlist spacing="compact">
+<listitem>
+<para>CPE (Collection Processing Engine) descriptor, which has sections specifying a Collection Reader, and a set of CAS Processors</para></listitem>
+<listitem>
+<para>Each CAS Processor can, as well, be an aggregate</para></listitem></orderedlist></para> </entry></row>
+<row>
+<entry>Kinds of Aggregates</entry>
+<entry>
+<para>An aggregate can be run
+<emphasis role="bold">asynchronously</emphasis> using the AS mechanism, with a queue in front of each delegate, or it can by run
+<emphasis role="bold">synchronously</emphasis>. When run asynchronously,
+<emphasis>all</emphasis> of the delegates will have queues in front of them, and AS Primitive delegates can be individually scaled out (replicated) as needed. </para> </entry>
+<entry>All aggregates are run synchronously. In an aggregate, only one component is running at a time.</entry></row>
+<row>
+<entry>CAS flow</entry>
+<entry>Any, including custom user-defined sequence using user-provided flow controller. </entry>
+<entry>Fixed linear flow between CAS processors. A single CAS processor can be an aggregate, and within the aggregate, can have any flow including custom user-defined sequence using user-provided flow controller.</entry></row>
+<row>
+<entry>Threading</entry>
+<entry>Each instance of a component runs in its own thread.</entry>
+<entry>One thread for the collection reader, one for the CAS Consumers, "n" threads for the main pipeline.</entry></row>
+<!--row>
<entry>Load Balancing</entry>
<entry>Queue in front of each (set of replicated) component(s); when component is available, it
"pulls" requests from the queue</entry>
<entry>One master queue; entries are "pushed" to components; limited load balancing capability.</entry>
</row-->
-
-
- <row>
- <entry>Delegate deployment</entry>
- <entry>Co-located or remote.</entry>
- <entry>Co-located or remote.</entry>
- </row>
-
-
- <!--row>
+<row>
+<entry>Delegate deployment</entry>
+<entry>Co-located or remote.</entry>
+<entry>Co-located or remote.</entry></row>
+<!--row>
<entry>Remoting specifications</entry>
<entry>
<formalpara><title><emphasis role="bold">AS:</emphasis></title>
@@ -337,74 +214,34 @@
recovery. </para>
</entry> - >
</row-->
-
-
-
- <row>
- <entry>Life cycle management</entry>
- <entry>
- <para>Scripts to launch services, launch Queue Brokers.</para>
- </entry>
- <entry>
- <para>Scripts to launch services, start Vinci Name Service.</para>
- <para>
- In addition, CPE "managed" configuration provides for automatic launching of
- UIMA Vinci services in same machine, in different processes.
- </para>
- </entry>
- </row>
-
-
- <row>
- <entry>Error recovery</entry>
- <entry>
- <para>Similar capabilities as the CPM provides for CAS Processors, but at the finer granularity
- of each AS component. The support includes customizable behavior overrides and
- extensions via user code. </para>
- </entry>
- <entry>
- <para>Error detection, thresholding, and
- recovery options at the granularity of CAS Processors (which are CPM components, not
- delegates of aggregates), with some
- customizable callback notifications</para>
-
- </entry>
- </row>
-
- <row>
- <entry>Firewall interactions</entry>
- <entry>Enables deployment of AS services behind a firewall using a public broker. Enables deployment of a public broker through single port, or using HTTP "tunneling".</entry>
- <entry>When using Vinci protocol, requires opening a
- large number of ports for each deployed service. SOAP connected services require one open port.</entry>
- </row>
-
- <row>
- <entry>Monitoring</entry>
- <entry>
- <para>JMX (Java Management Extensions) are enabled for recording many
- kinds of statistical information, and can be used to monitor (and, in the future,
- control) the operations of AS configured systems. </para>
- </entry>
- <entry>
- <para>Limited JMX information</para>
- </entry>
- </row>
-
- <row>
- <entry>Collection Reader</entry>
- <entry>Supported for backwards compatibility. New programs should use the
- CAS Multiplier instead, which is more general, or
- have the application pass in CASes to be processed. The compatibility support
- wraps Collection Readers as Cas Multipliers.</entry>
- <entry>Is always first element in linear CPE sequence chain</entry>
- </row>
-
- </tbody>
- </tgroup>
-
- </informaltable>
-
- <!--
+<row>
+<entry>Life cycle management</entry>
+<entry>
+<para>Scripts to launch services, launch Queue Brokers.</para> </entry>
+<entry>
+<para>Scripts to launch services, start Vinci Name Service.</para>
+<para>In addition, CPE "managed" configuration provides for automatic launching of UIMA Vinci services in same machine, in different processes. </para> </entry></row>
+<row>
+<entry>Error recovery</entry>
+<entry>
+<para>Similar capabilities as the CPM provides for CAS Processors, but at the finer granularity of each AS component. The support includes customizable behavior overrides and extensions via user code. </para> </entry>
+<entry>
+<para>Error detection, thresholding, and recovery options at the granularity of CAS Processors (which are CPM components, not delegates of aggregates), with some customizable callback notifications</para> </entry></row>
+<row>
+<entry>Firewall interactions</entry>
+<entry>Enables deployment of AS services behind a firewall using a public broker. Enables deployment of a public broker through single port, or using HTTP "tunneling".</entry>
+<entry>When using Vinci protocol, requires opening a large number of ports for each deployed service. SOAP connected services require one open port.</entry></row>
+<row>
+<entry>Monitoring</entry>
+<entry>
+<para>JMX (Java Management Extensions) are enabled for recording many kinds of statistical information, and can be used to monitor (and, in the future, control) the operations of AS configured systems. </para> </entry>
+<entry>
+<para>Limited JMX information</para> </entry></row>
+<row>
+<entry>Collection Reader</entry>
+<entry>Supported for backwards compatibility. New programs should use the CAS Multiplier instead, which is more general, or have the application pass in CASes to be processed. The compatibility support wraps Collection Readers as Cas Multipliers.</entry>
+<entry>Is always first element in linear CPE sequence chain</entry></row></tbody></tgroup></informaltable>
+<!--
<section id="ugr.async.ov.as_vs_cpm.cpm">
<title>CPM characteristics</title>
<formalpara>
@@ -518,309 +355,155 @@
</formalpara>
</section>
- -->
-
- </section>
-
- <!-- ======================================================= -->
- <!-- | Design Goals | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.design_goals">
- <title>Design goals for Asynchronous Scaleout</title>
- <para>
- The design goals for AS are:
- <orderedlist spacing="compact">
- <listitem>
- <para>Increased flexibility and options for scaleout (versus CPM)</para>
- <orderedlist spacing="compact">
- <listitem><para>scale out parts independently of other parts,
- to appropriate degree</para></listitem>
- <listitem><para>more options for protocols for remote connections, including
- some that don't require many ports through firewalls</para></listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Build upon widely accepted Apache-licensed open source middleware</para>
- </listitem>
- <listitem>
- <para>Simplification:
- <orderedlist spacing="compact">
- <listitem><para>Standardize on single approach to aggregate components</para></listitem>
- <listitem><para>More uniform Error handling / recovery / monitoring
- for all AS managed components.</para></listitem>
- </orderedlist>
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- </section>
-
- <!-- ======================================================= -->
- <!-- | Concepts | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts">
- <title>AS Concepts</title>
-
- <section id="ugr.async.ov.concepts.threading">
- <title>User written components and multi-threading</title>
- <titleabbrev>Threading</titleabbrev>
- <para>
- AS provides for scaling out of annotators - both aggregates and
- primitives. Each of these can specify a user-written implementation class. For primitives,
- this is the annotator class with the process() method that does the work. For
- aggregates, this can be an (optional) custom flow controller class that computes the flow.
- </para>
-
- <para>
- The classes for annotators and flow controllers do not need to be "thread-safe" with
- respect to their instance data - meaning,
- they do not need to be implemented with synchronization locks for access to their instance
- data, because each instance will only be called using one thread at a time. Scale out for these
- classes is done using multiple instances of the class.</para>
-
- <para>
- However, if you have class "static" fields
- shared by all instances, or other kinds of external data shared by all instances (such as
- a writable file), you must be aware of the possibility of multiple threads accessing these
- fields or external resources,
- running on separate instances of the class, and do any required synchronization for these.
- </para>
-
- </section>
-
- <!-- ======================================================= -->
- <!-- | Component Wrapping | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.wrapping">
- <title>AS Component wrapping</title>
-
- <para> Components managed by AS
- <orderedlist>
- <listitem><para>have an associated input queue (this may be internal, or explicit and externalized.</para>
- <para>They receive work units (CASes) from this queue, and return
- the updated CASes to an output queue which is specified as part of the message delivering the
- input work unit (CAS).</para></listitem>
- <listitem><para>have a container which wraps the component and provides the
- following services (see <xref linkend="ugr.async.ov.fig.wrapAE"/>):
- <itemizedlist spacing="compact">
- <listitem><para>A connection to an input queue of CASes to be
- processed</para></listitem>
- <listitem><para>Scale-out within the JVM for components at the bottom level - the AS Primitives.
- Scaleout creates multiple instances of the annotator(s),
- and runs each one on its own thread, all drawing work from the same input queue.</para></listitem>
- <listitem><para>(For AS Aggregates)
- connections to input queues of the delegates</para></listitem>
- <listitem><para>A "pull" mechanism for the component to pull new CASes (to be
- processed) from their associated input queue </para></listitem>
- <listitem><para>(For AS Aggregates) A separate, built-in internal queue to receive CASes back
- from delegates. These are passed to the aggregate's flow controller, which then specifies where they
- go next.</para></listitem>
- <listitem><para>A connection to user-specified error handlers. Error
- conditions are communicated to the flow controller, to enable user /
- dynamically determined recovery or termination actions.</para></listitem>
- </itemizedlist></para></listitem>
- </orderedlist> </para>
-
- <figure id="ugr.async.ov.fig.wrapAE">
- <title>AS Primitive Wrapper</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="279px" format="PNG" fileref="&imgroot;wrapAE.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="2.7in" format="PNG" fileref="&imgroot;wrapAE.png"/>
- </imageobject>
- <textobject><phrase>AS Primitive Wrapper</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>As shown in the next figure, when the component being wrapped is an AS Aggregate, the
- container will use the aggregate's flow controller (shown as "FC") to determine the
- flow of the CASes among the delegates. The next figure shows the additional output
- queue configured for aggregates to receive CASes returning from delegates. The
- dashed lines show how the queues are associated with the components.</para>
-
- <figure id="ugr.async.ov.fig.wrapAAE">
- <title>AS Aggregate wrapper</title>
- <mediaobject>
- <imageobject role="html">
- <imagedata width="590px" format="PNG" fileref="&imgroot;wrapAAE.png"/>
- </imageobject>
- <imageobject role="fo">
- <imagedata width="5.5in" format="PNG" fileref="&imgroot;wrapAAE.png"/>
- </imageobject>
- <textobject><phrase>AS Aggregate Container wrapping an Aggregate Analysis Engine</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The collection of parts and queues is wired together according to a deployment
- specification, provided by the deployer. This specification is a
- collection of one or more deployment descriptors.</para>
- </section> <!-- end of wrapping -->
-
- <!-- ======================================================= -->
- <!-- | deployment alternatives | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.deploying">
- <title>Deployment alternatives</title>
- <para>Deployment is concerned with the following kinds of parts, and allocating these
- parts (possibly replicated) to various hosts:
- <itemizedlist spacing="compact">
- <listitem><para>Application Drivers. These represent the top
- level caller of UIMA functionality. Examples include: stand-alone Java applications, such as
- the example document analyzer tool, a custom Web servlet, etc. </para></listitem>
- <listitem><para>AS Services. AS primitive or AS aggreate services deployed on one or more nodes as needed to meet scalability requirements.</para></listitem>
- <listitem><para>Queue Brokers. Each Queue Broker manages and provides the storage
- facility for one or more named queues. </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Parts can be co-located or not; when they're not, we say they're remote.
- Remote includes running on the same host, but in a different process space,
- using a different JVM or other native process. Connections between the parts
- are done using the JMS (Java Messaging
- Service) protocols, and in this version the support for this is provided by the
- ActiveMQ implementation from Apache.org.
- </para>
-
- <note><para>For high availability, the Queue Brokers can be,
- themselves, replicated over many hosts, with fail-over capability provided by the
- underlying ActiveMQ implementation.</para></note>
-
- <!-- ======================================================= -->
- <!-- | Multiples for scaleout | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.deploying.multiples">
- <title>Configuring multiple instances of components</title>
- <titleabbrev>Multiple Instances</titleabbrev>
- <para>
- AS components can be replicated; the replicated components can be
- co-located or distributed across different nodes. The purpose of the replication
- is to allow multiple work units (CASes) to be processed in parallel, in multiple
- threads, either in the same host, or using different hosts. The vision is that the deployment
- is able to replicate just those components which are the bottleneck in overall
- system thruput.
- </para>
-
- <para>There are two ways replication can be specified.
- <orderedlist>
- <listitem><para>In the deployment descriptor, set the numberOfInstances attribute to
- a number bigger than one.</para></listitem>
- <!--listitem><para>In the deployment descriptor, hook up multiple <service>
+ --></section>
+<!-- ======================================================= -->
+<!-- | Design Goals | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.design_goals">
+<title>Design goals for Asynchronous Scaleout</title>
+<para>The design goals for AS are:
+<orderedlist spacing="compact">
+<listitem>
+<para>Increased flexibility and options for scaleout (versus CPM)</para>
+<orderedlist spacing="compact">
+<listitem>
+<para>scale out parts independently of other parts, to appropriate degree</para></listitem>
+<listitem>
+<para>more options for protocols for remote connections, including some that don't require many ports through firewalls</para></listitem></orderedlist></listitem>
+<listitem>
+<para>Build upon widely accepted Apache-licensed open source middleware</para></listitem>
+<listitem>
+<para>Simplification:
+<orderedlist spacing="compact">
+<listitem>
+<para>Standardize on single approach to aggregate components</para></listitem>
+<listitem>
+<para>More uniform Error handling / recovery / monitoring for all AS managed components.</para></listitem></orderedlist> </para></listitem></orderedlist> </para></section>
+<!-- ======================================================= -->
+<!-- | Concepts | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts">
+<title>AS Concepts</title>
+<section id="ugr.async.ov.concepts.threading">
+<title>User written components and multi-threading</title>
+<titleabbrev>Threading</titleabbrev>
+<para>AS provides for scaling out of annotators - both aggregates and primitives. Each of these can specify a user-written implementation class. For primitives, this is the annotator class with the process() method that does the work. For aggregates, this can be an (optional) custom flow controller class that computes the flow. </para>
+<para>The classes for annotators and flow controllers do not need to be "thread-safe" with respect to their instance data - meaning, they do not need to be implemented with synchronization locks for access to their instance data, because each instance will only be called using one thread at a time. Scale out for these classes is done using multiple instances of the class.</para>
+<para>However, if you have class "static" fields shared by all instances, or other kinds of external data shared by all instances (such as a writable file), you must be aware of the possibility of multiple threads accessing these fields or external resources, running on separate instances of the class, and do any required synchronization for these. </para></section>
+<!-- ======================================================= -->
+<!-- | Component Wrapping | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.wrapping">
+<title>AS Component wrapping</title>
+<para>Components managed by AS
+<orderedlist>
+<listitem>
+<para>have an associated input queue (this may be internal, or explicit and externalized.</para>
+<para>They receive work units (CASes) from this queue, and return the updated CASes to an output queue which is specified as part of the message delivering the input work unit (CAS).</para></listitem>
+<listitem>
+<para>have a container which wraps the component and provides the following services (see
+<xref linkend="ugr.async.ov.fig.wrapAE"></xref>):
+<itemizedlist spacing="compact">
+<listitem>
+<para>A connection to an input queue of CASes to be processed</para></listitem>
+<listitem>
+<para>Scale-out within the JVM for components at the bottom level - the AS Primitives. Scaleout creates multiple instances of the annotator(s), and runs each one on its own thread, all drawing work from the same input queue.</para></listitem>
+<listitem>
+<para>(For AS Aggregates) connections to input queues of the delegates</para></listitem>
+<listitem>
+<para>A "pull" mechanism for the component to pull new CASes (to be processed) from their associated input queue </para></listitem>
+<listitem>
+<para>(For AS Aggregates) A separate, built-in internal queue to receive CASes back from delegates. These are passed to the aggregate's flow controller, which then specifies where they go next.</para></listitem>
+<listitem>
+<para>A connection to user-specified error handlers. Error conditions are communicated to the flow controller, to enable user / dynamically determined recovery or termination actions.</para></listitem></itemizedlist></para></listitem></orderedlist> </para>
+<figure id="ugr.async.ov.fig.wrapAE">
+<title>AS Primitive Wrapper</title>
+<mediaobject>
+<imageobject role="html">
+<imagedata width="279px" format="PNG" fileref="../images/uima_async_scaleout/async.overview/wrapAE.png"></imagedata></imageobject>
+<imageobject role="fo">
+<imagedata width="2.7in" format="PNG" fileref="../images/uima_async_scaleout/async.overview/wrapAE.png"></imagedata></imageobject>
+<textobject>
+<phrase>AS Primitive Wrapper</phrase></textobject></mediaobject></figure>
+<para>As shown in the next figure, when the component being wrapped is an AS Aggregate, the container will use the aggregate's flow controller (shown as "FC") to determine the flow of the CASes among the delegates. The next figure shows the additional output queue configured for aggregates to receive CASes returning from delegates. The dashed lines show how the queues are associated with the components.</para>
+<figure id="ugr.async.ov.fig.wrapAAE">
+<title>AS Aggregate wrapper</title>
+<mediaobject>
+<imageobject role="html">
+<imagedata width="590px" format="PNG" fileref="../images/uima_async_scaleout/async.overview/wrapAAE.png"></imagedata></imageobject>
+<imageobject role="fo">
+<imagedata width="5.5in" format="PNG" fileref="../images/uima_async_scaleout/async.overview/wrapAAE.png"></imagedata></imageobject>
+<textobject>
+<phrase>AS Aggregate Container wrapping an Aggregate Analysis Engine</phrase></textobject></mediaobject></figure>
+<para>The collection of parts and queues is wired together according to a deployment specification, provided by the deployer. This specification is a collection of one or more deployment descriptors.</para></section>
+<!-- end of wrapping -->
+<!-- ======================================================= -->
+<!-- | deployment alternatives | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.deploying">
+<title>Deployment alternatives</title>
+<para>Deployment is concerned with the following kinds of parts, and allocating these parts (possibly replicated) to various hosts:
+<itemizedlist spacing="compact">
+<listitem>
+<para>Application Drivers. These represent the top level caller of UIMA functionality. Examples include: stand-alone Java applications, such as the example document analyzer tool, a custom Web servlet, etc. </para></listitem>
+<listitem>
+<para>AS Services. AS primitive or AS aggregate services deployed on one or more nodes as needed to meet scalability requirements.</para></listitem>
+<listitem>
+<para>Queue Brokers. Each Queue Broker manages and provides the storage facility for one or more named queues. </para></listitem></itemizedlist> </para>
+<para>Parts can be co-located or not; when they're not, we say they're remote. Remote includes running on the same host, but in a different process space, using a different JVM or other native process. Connections between the parts are done using the JMS (Java Messaging Service) protocols, and in this version the support for this is provided by the ActiveMQ implementation from Apache.org. </para>
+<note>
+<para>For high availability, the Queue Brokers can be, themselves, replicated over many hosts, with fail-over capability provided by the underlying ActiveMQ implementation.</para></note>
+<!-- ======================================================= -->
+<!-- | Multiples for scaleout | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.deploying.multiples">
+<title>Configuring multiple instances of components</title>
+<titleabbrev>Multiple Instances</titleabbrev>
+<para>AS components can be replicated; the replicated components can be co-located or distributed across different nodes. The purpose of the replication is to allow multiple work units (CASes) to be processed in parallel, in multiple threads, either in the same host, or using different hosts. The vision is that the deployment is able to replicate just those components which are the bottleneck in overall system thruput. </para>
+<para>There are two ways replication can be specified.
+<orderedlist>
+<listitem>
+<para>In the deployment descriptor, set the numberOfInstances attribute to a number bigger than one.</para></listitem>
+<!--listitem><para>In the deployment descriptor, hook up multiple <service>
elements to the same input queue</para></listitem-->
- <listitem><para>Deploy the same service on many nodes, specifying the same input service queue</para></listitem>
- </orderedlist></para>
-
- <para>
- The first way is limited to replicating an AS Primitive. An AS Primitive can be
- the whole component of the service, or it can be
- at the bottom of an aggregate hierarchy of co-located parts.
- </para>
-
- <para>Replicating an AS Primitive has the
- effect of replicating all of its components, since no queues are used below its input queue. </para>
-
- </section>
-
- <!-- ======================================================= -->
- <!-- | Queues | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.deploying.queues">
- <title>Queues</title>
- <para>
- Asynchronous operation is enabled by use queues to connect components.
- Each queue is defined by a queue name and the URL of its Queue Broker.
- AS services register as queue consumers to obtain CASes to work on (as input) and to send
- CASes they're finished with (as output) to the reply queue specified by the AS client.
- </para>
- <para>
- For the AS-JMS/AMQ/Spring
- implementation, the queue implementation is provided by ActiveMQ queue broker.
- A single Queue Broker manages multiple queues.
- By default UIMA AS configures the Queue Broker to use in-memory queues, so the queue is resident on the
- same JVM as its managing Queue Broker.
- ActiveMQ offers serveral failsafe options, including the use of disc-based queues and redundant
- master/slave broker configurations.
- </para>
- <para>
- The decisions about where to deploy Queue Brokers are deployment decisions, made based on issues
- such as domain of control, firewalls, CPU / memory resources, etc. Of particular interest for distributed
- applications is that a UIMA AS service can be deployed behind a firewall but still be publicly available
- by using a queue broker that is available publicly.
- </para>
-
- <para>
- When components are co-located, an optimization is done so that CASes are not
- actually sent as they would be over the network; rather, a reference to
- the in-memory Java object is passed using the queue.
- </para>
-
- <warning><para>Do not hook up different kinds of services to the same input queue.
- The framework expects that multiple services all listening to a particular input queue are
- sharing the workload of processing CASes sent to that queue.
- The framework does not currently verify that all services on a queue are
- the same kind, but likely will in a future release.</para>
- </warning>
- </section>
-
- <!-- ======================================================= -->
- <!-- | deployment descriptors | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.deployment_descriptors">
- <title>Deployment Descriptors</title>
- <para>Each deployment descriptor specifies deployment information for one service, including
- all of its co-located delegates (if any).
- A service is an AS component, having one top level input queue, to which
- CASes are sent for processing.</para>
-
- <para>Each deployment descriptor has a reference to an associated Analysis Engine descriptor, which can
- be an aggregate, primitive (including CAS Consumers), or service client descriptor.</para>
-
- <para>AS Components and their associated queue brokers can be co-located on the
- same host/jvm; the deployment descriptor indicates which components (if any) are co-located on its
- host/jvm, and specifies the remote queues (queue-brokers and queue-names) for all other components.</para>
-
- <para>
- All services need to be manually started using an appropriate deployment descriptor
- (describing the things to be set up on that server).</para>
-
- <section id="ugr.async.ov.concepts.deployment_descriptors.aggregate">
- <title>Deploying UIMA aggregates</title>
- <para>UIMA aggregates can either be run asynchronously as AS Aggregates, or synchronously
- (as AS Primitives).
- AS Aggregates have a queue in front of each delegate; results from
- each delegate are sent to a receiving (internal) queue.
- UIMA aggregates run as AS Primitives send CASes synchronously to each delegate, without using
- any queuing mechanism.</para>
-
- <para>Each delegate in an AS Aggregate can be specified to be local or remote.
- Local means co-located using internal (hidden) queues; remote means all others, including
- delegates running in a different JVM, or in the same JVM but that can be shared by multiple clients
- For each delegate which is remote, the deployment
- descriptor specifies the delegate's input queue. If the delegate is local, an
- hidden, internal queue is automatically created for that delegate.</para>
- </section> <!-- of aggregate descriptors -->
-
-
-
- </section>
-
- </section> <!-- of deployment alternatives -->
- <!-- ======================================================= -->
- <!-- | First Limits | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.first_limits">
- <title>First implementation - Design limitations</title>
- <titleabbrev>Limits</titleabbrev>
- <para>
- This section describes limitations of the initial support for AS. Some of these limitations
- are due to the functionality being staged over several releases.
- </para>
- <!--
+<listitem>
+<para>Deploy the same service on many nodes, specifying the same input service queue</para></listitem></orderedlist></para>
+<para>The first way is limited to replicating an AS Primitive. An AS Primitive can be the whole component of the service, or it can be at the bottom of an aggregate hierarchy of co-located parts. </para>
+<para>Replicating an AS Primitive has the effect of replicating all of its components, since no queues are used below its input queue. </para></section>
+<!-- ======================================================= -->
+<!-- | Queues | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.deploying.queues">
+<title>Queues</title>
+<para>Asynchronous operation is enabled by use queues to connect components. Each queue is defined by a queue name and the URL of its Queue Broker. AS services register as queue consumers to obtain CASes to work on (as input) and to send CASes they're finished with (as output) to the reply queue specified by the AS client. </para>
+<para>For the AS-JMS/AMQ/Spring implementation, the queue implementation is provided by ActiveMQ queue broker. A single Queue Broker manages multiple queues. By default UIMA AS configures the Queue Broker to use in-memory queues, so the queue is resident on the same JVM as its managing Queue Broker. ActiveMQ offers several failsafe options, including the use of disc-based queues and redundant master/slave broker configurations. </para>
+<para>The decisions about where to deploy Queue Brokers are deployment decisions, made based on issues such as domain of control, firewalls, CPU / memory resources, etc. Of particular interest for distributed applications is that a UIMA AS service can be deployed behind a firewall but still be publicly available by using a queue broker that is available publicly. </para>
+<para>When components are co-located, an optimization is done so that CASes are not actually sent as they would be over the network; rather, a reference to the in-memory Java object is passed using the queue. </para>
+<warning>
+<para>Do not hook up different kinds of services to the same input queue. The framework expects that multiple services all listening to a particular input queue are sharing the workload of processing CASes sent to that queue. The framework does not currently verify that all services on a queue are the same kind, but likely will in a future release.</para></warning></section>
+<!-- ======================================================= -->
+<!-- | deployment descriptors | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.deployment_descriptors">
+<title>Deployment Descriptors</title>
+<para>Each deployment descriptor specifies deployment information for one service, including all of its co-located delegates (if any). A service is an AS component, having one top level input queue, to which CASes are sent for processing.</para>
+<para>Each deployment descriptor has a reference to an associated Analysis Engine descriptor, which can be an aggregate, primitive (including CAS Consumers), or service client descriptor.</para>
+<para>AS Components and their associated queue brokers can be co-located on the same host/jvm; the deployment descriptor indicates which components (if any) are co-located on its host/jvm, and specifies the remote queues (queue-brokers and queue-names) for all other components.</para>
+<para>All services need to be manually started using an appropriate deployment descriptor (describing the things to be set up on that server).</para>
+<section id="ugr.async.ov.concepts.deployment_descriptors.aggregate">
+<title>Deploying UIMA aggregates</title>
+<para>UIMA aggregates can either be run asynchronously as AS Aggregates, or synchronously (as AS Primitives). AS Aggregates have a queue in front of each delegate; results from each delegate are sent to a receiving (internal) queue. UIMA aggregates run as AS Primitives send CASes synchronously to each delegate, without using any queuing mechanism.</para>
+<para>Each delegate in an AS Aggregate can be specified to be local or remote. Local means co-located using internal (hidden) queues; remote means all others, including delegates running in a different JVM, or in the same JVM but that can be shared by multiple clients For each delegate which is remote, the deployment descriptor specifies the delegate's input queue. If the delegate is local, an hidden, internal queue is automatically created for that delegate.</para></section>
+<!-- of aggregate descriptors --></section></section>
+<!-- of deployment alternatives -->
+<!-- ======================================================= -->
+<!-- | First Limits | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.first_limits">
+<title>First implementation - Design limitations</title>
+<titleabbrev>Limits</titleabbrev>
+<para>This section describes limitations of the initial support for AS. Some of these limitations are due to the functionality being staged over several releases. </para>
+<!--
<para>There are several kinds of limitations:
<itemizedlist spacing="compact">
<!-
@@ -831,7 +514,7 @@
<listitem><para>Resource Sharing</para></listitem>
</itemizedlist></para>
-->
- <!--
+<!--
<section id="ugr.async.ov.concepts.first_limits.descriptors">
<title>XML Descriptor limits</title>
<para>The ultimate design goal is to retain the UIMA descriptors for
@@ -847,85 +530,60 @@
and when that happens, the information must be the same (but will not be checked).
</para>
</section> -->
-
- <section id="ugr.async.ov.concepts.first_limits.sofa_mapping">
- <title>Sofa Mapping limits</title>
- <para>Sofa mapping works for co-located delegates, only.
- As with Vinci and SOAP, remote delegates needing sofa mapping need to respecify sofa
- mappings in an aggregate descriptor at the remote node.</para>
- </section>
-
- <section id="ugr.async.ov.concepts.first_limits.parameter_overriding">
- <title>Parameter Overriding limits</title>
- <para>Parameter overrides only work for co-located delegates.
- As with Vinci and SOAP, remote delegates needing parameter overrides need to respecify
- the overrides in an aggregate descriptor at the remote node.</para>
- </section>
-
- <section id="ugr.async.ov.concepts.first_limits.resource_sharing">
- <title>Resource Sharing limits</title>
- <para>Resource Sharing works for co-located delegates, only.
- </para>
- </section>
- <!--
+<section id="ugr.async.ov.concepts.first_limits.sofa_mapping">
+<title>Sofa Mapping limits</title>
+<para>Sofa mapping works for co-located delegates, only. As with Vinci and SOAP, remote delegates needing sofa mapping need to respecify sofa mappings in an aggregate descriptor at the remote node.</para></section>
+<section id="ugr.async.ov.concepts.first_limits.parameter_overriding">
+<title>Parameter Overriding limits</title>
+<para>Parameter overrides only work for co-located delegates. As with Vinci and SOAP, remote delegates needing parameter overrides need to respecify the overrides in an aggregate descriptor at the remote node.</para></section>
+<section id="ugr.async.ov.concepts.first_limits.resource_sharing">
+<title>Resource Sharing limits</title>
+<para>Resource Sharing works for co-located delegates, only. </para></section>
+<!--
<section id="ugr.async.ov.concepts.first_limits.xyz">
<title>XYZ limits</title>
<para></para>
</section>
- -->
- </section>
-
- <section id="ugr.async.ov.concepts.first_limits.compatibility">
- <title>Compatibility with earlier version of remoting and scaleout</title>
- <titleabbrev>Compatibility</titleabbrev>
- <para>A Vinci client service descriptor can be used in an aggregate descriptor as before, and can be
- used as a primitive analysis engine in a deployment descriptor. There is a new type of client service
- descriptor for an AS service, the JMS service descriptor;
- see <xref linkend="ugr.async.ov.concepts.jms_descriptor"/>
- </para>
- </section>
-
- </section> <!-- of ov.concepts.first_limits -->
-
-
- <!-- ======================================================= -->
- <!-- | Application Level Concepts | -->
- <!-- ======================================================= -->
-
- <section id="ugr.async.ov.concepts.application">
- <title>Application Concepts</title>
- <para>
- When UIMA is used, it is called using Application APIs. A typical top-level driver
- has this basic flow:
- <orderedlist spacing="compact">
- <listitem><para>Read UIMA descriptors and instantiate components</para></listitem>
- <listitem><para>Do a Run</para></listitem>
- <listitem><para>Do another Run, etc.</para></listitem>
- <listitem><para>Stop</para></listitem>
- </orderedlist>
- <note><para>The initial release limits this flow to one run.</para></note>
- </para>
-
- <para>
- A "run", in turn, consists of 3 parts:
- <orderedlist spacing="compact">
- <listitem><para>initialize (or reinitialize, if already run)</para></listitem>
- <listitem><para>process CASes</para></listitem>
- <listitem><para>finish (collectionProcessComplete is called)</para></listitem>
- </orderedlist>
- </para>
-
- <para>Initialize is called by the framework when the instance is created. The other methods need to be called by
- the driver. <literal>collectionProcessComplete</literal> should be called when the driver determines that it is finished
- sending input CASes for processing using the <literal>process()</literal> method.
- <literal>reinitialize()</literal> can be called if needed, after changing parameter settings, to get the
- co-located components to reinitialize.
- </para>
-
- <section id="ugr.async.ov.concepts.application.api">
- <title>Application API</title>
- <para>Please see the sample code.</para>
- <!--
+ --></section>
+<section id="ugr.async.ov.concepts.first_limits.compatibility">
+<title>Compatibility with earlier version of remoting and scaleout</title>
+<titleabbrev>Compatibility</titleabbrev>
+<para>A Vinci client service descriptor can be used in an aggregate descriptor as before, and can be used as a primitive analysis engine in a deployment descriptor. There is a new type of client service descriptor for an AS service, the JMS service descriptor; see
+<xref linkend="ugr.async.ov.concepts.jms_descriptor"></xref> </para></section></section>
+<!-- of ov.concepts.first_limits -->
+<!-- ======================================================= -->
+<!-- | Application Level Concepts | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.application">
+<title>Application Concepts</title>
+<para>When UIMA is used, it is called using Application APIs. A typical top-level driver has this basic flow:
+<orderedlist spacing="compact">
+<listitem>
+<para>Read UIMA descriptors and instantiate components</para></listitem>
+<listitem>
+<para>Do a Run</para></listitem>
+<listitem>
+<para>Do another Run, etc.</para></listitem>
+<listitem>
+<para>Stop</para></listitem></orderedlist>
+<note>
+<para>The initial release limits this flow to one run.</para></note> </para>
+<para>A "run", in turn, consists of 3 parts:
+<orderedlist spacing="compact">
+<listitem>
+<para>initialize (or reinitialize, if already run)</para></listitem>
+<listitem>
+<para>process CASes</para></listitem>
+<listitem>
+<para>finish (collectionProcessComplete is called)</para></listitem></orderedlist> </para>
+<para>Initialize is called by the framework when the instance is created. The other methods need to be called by the driver.
+<literal>collectionProcessComplete</literal> should be called when the driver determines that it is finished sending input CASes for processing using the
+<literal>process()</literal> method.
+<literal>reinitialize()</literal> can be called if needed, after changing parameter settings, to get the co-located components to reinitialize. </para>
+<section id="ugr.async.ov.concepts.application.api">
+<title>Application API</title>
+<para>Please see the sample code.</para>
+<!--
<para>AS provides an interface, <literal>UIMAAsynchronousEngine</literal>, to enable
the driver code to instantiate and initialize a set of AS components, and run them.
@@ -1002,11 +660,8 @@
*/
public void collectionProcessComplete() throws ResourceProcessException;
}
- -->
- </section>
-
-
- <!--
+ --></section>
+<!--
<para>The following concepts are tied to <emphasis role="bold">runs</emphasis>:
<itemizedlist>
<listitem><para>Aggregate statistics delivered by monitoring</para></listitem>
@@ -1015,58 +670,26 @@
</itemizedlist>
</para>
-->
-
- <!-- ======================================================= -->
- <!-- | Collection Process Complete | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.collection_process_complete">
- <title>Collection Process Complete</title>
- <para>
- Applications may want to signal a chain of annotators being used
- in a particular "run" when all CASes for this run have been processed, and
- any final computation and outputting is to be done; it
- calls the collectionProcessComplete method to do this.
- This is
- frequently done when using statefull components which are
- accumulating information over multiple documents.
- </para>
-
- <para>
- It is up to the application to determine when
- the run is finished and there are no more CASes to process.
- It then calls this method on the top level analysis engine; the
- framework propagates this method call to all delegates of this aggregate,
- and this is repeated recursively for all delegate aggregates.
- </para>
- <para>
- This call is synchronous, meaning
- when this call is issued by an application, the framework will
- block the thread issuing the call until all processing of CASes
- within the aggregate has completed and the collectionProcessComplete method
- has returned (or timed out) from every component it was sent to.
- <!--If the top level component
+<!-- ======================================================= -->
+<!-- | Collection Process Complete | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.collection_process_complete">
+<title>Collection Process Complete</title>
+<para>Applications may want to signal a chain of annotators being used in a particular "run" when all CASes for this run have been processed, and any final computation and outputting is to be done; it calls the collectionProcessComplete method to do this. This is frequently done when using statefull components which are accumulating information over multiple documents. </para>
+<para>It is up to the application to determine when the run is finished and there are no more CASes to process. It then calls this method on the top level analysis engine; the framework propagates this method call to all delegates of this aggregate, and this is repeated recursively for all delegate aggregates. </para>
+<para>This call is synchronous, meaning when this call is issued by an application, the framework will block the thread issuing the call until all processing of CASes within the aggregate has completed and the collectionProcessComplete method has returned (or timed out) from every component it was sent to.
+<!--If the top level component
is an Aggregate, the components of that aggregate receive this
method call in an arbitrary order, and possibly in parallel (on different
threads),
with one exception: An aggregate
being run synchronously using fixed-flow sequencing will have the
collection complete method call done to each component, synchronously,
- in the order specified in the fixed flow. -->
- </para>
-
- <para>
- Components receive this call in a fixed order taken from the
- <fixedFlow> sequence information in the descriptors, if that is
- available, and in an arbitrary order otherwise.
- </para>
-
- <para>
- If a component is replicated, only one of the instances will receive the
- collectionProcessComplete call.
- <!--Components which are not co-located also receive this call.-->
- </para>
-
- <!--
+ in the order specified in the fixed flow. --> </para>
+<para>Components receive this call in a fixed order taken from the <fixedFlow> sequence information in the descriptors, if that is available, and in an arbitrary order otherwise. </para>
+<para>If a component is replicated, only one of the instances will receive the collectionProcessComplete call.
+<!--Components which are not co-located also receive this call.--> </para>
+<!--
<para>
If more complex control is desired to handle end-of-run operations, users
should not use this method. Instead, they should
@@ -1076,8 +699,7 @@
which the user can write, can then route the CAS in any manner that it
needs to.
</para> -->
-
- <!--
+<!--
<blockquote>
<para>The flow controller has additional capabilities to enable it to
perform this work. It can
@@ -1090,15 +712,14 @@
</itemizedlist></para>
</blockquote>
-->
-
- <!--
+<!--
<para>
To aid in this process, the framework provides a method to signal when
there are no more CASes active within an aggregate (or primitive).
</para>
-->
- <!--
-For an aynch aggregate AE, the behavior of this call is:
+<!--
+For an asynch aggregate AE, the behavior of this call is:
1) The aggregate controller must wait (block) until all processing of CASes has completely finished.
2) The collectionProcessComplete() is then broadcast to all delegates in no particular order.
@@ -1145,101 +766,58 @@
in those cases. The use of the process(CAS) method for these is more general.
It also allows components to read from / write to the CAS during collectionProcessComplete,
which could be a useful feature.
- -->
-
- </section>
- </section>
-
- <!-- ======================================================= -->
- <!-- | Monitoring and Controlling | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.mc">
- <title>Monitoring and Controlling an AS application</title>
- <titleabbrev>Monitoring & Controlling</titleabbrev>
- <para>
- JMX (Java Management Extensions) are used for monitoring and controlling an AS application.
- This capability is being staged; initial versions have some monitoring capability, but little
- controlling capability.
- </para>
-
- <para>
- The first versions of AS will use the standard GUI tooling available as part of Java 5 to
- display the JMX results. Later versions may include additional UIMA-specific tooling for this.
- </para>
-
- <section id="ugr.async.ov.concepts.mc.what">
- <title>Instrumentation provided</title>
- <para>
- The implementation provides the following kinds of instrumentation via JMX:
- <itemizedlist>
- <listitem>
- <para>Timing</para>
- <itemizedlist spacing="compact">
- <listitem><para>by component, by CAS(?)</para></listitem>
- <listitem><para>by queue</para></listitem>
- <listitem><para>message transit & serialization/deserialization</para></listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>component / host status</para>
- <itemizedlist spacing="compact">
- <listitem><para>by component</para></listitem>
- <listitem><para>state: OK, Idle, Working, Stopped, restarting, etc.</para></listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </para>
- </section> <!-- of ugr.async.ov.concepts.mc.what -->
- </section> <!-- of ugr.async.ov.concepts.mc -->
-
-
- <!-- ======================================================= -->
- <!-- | JMS Service Descriptor | -->
- <!-- ======================================================= -->
- <section id="ugr.async.ov.concepts.jms_descriptor">
- <title>JMS Service Descriptor</title>
- <para>To call a UIMA AS Service from Document Analyzer or any other base UIMA application,
- use a descriptor such as the following:
- </para>
- <programlisting><![CDATA[<customResourceSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
- <resourceClassName>
- org.apache.uima.aae.jms_adapter.JmsAnalysisEngineServiceAdapter
- </resourceClassName>
- <parameters>
- <parameter name="brokerURL"
- value="tcp://uima17.watson.ibm.com:61616"/>
- <parameter name="endpoint"
- value="uima.ee.RoomDateMeetingDetectorAggregateQueue"/>
- </parameters>
+ --></section></section>
+<!-- ======================================================= -->
+<!-- | Monitoring and Controlling | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.mc">
+<title>Monitoring and Controlling an AS application</title>
+<titleabbrev>Monitoring & Controlling</titleabbrev>
+<para>JMX (Java Management Extensions) are used for monitoring and controlling an AS application. This capability is being staged; initial versions have some monitoring capability, but little controlling capability. </para>
+<para>The first versions of AS will use the standard GUI tooling available as part of Java 5 to display the JMX results. Later versions may include additional UIMA-specific tooling for this. </para>
+<section id="ugr.async.ov.concepts.mc.what">
+<title>Instrumentation provided</title>
+<para>The implementation provides the following kinds of instrumentation via JMX:
+<itemizedlist>
+<listitem>
+<para>Timing</para>
+<itemizedlist spacing="compact">
+<listitem>
+<para>by component, by CAS(?)</para></listitem>
+<listitem>
+<para>by queue</para></listitem>
+<listitem>
+<para>message transit & serialization/deserialization</para></listitem></itemizedlist></listitem>
+<listitem>
+<para>component / host status</para>
+<itemizedlist spacing="compact">
+<listitem>
+<para>by component</para></listitem>
+<listitem>
+<para>state: OK, Idle, Working, Stopped, restarting, etc.</para></listitem></itemizedlist></listitem></itemizedlist> </para></section>
+<!-- of ugr.async.ov.concepts.mc.what --></section>
+<!-- of ugr.async.ov.concepts.mc -->
+<!-- ======================================================= -->
+<!-- | JMS Service Descriptor | -->
+<!-- ======================================================= -->
+<section id="ugr.async.ov.concepts.jms_descriptor">
+<title>JMS Service Descriptor</title>
+<para>To call a UIMA AS Service from Document Analyzer or any other base UIMA application, use a descriptor such as the following: </para>
+<programlisting>
+<![CDATA[<customResourceSpecifier xmlns="http://uima.apache.org/resourceSpecifier">
+<resourceClassName>
+org.apache.uima.aae.jms_adapter.JmsAnalysisEngineServiceAdapter
+</resourceClassName>
+<parameters>
+<parameter name="brokerURL"
+value="tcp://uima17.watson.ibm.com:61616"/>
+<parameter name="endpoint"
+value="uima.as.RoomDateMeetingDetectorAggregateQueue"/>
+</parameters>
</customResourceSpecifier>]]></programlisting>
- <para>The resouceClassName must be set exactly as shown. Set the brokerURL and endpoint parameters
- to the appropriate values for the UIMA AS Service you want to call. These are the same settings
- you would use in a deployment descriptor to specify the location of a remote delegate. Note that
- this is a synchronous adapter, which processes one CAS at a time, so it will not take advantage of
- the scalability that UIMA AS provides. To process more than one CAS at a time, you must use the
- Asynchronous UIMA AS Client.</para>
-
- <para>For more information on the customResourceSpecifier see
- <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.component_descriptor.custom_resource_specifiers"/>.
- </para>
- </section>
-
- <section id="ugr.async.ov.concepts.collection_reader">
- <title>Collection Reader support</title>
- <para>
- Collection Readers are supported for backwards compatibility; new programs should use the Cas Multiplier.
- The compatibility is achieved by wrapping the Collection Reader so that it looks like a Cas Multiplier.
- Because of this implementation, you can use a CollectionReader descriptor anywhere that a CAS Multiplier
- descriptor would work. Calls to the CAS Multiplier's next() method are translated into calls to the
- Collection Reader's getNext() method. Since a Collection Reader cannot accept a CAS as input,
- calls to the CAS Multiplier's process(CAS) method will be translated into calls to the
- Collection Reader's reconfigure() method
- (except for the very first call to process(), which is ignored).
- This is done so that if a Collection Reader reacts to reconfigure() by
- resetting its state to be at the beginning of the collection,
- then when deployed as a CAS Multiplier service it can be
- reused multiple times without having to restart the service.
- </para>
- </section>
-
-</chapter>
+<para>The resouceClassName must be set exactly as shown. Set the brokerURL and endpoint parameters to the appropriate values for the UIMA AS Service you want to call. These are the same settings you would use in a deployment descriptor to specify the location of a remote delegate. Note that this is a synchronous adapter, which processes one CAS at a time, so it will not take advantage of the scalability that UIMA AS provides. To process more than one CAS at a time, you must use the Asynchronous UIMA AS Client.</para>
+<para>For more information on the customResourceSpecifier see
+<olink targetdoc="references" targetptr="ugr.ref.xml.component_descriptor.custom_resource_specifiers"></olink>. </para></section>
+<section id="ugr.async.ov.concepts.collection_reader">
+<title>Collection Reader support</title>
+<para>Collection Readers are supported for backwards compatibility; new programs should use the Cas Multiplier. The compatibility is achieved by wrapping the Collection Reader so that it looks like a Cas Multiplier. Because of this implementation, you can use a CollectionReader descriptor anywhere that a CAS Multiplier descriptor would work. Calls to the CAS Multiplier's next() method are translated into calls to the Collection Reader's getNext() method. Since a Collection Reader cannot accept a CAS as input, calls to the CAS Multiplier's process(CAS) method will be translated into calls to the Collection Reader's reconfigure() method (except for the very first call to process(), which is ignored). This is done so that if a Collection Reader reacts to reconfigure() by resetting its state to be at the beginning of the collection, then when deployed as a CAS Multiplier service it can be reused multiple times without having to restart the service. </para></section></chapter>
\ No newline at end of file
Modified: incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml?rev=655671&r1=655670&r2=655671&view=diff
==============================================================================
--- incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml (original)
+++ incubator/uima/sandbox/trunk/uima-as/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml Mon May 12 15:22:05 2008
@@ -28,26 +28,29 @@
<title>Asynchronous Scaleout Application Interface</title>
<section id="ugr.ref.async.api.organization">
- <title>Asynchonous API Overview</title>
+ <title>Asynchronous API Overview</title>
<para>
The Asynchronous API provides Java applications the capability to connect to
- and to make reqests UIMA EE services. ProcessCas and CollectionProcessingComplete
+ and to make requests UIMA-AS services. ProcessCas and CollectionProcessingComplete
requests are supported.
</para>
<para>
- An application can prepare and send each CAS to a service one at a time, or
+ An application can use this API to
+ prepare and send each CAS to a service one at a time, or
alternately can use a UIMA collection reader to prepare the CASes to be delivered.
The application must provide a listener class to receive asynchronous replies.
For individual CAS requests a synchronous sendAndReceive call is available.
- Note that for synchronous requests to a
- UIMA EE service, the standard UIMA Analysis Engine APIs
+ As an alternative for this case (for synchronous requests to a
+ UIMA-AS service), instead of using this client API,
+ the standard UIMA Analysis Engine APIs
can be used with an analysis engine instantiated from a JMS Service Descriptor.
See <xref linkend="ugr.async.ov.concepts.jms_descriptor"/>.
</para>
<para>
- Other options include specifying the maximum number of outstanding requests allowed, timeout
+ Other options available in this API include
+ specifying the maximum number of outstanding requests allowed, timeout
values and the size of local Cas pool to create.
</para>
@@ -69,7 +72,7 @@
<section id="ugr.ref.async.api.descriptor">
<title>The UimaAsynchronousEngine Interface</title>
- <para>An application developer's starting point for accessing UIMA EE services is the
+ <para>An application developer's starting point for accessing UIMA-AS services is the
UimaAsynchronousEngine Interface. For each service an application wants to use, it
must instantiate a client object:
@@ -82,9 +85,9 @@
<listitem>
<para>void initialize( Map anApplicationContext ): Initializes asynchronous client.
Using configuration provided in a given Map object, this method creates a connection to
- UIMA EE Service queue, creates a response queue, and retrieves service metadata.
+ the UIMA-AS Service queue, creates a response queue, and retrieves the service metadata.
This method blocks until a reply is received from the service or a timeout occurs.
- If a collection reader has been specified, it's typesystem is merged with that from the
+ If a collection reader has been specified, its typesystem is merged with that from the
service. The combined typesystem is used to create a Cas pool.
On success the application is notified via the listener's initializationComplete() method.
Asynchronous errors are delivered to the listener's entityProcessComplete() method.
@@ -93,8 +96,8 @@
</listitem>
<listitem>
- <para>void addStatusCallbackListener(StatusCallbackListener aListener):
- Plugs-in application specific listener. The application receives callbacks
+ <para>void addStatusCallbackListener(UimaASStatusCallbackListener aListener):
+ Plugs in an application-specific listener. The application receives callbacks
via methods in this listener class. More than one listener can be added.
</para>
</listitem>
@@ -108,9 +111,9 @@
</listitem>
<listitem>
- <para>void sendCAS( CAS aCAS ): Sends a given CAS for analysis to UIMA EE Service.
+ <para>void sendCAS( CAS aCAS ): Sends a given CAS for analysis to the UIMA-AS Service.
This method may block if the client is configured to use a reply window which prevents
- from sending too many CASes to the service. Assuming the window is large enough to send
+ 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.
The application is notified of responses or timeouts via entityProcessComplete().
</para>
@@ -134,22 +137,22 @@
<listitem>
<para>void collectionProcessingComplete(): Sends a Collection Processing Complete request
- to UIMA EE Analysis Service. The method blocks until the service replies or a timeout occurs.
- On success the application is notified via the listener's initializationComplete() method.
- Asynchronous errors are delivered to the listener's entityProcessComplete() method.
+ to the UIMA-AS Analysis Service. The method blocks until the service replies or a timeout occurs.
+ On success the application is notified via the listener's collectionProcessComplete() method.
+
</para>
</listitem>
<listitem>
<para>void sendAndReceiveCAS(CAS aCAS):
Send a CAS, wait for response. On success aCAS contains the analysis results.
- Errors are delivered to the listener's entityProcessComplete() method.
+ Throws an exception on error.
</para>
</listitem>
<listitem>
<para>String deploy( String aDeploymentDescriptor, Map anApplicationContext):
- Deploys UIMA EE service specified by given deployment descriptor and returns a handle
+ Deploys the UIMA-AS service specified by the given deployment descriptor and returns a handle
to the Spring container for this service.
The application context map must contain DD2SpringXsltFilePath and SaxonClasspath entries.
This call blocks until the service is ready to process requests, or an exception occurs
@@ -165,9 +168,9 @@
<listitem>
<para>void stop():
- Stops the asynchronous client. Removes Cas pool, drops connection to the UIMA EE
- service queue and stops listening on it's response queue.
- Also, terminates and undeploys any services which have been started with this client.
+ Stops the asynchronous client. Removes the Cas pool, drops the connection to the UIMA-AS
+ service queue and stops listening on its response queue.
+ Terminates and undeploys any services which have been started with this client.
</para>
</listitem>
@@ -194,7 +197,7 @@
</listitem>
<listitem>
- <para>ServerURI: Broker connector for service. Required for initialize.</para>
+ <para>ServerUri: Broker connector for service. Required for initialize.</para>
</listitem>
<listitem>
@@ -202,15 +205,27 @@
</listitem>
<listitem>
+ <para>Resource Manager: (Optional) a UIMA ResourceManager to use for the client.</para>
+ </listitem>
+
+ <listitem>
<para>CasPoolSize: Size of Cas pool to create to send to specified service. Default = 1.</para>
</listitem>
<listitem>
+ <para>CAS_INITIAL_HEAPSIZE: (Optional) the initial CAS heapsize.</para>
+ </listitem>
+
+ <listitem>
<para>ReplyWindow: Maximum number of outstanding process CAS requests that can be sent.
Default = 5.</para>
</listitem>
<listitem>
+ <para>Application Name: optional name of the application using this API, for logging.</para>
+ </listitem>
+
+ <listitem>
<para>Timeout: Process CAS timeout in ms. Default = no timeout.</para>
</listitem>
@@ -234,7 +249,7 @@
<title>Status Callback Listener</title>
<para>Asynchronous events are delivered to applications via methods in classes registered
to the API object with addStatusCallbackListener(). These classes must implement the
- interface org.apache.uima.aae.client.UimaAsStatusCallbackListener.
+ interface org.apache.uima.aae.client.UimaASStatusCallbackListener.
<itemizedlist>
<listitem>
@@ -284,7 +299,7 @@
</section>
<section id="ugr.ref.async.api.usage">
- <title>Asynchonous API Usage Scenarios</title>
+ <title>Asynchronous API Usage Scenarios</title>
<section id="ugr.ref.async.api.usage_initialize">
<title>Instantiating a Client API Object</title>
@@ -329,12 +344,12 @@
</section>
<section id="ugr.ref.async.api.usage_getresults">
- <title>Retrieving Asynchonous Results</title>
+ <title>Retrieving Asynchronous Results</title>
<para>
Asynchronous events resulting from the process Cas request are passed to the registered listener.
<programlisting>
-// Callback Listener. Receives event notifications from CPE.
-class MyStatusCallbackListener implements StatusCallbackListener {
+// Callback Listener. Receives event notifications from UIMA-AS.
+class MyStatusCallbackListener implements UimaASStatusCallbackListener {
// Method called when the processing of a Document is completed.
public void entityProcessComplete(CAS aCas, EntityProcessStatus aStatus) {
@@ -368,7 +383,7 @@
appCtx.put(UimaAsynchronousEngine.DD2SpringXsltFilePath,
System.getenv("UIMA_HOME") + "/bin/dd2spring.xsl");
appCtx.put(UimaAsynchronousEngine.SaxonClasspath,
- "file:" + System.getenv("UIMA_HOME") + "/lib/saxon8.jar");
+ "file:" + System.getenv("UIMA_HOME") + "/saxon/saxon8.jar");
uimaAsEngine.deploy(service, appCtx);
</programlisting>
</para>
@@ -381,7 +396,7 @@
<section id="ugr.ref.async.api.sample.code">
<title>Sample Code</title>
- <para>See $UIMA_HOME/examples/src/org/apache/uima/examples/ee/RunRemoteAsyncAE.java
+ <para>See $UIMA_HOME/examples/src/org/apache/uima/examples/as/RunRemoteAsyncAE.java
</para>
</section>