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/01/08 03:20:52 UTC

svn commit: r609837 [1/4] - in /incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks: ./ src/ src/docbook/ src/docbook/uima_async_scaleout/ src/docbook/uima_async_scaleout/images/ src/docbook/uima_async_scaleout/images/async.errorhandling/ src/docbook...

Author: schor
Date: Mon Jan  7 18:20:50 2008
New Revision: 609837

URL: http://svn.apache.org/viewvc?rev=609837&view=rev
Log:
[UIMA-689] initial import under software grant to ASF.

Added:
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/.project
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/build.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/local.docbook.properties
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.errorhandling.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.overview.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/basic_error_chain.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/disable_action.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/error_chain.ppt   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/error_chain_aggregate_without_terminate_disable.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/errors_sent_up.ppt   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/message_commands.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/message_commands.ppt   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/terminate_action.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.errorhandling/terminate_disable.jpg   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.overview/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.overview/wrapAAE.png   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.overview/wrapAAE.ppt   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.overview/wrapAE.png   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/images/async.overview/wrapAE.ppt   (with props)
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/uima_async_scaleout.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/olink_db_html.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/olink_db_htmlsingle.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/olink_db_pdf.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/uima_async_scaleout/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/uima_async_scaleout/html-target.db
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/uima_async_scaleout/htmlsingle-target.db
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/olink/uima_async_scaleout/pdf-target.db
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/titlepage/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/titlepage/titlepage-html.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/titlepage/titlepage-html.xsl
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/titlepage/titlepage-pdf.xml
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/titlepage/titlepage-pdf.xsl
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/top/
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/top/html-single.xsl
    incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/styles/top/pdf.xsl

Added: incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/.project
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/.project?rev=609837&view=auto
==============================================================================
--- incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/.project (added)
+++ incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/.project Mon Jan  7 18:20:50 2008
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>uima-ee-docbooks</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+	</natures>
+</projectDescription>

Added: incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/build.xml
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/build.xml?rev=609837&view=auto
==============================================================================
--- incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/build.xml (added)
+++ incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/build.xml Mon Jan  7 18:20:50 2008
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.    
+-->
+
+<!-- set the basedir value to point to the top level of the project -->
+
+<project name="name of book to build" default="all" basedir=".">
+  
+  <property name="book_name" value="uima_async_scaleout"/>
+  
+  <import file="../uima-docbook-tool/build/build-docbook.xml"/>  
+  
+</project>

Added: incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/local.docbook.properties
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/local.docbook.properties?rev=609837&view=auto
==============================================================================
--- incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/local.docbook.properties (added)
+++ incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/local.docbook.properties Mon Jan  7 18:20:50 2008
@@ -0,0 +1,25 @@
+# Copyright 2006 The Apache Software Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# which version of fop to use
+fop.version = 0.93
+
+# which version of docbook to use
+docbook.version.xml = 4.5
+docbook.version.xsl = 1.72.0
+
+# uncomment these to skip parts of the build
+skip.html-chunked = true
+#skip.html-single = true
+#skip.pdf = true

Added: incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.errorhandling.xml
URL: http://svn.apache.org/viewvc/incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.errorhandling.xml?rev=609837&view=auto
==============================================================================
--- incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.errorhandling.xml (added)
+++ incubator/uima/sandbox/trunk/uima-ee/uima-ee-docbooks/src/docbook/uima_async_scaleout/async.errorhandling.xml Mon Jan  7 18:20:50 2008
@@ -0,0 +1,796 @@
+<?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 % uimaents SYSTEM "../../../../uima-docbook-tool/styles/uima-style/common/entities.ent" >
+  %uimaents;
+<!ENTITY imgroot "../images/uima_async_scaleout/async.errorhandling/" >
+  ]>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+  
+<chapter id="ugr.async.eh">
+  <title>Error Handling for Asynchronous Scaleout</title>
+  <para> This chapter discusses the high level architecture for Error Handling from the
+    user's point of view. </para>
+  
+  <section id="ugr.async.eh.basic">
+    <title>Basic concepts</title>
+    
+    <para>This chapter describes error configuration for AS components. The service client
+      descriptor for connecting to an AS component also has some configuration related to
+      errors, but that is discussed elsewhere.</para>
+    
+    <para>The AS framework manages a collection of component parts written by users (user
+      code) which can throw exceptions. In addition, the AS framework can run timers when
+      sending commands to user code which can create timeouts.</para>
+    
+    <para>An AS component is either an AS aggregate or an AS primitive. AS aggregates can have
+      multiple levels of aggregation; error configuration is done for each level of
+      aggregation. The rest of this chapter focuses on the error configuration one level at a
+      time (either for one particular level in an aggregate hierarchy, or for an AS
+      primitive). </para>
+    
+    <para>There is a small number of commands which can be sent to an AS component. When a
+      component returns the result, if an error occurs, an error result is returned instead of
+      the normal result.</para>
+    
+    <para>Configuration and support is provided for three classes of errors: </para>
+    
+    <orderedlist>
+      <listitem><para>Exceptions thrown from code (component or framework) at this
+        level</para></listitem>
+      <listitem><para>error messages received from delegates.</para></listitem>
+      <listitem><para>timeouts of commands sent to delegates.</para></listitem>
+    </orderedlist>
+    
+    <para>The second and third class of errors is only possible for AS aggregates.</para>
+    
+    <para>When errors happen, the framework provides a standard set of configurable
+      actions. These can be extended with (optional) user-supplied error handling code. See
+        <xref linkend="ugr.async.eh.commands_allowed_actions"/> for a summary table of
+      the actions available in different situations.</para>
+    
+  </section>
+  
+  <section id="ugr.async.eh.incoming_commands">
+    <title>Associating Errors with incoming commands</title>
+    <para> Components managed by AS may generate errors when they are sent a command. The error
+      is associated with the command that was running to produce the error. </para>
+    
+    <!--figure id="ugr.async.eh.fig.message_commands">
+    <title>Commands contained in messages</title>
+    <mediaobject>
+    <imageobject>
+    <imagedata width="350px" format="JPG"
+    fileref="&imgroot;message_commands.jpg"/>
+    </imageobject>
+    <textobject><phrase>Commands contained in messages</phrase>
+    </textobject>
+    </mediaobject>
+    </figure-->
+    
+    <para>There are three incoming message commands supported by the AS framework:
+      <orderedlist spacing="compact">
+        <listitem><para>getMetadata - sent by the framework when setting up a new
+          run</para></listitem>
+        <listitem><para>processCas - sent repeatedly, once for each CAS</para>
+          </listitem>
+        <listitem><para>collectionProcessComplete - sent when an application calls
+          this method</para>
+        </listitem>
+        <!--listitem><para>terminate - stop running and clean up; sent by the framework as part
+          of a terminate action</para></listitem-->
+      </orderedlist>
+      </para>
+    
+    <!--itemizedlist mark="none"><listitem><para>There are three other commands, but
+    these are not passed as messages:
+    <orderedlist spacing="compact">
+    <listitem><para>initialize (called by the framework when creating an instance
+    of the component)</para></listitem>
+    <listitem><para>reinitialize</para></listitem>
+    <listitem><para>terminate</para></listitem>
+    </orderedlist> </para></listitem>
+    
+    </itemizedlist-->
+    <para> Error handling actions are associated with these various commands. Some error
+      handling actions make sense only if there is an associated CAS object, and are therefore
+      only allowed with the processCas command. </para>
+    
+  </section>
+  
+  <section id="ugr.async.eh.error_handling_overview">
+    <title>Error handling overview</title>
+    
+    <para>When an error happens, it is either "recovered", or not; only errors from delegates
+      of an AS aggregate can be recovered.</para>
+    
+    <para>Commands normally return results; however if an non-recoverable error occurs,
+      the command returns an error result instead. </para>
+    
+    <para> For AS aggregates, each level in aggregate hierarchy can be configured to try to
+      recover the error. If a particular AS aggregate level does not recover, the error is sent
+      up to the next level of the hierarchy (or to the calling client, if a top level). The error
+      result is updated to reflect the actions the framework takes for this error. </para>
+    
+    <para> Non-recovered errors can optionally have an associated "Terminate" or "Disable"
+      action (see below), triggered by the error when a threshold is reached.
+      
+      <!--itemizedlist mark="none"><listitem><para>The "Disable" action is only available 
+      in AS Aggregates for non-recovered errors involving a delegate.</para></listitem>
+      </itemizedlist--> </para>
+    
+    <para> These actions, if they occur, are recorded in the error result, indicating that the
+      additional Terminate or Disable action occurred. </para>
+    
+    <figure id="ugr.async.eh.fig.basic_eh_chain">
+      <title>Basic error handling chain for AS Aggregates for errors from
+        delegates</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata width="230px" format="JPG"
+            fileref="&imgroot;basic_error_chain.jpg"/>
+        </imageobject>
+        <textobject><phrase>Basic error handling chain</phrase>
+        </textobject>
+      </mediaobject>
+    </figure>
+    
+    <para> The basic error handling chain starts with an error, and can attempt to recover
+      using retry. If this fails (or is not configured), any Terminate or Disable action that
+      is specified is examined to see if this error exceeded their threshold, and if so, the
+      framework disables a delegate or terminates the entire component. If not, the error is
+      counted for those thresholds, and recovery by the Continue action can be attempted. If
+      that fails, an error result is returned to the caller. </para>
+  </section>
+  
+  <section id="ugr.async.eh.error_results">
+    <title>Error results</title>
+    <para>When an error occurs and is not recovered, an error result is returned to the caller.
+      This is an object with the following methods: </para>
+    
+    <table frame="all" rowsep="1" colsep="1" id="ugr.async.eh.table.error_result">
+      <title>Error Result</title>
+      <tgroup cols="2">
+        <colspec colnum="1" colname="col1" colwidth="1*"/>
+        <colspec colnum="2" colname="col2" colwidth="2*"/>
+        <thead>
+          <row>
+            <entry>Method</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>Throwable getRootCause()</entry>
+            <entry>Returns the underlying root cause first reported as an error</entry>
+          </row>
+          <row>
+            <entry>ErrorResultComponentPath getComponentKeyPath()</entry>
+            <entry>Returns a path consisting of a list of component key names (for
+              delegates) or brokerURL + endpoint elements, for top-level components not
+              contained in an aggregate, leading down to the component that first reported
+              the error. The path starts with the current component, and ends with the
+              component associated with the original error.</entry>
+          </row>
+          <row><entry>wasTerminated()</entry><entry>true if any termination occurred
+            with this error</entry></row>
+          <row><entry>wasDisabled()</entry><entry>true if any disabling occurred with
+            this error</entry></row>
+          <row>
+            <entry>ErrorResultTDs getTDs()</entry>
+            <entry>Returns a collection of path(s) to the component(s) that was/were
+              terminated or disabled, together with a flag indicating which (could be
+              both).
+            </entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+  </section>
+  
+  <section id="ugr.async.eh.aggregate_managed">
+    <title>Error Recovery actions</title>
+    <para> When errors occur in delegates, the aggregate containing them can attempt to
+      recover. There are two basic recovery actions: retrying the same command and
+      continuing past (skipping) the failing component. </para>
+    
+    <!--para>Errors associated with a delegate are either exceptions or timeouts.</para>
+    
+    <para>An aggregate receives exceptions thrown by a delegate as a message being
+    returned from that delegate, in place of the normal return message.
+    Normal execution returns a CAS if the command was "processCas"; but if an
+    exception is returned, the CAS is not sent back. </para>
+    <note><para>If the delegate is co-located, the
+    aggregate and the delegate are actually sharing a common CAS object, so the
+    aggregate has access to the CAS in this case.</para></note-->
+    
+    <para>Every command sent to a delegate can have an associated (configurable) timeout. If
+      the timeout occurs before the delegate responds, the framework creates an error
+      representing the timeout. <note><para>If, subsequently, a response is (finally)
+      received corresponding to the command that had timed-out, this is logged, but the
+      response is discarded and no further action is taken.</para></note> </para>
+    
+    <!--figure
+      id="ugr.async.eh.fig.error_chain_aggregate_without_terminate_disable">
+      <title>Retry chain</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata width="170px" format="JPG"
+            fileref="&imgroot;error_chain_aggregate_without_terminate_disable.jpg"/>
+        </imageobject>
+        <textobject><phrase>Error handling - aggregate</phrase>
+        </textobject>
+      </mediaobject>
+    </figure-->
+    
+    <para>When errors occur in delegates, retry is attempted (if configured), some number of
+      times. If that fails, error counts are incremented and thresholds examined for
+      Terminate/Disable actions. If those actions are not taken, Continue is attempted (if
+      configured). If Continue fails, the error is not recovered, and the aggregate returns
+      the error result from the delegate to the aggregate's caller. </para>
+    
+    <section id="ugr.async.eh.aggregate_managed.actions">
+      <title>Aggregate Error Actions</title>
+      <para>This section describes the error actions in more detail.</para>
+      <section id="ugr.async.eh.aggregate_managed.actions.retry">
+        <title>Retry</title>
+        <para>Retry is an action which re-sends the same command that failed back to the input
+          queue of the delegate. (Note: It may be picked up by a different instance of that
+          delegate, which may have a better chance of succeeding.)
+          The framework will keep a copy of the CAS sent to remote components in order to
+          have it to send again if a retry is required.</para>
+        
+        <para><emphasis role="bold">Retry is not allowed for colocated delegates.</emphasis></para>
+        
+        <para>The "collectionProcessComplete" command is never retried.</para>
+        
+        <para>Retry is done some number of times, as specified in the deployment
+          descriptor.</para>
+      </section> <!-- end of retry -->
+      
+      <section id="ugr.async.eh.aggregate_disable">
+        <title>Disable Action</title>
+        
+        <figure id="ugr.async.eh.fig.disable">
+          <title>Disable action</title>
+          <mediaobject>
+            <imageobject>
+              <imagedata width="150px" format="JPG"
+                fileref="&imgroot;disable_action.jpg"/>
+            </imageobject>
+            <textobject><phrase>Disable Action</phrase>
+            </textobject>
+          </mediaobject>
+        </figure>
+        
+        <para>The Disable action is allowed only on delegate errors. When trigger, it marks
+          the particular delegate causing the error as "disabled" so it is always skipped in
+          subsequent calls. When this action is taken, the framework calls the flow
+          controller, telling it to remove the particular delegate from the flow.</para>
+        
+      </section>
+      
+      <section id="ugr.async.eh.aggregate_managed.actions.continue">
+        <title>Continue Option on Delegate Process CAS Failures</title>
+        <para>For processCas commands, the Continue action causes the framework to give the
+          flow controller object for that CAS the error details, and ask the flow controller
+          if processing can continue. If the flow controller returns "true", the flow controller
+          will be called asking for the next step; if "false", the framework stops processing the 
+          CAS, returning an error to the client reply queue, or just returning the CAS to the 
+          casPool of the CAS multiplier which created it. </para>
+        
+        <para>For "collectionProcessComplete" commands, Continue means to ignore the
+          error, and continue as if the collectionProcessComplete call had returned
+          normally.</para>
+        
+        <para>This action is not allowed for the getMetadata command.</para>
+      </section>
+      
+      <!--section id="ugr.async.eh.aggregate_managed.actions.abort_cas">
+      <title>AbortCas Action</title>
+      <para>AbortCas means that, at this level in the aggregate nesting,
+      <itemizedlist spacing="compact">
+      <listitem><para>further CAS processing stops</para></listitem>
+      <listitem><para>the underlying error result is return, with an indication that
+      CAS processing was aborted.</para></listitem>
+      </itemizedlist> </para>
+      
+      <para>AbortCas is only allowed for the processCas command; the other commands do not have
+      an associated CAS.</para>
+      </section-->
+    </section> <!-- end of aggregate_managed.actions -->
+    
+  </section> <!-- end of aggregate_managed -->
+  
+    <!--para>The Terminate looking "upwards" towards its caller, disconnects the component (where the error is being handled) 
+    from its input queue; while the Disable, looking "downwards" toward a particular delegate, removes that delegate
+    from the list of delegates its flow controller will send work to.
+    </para-->
+    
+    <!--figure id="ugr.async.eh.fig.terminate_disable">
+    <title>Terminate and Disable actions</title>
+    <mediaobject>
+    <imageobject>
+    <imagedata width="250px" format="JPG"
+    fileref="&imgroot;terminate_disable.jpg"/>
+    </imageobject>
+    <textobject><phrase>Terminate and Disable Actions</phrase>
+    </textobject>
+    </mediaobject>
+    </figure-->
+    
+    <section id="ugr.async.eh.errors_passed_up.thresholds">
+      <title>Thresholds for Terminate and Disable</title>
+      
+      <para> The Terminate and Disable actions are conditioned by testing against a
+        threshold. Thresholds are specified as a "rate" based on processed CASes - so many
+        errors per number of CASes processed. </para>
+      
+      <para> Thresholds are specified as two numbers - an error count and a window. The
+        threshold is exceeded if the number of errors occurring within the window size is equal
+        to or greater than "error count". (A count of 0 for the error count is treated as a
+        special value and disables the error threshold.)</para>
+      
+     <para>Errors associated with the processCas command are the only ones that
+       are counted in the threshold measurements.</para>
+
+    </section>
+    
+    <section id="ugr.async.eh.terminate">
+      
+      <title>Terminate Action</title>
+      
+      <para>If the threshold is exceeded, the service represented by this component
+        terminates, disconnecting itself as a listener from its input queue, and cleaning
+        itself up (releasing resources, etc.). During cleanup, the component analysis
+        engine's <literal>destroy</literal> method is called.</para>
+      
+      <itemizedlist mark="none"><listitem>
+        <para>The termination action is cascaded down to all co-located, non-shared
+          delegates, if any.</para>
+        </listitem>
+      </itemizedlist>
+      
+      <figure id="ugr.async.eh.fig.terminate">
+        <title>Terminate action</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata width="150px" format="JPG"
+              fileref="&imgroot;terminate_action.jpg"/>
+          </imageobject>
+          <textobject><phrase>Terminate Action</phrase>
+          </textobject>
+        </mediaobject>
+      </figure>
+      
+      <para>If the threshold is not exceeded, the error counts associated with the threshold
+        are incremented.</para> <note><para>Some errors will always cause a terminate:
+      for instance, framework or flow controller errors cause immediate
+      termination.</para></note>
+      
+    </section> <!-- end of actions for terminate -->
+    
+  
+  <!--section id="ugr.async.eh.error_wrapping">
+  <title>Error wrapping</title>
+  <para>An error occurring at some level will be wrapped by other errors as it is passed up the chain.
+  The wrapping mechanism used is the standard Java one (since Java 1.4).  The wrapping preserves the
+  original error while adding information about how it was handled at higher levels.</para>
+  </section-->
+  
+  <!--section id="ugr.async.eh.error_chaining">
+  <title>Error chaining</title>
+  <para>Once an error occurs, it may result in several different actions happening
+  as the error is passed through a chain of error handlers.  There are four possible situations,
+  each having a particular chain configuration:
+  
+  <orderedlist>
+  <listitem><para>AS aggregate</para></listitem>
+  <listitem><para>AS primitive having a remote service client connecting to an AS service</para></listitem>
+  <listitem><para>Synchronous component having a remote service client connecting to an AS service</para></listitem>
+  <listitem><para>AS primitive without a service client descriptor connecting to an AS service
+  </para></listitem>
+  </orderedlist>
+  </para>
+  
+  <section id="ugr.async.eh.error_chaining.as-aggregate">
+  <title>AS aggregate error chaining</title>
+  <para> For an AS aggregate, the actions are chained together as follows:
+  <figure id="ugr.async.eh.fig.error_chain_aggregate_without_terminate_disable">
+  <title>Retry chain</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="170px" format="JPG"
+  fileref="&imgroot;error_chain_aggregate_without_terminate_disable.jpg"/>
+  </imageobject>
+  <textobject><phrase>Error handling - aggregate</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  
+  <orderedlist>
+  <listitem><para>First, retry is attempted, if it's enabled, and the retry
+  count has not been exceeded.</para></listitem>
+  <listitem><para>Second, recovery by Continuing is attempted, if
+  specified.</para></listitem>
+  <listitem><para>If neither of these two stratagies succeeds, a AbortCas error, 
+  wrapping the error being handled, will be sent
+  back as a reply to the command associated with the error, in place of the CAS.</para></listitem>
+  </orderedlist> </para>
+  
+  <para>In the figure, the upwards pointing arrows show the next error handler in the chain.  If
+  the "Retry" or "Continue" action succeeds, no error is reported up higher.</para>
+  
+  <para>When an error is sent back as a reply from the aggregate, if the Disable and/or
+  Terminate actions have been configured for this aggregate, the error counts are
+  checked against the threshold, and if the threshold is passed, the Disable or Terminate
+  action occurs as the error is sent up, and the error is again wrapped, indicating this.</para>
+  
+  <figure id="ugr.async.eh.fig.error_chain_aggregate">
+  <title>Error chain - aggregate</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="230px" format="JPG"
+  fileref="&imgroot;error_chain_aggregate.jpg"/>
+  </imageobject>
+  <textobject><phrase>Error handling - in an aggregate</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  
+  </section>
+  
+  <section id="ugr.async.eh.error_chaining.as_primitive_or_synchronouse_as_remote">
+  <title>AS primitive and synchronous with AS remote: error chaining</title>
+  <para>AS primitive or synchronous components having AS remote service clients 
+  have an error chain for each of those remotes, similar
+  to normal AS-managed aggregates, except that there is no "Continue" action (because
+  there is no flow controller involved), and the
+  "Terminate" action is allowed only for AS primitive components (it is not allowed
+  for synchronous ones).
+  </para>  
+  
+  <figure id="ugr.async.eh.fig.error_as_primitive_with_AS_remote">
+  <title>Error chain for AS primitive or synchronous components having AS remotes</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="150px" format="JPG"
+  fileref="&imgroot;error_primitive_with_AS_remote.jpg"/>
+  </imageobject>
+  <textobject><phrase>Error handling - AS primitive or synchronous components having AS remotes</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  </section>
+  
+  <section id="ugr.async.eh.error_chaining.as_primitive_without_as_remote">
+  <title>AS primitive without AS remote: error chaining</title>
+  <para>AS primitive components not containing AS remote service clients can only specify a Terminate action for exceptions
+  thrown in the component.</para>  
+  
+  <figure id="ugr.async.eh.fig.error_primitive">
+  <title>Terminate action for AS Primitive Components without AS remote service clients</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="230px" format="JPG"
+  fileref="&imgroot;error_primitive.jpg"/>
+  </imageobject>
+  <textobject><phrase>Error handling - AS primitive components without AS remote service clients only support Terminate</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  </section>
+  
+  </section-->
+  
+  <section id="ugr.async.eh.commands_allowed_actions">
+    <title>Commands and allowed actions</title>
+    <para>All of the allowed actions are optional, and default to not being done, except for
+      getMetadata being sent to a delegate that is remote - this has a default timeout of 1
+      minute.</para>
+    
+    <para>Here's a table of the allowed actions, by command. In this table, the Retry,
+      Continue, and Disable actions apply to the particular Delegate associated with the
+      error; the Terminate action applies to the entire component. </para>
+    
+    <para>The framework returns an Error Result to the caller for errors that are not
+      recovered.</para>
+    
+    <table frame="all" rowsep="1" colsep="1" id="ugr.async.eh.table.error_actions_by_command">
+      <title>Error actions by command type</title>
+      <tgroup cols="3">
+        <colspec colnum="1" colname="col1" colwidth="1*"/>
+        <colspec colnum="2" colname="col2" colwidth="2*"/>
+        <colspec colnum="3" colname="col3" colwidth="2*"/>
+        <thead>
+          <row>
+            <entry morerows="1" valign="middle">Command</entry>
+            <entry namest="col2" nameend="col3" align="center">Error actions
+              allowed</entry>
+          </row>
+          <row>
+            <entry colname="col2">AS Aggregate</entry>
+            <entry>AS Primitive</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>getMetadata</entry>
+            <entry>Retry, Disable, Terminate</entry>
+            <entry>Terminate</entry>
+          </row>
+          <row>
+            <entry>processCas</entry>
+            <entry>Retry, Continue, Disable, Terminate</entry>
+            <entry>Terminate</entry>
+          </row>
+          <row>
+            <entry>collection Processing Complete</entry>
+            <entry>Continue, Disable, Terminate</entry>
+            <entry>Terminate</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+  </section>
+  
+  <!--
+  There are predefined error conditions, and predefined actions that can be taken for
+  these.</para>
+  
+  <para>Aggregate components specify error handling for each of their delegates. Error
+  Handling is configured using the Deployment Descriptor &lt;errorConfiguration>
+  element. This element associates a specification with each delegate of an aggregate.
+  </para>
+  
+  <para>In addition, any AS component can specify a &lt;terminate> element, specifying that
+  the component should disconnect from its input queue and return a "terminate" message,
+  once a specified threshold is reached. The threshold is frequency and/or absolute count
+  based.</para>
+  
+  <figure id="ugr.async.eh.fig.eh_done_1_higher">
+  <title>Error Handling using specs from delegates</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="400px" format="PNG"
+  fileref="&imgroot;eh_done_1_higher.png"/>
+  </imageobject>
+  <textobject><phrase>Error Handling using specs from delegates</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  
+  <para>The deployment descriptor configures error handling; it can be configured at each
+  level of a nested aggregate hierarchy. An &lt;errorConfiguration> element contained in
+  a &lt;delegate> elment specifies error handling configuration for the containing
+  aggregate. A special &lt;terminate> element specifies termination behavior for the
+  component it is contained in.</para>
+  
+  <para>Error handling is always (with the exception of Terminate, described later) done one
+  level up from the component that produced the error (in other words, in the containing
+  aggregate, if there is one, or in the client if there is no containing aggregate). </para>
+  
+  <para>There are two classes of errors: time-out errors and exception errors.</para>
+  
+  <itemizedlist>
+  <listitem>
+  <para>When an AS component receives a CAS to work on, it either returns that CAS (no error
+  case), or it returns the error (typically (in Java) a serialized version of a
+  "throwable" object), instead of a CAS.</para></listitem>
+  <listitem>
+  
+  <para>Timeout errors are generated, not at the delegate, but at the aggregate which
+  sent a request for some kind of processing and timed-out waiting for the
+  response.</para>
+  
+  <para>When timeout errors happen, the delegate may at some later time actually
+  complete the request send the reply message, or it may send an exception error. In both
+  cases, after a time out has occurred, these messages are discarded.</para>
+  </listitem>
+  </itemizedlist>
+  
+  <section id="ugr.async.eh.basic.chains">
+  <title>Error handling chains</title>
+  
+  <figure id="ugr.async.eh.fig.basic_chain">
+  <title>Error Handling chain sequence</title>
+  <mediaobject>
+  <imageobject>
+  <imagedata width="150px" format="PNG"
+  fileref="&imgroot;basic_chain.png"/>
+  </imageobject>
+  <textobject><phrase>Error Handling chain sequence</phrase>
+  </textobject>
+  </mediaobject>
+  </figure>
+  
+  <para> Error handling is done in a chain, as follows. </para>
+  <orderedlist>
+  <listitem><para>If Terminate or Disable action has been specified, the error is
+  counted, and tested to see if the threshold / frequency has been exceeded. If not, the
+  error is passed to the next part of the chain.</para></listitem>
+  <listitem><para>If the error is one where a retry operation is enabled, and the
+  threshold has not been exceeded, a retry is done.</para></listitem>
+  <listitem><para>Otherwise, the specified action is done.</para></listitem>
+  </orderedlist>
+  </section>
+  
+  <section id="ugr.async.eh.basic.thresholds_frequencies">
+  <title>Thresholds and Frequencies</title>
+  <para>The configuration includes specification of thresholds and frequencies. These
+  are used to control when certain actions are taken.</para>
+  <itemizedlist spacing="compact">
+  <listitem>
+  <para><emphasis role="bold">Thresholds</emphasis> imply an implicit retry (if
+  retry is possible) up to the number of times indicated in the threshold. Retry is
+  only possible if the aggregate kept a copy of the original CAS when sending it for
+  processing to the delegate which subsequently produced the error. In the
+  deployment descriptor, this is controlled using the
+  &lt;casManagement enableRevert="true | false"/> element in the
+  &lt;errorConfiguration> element. </para>
+  </listitem>
+  <listitem>
+  <para>Frequencies specify an error "rate" - expressed as two numbers. The first is
+  the number of errors, the second is a number of CASes processed ("NumberOfCases").
+  The frequency is exceeded if there are greater than the number of errors in a
+  consecutive set of "NumberOfCASes" CASes.</para>
+  </listitem>
+  </itemizedlist>
+  </section>
+  
+  <!- section id="ugr.async.eh.basic.action_directions">
+  <title>Action Directions</title>
+  <para>In a general aggregate analysis engine, actions can be directed "upwards"
+  toward the containing aggregate (if there is one) or "downwards" toward one (or more)
+  of the delegate(s).</para>
+  </section-->
+  
+  <!--section id="ugr.async.eh.basic.action_types">
+  <title>Available Actions</title>
+  <para>All error handling routines tell the framework to take one of several possible
+  actions. The set of actions available depends on the context of the error; the context
+  includes the following: </para>
+  <itemizedlist spacing="compact">
+  <listitem>
+  <para>Does this component have delegates being managed by AS?</para>
+  </listitem>
+  <listitem>
+  <para>Is this component co-located with its containing aggregate (if it has a
+  containing aggregate)? </para>
+  </listitem>
+  <listitem><para>Is this component's delegate co-located?</para></listitem>
+  <listitem><para>Was the &lt;casManagement> element configured to enable CAS
+  reversion (returning the CAS to the state it was before it was sent to the delegate
+  which raised the error condition)?</para></listitem>
+  <listitem><para>Did the request which resulted in the error being received have an
+  associated CAS being managed in a flow?</para></listitem>
+  </itemizedlist>
+  
+  <para>Actions available include: Terminate, Disable, Continue, and DropCas.</para>
+  
+  <para>The {Terminate, Disable} actions are considered first. If not applicable, the
+  other actions are considered. </para>
+  
+  <section id="ugr.async.eh.basic.action_types.terminate">
+  <title>Terminate action</title>
+  
+  <para>Only one of {Terminate, Disable} can be specified; Terminate is associated with
+  the component where the &lt;errorConfiguration> element is. It is the only action
+  that is allowed for a top-level component of a service, and for non-AS components
+  (primitives and async="no" aggregates)</para>
+  
+  <para>Enabled: always</para>
+  
+  <para>Threshold/Frequency: if not met, increment the monitoring counters, and
+  Otherwise, do the action.</para>
+  
+  <para>Effect: the service removes itself as a listener on its input queue, "cleans up"
+  any resources it can, and shuts down. For services containing co-located delegates,
+  the cleanup and shut down process is propagated to all local delegates. (In this
+  version, we required local, co-located delegates to be non-shared.)</para>
+  
+  <para>An example: consider an aggregate having several components, one of which is
+  "critical". If the critical component fails, the deployer can decide to terminate
+  the entire aggregate service.</para>
+  </section>
+  
+  <section id="ugr.async.eh.basic.action_types.disable">
+  <title>Disable action</title>
+  
+  <para>Only one of {Terminate, Disable} can be specified; Disable is a specific to one
+  delegate of an aggregate</para>
+  
+  <para>Enabled: always</para>
+  
+  <para>Threshold/Frequency: if not met, increment the monitoring counters, and
+  Otherwise, do the action.</para>
+  
+  <para>Effect: for this (if a CAS exists for this request) and all subsequent CASes in a
+  run, override the flow controller and "skip" any requests to send a CAS to that
+  component.</para>
+  </section>
+  
+  <section id="ugr.async.eh.basic.action_types.continue">
+  <title>Continue action</title>
+  
+  <para>Enabled: only for requests to delegates passing a CAS and when
+  &lt;casManagement enableRevert="true"/> is configured for this delegate</para>
+  
+  <para>Threshold: if not met, and &lt;casManagement enableRevert="true"/>, retry
+  the operation on the component using the reverted CAS, and increment the retry count.
+  Otherwise, do the action.</para>
+  
+  <para>Effect: causes the framework to send the CAS to the flow controller, asking it to
+  continue to the next delegate. The flow controller can decline to do this in this case
+  (it is told that the previous component signalled an error), and if so, the Continue is
+  converted to a DropCas action. <emphasis role="review">This action is not
+  permitted for CAS Multipliers.</emphasis> </para>
+  </section>
+  
+  <section id="ugr.async.eh.basic.action_types.drop_cas">
+  <title>Drop Cas action</title>
+  
+  <para>Enabled: only for requests to delegates passing a CAS</para>
+  
+  <para>Threshold: if not met, and &lt;casManagement enableRevert="true"/>, retry
+  the operation on the component using the reverted CAS, and increment the retry count.
+  Otherwise, do the action.</para>
+  
+  <para>Effect: causes the framework to return the Cas to the Cas Pool, and return a
+  "DropCas" exception to its caller. </para>
+  </section>
+  </section> <!- - action_types - ->
+  
+  </section> <!- - basic -->
+  
+  <!--section id="ugr.async.eh.callbacks">
+  <title>Considerations for call-back routines</title>
+  <para> Error handling supports the following callbacks: </para>
+  
+  <para> Call back routines are configured by: </para>
+  
+  <para> For each call back routine: when it is called, what it is passed, what it can do.
+  </para>
+  
+  </section-->
+  <!--section id="ugr.async.eh.cas_multipliers">
+  <title>Considerations for Cas Multipliers</title>
+  <para>tbd</para>
+  </section-->
+  
+  <!--section id="ugr.async.eh.defaulting">
+  <title>Error Handling defaults and inheritance</title>
+  <para>tbd</para>
+  </section-->
+  
+  <!--section id="ugr.async.eh.error_context">
+  <title>Error Contexts</title>
+  <para>An Error Context is created for each error and passed to error handling methods. It
+  contains the following:
+  <itemizedlist spacing="compact">
+  <listitem><para>The command instigating the action</para></listitem>
+  <listitem><para>The exception (if there is one)</para></listitem>
+  <listitem><para>A flag indicating timeout (if it is a timeout)</para></listitem>
+  <listitem><para>(aggregate-detected errors only) The delegate key</para>
+  </listitem>
+  </itemizedlist> </para>
+  </section-->
+  
+</chapter>