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/11 05:06:53 UTC
svn commit: r485487 - in /incubator/uima/uimaj/trunk/uima-docbooks/src:
docbook/tools/ docbook/tutorials_and_users_guides/
olink/tutorials_and_users_guides/
Author: schor
Date: Sun Dec 10 20:06:52 2006
New Revision: 485487
URL: http://svn.apache.org/viewvc?view=rev&rev=485487
Log:
UIMA-119 update docs for result spec design change
Modified:
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml
incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/htmlsingle-target.db
incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/pdf-target.db
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml?view=diff&rev=485487&r1=485486&r2=485487
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cde.xml Sun Dec 10 20:06:52 2006
@@ -248,7 +248,7 @@
<screenshot>
<mediaobject>
<imageobject>
- <imagedata width="473px" format="JPG" fileref="&imgroot;image012.jpg"/>
+ <imagedata width="370px" format="JPG" fileref="&imgroot;image012.jpg"/>
</imageobject>
<textobject><phrase>Adding an Analysis Engine to an Aggregate</phrase>
</textobject>
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml?view=diff&rev=485487&r1=485486&r2=485487
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml Sun Dec 10 20:06:52 2006
@@ -1902,10 +1902,12 @@
<para>The Result Specification is passed to the annotator instance by calling its
setResultSpecificaiton method. When called, the default implementation saves the
- result specification in an instance variable of the Annotator instance.</para>
+ result specification in an instance variable of the Annotator instance, which can be
+ accessed by the annotator using the protected
+ <literal>getResultSpecification()</literal> method.</para>
<para>A results specification is a list of output types and / or type:feature
- specifications, which are expected to be <quote>output</quote> from the
+ names, which are expected to be <quote>output</quote> from the
annotator. Annotators may use this to optimize their operations, when possible, for
those cases where only particular outputs are wanted. The interface to the Result
Specification object (see the JavaDocs) allows querying both types and particular
@@ -1934,76 +1936,102 @@
<section id="ugr.tug.aae.result_spec.passing_to_annotators">
<title>Passing Result Specifications to Annotators</title>
- <para>If you are not using aggregation or collection processing, but instead are
- instantiating your own primitive analysis engines and calling their process
- methods, you can pass whatever Result Specification is appropriate in your call to
- process(CAS, ResultSpecification). For primitive engines, whatever you pass in is
- passed along as the value of the 2nd argument in the annotator's process()
- method. If you use the form of the call without the Result Specification, the default
- Result Specification is created and passed, as above.</para>
+ <para>If you are not using a Collection Processing Engine, you can specify a Result
+ Specification for your AnalysisEngine(s) by calling the
+ <literal>AnalysisEngine.setResultSpecification(ResultSpecification)</literal>
+ method.</para>
+ <para>It is also possible to pass a Result Specification on each call to
+ <literal>AnalysisEngine.process(CAS, ResultSpecification)</literal>. However,
+ this is not recommended if your Result Specification will stay constant across
+ multiple calls to
+ <literal>process</literal>. In that case it will be more efficient to call
+ <literal>AnalysisEngine.setResultSpecification(ResultSpecification)</literal>
+ only when the Result Specification changes.</para>
+ <para> For primitive Analysis Engines, whatever Result Specification you pass in is
+ passed along to the annotator's
+ <literal>setResultSpecification(ResultSpecification)</literal> method. For
+ aggregate Analysis Engines, see below.</para>
</section>
<section id="ugr.tug.aae.result_spec.aggregates">
<title>Aggregates</title>
+ <para>For aggregate engines, the Result Specification passed to the
+ <code>AnalysisEngine.setResultSpecification(ResultSpecification)</code>
+ method is intended to specify the set of output types/features that the aggregate
+ should produce. This is not necessarily equivalent to the set of output
+ types/features that each annotator should produce. For example, an annotator may
+ need to produce an intermediate type that is then consumed by a downstream annotator,
+ even though that intermediate type is not part of the Result Specification.</para>
+ <para>To handle this situation, when
+ <code>AnalysisEngine.setResultSpecification(ResultSpecification)</code>
+ is called on an aggregate, the framework computes the union of the passed Result
+ Specification with the set of
+ <emphasis>all</emphasis> input types and features of
+ <emphasis>all</emphasis> component AnalysisEngines within that aggregate. This forms the
+ complete set of types and features that any component of the aggregate might need to
+ produce. This derived Result Specification is then passed to the
+ <code>AnalysisEngine.setResultSpecification(ResultSpecification)</code>
+ of each component AnalysisEngine. In the case of nested aggregates, this procedure
+ is applied recursively.</para>
+ <!-- to be deleted because design changed
<para>For aggregate engines, the value passed to the primitive annotator code depends
on the kind of flow.</para>
-
-
- <section id="ugr.tug.aae.result_spec.aggregates.fixed_flow">
- <title>Fixed Flow</title>
-
- <para>For FixedFlow, any ResultSpecification passed into the aggregate is ignored,
- and instead, each primitive annotator is passed a result spec that corresponds to the
- union of its output capability specifications at the primitive descriptor level. If
- no output capability specification is given, the annotator will still be called, but
- the result specification will be empty.</para>
-
- </section>
-
- <section id="ugr.tug.aae.result_spec.aggregates.capability_language_flow">
- <title>CapabilityLanguageFlow</title>
- <para>For CapabilityLanguageFlow, each annotator is passed a ResultSpecification
- that is the intersection of the primitive annotator's output Capability
- Specification with the ResultSpecification passed to the aggregate. If this
- intersection is null (the annotator does not produce any type or feature included in
- the ResultSpecification), the annotator will not be called at all.</para>
-
- <para>Therefore, if using the CapabilityLanguageFlow, if you want to supply a custom
- ResultSpecification for the aggregate it must include any intermediate types that
- need to be produced internally in the flow, or else things will not work
- properly.</para>
- </section>
-
-
- <section id="ugr.tug.aae.skipping_ae_in_capability_language_flow">
- <title>Special rule for skipping Analysis Engines</title>
-
- <para>When using the CapabilityLanguageFlow, an annotator will be also be skipped if
- all of its outputs are in the output capability of some annotator(s) that has (have)
- executed previously in the flow. The concept here is that if all of an
- annotator's output types have already been produced, that annotator will not
- be called.</para>
-
- <para>For an Aggregate, each annotator is passed a Result Specification that is the
- intersection of the set of types mentioned in its output with the Result
- Specification passed to the aggregate. If this intersection is null (the annotator
- does not produce any type included in the ResultSpecification), the annotator will
- not be called at all.</para>
-
- <para>Therefore, if using the CapabilityLanguageFlow, if you want to supply a custom
- ResultSpecification for the aggregate it must include any intermediate types that
- need to be produced, or else things will not work properly.</para>
- </section>
-
- <section id="ugr.tug.aae.result_spec.aggregates.cpes">
- <title>Collection Proessing Engines</title>
-
- <para>The Default Result Specification is always used for all components of a
- Collection Processing Engine.</para>
+ <section id="ugr.tug.aae.result_spec.aggregates.fixed_flow">
+ <title>Fixed Flow</title>
+
+ <para>For FixedFlow, any ResultSpecification passed into the aggregate is
+ ignored, and instead, each primitive annotator is passed a result spec that
+ corresponds to the union of its output capability specifications at the primitive
+ descriptor level. If no output capability specification is given, the annotator
+ will still be called, but the result specification will be empty.</para>
+
+ </section>
+
+ <section id="ugr.tug.aae.result_spec.aggregates.capability_language_flow">
+ <title>CapabilityLanguageFlow</title>
+ <para>For CapabilityLanguageFlow, each annotator is passed a
+ ResultSpecification that is the intersection of the primitive annotator's
+ output Capability Specification with the ResultSpecification passed to the
+ aggregate. If this intersection is null (the annotator does not produce any type or
+ feature included in the ResultSpecification), the annotator will not be called at
+ all.</para>
+
+ <para>Therefore, if using the CapabilityLanguageFlow, if you want to supply a
+ custom ResultSpecification for the aggregate it must include any intermediate
+ types that need to be produced internally in the flow, or else things will not work
+ properly.</para>
+ </section>
+
+ <section id="ugr.tug.aae.skipping_ae_in_capability_language_flow">
+ <title>Special rule for skipping Analysis Engines</title>
+
+ <para>When using the CapabilityLanguageFlow, an annotator will be also be skipped
+ if all of its outputs are in the output capability of some annotator(s) that has
+ (have) executed previously in the flow. The concept here is that if all of an
+ annotator's output types have already been produced, that annotator will
+ not be called.</para>
+
+ <para>For an Aggregate, each annotator is passed a Result Specification that is the
+ intersection of the set of types mentioned in its output with the Result
+ Specification passed to the aggregate. If this intersection is null (the
+ annotator does not produce any type included in the ResultSpecification), the
+ annotator will not be called at all.</para>
+
+ <para>Therefore, if using the CapabilityLanguageFlow, if you want to supply a
+ custom ResultSpecification for the aggregate it must include any intermediate
+ types that need to be produced, or else things will not work properly.</para>
+ </section>
+ -->
+ <section id="ugr.tug.aae.result_spec.aggregates.cpes">
+ <title>Collection Proessing Engines</title>
+
+ <para>The Default Result Specification is always used for all components of a
+ Collection Processing Engine.</para>
+
+ </section>
</section>
- </section>
<section id="ugr.tug.aae.classpath_when_using_jcas">
<title>Class path setup when using JCas</title>
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/htmlsingle-target.db
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/htmlsingle-target.db?view=diff&rev=485487&r1=485486&r2=485487
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/htmlsingle-target.db (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/htmlsingle-target.db Sun Dec 10 20:06:52 2006
@@ -165,21 +165,9 @@
<div element="section" href="#ugr.tug.aae.result_spec.aggregates" number="1.4.8" targetptr="ugr.tug.aae.result_spec.aggregates">
<ttl>Aggregates</ttl>
<xreftext>Section 1.4.8, âAggregatesâ</xreftext>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.fixed_flow" number="1.4.8.1" targetptr="ugr.tug.aae.result_spec.aggregates.fixed_flow">
- <ttl>Fixed Flow</ttl>
- <xreftext>Section 1.4.8.1, âFixed Flowâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.capability_language_flow" number="1.4.8.2" targetptr="ugr.tug.aae.result_spec.aggregates.capability_language_flow">
- <ttl>CapabilityLanguageFlow</ttl>
- <xreftext>Section 1.4.8.2, âCapabilityLanguageFlowâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.skipping_ae_in_capability_language_flow" number="1.4.8.3" targetptr="ugr.tug.aae.skipping_ae_in_capability_language_flow">
- <ttl>Special rule for skipping Analysis Engines</ttl>
- <xreftext>Section 1.4.8.3, âSpecial rule for skipping Analysis Enginesâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.cpes" number="1.4.8.4" targetptr="ugr.tug.aae.result_spec.aggregates.cpes">
+ <div element="section" href="#ugr.tug.aae.result_spec.aggregates.cpes" number="1.4.8.1" targetptr="ugr.tug.aae.result_spec.aggregates.cpes">
<ttl>Collection Proessing Engines</ttl>
- <xreftext>Section 1.4.8.4, âCollection Proessing Enginesâ</xreftext>
+ <xreftext>Section 1.4.8.1, âCollection Proessing Enginesâ</xreftext>
</div>
</div>
<div element="section" href="#ugr.tug.aae.classpath_when_using_jcas" number="1.4.9" targetptr="ugr.tug.aae.classpath_when_using_jcas">
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/pdf-target.db
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/pdf-target.db?view=diff&rev=485487&r1=485486&r2=485487
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/pdf-target.db (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/olink/tutorials_and_users_guides/pdf-target.db Sun Dec 10 20:06:52 2006
@@ -165,21 +165,9 @@
<div element="section" href="#ugr.tug.aae.result_spec.aggregates" number="1.4.8" targetptr="ugr.tug.aae.result_spec.aggregates">
<ttl>Aggregates</ttl>
<xreftext>Section 1.4.8, âAggregatesâ</xreftext>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.fixed_flow" number="1.4.8.1" targetptr="ugr.tug.aae.result_spec.aggregates.fixed_flow">
- <ttl>Fixed Flow</ttl>
- <xreftext>Section 1.4.8.1, âFixed Flowâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.capability_language_flow" number="1.4.8.2" targetptr="ugr.tug.aae.result_spec.aggregates.capability_language_flow">
- <ttl>CapabilityLanguageFlow</ttl>
- <xreftext>Section 1.4.8.2, âCapabilityLanguageFlowâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.skipping_ae_in_capability_language_flow" number="1.4.8.3" targetptr="ugr.tug.aae.skipping_ae_in_capability_language_flow">
- <ttl>Special rule for skipping Analysis Engines</ttl>
- <xreftext>Section 1.4.8.3, âSpecial rule for skipping Analysis Enginesâ</xreftext>
- </div>
- <div element="section" href="#ugr.tug.aae.result_spec.aggregates.cpes" number="1.4.8.4" targetptr="ugr.tug.aae.result_spec.aggregates.cpes">
+ <div element="section" href="#ugr.tug.aae.result_spec.aggregates.cpes" number="1.4.8.1" targetptr="ugr.tug.aae.result_spec.aggregates.cpes">
<ttl>Collection Proessing Engines</ttl>
- <xreftext>Section 1.4.8.4, âCollection Proessing Enginesâ</xreftext>
+ <xreftext>Section 1.4.8.1, âCollection Proessing Enginesâ</xreftext>
</div>
</div>
<div element="section" href="#ugr.tug.aae.classpath_when_using_jcas" number="1.4.9" targetptr="ugr.tug.aae.classpath_when_using_jcas">