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 2006/12/07 23:08:08 UTC

svn commit: r483694 [6/10] - in /incubator/uima/uimaj/trunk/uima-docbooks: ./ lib/ src/docbook/ src/docbook/overview_and_setup/ src/docbook/references/ src/docbook/references/images/ref.javadocs/ src/docbook/tools/ src/docbook/tutorials_and_users_guide...

Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml?view=diff&rev=483694&r1=483693&r2=483694
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/references/ref.xml.cpe_descriptor.xml Thu Dec  7 14:08:05 2006
@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "../images/annotator_analysis_engine_files/" >
+<!ENTITY imgroot "../images/references/ref.xml.cpe_descriptor/">
+<!ENTITY tp "ugr.ref.xml.cpe_descriptor.">
 <!ENTITY % uimaents SYSTEM "../entities.ent" >  
 %uimaents;
 ]>
@@ -24,1229 +25,1337 @@
 under the License.
 -->
 <chapter id="ugr.ref.xml.cpe_descriptor">
-  <title></title>
-  <section name="Collection Processing Engine Descriptor Reference"><a id="_crossRef160"> </a>
-
-
-
-<para>A UIMA <emphasis>Collection Processing Engine</emphasis> (CPE) is a
-combination of UIMA components assembled to analyze a collection of
-artifacts.  A CPE is an instantiation of
-the UIMA <emphasis>Collection Processing Architecture</emphasis>, which defines the
-collection processing components, interfaces, and APIs.  A CPE is executed by a UIMA framework
-component called the <emphasis>Collection Processing Manager</emphasis> (CPM), which provides
-a number of services for deploying CPEs, running CPEs, and handling errors.</para>
-
-<para>A CPE can be assembled programmatically within a Java
-application, or it can be assembled declaratively via a CPE configuration
-specification, called a CPE Descriptor. This chapter describes the format of
-the CPE Descriptor.</para>
-
-<para>Details about the CPE, including its function,
-sub-components, APIs, and related tools, can be found in <a class="crossrefText" href="CPE_Developers_Guide.htm#_crossRef183">Chapter
-5, <b>Collection Processing
-Engine Developer&apos;s Guide</b></a><emphasis>.</emphasis> Here we briefly summarize the
-CPE to define terms and provide context for the later sections that describe
-the CPE Descriptor.</para>
-
-
-
-<subsection name="CPE Overview"><a id="_crossRef161"> </a>
-
-
-
-<para><img alt="" width="550" height="301" src="../UIMA_SDK_Guide_Ref/CPE_Descriptor_Reference_files/image002.png"/></para>
-
-<a class="figCaption" id="_crossRef162">CPE Runtime Overview</a>
-
-<para>An illustration of the CPE runtime is shown in <a class="figReference" href="#_crossRef162">Figure nn</a>.  Some of the CPE components, such as the <emphasis>queues</emphasis> and <emphasis>processing
-pipelines</emphasis>, are internal to the CPE, but their behavior and deployment may
-be configured using the CPE Descriptor.  Other CPE components, such as the <emphasis>Collection Reader</emphasis> and <emphasis>CAS
-Processors</emphasis>, are defined and configured externally from the CPE and then
-plugged in to the CPE to create the overall engine.  The parts of a CPE are:</para>
-
-<para><b>Collection Reader</b> &ndash;understands the native data
-collection format and iterates over the collection producing subjects of
-analysis</para>
-
-<para><b>CAS Initializer</b> &ndash;initializes a CAS with a subject
-of analysis</para>
-
-<para><b>Artifact Producer</b> &ndash; asynchronously pulls CASes from
-the Collection Reader, creates batches of CASes and puts them into the work
-queue</para>
-
-<para><b>Work Queue</b> &ndash; shared queue containing batches of
-CASes queued by the Artifact Producer for analysis by Analysis Engines</para>
-
-<para><b>B1-Bn</b> &ndash; individual batches containing 1 or more
-CASes</para>
-
-<para><b>AE1-AEn</b> &ndash; Analysis Engines arranged by a CPE
-descriptor</para>
-
-<para><b>Processing Pipelines</b> &ndash; each pipeline runs in a
-separate thread and contains a replicated set of the Analysis Engines running
-in the defined sequence</para>
-
-<para><b>Output Queue</b> &ndash; holds batches of CASes with analysis
-results intended for CAS Consumers</para>
-
-<para><b>CAS Consumers</b> &ndash;perform collection level analysis
-over the CASes and extract analysis results, e.g., creating indexes or
-databases</para>
-
-
-
-
-
-
-  </subsection>
-<subsection name="Notation"><a id="_crossRef163"> </a>
-
-
-
-<para>CPE Descriptors are XML files.  This chapter uses an informal notation to
-specify the syntax of CPE Descriptors.</para>
-
-<para>The notation used in this chapter is:</para>
-
-<itemizedlist><listitem>An
-ellipsis (...) inside an element body indicates that the substructure
-of that element has been omitted (to be described in another section of this chapter).
-An example of this would be:
-</listitem></itemizedlist>
-
-<programlisting>&lt;collectionReader&gt;</programlisting>
-
-<programlisting>...</programlisting>
-
-<programlisting>&lt;/collectionReader&gt;</programlisting>
-
-<itemizedlist><listitem>An ellipsis immediately after an
-element indicates that the element type may be repeated arbitrarily many
-times.  For example:
-</listitem></itemizedlist>
-
-<programlisting>&lt;parameter&gt;[String]&lt;/parameter&gt;</programlisting>
-
-<programlisting>&lt;parameter&gt;[String]&lt;/parameter&gt;</programlisting>
-
-<programlisting>...</programlisting>
-
-<para>indicates that there may be
-arbitrarily many parameter elements in this context.</para>
-
-<itemizedlist><listitem>An ellipsis inside an element
-means details of the attributes associated with that element are defined later,
-e.g.:
-</listitem></itemizedlist>
-
-<programlisting>&lt;casProcessor ...&gt;</programlisting>
-
-<itemizedlist><listitem>Bracketed expressions (e.g. <literal>[String]</literal>) indicate the type of value that
-may be used at that location.</listitem>
-
-
-<listitem>A vertical bar, as in <literal>true|false</literal>, indicates alternatives.  This can be applied to literal values,
-bracketed type names, and elements.
-</listitem></itemizedlist>
-
-<para>Which elements are optional and which are required is
-specified in prose, not in the syntax definition.</para>
-
-
-
-
-  </subsection>
-<subsection name="Imports"><a id="_crossRef164"> </a>
-
-
-
-<para>A CPE Descriptor uses the following notation to reference
-descriptors for other components that are incorporated into the defined CPE:</para>
-
-<programlisting>&lt;descriptor&gt;
-    &lt;include href=<quote>[File]</quote>/&gt;
-&lt;/descriptor&gt;</programlisting>
-
-<para>The <literal>[File]</literal>
-attribute is a filename for the descriptor of the incorporated component.  A fully qualified filename may be provided,
-or the filename may relative to a directory specified using the <literal>CPM_HOME</literal> variable, e.g.,</para>
-
-<programlisting>&lt;descriptor&gt;
+  <title>Collection Processing Engine Descriptor Reference</title>
+  
+  <para>A UIMA <emphasis>Collection Processing Engine</emphasis> (CPE) is a combination
+    of UIMA components assembled to analyze a collection of artifacts. A CPE is an
+    instantiation of the UIMA <emphasis>Collection Processing Architecture</emphasis>,
+    which defines the collection processing components, interfaces, and APIs. A CPE is
+    executed by a UIMA framework component called the <emphasis>Collection Processing
+    Manager</emphasis> (CPM), which provides a number of services for deploying CPEs,
+    running CPEs, and handling errors.</para>
+  
+  <para>A CPE can be assembled programmatically within a Java application, or it can be
+    assembled declaratively via a CPE configuration specification, called a CPE
+    Descriptor. This chapter describes the format of the CPE Descriptor.</para>
+  
+  <para>Details about the CPE, including its function, sub-components, APIs, and related
+    tools, can be found in <olink targetdoc="&uima_docs_tutorial_guides;"
+      targetptr="ugr.tug.cpe"/>. Here we briefly summarize the CPE to define terms and
+    provide context for the later sections that describe the CPE Descriptor.</para>
+  
+  <section id="&tp;overview">
+    <title>CPE Overview</title>
+    
+    <figure id="&tp;overview.fig.runtime">
+      <title>CPE Runtime Overview</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata width="550" depth="301" format="PNG"
+            fileref="&imgroot;image002.png"/>
+        </imageobject>
+        <textobject><phrase>CPE Runtime Overview diagram</phrase></textobject>
+      </mediaobject>
+    </figure>
+    
+    <para>An illustration of the CPE runtime is shown in <xref
+        linkend="&tp;overview.fig.runtime"/>. Some of the CPE components, such as the
+      <emphasis>queues</emphasis> and <emphasis>processing pipelines</emphasis>, are
+      internal to the CPE, but their behavior and deployment may be configured using the CPE
+      Descriptor. Other CPE components, such as the <emphasis>Collection
+      Reader</emphasis> and <emphasis>CAS Processors</emphasis>, are defined and
+      configured externally from the CPE and then plugged in to the CPE to create the overall
+      engine. The parts of a CPE are:
+      
+      <variablelist>
+        <varlistentry>
+          <term>Collection Reader</term>
+          <listitem><para>understands the native data collection format and iterates
+            over the collection producing subjects of analysis</para></listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>CAS Initializer<footnote><para>Deprecated</para></footnote>
+            </term>
+          <listitem><para>initializes a CAS with a subject of analysis</para>
+            </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>Artifact Producer</term>
+          <listitem><para>asynchronously pulls CASes from the Collection Reader,
+            creates batches of CASes and puts them into the work queue</para></listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>Work Queue</term>
+          <listitem><para>shared queue containing batches of CASes queued by the Artifact
+            Producer for analysis by Analysis Engines</para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>B1-Bn</term>
+          <listitem><para>individual batches containing 1 or more CASes</para>
+            </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>AE1-AEn</term>
+          <listitem><para>Analysis Engines arranged by a CPE descriptor</para>
+            </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>Processing Pipelines</term>
+          <listitem><para>each pipeline runs in a separate thread and contains a
+            replicated set of the Analysis Engines running in the defined sequence</para>
+            </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>Output Queue</term>
+          <listitem><para>holds batches of CASes with analysis results intended for CAS
+            Consumers</para></listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>CAS Consumers</term>
+          <listitem><para>perform collection level analysis over the CASes and extract
+            analysis results, e.g., creating indexes or databases</para></listitem>
+        </varlistentry>
+      </variablelist>
+      </para>
+  </section>
+  
+  <section id="&tp;notation">
+    <title>Notation</title>
+    
+    <para>CPE Descriptors are XML files. This chapter uses an informal notation to specify
+      the syntax of CPE Descriptors.</para>
+    
+    <para>The notation used in this chapter is:
+      
+      <itemizedlist><listitem><para>An ellipsis (...) inside an element body indicates
+        that the substructure of that element has been omitted (to be described in another
+        section of this chapter). An example of this would be:
+        
+        
+        <programlisting>&lt;collectionReader&gt;
+...
+&lt;/collectionReader&gt;</programlisting></para>
+        </listitem>
+        
+        <listitem><para>An ellipsis immediately after an element indicates that the
+          element type may be repeated arbitrarily many times. For example:
+          
+          
+          <programlisting>&lt;parameter&gt;[String]&lt;/parameter&gt;
+&lt;parameter&gt;[String]&lt;/parameter&gt;
+...</programlisting>
+          indicates that there may be arbitrarily many parameter elements in this
+          context.</para></listitem>
+        
+        <listitem><para>An ellipsis inside an element means details of the attributes
+          associated with that element are defined later, e.g.:
+          
+          <programlisting>&lt;casProcessor ...&gt;</programlisting></para>
+          </listitem>
+        
+        <listitem><para>Bracketed expressions (e.g. <literal>[String]</literal>)
+          indicate the type of value that may be used at that location.</para></listitem>
+        
+        <listitem><para>A vertical bar, as in <literal>true|false</literal>, indicates
+          alternatives. This can be applied to literal values, bracketed type names, and
+          elements. </para></listitem></itemizedlist></para>
+    
+    <para>Which elements are optional and which are required is specified in prose, not in the
+      syntax definition.</para>
+    
+  </section>
+  
+  <section id="&tp;imports">
+    <title>Imports</title>
+    
+    <para>A CPE Descriptor uses the following notation to reference descriptors for other
+      components that are incorporated into the defined CPE:
+      
+      
+      <programlisting><![CDATA[<descriptor>
+    <include href="[File]"/>
+</descriptor>]]></programlisting></para>
+    
+    <para>The <literal>[File]</literal> attribute is a filename for the descriptor of the
+      incorporated component. A fully qualified filename may be provided, or the filename
+      may relative to a directory specified using the <literal>CPM_HOME</literal>
+      variable, e.g.,</para>
+    
+    
+    <programlisting>&lt;descriptor&gt;
     &lt;include href=<quote>${CPM_HOME}/desc_dir/descriptor.xml</quote>/&gt;
 &lt;/descriptor&gt;</programlisting>
-
-<para>In this case, the value for the <literal>CPM_HOME</literal>
-variable must be provided to the CPE by specifying it on the Java command line,
-e.g.,</para>
-
-<programlisting>java -DCPM_HOME=<quote>C:/Program Files/apache/uima/cpm</quote> ...</programlisting>
-
-<para>Note that this mechanism for referencing other component
-descriptor files is different from and in no way related to either of the two
-import mechanisms described in <a class="crossrefText" href="Component_Descriptor_Reference.htm#_crossRef120">Chapter 23  </a></para>
-
-
-
-
-  </subsection>
-<subsection name="CPE Descriptor"><a id="_crossRef165"> </a>
-
-
-
-<para>A CPE Descriptor consists of information describing the
-following four main elements.</para>
-
-<orderedlist><listitem>The <emphasis>Collection Reader</emphasis>, which is responsible for gathering artifacts and
-initializing the Common Analysis Structure (CAS) used to support processing in
-the UIMA collection processing engine.</listitem>
-
-
-<listitem>The <emphasis>CAS Processors</emphasis> responsible for analyzing individual artifacts,
-analyzing across artifacts, and extracting analysis results.  CAS Processors include <emphasis>Analysis Engines</emphasis> and <emphasis>CAS
-Consumers</emphasis>.</listitem>
-
-
-<listitem>Operational parameters of the <emphasis>Collection Processing Manager</emphasis> (CPM),
-such as checkpoint frequency and deployment mode.</listitem>
-
-
-<listitem>Resource Manager Configuration
-(optional).
-</listitem></orderedlist>
-
-<para>The CPE Descriptor has the following high level skeleton:</para>
-
-<programlisting>&lt;?xml version=<quote>1.0</quote> encoding=<quote>UTF-8</quote>?&gt;
-&lt;cpeDescription&gt;
-   &lt;collectionReader&gt;
+    
+    <para>In this case, the value for the <literal>CPM_HOME</literal> variable must be
+      provided to the CPE by specifying it on the Java command line, e.g.,</para>
+    
+    
+    <programlisting>java -DCPM_HOME="C:/Program Files/apache/uima/cpm" ...</programlisting>
+    
+    <para>Note that this mechanism for referencing other component descriptor files is
+      different from and in no way related to either of the two import mechanisms described in
+        <olink targetdoc="&uima_docs_ref;"
+        targetptr="ugr.ref.xml.component_descriptor"/>.</para>
+    
+  </section>
+  
+  <section id="&tp;descriptor">
+    <title>CPE Descriptor</title>
+    
+    <para>A CPE Descriptor consists of information describing the following four main
+      elements.</para>
+    
+    <orderedlist><listitem><para>The <emphasis>Collection Reader</emphasis>, which
+      is responsible for gathering artifacts and initializing the Common Analysis
+      Structure (CAS) used to support processing in the UIMA collection processing
+      engine.</para></listitem>
+      
+      <listitem><para>The <emphasis>CAS Processors</emphasis>, responsible for
+        analyzing individual artifacts, analyzing across artifacts, and extracting
+        analysis results. CAS Processors include <emphasis>Analysis Engines</emphasis>
+        and <emphasis>CAS Consumers</emphasis>.</para></listitem>
+      
+      <listitem><para>Operational parameters of the <emphasis>Collection Processing
+        Manager</emphasis> (CPM), such as checkpoint frequency and deployment
+        mode.</para></listitem>
+      
+      <listitem><para>Resource Manager Configuration (optional). </para></listitem>
+      </orderedlist>
+    
+    <para>The CPE Descriptor has the following high level skeleton:
+      
+      
+      <programlisting><![CDATA[<?xml version="1.0"?>
+<cpeDescription>
+   <collectionReader>
 ...
-   &lt;/collectionReader&gt;
-   &lt;casProcessors&gt;
+   </collectionReader>
+   <casProcessors>
 ...
-   &lt;/casProcessors&gt;
-   &lt;cpeConfig&gt;
+   </casProcessors>
+   <cpeConfig>
 ...
-   &lt;/cpeConfig&gt;
-   &lt;resourceManagerConfiguration&gt;
+   </cpeConfig>
+   <resourceManagerConfiguration>
 ...
-   &lt;/resourceManagerConfiguration&gt;
-&lt;/cpeDescription&gt;</programlisting>
-
-<para>Details of each of the four main elements are described in
-the sections that follow.</para>
-
-<h3>Collection Reader</h3>
-
-<para>The <literal>&lt;collectionReader&gt;</literal>
-section identifies the Collection Reader and optional CAS Initializer that are
-to be used in the CPE.  The Collection
-Reader is responsible for retrieval of artifacts from a collection outside of
-the CPE, and the optional CAS Initializer is responsible for initializing the
-CAS with the artifact.</para>
-
-<para>A Collection Reader may initialize the CAS itself, in
-which case it does not require a CAS Initializer.  This should be clearly specified in the
-documentation for the Collection Reader.  Specifying a CAS Initializer for a Collection Reader that does not make
-use of a CAS Initializer will not cause an error, but the specified CAS Initializer
-will not be used.</para>
-
-<para>The complete structure of the <literal>&lt;collectionReader&gt;</literal>
-section is:</para>
-
-<programlisting>&lt;collectionReader&gt;
-  &lt;collectionIterator&gt;
-    &lt;descriptor&gt;
-      &lt;include href=<quote>[File]</quote>/&gt;
-    &lt;/descriptor&gt;
-    &lt;configurationParameterSettings&gt;...&lt;/configurationParameterSettings&gt;
-    &lt;sofaNameMappings&gt;...&lt;/sofaNameMappings&gt;
-  &lt;/collectionIterator&gt;
-  &lt;casInitializer&gt;
-    &lt;descriptor&gt;
-      &lt;include href=<quote>[File]</quote>/&gt;
-    &lt;/descriptor&gt;
-    &lt;configurationParameterSettings&gt;...&lt;/configurationParameterSettings&gt;
-    &lt;sofaNameMappings&gt;...&lt;/sofaNameMappings&gt;
-  &lt;/casInitializer&gt;
-&lt;/collectionReader&gt;</programlisting>
-
-<para>The <literal>&lt;collectionIterator&gt;</literal>
-identifies the descriptor for the Collection Reader, and the <literal>&lt;casInitializer&gt; </literal>identifies the descriptor for the
-CAS Initializer.  The format and details
-of the Collection Reader and CAS Initializer descriptors are described in <a class="crossrefText" href="Component_Descriptor_Reference.htm#_crossRef120">Chapter 23  </a>. The <literal>&lt;configurationParameterSettings&gt;
-</literal>and the <literal>&lt;sofaNameMappings&gt;</literal> elements are
-described in the next section.</para>
+   </resourceManagerConfiguration>
+</cpeDescription>]]></programlisting></para>
+    
+    <para>Details of each of the four main elements are described in the sections that
+      follow.</para>
+    
+    <section id="&tp;descriptor.collection_reader">
+      <title>Collection Reader</title>
+      
+      <para>The <literal>&lt;collectionReader&gt;</literal> section identifies the
+        Collection Reader and optional CAS Initializer that are to be used in the CPE. The
+        Collection Reader is responsible for retrieval of artifacts from a collection
+        outside of the CPE, and the optional CAS Initializer (deprecated as of UIMA Version 2)
+        is responsible for initializing the CAS with the artifact.</para>
+      
+      <para>A Collection Reader may initialize the CAS itself, in which case it does not
+        require a CAS Initializer. This should be clearly specified in the documentation for
+        the Collection Reader. Specifying a CAS Initializer for a Collection Reader that
+        does not make use of a CAS Initializer will not cause an error, but the specified CAS
+        Initializer will not be used.</para>
+      
+      <para>The complete structure of the <literal>&lt;collectionReader&gt;</literal>
+        section is:
+        
+        
+        <programlisting><![CDATA[<collectionReader>
+  <collectionIterator>
+    <descriptor>
+      <include href="[File]"/>
+    </descriptor>
+    <configurationParameterSettings>...</configurationParameterSettings>
+    <sofaNameMappings>...</sofaNameMappings>
+  </collectionIterator>
+  <casInitializer>
+    <descriptor>
+      <include href="[File]"/>
+    </descriptor>
+    <configurationParameterSettings>...</configurationParameterSettings>
+    <sofaNameMappings>...</sofaNameMappings>
+  </casInitializer>
+</collectionReader>]]></programlisting></para>
+      
+      <para>The <literal>&lt;collectionIterator&gt;</literal> identifies the
+        descriptor for the Collection Reader, and the <literal>&lt;casInitializer&gt;
+        </literal>identifies the descriptor for the CAS Initializer. The format and
+        details of the Collection Reader and CAS Initializer descriptors are described in
+          <olink targetdoc="&uima_docs_ref;"
+          targetptr="ugr.ref.xml.component_descriptor.collection_processing_parts.collection_reader"/>
+        . The <literal>&lt;configurationParameterSettings&gt; </literal>and the
+        <literal>&lt;sofaNameMappings&gt;</literal> elements are described in the next
+        section.</para>
+      
+      <section id="&tp;descriptor.collection_reader.error_handling">
+        <title>Error handling for Collection Readers</title>
+        
+        <para>The CPM will abort if the Collection Reader throws a large number of
+          consecutive exceptions (default = 100). This default can by changed by using the
+          Java initialization parameter <literal>-DMaxCRErrorThreshold
+          xxx.</literal></para>
+      </section>
+    </section>
+    
+    <section id="&tp;descriptor.cas_processors">
+      <title>CAS Processors</title>
+      
+      <para>The <literal>&lt;casProcessors&gt;</literal> section identifies the
+        components that perform the analysis on the input data, including CAS analysis
+        (Analysis Engines) and analysis results extraction (CAS Consumers). The CAS
+        Consumers may also perform collection level analysis, where the analysis is
+        performed (or aggregated) over multiple CASes. The basic structure of the CAS
+        Processors section is:
+        
+        
+        <programlisting><![CDATA[<casProcessors 
+    dropCasOnException="true|false"
+    casPoolSize="[Number]" 
+    processingUnitThreadCount="[Number]">
 
-<h4>Error handling for
-Collection Readers</h4>
-
-<para>The CPM will abort if the Collection Reader throws a large
-number of consecutive exceptions (default = 100).  This default can by changed by using the Java
-initialization parameter <literal>-DMaxCRErrorThreshold xxx.</literal></para>
-
-<h3><a id="_crossRef166">CAS Processors</a></h3>
-
-<para>The <literal>&lt;casProcessors&gt;</literal>
-section identifies the components that perform the analysis on the input data,
-including CAS analysis (Analysis Engines) and analysis results extraction (CAS
-Consumers).  The CAS Consumers may also
-perform collection level analysis, where the analysis is performed (or
-aggregated) over multiple CASes.  The
-basic structure of the CAS Processors section is:</para>
-
-<programlisting>&lt;casProcessors dropCasOnException=<quote>true|false</quote> casPoolSize=<quote>[Number]</quote> processingUnitThreadCount=<quote>[Number]</quote>&gt;
-    &lt;casProcessor ...&gt;
+  <casProcessor ...>
         ...
-    &lt;/casProcessor&gt;
-    &lt;casProcessor ...&gt;
+  </casProcessor>
+
+  <casProcessor ...>
         ...
-    &lt;/casProcessor&gt;
+  </casProcessor>
     ...
-&lt;/casProcessors&gt;</programlisting>
-
-<para>The <literal>&lt;casProcessors&gt;</literal>
-section has two mandatory attributes and one optional attribute that configure
-the characteristics of the CAS Processor flow in the CPE.  The first mandatory attribute is<a id="_crossRef167"> a casPoolSize</a>, which defines the fixed number of CAS
-instances that the CPM will create and use during processing. All CAS instances
-are maintained in a CAS Pool with a check-in and check-out access. Each CAS is checked-out
-from the CAS Pool by the Collection Reader and initialized with an initial
-subject of analysis. The CAS is checked-in into the CAS Pool when it is completely
-processed, at the end of the processing chain. A larger CAS Pool size will
-result in more memory being used by the CPM. CAS objects can be large and care
-should be taken to determine the optimum size of the CAS Pool, weighing memory
-tradeoffs with performance.</para>
-
-<para><a id="_crossRef168">The second mandatory</a><a id="_crossRef169"> </a><literal>&lt;casProcessors&gt;</literal> attribute is <literal>processingUnitThreadCount</literal>,
-which specifies the number of replicated <emphasis>Processing Pipelines</emphasis>.  Each Processing Pipeline runs in its own
-thread.  The CPM takes CASes from the
-work queue and submits each CAS to one of the Processing Pipelines for
-analysis.  A Processing Pipeline contains
-one or more Analysis Engines invoked in a given sequence.  If more than one Processing Pipeline is
-specified, the CPM replicates instances of each Analysis Engine defined in the
-CPE descriptor.  Each Processing Pipeline
-thread runs independently, consuming CASes from work queue and depositing CASes
-with analysis results onto the output queue.  On multiprocessor machines, multiple Processing Pipelines can run in
-parallel, improving overall throughput of the CPM.</para>
-
-<note>The number of Processing Pipelines should be equal to or greater than
-CAS Pool size. </listitem>
-
-
-<listitem>Elements in the pipeline (each represented by a &lt;casProcessor&gt;
-element) may indicate that they do not permit multiple deployment in their
-Analysis Engine descriptor.  If so, even
-though multiple pipelines are being used, all CASes passing through the
-pipelines will be routed through one instance of these marked Engines.
-</listitem></itemizedlist>
-
-<para>The final, optional, &lt;casProcessors&gt; attribute is <literal>dropCasOnException</literal>. It defines a policy that determines
-what happens with the CAS when an exception happens during processing. If the
-value of this attribute is set to true and an exception happens, the CPM will
-notify all registered listeners of the exception (see <b><a class="crossrefText" href="CPE_Developers_Guide.htm#_crossRef190">Using
-Listeners</a></b> <a class="crossrefPage" href="CPE_Developers_Guide.htm#_crossRef190"></a>), clear the CAS and check the CAS back into the CAS
-Pool so that it can be re-used. The presumption is that an exception may leave
-the CAS in an inconsistent state and therefore that CAS should not be allowed
-to move through the processing chain. When this attribute is omitted the CPM&apos;s
-default is the same as specifying  <literal>dropCasOnException=<quote>false</quote></literal>.</para>
-
-<h4>Specifying an
-Individual CAS Processor</h4>
-
-<para>The CAS Processors that make up the Processing Pipeline
-and the CAS Consumer pipeline are specified with the <literal>&lt;casProcessor&gt;</literal>
-entity, which appears within the <literal>&lt;casProcessors&gt;</literal>
-entity.  It may appear multiple times,
-once for each CAS Processor specified for this CPE.</para>
-
-<para>The order of the <literal>&lt;casProcessor&gt;</literal>
-entities with the <literal>&lt;casProcessors&gt;</literal> section
-specifies the order in which the CAS Processors will run.  Although CAS Consumers are usually put at the
-end of the pipeline, they need not be.  Also, Aggregate Analysis Engines may include CAS Consumers.</para>
-
-<para>The overall format of the <literal>&lt;casProcessor&gt;</literal>
-entity is:</para>
-
-<programlisting>&lt;casProcessor deployment=<quote>local|remote|integrated</quote> name=<quote>[String]</quote> &gt;
-    &lt;descriptor&gt;
-        &lt;include href=[File]/&gt;
-    &lt;/descriptor&gt;
-    &lt;configurationParameterSettings&gt;...&lt;/configurationParameterSettings&gt;
-    &lt;sofaNameMappings&gt;...&lt;/sofaNameMappings&gt;
-    &lt;runInSeparateProcess&gt;...&lt;/runInSeparateProcess&gt;
-    &lt;deploymentParameters&gt;...&lt;/deploymentParameters&gt;
-    &lt;filter/&gt;
-    &lt;errorHandling&gt;...&lt;/errorHandling&gt;
-    &lt;checkpoint batch=<quote>Number</quote>/&gt;
-&lt;/casProcessor&gt;</programlisting>
-
-<para><a id="_crossRef170">The </a><literal>&lt;casProcessor&gt;</literal> element
-has two mandatory attributes, <literal>deployment</literal> and <literal>name.</literal>
-The mandatory <literal>name</literal> attribute specifies a unique
-string identifying the CAS Processor.</para>
-
-<para>The mandatory <literal>deployment</literal> attribute specifies the CAS
-Processor deployment mode.  Currently,
-three deployment options are supported:</para>
-
-<itemizedlist spacing="compact"><listitem><literal>integrated</literal>
-&ndash; indicates <emphasis>integrated</emphasis> deployment of the CAS Processor.  The CPM deploys and collocates the CAS
-Processor in the same process space as the CPM.  This type of deployment is recommended to increase the performance of
-the CPE.  However, it is NOT recommended
-to deploy annotators containing JNI this way.  Such CAS Processors may cause a fatal exception and force the JVM to
-exit without cleanup (bringing down the CPM).  Any UIMA SDK compliant pure Java CAS Processors may be safely deployed
-this way.<br/>
-<br/>
-The descriptor for an integrated deployment can, in fact, be a remote service
-descriptor.  When used this way, with
-Vinci, the Sofa mapping needed for the remote is done before sending the CAS to
-the remote (see <b><a class="crossrefText" href="SOFA_Developers_Guide.htm#_crossRef315">Name
-Mapping for Remote Services</a></b> <a class="crossrefPage" href="SOFA_Developers_Guide.htm#_crossRef315"></a>).  When used
-this way, however, the CPM error recovery options (see below) operate in the
-integrated mode, which means that many of the retry options are not available.</listitem>
-
-
-<listitem><literal>remote</literal>
-&ndash; indicates <emphasis>non-managed</emphasis> deployment of the CAS Processor.  The CAS Processor descriptor referenced in
-the <literal>&lt;descriptor&gt;</literal> element must be a
-Vinci <emphasis>Service Client Descriptor</emphasis>, which identifies a remotely deployed
-CAS Processor service (see <emphasis>Section </emphasis><a class="crossrefText" href="Application_Developers_Guide.htm#_crossRef64">6.6, <b>Working with Analysis Engine and CAS Consumer
-Services</b></a>).  The
-CPM assumes that the CAS Processor is already running as a remote service and
-will connect to it using the URI provided in the client service
-descriptor.  The lifecycle of a remotely
-deployed CAS Processor is not managed by the CPM, so appropriate infrastructure
-should be in place to start/restart such CAS Processors when necessary.  This deployment provides fault isolation and
-is implementation (i.e., programming language) neutral.  </listitem>
-
-
-<listitem><literal>local</literal> &ndash;
-indicates <emphasis>managed</emphasis> deployment of the CAS Processor.  The CAS Processor descriptor referenced in the
-<literal>&lt;descriptor&gt;</literal> element must be a Vinci <emphasis>Service
-Deployment Descriptor</emphasis>, which configures a CAS Processor for deployment as a
-Vinci service (see <emphasis>Section </emphasis><a class="crossrefText" href="Application_Developers_Guide.htm#_crossRef64">6.6, <b>Working with Analysis Engine and CAS Consumer
-Services</b></a>).  The
-CPM deploys the CAS Processor in a separate process and manages the life cycle
-(start/stop) of the CAS Processor.  Communication between the CPM and the CAS Processor is done with
-Vinci.  When the CPM completes
-processing, the process containing the CAS Processor is terminated.  This deployment mode insulates the CPM from
-the CAS Processor, creating a more robust deployment at the cost of a small
-communication overhead.  On
-multiprocessor machines, the separate processes may run concurrently and
-improve overall throughput.
-</listitem></itemizedlist>
-
-<para>A number of elements may appear within the <literal>&lt;casProcessor&gt;</literal> element.</para>
-
-<h4><emphasis>&lt;descriptor&gt; Element</emphasis></h4>
-
-<para>The <literal>&lt;descriptor&gt;</literal> element
-is mandatory.  It identifies the
-descriptor for the referenced CAS Processor using the syntax described in
-Section <a class="crossrefText" href="Component_Descriptor_Reference.htm#_crossRef122">23.2
-</a> above.</para>
-
-<itemizedlist spacing="compact"><listitem>For <literal><emphasis>remote</emphasis></literal>
-CAS Processors, the referenced descriptor must be a Vinci <emphasis>Service Client
-Descriptor</emphasis>, which identifies a remotely deployed CAS Processor
-service.  </listitem>
-
-
-<listitem>For <emphasis>local</emphasis> CAS Processors,
-the referenced descriptor must be a Vinci <emphasis>Service Deployment Descriptor</emphasis>.</listitem>
-
-
-<listitem>For <emphasis>integrated</emphasis> CAS
-Processors, the referenced descriptor must be an Analysis Engine Descriptor
-(primitive or aggregate).   
-</listitem></itemizedlist>
-
-<para>See Section <a class="crossrefText" href="Application_Developers_Guide.htm#_crossRef64">6.6, <b>Working with Analysis Engine and CAS Consumer
-Services</b></a>  for more
-information on creating these descriptors and deploying services.</para>
-
-<h4><emphasis>&lt;configurationParameterSettings&gt;
-Element</emphasis></h4>
-
-<para>This element provides a way to override the contained
-Analysis Engine&apos;s parameters settings.  Any entry specified here must already be defined; values specified
-replace the corresponding values for each parameter.  <b><u>For Cas Processors, this mechanism is
-only available when they are deployed in <quote>integrated</quote> mode.</u></b>  For Collection Readers and Initializers, it
-always is available.</para>
-
-<para>The content of this element is identical to the component
-descriptor for specifying parameters (in the case where no parameter groups are
-specified), except that the names for the primitive types have a <quote>_p</quote>
-suffixed to them:  string_p, integer_p,
-float_p.  Here is an example:</para>
-
-<para><literal>&lt;configurationParameterSettings&gt;<br/>
-  &lt;nameValuePair&gt;<br/>
-    &lt;name&gt;CivilianTitles&lt;/name&gt;<br/>
-    &lt;value&gt;<br/>
-      &lt;array&gt;<br/>
-        &lt;string_p&gt;Mr.&lt;/string_p&gt;<br/>
-        &lt;string_p&gt;Ms.&lt;/string_p&gt;<br/>
-        &lt;string_p&gt;Mrs.&lt;/string_p&gt;<br/>
-        &lt;string_p&gt;Dr.&lt;/string_p&gt;<br/>
-      &lt;/array&gt;  <br/>
-    &lt;/value&gt;<br/>
-  &lt;/nameValuePair&gt;<br/>
-  ...<br/>
-&lt;/configurationParameterSettings&gt;</literal></para>
-
-<h4><a id="_crossRef171"><emphasis>&lt;sofaNameMappings&gt;
-Element</emphasis></a></h4>
-
-<para>This optional element provides a mapping from defined Sofa
-names in the component, or the default Sofa name (if the component does not
-declare any Sofa names).  The form of
-this element is:</para>
-
-<programlisting>&lt;sofaNameMappings&gt;
+</casProcessors>]]></programlisting></para>
+      
+      <para>The <literal>&lt;casProcessors&gt;</literal> section has two mandatory
+        attributes and one optional attribute that configure the characteristics of the CAS
+        Processor flow in the CPE. The first mandatory attribute is a casPoolSize, which
+        defines the fixed number of CAS instances that the CPM will create and use during
+        processing. All CAS instances are maintained in a CAS Pool with a check-in and
+        check-out access. Each CAS is checked-out from the CAS Pool by the Collection Reader
+        and initialized with an initial subject of analysis. The CAS is checked-in into the
+        CAS Pool when it is completely processed, at the end of the processing chain. A larger
+        CAS Pool size will result in more memory being used by the CPM. CAS objects can be large
+        and care should be taken to determine the optimum size of the CAS Pool, weighing memory
+        tradeoffs with performance.</para>
+      
+      <para>The second mandatory <literal>&lt;casProcessors&gt;</literal> attribute
+        is <literal>processingUnitThreadCount</literal>, which specifies the number of
+        replicated <emphasis>Processing Pipelines</emphasis>. Each Processing
+        Pipeline runs in its own thread. The CPM takes CASes from the work queue and submits
+        each CAS to one of the Processing Pipelines for analysis. A Processing Pipeline
+        contains one or more Analysis Engines invoked in a given sequence. If more than one
+        Processing Pipeline is specified, the CPM replicates instances of each Analysis
+        Engine defined in the CPE descriptor. Each Processing Pipeline thread runs
+        independently, consuming CASes from work queue and depositing CASes with analysis
+        results onto the output queue. On multiprocessor machines, multiple Processing
+        Pipelines can run in parallel, improving overall throughput of the CPM.</para>
+      <note><para>The number of Processing Pipelines should be equal to or greater than CAS
+      Pool size. </para></note>
+      
+      <para>Elements in the pipeline (each represented by a &lt;casProcessor&gt; element)
+        may indicate that they do not permit multiple deployment in their Analysis Engine
+        descriptor. If so, even though multiple pipelines are being used, all CASes passing
+        through the pipelines will be routed through one instance of these marked Engines.
+        </para>
+      
+      <para>The final, optional, &lt;casProcessors&gt; attribute is
+        <literal>dropCasOnException</literal>. It defines a policy that determines what
+        happens with the CAS when an exception happens during processing. If the value of this
+        attribute is set to true and an exception happens, the CPM will notify all registered
+        listeners of the exception (see <olink targetdoc="&uima_docs_tutorial_guides;"
+          targetptr="ugr.tug.cpe.using_listeners"/>), clear the CAS and check the CAS
+        back into the CAS Pool so that it can be re-used. The presumption is that an exception
+        may leave the CAS in an inconsistent state and therefore that CAS should not be allowed
+        to move through the processing chain. When this attribute is omitted the CPM&apos;s
+        default is the same as specifying
+        <literal>dropCasOnException="false"</literal>.</para>
+      
+      <section id="&tp;descriptor.cas_processors.individual">
+        <title>Specifying an Individual CAS Processor</title>
+        
+        <para>The CAS Processors that make up the Processing Pipeline and the CAS Consumer
+          pipeline are specified with the <literal>&lt;casProcessor&gt;</literal>
+          entity, which appears within the <literal>&lt;casProcessors&gt;</literal>
+          entity. It may appear multiple times, once for each CAS Processor specified for
+          this CPE.</para>
+        
+        <para>The order of the <literal>&lt;casProcessor&gt;</literal> entities with
+          the <literal>&lt;casProcessors&gt;</literal> section specifies the order in
+          which the CAS Processors will run. Although CAS Consumers are usually put at the end
+          of the pipeline, they need not be. Also, Aggregate Analysis Engines may include CAS
+          Consumers.</para>
+        
+        <para>The overall format of the <literal>&lt;casProcessor&gt;</literal> entity
+          is:
+          
+          
+          <programlisting><![CDATA[<casProcessor deployment="local|remote|integrated" name="[String]" >
+    <descriptor>
+        <include href=[File]/>
+    </descriptor>
+    <configurationParameterSettings>...</configurationParameterSettings>
+    <sofaNameMappings>...</sofaNameMappings>
+    <runInSeparateProcess>...</runInSeparateProcess>
+    <deploymentParameters>...</deploymentParameters>
+    <filter/>
+    <errorHandling>...</errorHandling>
+    <checkpoint batch="Number"/>
+</casProcessor>]]></programlisting></para>
+        
+        <para>The <literal>&lt;casProcessor&gt;</literal> element has two mandatory
+          attributes, <literal>deployment</literal> and <literal>name</literal>. The
+          mandatory <literal>name</literal> attribute specifies a unique string
+          identifying the CAS Processor.</para>
+        
+        <para>The mandatory <literal>deployment</literal> attribute specifies the CAS
+          Processor deployment mode. Currently, three deployment options are supported:
+          
+          <variablelist>
+            <varlistentry>
+              <term>integrated</term>
+              <listitem><para>indicates <emphasis>integrated</emphasis> deployment
+                of the CAS Processor. The CPM deploys and collocates the CAS Processor in the
+                same process space as the CPM. This type of deployment is recommended to
+                increase the performance of the CPE. However, it is NOT recommended to
+                deploy annotators containing JNI this way. Such CAS Processors may cause a
+                fatal exception and force the JVM to exit without cleanup (bringing down the
+                CPM). Any UIMA SDK compliant pure Java CAS Processors may be safely deployed
+                this way.</para>
+                <para>The descriptor for an integrated deployment can, in fact, be a remote
+                  service descriptor. When used this way, with Vinci, the Sofa mapping
+                  needed for the remote is done before sending the CAS to the remote (see
+                    <olink targetdoc="&uima_docs_tutorial_guides;"
+                    targetptr="ugr.tug.mvs.name_mapping_remote_services"/>). When
+                  used this way, however, the CPM error recovery options (see below)
+                  operate in the integrated mode, which means that many of the retry options
+                  are not available.</para></listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>remote</term>
+              <listitem><para>indicates <emphasis>non-managed</emphasis>
+                deployment of the CAS Processor. The CAS Processor descriptor referenced
+                in the <literal>&lt;descriptor&gt;</literal> element must be a Vinci
+                <emphasis>Service Client Descriptor</emphasis>, which identifies a
+                remotely deployed CAS Processor service (see <olink
+                  targetdoc="&uima_docs_tutorial_guides;"
+                  targetptr="ugr.tug.application.remote_services"/>). The CPM
+                assumes that the CAS Processor is already running as a remote service and
+                will connect to it using the URI provided in the client service descriptor.
+                The lifecycle of a remotely deployed CAS Processor is not managed by the CPM,
+                so appropriate infrastructure should be in place to start/restart such CAS
+                Processors when necessary. This deployment provides fault isolation and
+                is implementation (i.e., programming language) neutral.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>local</term>
+              <listitem><para>indicates <emphasis>managed</emphasis> deployment of
+                the CAS Processor. The CAS Processor descriptor referenced in the
+                <literal>&lt;descriptor&gt;</literal> element must be a Vinci
+                <emphasis>Service Deployment Descriptor</emphasis>, which configures
+                a CAS Processor for deployment as a Vinci service (see <olink
+                  targetdoc="&uima_docs_tutorial_guides;"
+                  targetptr="ugr.tug.application.remote_services"/>). The CPM
+                deploys the CAS Processor in a separate process and manages the life cycle
+                (start/stop) of the CAS Processor. Communication between the CPM and the
+                CAS Processor is done with Vinci. When the CPM completes processing, the
+                process containing the CAS Processor is terminated. This deployment mode
+                insulates the CPM from the CAS Processor, creating a more robust deployment
+                at the cost of a small communication overhead. On multiprocessor machines,
+                the separate processes may run concurrently and improve overall
+                throughput.</para></listitem>
+            </varlistentry>
+          </variablelist></para>
+        
+        <para>A number of elements may appear within the
+          <literal>&lt;casProcessor&gt;</literal> element.</para>
+        
+        <section id="&tp;descriptor.cas_processors.individual.descriptor">
+          <title>&lt;descriptor&gt; Element</title>
+          
+          <para>The <literal>&lt;descriptor&gt;</literal> element is mandatory. It
+            identifies the descriptor for the referenced CAS Processor using the syntax
+            described in <olink targetdoc="&uima_docs_ref;"
+              targetptr="ugr.ref.xml.component_descriptor.aes"/>.
+            
+            <itemizedlist spacing="compact"><listitem><para>For
+              <emphasis><literal>remote</literal></emphasis> CAS Processors, the
+              referenced descriptor must be a Vinci <emphasis>Service Client
+              Descriptor</emphasis>, which identifies a remotely deployed CAS Processor
+              service.</para></listitem>
+              
+              <listitem><para>For <emphasis>local</emphasis> CAS Processors, the
+                referenced descriptor must be a Vinci <emphasis>Service Deployment
+                Descriptor</emphasis>.</para></listitem>
+              
+              <listitem><para>For <emphasis>integrated</emphasis> CAS Processors,
+                the referenced descriptor must be an Analysis Engine Descriptor
+                (primitive or aggregate). </para></listitem></itemizedlist> </para>
+          
+          <para>See <olink targetdoc="&uima_docs_tutorial_guides;"
+              targetptr="ugr.tug.application.remote_services"/> for more
+            information on creating these descriptors and deploying services.</para>
+          
+        </section>
+        
+        <section
+          id="&tp;descriptor.cas_processors.individual.configuration_parameter_settings">
+          <title>&lt;configurationParameterSettings&gt; Element</title>
+          
+          <para>This element provides a way to override the contained Analysis
+            Engine&apos;s parameters settings. Any entry specified here must already be
+            defined; values specified replace the corresponding values for each
+            parameter. <emphasis role="bolditalic">For Cas Processors, this mechanism
+            is only available when they are deployed in <quote>integrated</quote>
+            mode.</emphasis> For Collection Readers and Initializers, it always is
+            available.</para>
+          
+          <para>The content of this element is identical to the component descriptor for
+            specifying parameters (in the case where no parameter groups are
+            specified)<footnote><para>An earlier UIMA version required these to have a
+            suffix of <quote>_p</quote>, e.g., <quote>string_p</quote>. This is no
+            longer required, but this format is accepted, also, for backward
+            compatibility.</para></footnote>. Here is an example:
+            
+            
+            <programlisting><![CDATA[<configurationParameterSettings>
+  <nameValuePair>
+    <name>CivilianTitles</name>
+    <value>
+      <array>
+        <string>Mr.</string>
+        <string>Ms.</string>
+        <string>Mrs.</string>
+        <string>Dr.</string>
+      </array>  
+    </value>
+  </nameValuePair>
+  ...
+</configurationParameterSettings>]]></programlisting></para>
+          
+        </section>
+        
+        <section
+          id="&tp;descriptor.cas_processors.individual.sofa_name_mappings">
+          <title>&lt;sofaNameMappings&gt; Element</title>
+          
+          <para>This optional element provides a mapping from defined Sofa names in the
+            component, or the default Sofa name (if the component does not declare any Sofa
+            names). The form of this element is:
+            
+            
+            <programlisting>&lt;sofaNameMappings&gt;
   &lt;sofaNameMapping cpeSofaName=<quote>a_CPE_name</quote>
                    componentSofaName=<quote>a_component_Name</quote>/&gt;
   ...
-&lt;/sofaNameMappings&gt;</programlisting>
-
-<para>There can be any number of<literal>
-&lt;sofaNameMapping&gt;</literal> elements contained in the <literal>&lt;sofaNameMappings&gt;</literal>
-element.  The <literal>componentSofaName</literal>
-attribute is optional;  leave it out to
-specify a mapping for the _InitialView - that is, for Single-View components.</para>
-
-<h4><emphasis>&lt;runInSeparateProcess&gt; Element</emphasis></h4>
-
-<para>The <literal>&lt;runInSeparateProcess&gt;</literal>
-element is mandatory for <literal>local</literal> CAS Processors, but
-should not appear for <literal>remote</literal> or <literal>integrated</literal>
-CAS Processors.  It enables the CPM to
-create external processes using the provided runtime environment.  Applications launched this way communicate
-with the CPM using the Vinci protocol and connectivity is enabled by a local instance
-of the VNS that the CPM manages.  Since
-communication is based on Vinci, the application need not be implemented in Java.
-Any language for which Vinci provides support may be used to create an
-application, and the CPM will seamlessly communicate with it.  The overall structure of this element is:</para>
-
-<programlisting>&lt;runInSeparateProcess&gt;
-    &lt;exec dir=<quote>[String]</quote> executable=<quote>[String]</quote>&gt;
-        &lt;env key=<quote>[String]</quote> value =<quote>[String]</quote>/&gt;
+&lt;/sofaNameMappings&gt;</programlisting></para>
+          
+          <para>There can be any number of<literal>
+            &lt;sofaNameMapping&gt;</literal> elements contained in the
+            <literal>&lt;sofaNameMappings&gt;</literal> element. The
+            <literal>componentSofaName</literal> attribute is optional; leave it out to
+            specify a mapping for the <literal>_InitialView</literal> - that is, for
+            Single-View components.</para>
+          
+        </section>
+        
+        <section id="&tp;descriptor.cas_processors.run_in_separate_process">
+          <title>&lt;runInSeparateProcess&gt; Element</title>
+          
+          <para>The <literal>&lt;runInSeparateProcess&gt;</literal> element is
+            mandatory for <literal>local</literal> CAS Processors, but should not appear
+            for <literal>remote</literal> or <literal>integrated</literal> CAS
+            Processors. It enables the CPM to create external processes using the provided
+            runtime environment. Applications launched this way communicate with the CPM
+            using the Vinci protocol and connectivity is enabled by a local instance of the
+            VNS that the CPM manages. Since communication is based on Vinci, the application
+            need not be implemented in Java. Any language for which Vinci provides support
+            may be used to create an application, and the CPM will seamlessly communicate
+            with it. The overall structure of this element is:
+            
+            
+            <programlisting><![CDATA[<runInSeparateProcess>
+    <exec dir="[String]" executable="[String]">
+        <env key="[String]" value ="[String]"/>
         ...
-        &lt;arg&gt;[String]&lt;/arg&gt;
+        <arg>[String]</arg>
         ...
-    &lt;/exec&gt;
-&lt;/runInSeparateProcess&gt;</programlisting>
-
-<para>The <literal>&lt;exec&gt;</literal> element
-provides information about how to execute the referenced CAS Processor.  Two attributes are defined for the <literal>&lt;exec&gt;</literal> element.  The <literal>dir</literal> attribute is currently not used &ndash; it
-is reserved for future functionality.  The <literal>executable</literal> attribute specifies the actual
-Vinci service executable that will be run by the CPM, e.g., <literal>java</literal>, a batch script, an application (.exe), etc.  The executable must be specified with a fully
-qualified path, or be found in the <literal>PATH</literal> of the CPM.</para>
-
-<para>The <literal>&lt;exec&gt;</literal> element has
-two elements within it that define parameters used to construct the command
-line for executing the CAS Processor.  These elements must be listed in the order in which they should be
-defined for the CAS Processor.</para>
-
-<para>The optional <literal>&lt;env&gt;</literal>
-element is used to set an environment variable.  The variable <literal>key</literal> will be set to <literal>value</literal>.  For example,
-</para>
-
-<programlisting>&lt;env key=<quote>CLASSPATH</quote> value =<quote>C:Javalib</quote>/&gt;</programlisting>
-
-<para>will set the environment variable <literal>CLASSPATH</literal>
-to the value <literal>C:\Java\lib</literal>.  The <literal>&lt;env&gt;</literal>
-element may be repeated to set multiple environment variables.  All of the key/value pairs will be added to
-the environment by the CPM prior to launching the executable.</para>
-
-<para><b>Note</b>:  <emphasis>The
-CPM actually adds ALL system environment variables when it launches the
-program.  It queries the Operating System
-for its current system variables and one by one adds them to the program&apos;s
-process configuration.</emphasis></para>
-
-<para>The <literal>&lt;arg&gt;</literal> element is used
-to specify arbitrary string arguments that will appear on the command line when
-the CPM runs the command specified in the <literal>executable</literal>
-attribute.</para>
-
-<para>For example, the following would be used to invoke the
-UIMA Java implementation of the Vinci service wrapper on a Java CAS Processor:</para>
-
-<programlisting>&lt;runInSeparateProcess&gt;
-    &lt;exec executable=<quote>java</quote>&gt;
-        &lt;arg&gt;-DVNS_HOST=localhost&lt;/arg&gt; 
-        &lt;arg&gt;-DVNS_PORT=9099&lt;/arg&gt;
-        &lt;arg&gt;org.apache.uima.reference_impl.analysis_engine.service.
-vinci.VinciAnalysisEngineService_impl&lt;/arg&gt; 
-        &lt;arg&gt;C:uimadescdeployCasProcessor.xml&lt;/arg&gt;
-    &lt;/exec&gt;
-&lt;runInSeparateProcess&gt; </programlisting>
-
-<para>This will cause the CPM to run the following command line
-when starting the CAS Processor:</para>
-
-<programlisting>java -DVNS_HOST=localhost -DVNS_PORT=9099 org.apache.uima.reference_impl.analysis_engine.service.vinci.VinciAnalysisEngineService_impl C:uimadescdeployCasProcessor.xml</programlisting>
-
-<para>The first argument specifies that the Vinci Naming Service
-is running on the <literal>localhost</literal>.  The second argument specifies that the Vinci
-Naming Service port number is <literal>9099</literal>.  The third argument identifies the UIMA
-implementation of the Vinci service wrapper.  This class contains the <literal>main</literal> method that will
-execute.  That main method in turn takes
-a single argument &ndash; the filename for the CAS Processor service deployment
-descriptor.  Thus the last argument
-identifies the Vinci service deployment descriptor file for the CAS
-Processor.  Since this is the same
-descriptor file specified earlier in the <literal>&lt;descriptor&gt;</literal>
-element, the string <literal>${desc</literal><literal>riptor}</literal>
-can be used to refer to the descriptor, e.g.:</para>
-
-<programlisting>&lt;arg&gt;${descriptor}&lt;/arg&gt;</programlisting>
-
-<para>The CPM will expand this out to the service deployment
-descriptor file referenced in the <literal>&lt;descriptor&gt;</literal>
-element. <a id="_crossRef172"></a></para>
-
-<h4><a id="_crossRef173"><emphasis>&lt;deploymentParameters&gt;
-Element</emphasis></a></h4>
-
-<para>The <literal>&lt;deploymentParameters&gt;</literal>
-element defines a number of deployment parameters that control how the CPM will
-interact with the CAS Processor.  This
-element has the following overall form:</para>
-
-<programlisting>&lt;deploymentParameters&gt;
-    &lt;parameter name=<quote>[String]</quote> value=<quote>...</quote> type=<quote>string|integer</quote> /&gt; 
+    </exec>
+</runInSeparateProcess>]]></programlisting></para>
+          
+          <para>The <literal>&lt;exec&gt;</literal> element provides information
+            about how to execute the referenced CAS Processor. Two attributes are defined
+            for the <literal>&lt;exec&gt;</literal> element. The
+            <literal>dir</literal> attribute is currently not used &ndash; it is reserved
+            for future functionality. The <literal>executable</literal> attribute
+            specifies the actual Vinci service executable that will be run by the CPM, e.g.,
+            <literal>java</literal>, a batch script, an application (.exe), etc. The
+            executable must be specified with a fully qualified path, or be found in the
+            <literal>PATH</literal> of the CPM.</para>
+          
+          <para>The <literal>&lt;exec&gt;</literal> element has two elements within it
+            that define parameters used to construct the command line for executing the CAS
+            Processor. These elements must be listed in the order in which they should be
+            defined for the CAS Processor.</para>
+          
+          <para>The optional <literal>&lt;env&gt;</literal> element is used to set an
+            environment variable. The variable <literal>key</literal> will be set to
+            <literal>value</literal>. For example,
+            
+            
+            <programlisting>&lt;env key="CLASSPATH" value="C:Javalib"/&gt;</programlisting>
+            will set the environment variable <literal>CLASSPATH</literal> to the value
+            <literal>C:Javalib</literal>. The <literal>&lt;env&gt;</literal>
+            element may be repeated to set multiple environment variables. All of the
+            key/value pairs will be added to the environment by the CPM prior to launching the
+            executable.</para>
+          <note><para>The CPM actually adds ALL system environment variables when it
+          launches the program. It queries the Operating System for its current system
+          variables and one by one adds them to the program&apos;s process
+          configuration.</para></note>
+          
+          <para>The <literal>&lt;arg&gt;</literal> element is used to specify arbitrary
+            string arguments that will appear on the command line when the CPM runs the
+            command specified in the <literal>executable</literal> attribute.</para>
+          
+          <para>For example, the following would be used to invoke the UIMA Java
+            implementation of the Vinci service wrapper on a Java CAS Processor:
+            
+            
+            <programlisting><![CDATA[<runInSeparateProcess>
+    <exec executable="java">
+        <arg>-DVNS_HOST=localhost</arg> 
+        <arg>-DVNS_PORT=9099</arg>
+        <arg>org.apache.uima.reference_impl.analysis_engine.service.
+vinci.VinciAnalysisEngineService_impl</arg> 
+        <arg>C:uimadescdeployCasProcessor.xml</arg>
+    </exec>
+<runInSeparateProcess>]]></programlisting></para>
+          
+          <para>This will cause the CPM to run the following command line when starting the
+            CAS Processor:
+            
+            
+            <programlisting>java -DVNS_HOST=localhost -DVNS_PORT=9099 
+  org.apache.uima.reference_impl.analysis_engine.service.vinci.VinciAnalysisEngineService_impl 
+  C:uimadescdeployCasProcessor.xml</programlisting></para>
+          
+          <para>The first argument specifies that the Vinci Naming Service is running on the
+            <literal>localhost</literal>. The second argument specifies that the Vinci
+            Naming Service port number is <literal>9099</literal>. The third argument
+            identifies the UIMA implementation of the Vinci service wrapper. This class
+            contains the <literal>main</literal> method that will execute. That main
+            method in turn takes a single argument &ndash; the filename for the CAS Processor
+            service deployment descriptor. Thus the last argument identifies the Vinci
+            service deployment descriptor file for the CAS Processor. Since this is the same
+            descriptor file specified earlier in the
+            <literal>&lt;descriptor&gt;</literal> element, the string
+            <literal>${descriptor}</literal> can be used to refer to the descriptor,
+            e.g.:
+            
+            
+            <programlisting>&lt;arg&gt;${descriptor}&lt;/arg&gt;</programlisting></para>
+          
+          <para>The CPM will expand this out to the service deployment descriptor file
+            referenced in the <literal>&lt;descriptor&gt;</literal> element.</para>
+          
+        </section>
+        
+        <section
+          id="&tp;descriptor.cas_processors.individual.deployment_parameters">
+          <title>&lt;deploymentParameters&gt; Element</title>
+          
+          <para>The <literal>&lt;deploymentParameters&gt;</literal> element defines
+            a number of deployment parameters that control how the CPM will interact with the
+            CAS Processor. This element has the following overall form:
+            
+            
+            <programlisting>&lt;deploymentParameters&gt;
+    &lt;parameter name="[String]" value="..." type="string|integer" /&gt; 
     ...
-&lt;/deploymentParameters&gt;</programlisting>
-
-<para>The <literal>name</literal> attribute
-identifies the parameter, the <literal>value</literal> attribute specifies the value that will be assigned
-to the parameter, and the <literal>type</literal> attribute
-indicates the type of the parameter, either <literal>string</literal>
-or <literal>integer</literal>.  The available parameters include:</para>
-
-<itemizedlist spacing="compact"><listitem><literal>vnsHost</literal>
-&ndash; (Deprecated) string parameter specifying the VNS host, e.g., <literal>localhost</literal> for local CAS Processors, host name or IP
-address of VNS host for remote CAS Processors.  This parameter is deprecated; use the parameter specification instead
-inside the Vinci <emphasis>Service Client Descriptor</emphasis>, if needed.  It is ignored for integrated and local deployments.  If present, for remote deployments, it
-specifies the VNS Host to use, unless that is specified in the Vinci <emphasis>Service
-Client Descriptor</emphasis>.</listitem>
-
-
-<listitem><literal>vnsPort </literal>&ndash;
-(Deprecated) integer parameter specifying the VNS port number.  This parameter is deprecated; use the
-parameter specification instead inside the Vinci <emphasis>Service Client Descriptor,</emphasis>
-if needed.  It is ignored for integrated
-and local deployments.  If present, for
-remote deployments, it specifies the VNS
- Port number to use, unless that is
-specified in the Vinci <emphasis>Service Client Descriptor.</emphasis></listitem>
-
-
-<listitem>service-access &ndash; string parameter
-whose value must be <quote>exclusive</quote>, if present.  This parameter is only effective for remote
-deployments.  It modifies the Vinci
-service connections to be preallocated and dedicated, one service instance per
-pipe-line.  It is only relevant for
-non-Integrated deployement modes.  If
-there are fewer services instances that are available (and alive &ndash; responding
-to a <quote>ping</quote> request) than there are pipelines, the number of
-pipelines (the number of concurrent threads) is reduced to match the number of
-available instances.  If not specified,
-the VNS is queried each time a service is needed, and a <quote>random</quote>
-instance is assigned from the pool of available instances.   If a services dies during processing, the CPM
-will use its normal error handling procedures to attempt to reconnect.  The number of attempts is specified in the
-CPE descriptor for each Cas Processor using the <literal>&lt;maxConsecutiveRestarts
-value=<quote>10</quote> action=<quote>kill-pipeline</quote>  waitTimeBetweenRetries=<quote>50</quote> /&gt; </literal>xml
-element.  The <quote>value</quote> attribute
-is the number of reconnection tries; the <quote>action</quote> says what to do if
-the retries exceed the limit.  The
-<quote>kill-pipeline</quote> action stops the pipeline that was associated with
-the failing service (other pipelines will continue to work).  The CAS in process within a killed pipeline
-will be dropped.  These events are
-communicated to the application using the normal event listener mechanism. The <literal>waitTimeBetweenRetries</literal> says how many milliseconds to wait
-inbetween attempts to reconnect.
-</listitem></itemizedlist>
-
-<para>For example, the following parameters might be used with a
-CAS Processor deployed in local mode:</para>
-
-<programlisting>&lt;deploymentParameters&gt;
-  &lt;parameter name=<quote>service-access</quote> value=<quote>exclusive</quote> type=<quote>string</quote>/&gt; 
-&lt;/deploymentParameters&gt;</programlisting>
-
-<h4><a id="_crossRef174"><emphasis>&lt;filter&gt; Element</emphasis></a></h4>
-
-<para>The &lt;filter&gt; element is a required element but
-currently should be left empty.  This
-element is reserved for future use.</para>
-
-<h4><a id="_crossRef175"><emphasis>&lt;errorHandling&gt; Element</emphasis></a></h4>
-
-<para>The mandatory <literal>&lt;er</literal><literal>rorHandling&gt;</literal> element defines error and restart
-policies for the CAS Processor.  Each CAS
-Processor may define different actions in the event of errors and
-restarts.  The CPM monitors and logs
-errant behaviors and attempts to recover the component based on the policies
-specified in this element.</para>
-
-<para>There are two kinds of faults.</para>
-
-<orderedlist><listitem>One kind only occurs with non-integrated CAS Processors &ndash; this fault is
-either a timeout attempting to launch or connect to the non-integrated
-component, or some other kind of connection related exception (for instance,
-the network connection might timeout or get reset).</listitem>
-
-
-<listitem>The other kind happens when the CAS Processor component (an Annotator,
-for example) throws any kind of exception.  This kind may occur with any kind of deployment, integrated or not.
-</listitem></orderedlist>
-
-<para>The &lt;errorHandling&gt; has specifications for each of
-these kinds of faults.  The format of
-this element is:</para>
-
-<programlisting>&lt;errorHandling&gt;
-  &lt;maxConsecutiveRestarts action=<quote>continue|disable|terminate</quote>
-                           value=<quote>[Number]</quote>/&gt;
-  &lt;errorRateThreshold action=<quote>continue|disable|terminate</quote> value=<quote>[Rate]</quote>/&gt;
-  &lt;timeout max=<quote>[Number]</quote>/&gt;
-&lt;/errorHandling&gt;</programlisting>
-
-<para>The mandatory <literal>&lt;maxConsecutiveRestarts&gt;</literal> element
-applies only to faults of the first kind, and therefore, only applies to
-non-integrated deployments.  If such a
-fault occurs, a retry is attempted, up to <literal>value=<quote>[Number]</quote></literal>
-of times.  This retry resets the connection
-(if one was made) and attempts to reconnect and perhaps re-launch (see below
-for details).  The original CAS (not a
-partially updated one) is sent to the CAS Processor as part of the retry, once
-the deployed component has been successfully restarted or reconnected to.</para>
-
-<para>The <literal>action</literal> attribute specifies
-the action to take when the threshold specified by the <literal>value=<quote>[Number]</quote></literal>
-is exceeded.  The possible actions are:</para>
-
-<itemizedlist spacing="compact"><listitem><literal>continue</literal>
-&ndash; skip any further processing for this CAS by this CAS Processor, and pass
-the CAS to the next CAS Processor in the Pipeline. </listitem>
-
-
-<listitem>The <quote>restart</quote> action is done, because it is needed for the
-next CAS.</listitem>
-
-
-<listitem>If the <literal>dropCasOnException=</literal><quote><literal>true</literal></quote>, the CPM will NOT
-pass the CAS to the next CAS Processor in the chain. Instead, the CPM will
-abort processing of this CAS, release the CAS back to the CAS Pool and will
-process the next CAS in the queue.</listitem>
-
-
-<listitem>The counter counting the restarts toward the threshold is only reset
-after a CAS is successfully processed. </listitem>
-
-
-<listitem><literal>disable</literal>
-&ndash; the current CAS is handled just as in the <literal>continue</literal>
-case, but in addition, the CAS Processor is marked so that its <emphasis>process()</emphasis>
-method will not be called again (i.e., it will be <quote>skipped</quote> for
-future CASes)</listitem>
-
-
-<listitem><literal>terminate</literal>
-&ndash; the CPM will terminate all processing and exit
-</listitem></itemizedlist>
-
-<para>The definition of an error for the <literal>&lt;maxConsecutiveRestarts&gt;</literal>
-element differs slightly for each of the three CAS Processor deployment modes:</para>
-
-<table>
- <tr>
-  <td>
-  <para>local</para>
-  </td>
-  <td>
-  <para>Local CAS Processors experience two general error
-  types:</para>
-  <ul style=&apos;margin-top:0in&apos; type="disc">
-   <listitem>launch errors &ndash;
-       errors associated with launching a process</listitem>
-   <listitem>processing errors &ndash;
-       errors associated with sending Vinci commands to the process</listitem>
-  </itemizedlist>
-  <para>A launch error is defined by a failure of the
-  process to successfully register with the local VNS within a default time
-  window.  The current timeout is 15
-  minutes.  Multiple local CAS Processors
-  are launched sequentially, with a subsequent processor launched immediately
-  after its previous processor successfully registers with the VNS.</para>
-  <para>A processing error is detected if a connection to
-  the CAS Processor is lost or if the processing time exceeds a specified
-  timeout value.</para>
-  <para>For local CAS Processors, the
-  &lt;maxConsecutiveRestarts&gt; element specifies the number of consecutive
-  attempts made to launch the CAS Processor at CPM startup or after the CPM has
-  lost a connection to the CAS Processor.</para>
-  </td>
- </tr>
- <tr>
-  <td>
-  <para>remote</para>
-  </td>
-  <td>
-  <para>For remote CAS Processors, the
-  &lt;maxConsecutiveRestarts&gt; element applies to errors from sending Vinci
-  commands.  An error is detected if a
-  connection to the CAS Processor is lost, or if the processing time exceeds
-  the timeout value specified in the &lt;timeout&gt; element (see below).</para>
-  </td>
- </tr>
- <tr>
-  <td>
-  <para>integrated</para>
-  </td>
-  <td>
-  <para>Although
-  mandatory, the &lt;maxConsecutiveRestarts&gt; element is NOT used for
-  integrated CAS Processors, because Integrated CAS Processors are not
-  re-instantiated/restarted on exceptions. This setting is ignored by the CPM
-  for Integrated CAS Processors but it is required. Future version of the CPM
-  will make this element mandatory for remote and local CAS Processors only.</para>
-  </td>
- </tr>
-</table>
-
-<para>The mandatory <literal>&lt;errorRateThreshold&gt;</literal>
-element is used for all faults &ndash; both those above, and exceptions thrown by the
-CAS Processor itself.  It specifies the
-number of retries for exceptions thrown by the CAS Processor itself, a maximum
-error rate, and the corresponding action to take when this rate is
-exceeded.  The <literal>value</literal>
-attribute specifies the error rate in terms of errors per sample size in the
-form &ldquo;<literal>N/M</literal><quote>, where <literal>N</literal>
-is the number of errors and <literal>M</literal> is the sample size,
-defined in terms of the number of documents.</para>
-
-<para>The first number is used also to indicate the maximum
-number of retries.  If this number is
-less than the <literal>&lt;maxConsecutiveRestarts value=</quote>[Number]<quote>&gt;,
-</literal>it will override, reducing the number of </quote>restarts<quote>
-attempted.  A retry is done only if the <literal>dropCasOnException </literal>is false.  If it is set to true, no retry occurs, but
-the error is counted.</para>
-
-<para>When the number of counted errors exceeds the sample size,
-an action specified by the <literal>action</literal> attribute is
-taken.  The possible actions and their
-meaning are the same as described above for the <literal>&lt;maxConsecutiveRestarts&gt;</literal>
-element:</para>
-
-<para><literal>continue</literal></para>
-
-<para><literal>disable</literal></para>
-
-<para><literal>terminate</literal></para>
-
-<para>The <literal>dropCasOnException=</literal></quote><literal>true</literal><quote> attribute of the <literal>&lt;casProcessors&gt;</literal> element modifies the action taken
-for continue and disable, in the same manner as above. For example:</para>
-
-<programlisting>&lt;errorRateThreshold value=</quote>3/1000<quote> action=</quote>disable<quote> /&gt;</programlisting>
-
-<para>specifies that each error thrown by the CAS Processor
-itself will be retried up to 3 times (if <literal>dropCasOnException</literal>
-is false) and the CAS Processor will be disabled if the error rate exceeds 3
-errors in 1000 documents.</para>
-
-<para>If a document causes an error and the error rate threshold
-for the CAS Processor is not exceeded, the CPM increments the CAS Processor&apos;s
-error count and retries processing that document (if <literal>dropCasOnException</literal>
-is false).  The retry means that the CPM
-calls the CAS Processor&apos;s process() method again, passing in as an argument the
-same CAS that previously caused an exception.</para>
-
-<note>The CPM does not attempt to rollback any partial changes that may have
-been applied to the CAS in the previous process() call.  
-</listitem></itemizedlist>
-
-<para>Errors are accumulated across documents.  For example, assume the error rate threshold
-is <literal>3/1000</literal>.  The same document may fail three times before
-finally succeeding on the fourth try, but the error count is now 3.  If one more error occurs within the current
-sample of 1000 documents, the error rate threshold will be exceeded and the
-specified action will be taken.  If no
-more errors occur within the current sample, the error counter is reset to 0
-for the next sample of 1000 documents.</para>
-
-<para>The <literal>&lt;timeout&gt;</literal> element is
-a mandatory element. Although mandatory for all CAS Processors, this element is
-only relevant for local and remote CAS Processors. For integrated CAS
-Processors, this element is ignored. In the current CPM implementation the
-integrated CAS Processor process() method is not subject to timeouts.</para>
-
-<para>The <literal>max</literal> attribute specifies the
-maximum amount of time in milliseconds the CPM will wait for a process() method
-to complete  When exceeded, the CPM will
-generate an exception and will treat this as an error subject to the threshold
-defined in the <literal>&lt;errorRateThreshold&gt;</literal> element
-above, including doing retries.</para>
-
-<h4>Retry action taken
-on a timeout</h4>
-
-<para>The action taken depends on whether the CAS Processor is
-local (managed) or remote (unmanaged).  Local CAS Processors (which are services) are killed and restarted, and
-a new connection to them is established.  For remote CAS Processors, the connection to them is dropped, and a new
-connection is reestablished (which may actually connect to a different instance
-of the remote services, if it has multiple instances).</para>
-
-<h4><a id="_crossRef176"><emphasis>&lt;checkpoint&gt; Element</emphasis></a></h4>
-
-<para>The <literal>&lt;checkpoint&gt;</literal> element
-is an optional element used to improve the performance of CAS Consumers.  It has a single attribute, <literal>batch</literal>, which specifies the number of CASes in a batch,
-e.g.:</para>
-
-<programlisting>&lt;checkpoint batch=</quote>1000<quote>&gt;</programlisting>
-
-<para>sets the batch size to 1000 CASes.  The batch size is the interval used to mark a
-point in processing requiring special handling.  The CAS Processor&apos;s     <literal>batchProcessComplete() </literal>method will be called by the CPM
-when this mark is reached so that the processor can take appropriate
-action.  This mark could be used as a
-mechanism to buffer up results in CAS Consumers and perform time-consuming
-operations, such as check-pointing, that should not be done on a per-document
-basis.</para>
-
-<h3><a id="_crossRef177">CPE Operational Parameters</a></h3>
-
-<para>The parameters for configuring the overall CPE and CPM are
-specified in the <literal>&lt;cpeConfig&gt;</literal> section.  The overall format of this section is:</para>
-
-<programlisting>&lt;cpeConfig&gt;</programlisting>
-
-<programlisting>    &lt;startAt&gt;[NumberOrID]&lt;/startAt&gt;</programlisting>
-
-<programlisting>    &lt;numToProcess&gt;[Number]&lt;/numToProcess&gt;</programlisting>
-
-<programlisting>    &lt;outputQueue dequeueTimeout=</quote>[Number]<quote> queueClass=</quote>[ClassName]<quote> /&gt;</programlisting>
-
-<programlisting>    &lt;checkpoint file=</quote>[File]<quote> time=</quote>[Number]<quote> batch=</quote>[Number]<quote>/&gt;</programlisting>
-
-<programlisting>    &lt;timerImpl&gt;[ClassName]&lt;/timerImpl&gt;</programlisting>
-
-<programlisting>    &lt;deployAs&gt;vinciService|interactive|immediate|single-threaded
-&lt;/deployAs&gt;</programlisting>
-
-<programlisting>&lt;/cpeConfig&gt;</programlisting>
-
-<para>This section of the CPE descriptor allows for defining the
-starting entity, the number of entities to process, a checkpoint file and frequency,
-a pluggable timer, an optional output queue implementation, and finally a mode
-of operation.  The mode of operation
-determines how the CPM interacts with users and other systems.</para>
-
-<para><a id="_crossRef178">The </a><literal>&lt;startAt&gt;</literal>
-element is an optional argument.   It defines the starting entity in the collection at which the CPM should
-start processing.</para>
-
-<para>The implementation in the CPM passes the this argument to
-the Collection Reader as the value of the parameter </quote><literal>startNumber</literal><quote>.   The CPM does not do anything else with this
-parameter; in particular, the CPM has no ability to skip to a specific document
-- that function, if available, is only provided by a particular Collection
-Reader implementation.</para>
-
-<para>If the <literal>&lt;startAt&gt;</literal> element
-is used, the Collection Reader descriptor must define a single-valued
-configuration parameter with the name <literal>startNumber</literal>.  It can declare this value to be of any type;
-the value passed in this XML element must be convertible to that type.</para>
-
-<para>A typical use is to declare this to be an integer type,
-and to pass the sequential document number where processing should start.  An alternative implementation might take a
-specific document ID; the collection reader could search through its collection
-until it reaches this ID and then start there.</para>
-
-<para>This parameter will only make sense if the particular
-collection reader is implemented to use the <literal>startNumber</literal>
-configuration parameter.</para>
-
-<para>The <a id="_crossRef179"><literal>&lt;numToProcess&gt;</literal>
-element</a> is an optional element.  It specifies the total number of entities to process.  Use -1 to indicate ALL.  If not defined, the number of entities to
-process will be taken from the Collection Reader configuration.  If present, this value overrides the
-Collection <a id="_crossRef180">Reader configuration.</a></para>
-
-<para>The <literal>&lt;outputQueue&gt;</literal>
-element is an optional element. It enables plugging in a custom implementation
-for the Output Queue. When omitted, the CPM will use a default output queue
-that is based on First-in First-out (FIFO) model.</para>
-
-<para>The UIMA SDK provides a second implementation
-for the Output Queue that can be plugged in to the CPM, named <literal></quote>org.apache.uima.reference_impl.<br/>
-collection.cpm.engine.SequencedQueue<quote></literal>.</para>
-
-<para>This implementation supports handling very
-large documents that are split into </quote>chunks<quote>; it provides a delivery
-mechanism that insures the sequential order of the chunks using information
-carried in the CAS metadata. This metadata, which is required for this
-implementation to work correctly, must be added as an instance of a Feature
-Structure of type <literal>org.apache.es.tt.DocumentMetaData</literal>
-and referred to by an additional feature named <literal>esDocumentMetaData</literal> in the special instance of <literal>uima.tcas.DocumentAnnotation</literal> that is associated with the
-CAS. This is usually done by the Collection Reader; the instance contains the
-following features:</para>
-
-<orderedlist><listitem>sequenceNumber  &ndash; [Number]  the sequential number of a chunk, starting at
-1. If not a chunk (i.e. complete document), the value should be 0.</listitem>
-
-
-<listitem>documentId &ndash; [Number]
-current document id. Chunks belonging to the same document have
-identical document id.</listitem>
-
-
-<listitem>isCompleted &ndash; [Number] 1 if the chunk is the last in a sequence, 0
-otherwise. </listitem>
-
-
-<listitem>url &ndash; [String] document url</listitem>
-
-
-<listitem>throttleID &ndash; [String] special attribute currently used by OmniFind
-</listitem></orderedlist>
-
-<para>This implementation of a sequenced queue
-supports proper sequencing of CASes in CPM deployments that use document
-chunking. Chunking is a technique of splitting large documents into pieces to
-reduce overall memory consumption. Chunking does not depend on the number of
-CASes in the CAS Pool. It works equally well with one or more CASes in the CAS
-Pool. Each chunk is packaged in a separate CAS and placed in the Work Queue. If
-the CAS Pool is depleted, the CollectionReader thread is suspended until a CAS
-is released back to the pool by the processing threads. A document may be split
-into 1, 2, 3 or more chunks that are analyzed independently. In order to
-reconstruct the document correctly, the CAS Consumer can depend on receiving
-the chunks in the same sequential order that the chunks were
-</quote>produced<quote>, when this sequenced queue implementation is used. To plug
-in this sequenced queue to the CPM  use
-the following specification:</para>
-
-<para><literal>&lt;outputQueue
-dequeueTimeout=</quote>100000<quote>
-queueClass=</quote>org.apache.uima.reference_impl.collection.cpm.engine.SequencedQueue<quote>/&gt;</literal></para>
-
-<para>where the mandatory <literal>queueClass</literal><literal> </literal>attribute defines
-the name of the class and the second mandatory attribute, <literal>dequeueTimeout </literal>specifies the maximum number of
-milliseconds to wait for the expected chunk.</para>
-
-<note>The value for this timeout must be carefully determined to avoid
-excessive occurrences of timeouts.  Typically, the size of a chunk and the type of analysis being done are
-the most important factors when deciding on the value for the timeout. The
-larger the chunk and the more complicated analysis, the more time it takes for
-the chunk to go from source to sink.
-</listitem></itemizedlist>
-
-<para>If the chunk doesn&apos;t arrive in the configured
-time window, the entire document is presumed to be invalid and the CAS is
-dropped from further processing.  This
-action occurs regardless of any other error action specification.  The SequencedQueue invalidate the document,
-adding the offending document&apos;s metadata to a local cache of invalid documents.
-</para>
-
-<para>If the time out occurs, the CPM notifies all
-registered listeners (see <b><a class="crossrefText" href="CPE_Developers_Guide.htm#_crossRef190">Using
-Listeners</a></b> <a class="crossrefPage" href="CPE_Developers_Guide.htm#_crossRef190"></a>) by calling entityProcessComplete(). As part of this
-call, the SequencedQueue will pass null instead of a CAS as the first argument,
-and a special exception &ndash; CPMChunkTimeoutException. The reason for passing null
-as the first argument is because the time out occurs due to the fact that the
-chunk has not been received in the configured timeout window, so there is no
-CAS available when the timeout event occurs.</para>
-
-<para>The CPMChunkTimeoutException object exposes
-an API that allows the listener to retrieve the offending document id as well
-as the other metadata attributes as defined above. These attributes are part of
-each chunk&apos;s metadata and are added by the Collection Reader.</para>
-
-<para>Each chunk that SequencedQueue works on is
-subjected to a test to determine if the chunk belongs to an invalid document.
-This test checks the chunk&apos;s metadata against the data in the local cache. If
-there is a match, the chunk is dropped. This check is only performed for chunks
-and complete documents are not subject to this check.</para>
-
-<para>If there is an exception during the
-processing of a chunk, the CPM sends a notification to all registered
-listeners. The notification includes the CAS and an exception.  When the listener notification is completed,
-the CPM also sends separate notifications, containing the CAS, to the Artifact

[... 855 lines stripped ...]