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 2016/10/17 19:47:35 UTC
svn commit: r1765359 - in
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src:
docbook/ docbook/images/uima_v3_users_guide/select/ image-source/
Author: schor
Date: Mon Oct 17 19:47:35 2016
New Revision: 1765359
URL: http://svn.apache.org/viewvc?rev=1765359&view=rev
Log:
[UIMA-5115] update to docs for select after Richard's feedback, incorporating most of the suggestions, and clarifying docs.
Added:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_terminal_form_actions.png (with props)
Modified:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_big_pic.png
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_selection_and_ordering.png
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_source_type.png
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uima_v3_users_guide.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/image-source/source.pptx
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_big_pic.png
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_big_pic.png?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
Binary files - no diff available.
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_selection_and_ordering.png
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_selection_and_ordering.png?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
Binary files - no diff available.
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_source_type.png
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_source_type.png?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
Binary files - no diff available.
Added: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_terminal_form_actions.png
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_terminal_form_actions.png?rev=1765359&view=auto
==============================================================================
Binary file - no diff available.
Propchange: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/images/uima_v3_users_guide/select/select_terminal_form_actions.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uima_v3_users_guide.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uima_v3_users_guide.xml?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uima_v3_users_guide.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uima_v3_users_guide.xml Mon Oct 17 19:47:35 2016
@@ -26,9 +26,9 @@ under the License.
<toc/>
<!-- xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.overview.xml"/-->
- <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.select.xml"/> -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.select.xml"/>
<!-- xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.migrating_jcas.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.backwards_compatibility.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.performance.xml"/-->
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.resources.xml"/>
+ <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ref.resources.xml"/> -->
</book>
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml Mon Oct 17 19:47:35 2016
@@ -93,40 +93,63 @@ under the License.
<section id="uv3.select.sources">
<title>Sources of Feature Structures</title>
- <para>Feature Structures are kept in the CAS, and are accessed using UIMA Indexes.
+ <para>Feature Structures are kept in the CAS, and may be accessed using UIMA Indexes.
+ Note that not all Feature Structures in the CAS are in the UIMA indexes; only those that the
+ user had "added to the indexes" are. Feature Structures not in the indexes are not
+ included when using the CAS as the source for the select framework.</para>
+
+ <para>
Feature Structures may, additionally, be kept in <code>FSArrays</code> and <code>FSLists</code>.
All three of these sources may be used with <code>select</code>.</para>
- <para>For CAS sources, there are separate sets of indexes per CAS view; a typical CAS source is
- the Feature Structures belonging to a particular index, in a particular
- CAS view, perhaps filtered by UIMA Type.</para>
+ <para>For CAS sources, if Views are being used, there is a separate set of indexes per CAS view.
+ When there are multiple views, only one view's set of indexed Feature Structures is accessed - the
+ view implied by the CAS being used. Note that there is a way to specify aggregating over all views; see
+ <code>allViews</code> described later.</para>
- <para>You can omit the index; in that case, the default is
+ <para>Users may specify all Feature Structures in a view, or restrict this in two ways:
<itemizedlist spacing="compact">
<listitem>
- <para>all Feature Structures in a Cas View, or</para>
+ <para>specifying an index: Users may define their own indexes, in additional to the built in ones, and
+ then specify which index to use.
+ </para>
</listitem>
<listitem>
- <para>(if the selection and ordering specifications require an AnnotationIndex),
- all Feature Structures in the view's AnnotationIndex.</para>
+ <para>specifying a type: Only Feature Structures of this type (or its subtypes) are included.
+ </para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>You can extend any selection to be an aggregation over all the CAS views.</para>
+ <para>It is possible to specify both of these, using the form <code>myIndex.select(myType)</code>;
+ in that case the type must be the type or a subtype of
+ the index's top most type.
+ </para>
+
+ <para>If no index is specified, the default is
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>to use all Feature Structures in a CAS View, or</para>
+ </listitem>
+ <listitem>
+ <para>to use all Feature Structures in the view's AnnotationIndex,
+ if the selection and ordering specifications require an AnnotationIndex.</para>
+ </listitem>
+ </itemizedlist></para>
- <para>A UIMA index is the usual source. If a CAS is used, all Feature Structures that were added to the index in the
- specified CAS view are used as the source. The FSArray and FSList sources have more limited configurability,
- because they are considered non-sorted, and therefore cannot be used for an operations which require a sorted order.</para>
+ <para>Note that the FSArray and FSList sources are considered ordered, but non-sorted,
+ and therefore cannot be used for an operations which require a sorted order.</para>
<para>There are 4 sources of Feature Structures supported:</para>
<itemizedlist spacing="compact">
<listitem>
- <para>a CAS view: all the FSs that were added to the indexes for this view (in arbitrary order)
+ <para>a CAS view: all the FSs that were added to the indexes for this view.
</para>
</listitem>
<listitem>
- <para>an Index over a CAS view
+ <para>an Index over a CAS view. Note that the AnnotationIndex is often implied by other
+ <code>select</code> specifications, so it is often not necessary to supply this.
</para>
</listitem>
<listitem>
@@ -140,7 +163,10 @@ under the License.
</itemizedlist>
<para>Each of these sources has a new API method, <code>select(...)</code>, which initiates the select specification.
- The select method can take an optional positional parameter, specifying the UIMA type to return.</para>
+ The select method can take an optional parameter, specifying the UIMA type to return.
+ If supplied, the type must must be the type or subtype of the index
+ (if one is specified or implied); it serves to further restrict the types selected beyond whatever the
+ index (if specified) has as its top-most type.</para>
<figure id="uv3.select.source_type">
<title>select method with type</title>
@@ -153,14 +179,18 @@ under the License.
</mediaobject>
</figure>
- <para>A UIMA index is the usual source. If a CAS is used, all Feature Structures that were added to the index in the
+ <para>A UIMA index is the usual source.
+ If a CAS is used, all Feature Structures that were added to the index in the
specified CAS view are used as the source. The FSArray and FSList sources have more limited configurability,
- because they are considered non-sorted, and therefore cannot be used for an operations which require a sorted order.</para>
+ because they are considered non-sorted,
+ and therefore cannot be used for an operations which require a sorted order, such as
+ the various bounding selections (e.g. <code>coveredBy</code>)
+ or positioning operations (e.g. <code>startAt</code>).</para>
<para>
The optional type argument for <code>select(...)</code> specifies a UIMA type. This restricts the Feature Structures
to just those of the specified type or any of its subtypes. If omitted, if an index is used as a source,
- its type specification is used; otherwise the TOP type is used (meaning all types).</para>
+ its type specification is used; otherwise all types are included.</para>
<para>Type specifications may be specified in multiple ways.
The best practice, if you have a JCas cover class
@@ -182,10 +212,10 @@ under the License.
generically typed index variables.
</para>
- <para>A static version of the <code>select</code> method (named <code>sselect</code>) gets around this
- by providing the generically typed information as an argument, rather than having it come from the receiver.</para>
- <programlisting>
-// this works
+ <para>There is also a static version of the <code>select</code> method which takes a
+ generically typed index as an argument.</para>
+ <informalexample> <?dbfo keep-together="always"?>
+ <programlisting>// this works
// the generic type for Token is passed as an argument to select
FSIterator<Token> token_it = cas.select(Token.class).fsIterator();
@@ -197,18 +227,33 @@ FSIndex<Token> token_index = ... ;
FSIterator<Token> token_iterator = token_index.select().fsIterator();
// You can overcome this in two ways:
-// explicitly set the generic type select() should use, like this:
-FSIterator<Token> token_iterator =
- token_index.<Token>select().fsIterator();
+// pass in the type as an argument to select
+// using the JCas cover type.
+FSIterator<Token> token_iterator =
+ token_index.select(Token.class).fsIterator();
// You can also use the static form of select
-FSIterator<Token> token_iterator = sselect(token_index).fsIterator();
-// Java makes use of the generic information from the index,
-// coming in as an argument
- </programlisting>
+// to avoid repeating the type information
+FSIterator<Token> token_iterator =
+ SelectFSs.select(token_index).fsIterator();
+
+// Finally, you can also explicitly set the generic type
+// that select() should use, like a special kind of type cast, like this:
+FSIterator<Token> token_iterator =
+ token_index.<Token>select().fsIterator();
+</programlisting>
+</informalexample>
- <para>The <code>sselect</code> method may be statically imported into code that uses it, to avoid repeatedly
+ <para>Note: the static <code>select</code> method may be statically imported into code that uses it, to avoid repeatedly
qualifying this with its class, <code>SelectFSs</code>.</para>
+
+ <para>Any specification of an index may be further restricted to just a subType (including that
+ subtype's subtypes, if any) of that index's type.
+ For example, an AnnotationIndex may be specialized to just Sentences (and their subtypes):
+ <programlisting>FSIterator<Token> token_iterator =
+ annotation_index.select(Token.class).fsIterator();
+</programlisting>
+ </para>
</section>
</section> <!-- end of section "sources" -->
@@ -285,7 +330,7 @@ FSIterator<Token> token_iterator =
<varlistentry>
<term><emphasis role="strong">nullOk</emphasis></term>
<listitem>
- <para>changes the behavior for some processing actions, which would otherwise
+ <para>changes the behavior for some terminal_form actions, which would otherwise
throw an exception if a null result happened.
</para>
</listitem>
@@ -307,9 +352,11 @@ FSIterator<Token> token_iterator =
</para>
<para>When this is specified, it acts
- as an aggregation, in no particular order, of the underlying selections, one per view in the CAS.
- Because of this implementation, the items in the selection may not be unique - that is a single
- Feature Structure may be in multiple views.
+ as an aggregation of the underlying selections, one per view in the CAS.
+ The ordering among the views is arbitrary; the ordering within each view
+ is the same as if this setting wasn't in force.
+ Because of this implementation, the items in the selection may not be unique --
+ Feature Structures in the underlying selections that are in multiple views will appear multiple times.
</para>
</listitem>
</varlistentry>
@@ -318,9 +365,9 @@ FSIterator<Token> token_iterator =
</section>
<section id="uv3.select.ordered_index">
- <title>Configuration for ordered indexes</title>
+ <title>Configuration for sort-ordered indexes</title>
- <para>When an index is ordered, there are additional capabilities that can be configured, in particular positioning
+ <para>When an index is sort-ordered, there are additional capabilities that can be configured, in particular positioning
to particular Feature Structures, and running various iterations backwards.
</para>
@@ -341,8 +388,7 @@ FSIterator<Token> token_iterator =
<para>position the starting point of any iteration.
<code>startAt(xxx)</code> takes two forms, each of which has, in turn 2 subforms.
The form using <code>begin, end</code> is only valid for Annotation Indexes.
- <programlisting>
-startAt(fs); // fs specifies a feature structure
+ <programlisting>startAt(fs); // fs specifies a feature structure
// indicating the starting position
startAt(fs, shifted); // same as above, but after positioning,
@@ -375,28 +421,25 @@ startAt(begin, end, shifted) // same as
<section id="uv3.select.annot.subselect">
<title>Bounded sub-selection within an Annotation Index</title>
- <para>When selecting Feature Structures to process, frequently you may want to select only those which have
- a relation to a bounding Feature Structure. A commonly done selection is to select all Feature Structures
- (of a particular type) within the span of another, bounding Feature Structure, such as all <code>Tokens</code>
+ <para>When selecting Annotations, frequently you may want to select only those which have
+ a relation to a bounding Annotation. A commonly done selection is to select all Annotations
+ (of a particular type) within the span of another, bounding Annotation, such as all <code>Tokens</code>
within a <code>Sentence</code>.</para>
<para>There are four varieties of sub-selection within an annotation index. They all are based on a
- bounding Feature Structure (except the <code>between</code> which is based on two bounding Feature Structures).
+ bounding Annotation (except the <code>between</code> which is based on two bounding Annotations).
</para>
- <para>The bounding Feature Structures are specified using either a Annotation Feature Structure (or a subtype), or
- by specifying the begin and end offsets that would be for the bounding Feature Structure.</para>
+ <para>The bounding Annotations are specified using either a Annotation (or a subtype), or
+ by specifying the begin and end offsets that would be for the bounding Annotation.</para>
- <para>Leaving aside <code>between</code> as a special case, the bounding Feature Structure's
+ <para>Leaving aside <code>between</code> as a special case, the bounding Annotation's
<code>begin</code> and <code>end</code>
(and sometimes, its <code>type</code>) is used to specify where an iteration would start, where it would end,
- and possibly, which Feature Structures within those bounds would be filtered out. There are many variations
+ and possibly, which Annotations within those bounds would be filtered out. There are many variations
possible; these are described in the next section.</para>
- <para>The bounding information is specified either as an Annotation Feature Structure (or a subtype of Annotation),
- or the begin and end can be directly specified.</para>
-
- <para>The returned Feature Structures exclude the one(s) which are <code>equal</code> to the bounding FS.
+ <para>The returned Annotations exclude the one(s) which are <code>equal</code> to the bounding FS.
There are several
variations of how this <code>equal</code> test is done, discussed in the next section.</para>
@@ -404,31 +447,31 @@ startAt(begin, end, shifted) // same as
<varlistentry>
<term><emphasis role="strong">coveredBy</emphasis></term>
<listitem>
- <para>iterates over Feature Structures within the bound
+ <para>iterates over Annotations within the bound
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="strong">covering</emphasis></term>
<listitem>
- <para>iterates over Feature Structures that span (or are equal to) the bound.
+ <para>iterates over Annotations that span (or are equal to) the bound.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="strong">at</emphasis></term>
<listitem>
- <para>iterates over Feature Structures that have the same span (i.e., begin and end) as the bound.
+ <para>iterates over Annotations that have the same span (i.e., begin and end) as the bound.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="strong">between</emphasis></term>
<listitem>
- <para>uses two feature structures, and returns Feature Structures that are in between
+ <para>uses two Annotations, and returns Annotations that are in between
the two bounds. If the bounds are backwards, then they are automatically used in reverse order.
- The meaning of between is that an included Feature Structure's begin has to be >= the earlier bound's <code>end</code>,
- and the Feature Structure's end has to be <= the later bound's <code>begin</code>.
+ The meaning of between is that an included Annotation's begin has to be >= the earlier bound's <code>end</code>,
+ and the Annotation's end has to be <= the later bound's <code>begin</code>.
</para>
</listitem>
</varlistentry>
@@ -457,7 +500,7 @@ startAt(begin, end, shifted) // same as
<term><emphasis role="strong">positionUsesType</emphasis></term>
<listitem>
<para>When type priorities are not being used, Annotations with the same begin and end and type
- will be together in the index. The starting position, when there are many Feature Structures
+ will be together in the index. The starting position, when there are many Annotations
which might compare equal, is the left-most (earliest) one of these. In this comparison for
equality, by default, the <code>type</code> of the bounding Annotation is ignored;
only its begin and end values are used.
@@ -468,9 +511,9 @@ startAt(begin, end, shifted) // same as
<varlistentry>
<term><emphasis role="strong">nonOverlapping</emphasis></term>
<listitem>
- <para>This is also called <emphasis>unambiguous</emphasis> iteration. If specified, then after
- the iterator reaches a position, the <code>moveToNext()</code> operation moves to the next Annotation
- which has a <code>begin</code> offset >= to the previous Annotation's <code>end</code> position.
+ <para>Normally, all Annotations satisfying the bounds are returned. If this is set,
+ annotations whose <code>begin</code> position is not >= the previous annotation's (going forwards)
+ <code>end</code> position are skipped. This is also called <emphasis>unambiguous</emphasis> iteration.
If the iterator is run backwards, it is first run forwards to locate all the items that would be in the
forward iteration following the rules; and then those are traversed backwards.
This variant is ignored for <code>covering</code> selection.
@@ -478,24 +521,28 @@ startAt(begin, end, shifted) // same as
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="strong">endWithinBounds</emphasis></term>
+ <term><emphasis role="strong">includeAnnotationsWithEndBeyondBounds</emphasis></term>
<listitem>
- <para>This is also called <emphasis>strict</emphasis>. For <code>coveredBy</code> selection,
+ <para>The Subiterator <emphasis>strict</emphasis> configuration is equivalent to the opposite of this.
+ This only applied to the <code>coveredBy</code> selection;
if specified, then any Annotations whose
- <code>end</code> position is > the end position of the bounding Annotation is skipped.
- The <code>between</code> selection always behaves as if this is set.
- This variant is ignored for <code>covering</code> selection.
+ <code>end</code> position is > the end position of the bounding Annotation are included;
+ normally they are skipped.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="strong">skipEquals</emphasis></term>
+ <term><emphasis role="strong">useAnnotationEquals</emphasis></term>
<listitem>
<para>While doing bounded iteration, if the Annotation being returned is identical (has the same
- _id()) with the bounding Annotation, it is skipped. If this variant is specified, in addition to
+ _id()) with the bounding Annotation, it is always skipped.</para>
+
+ <para>
+ When this variant is specified, in addition to
that, any Annotation which has the same begin, end, and (maybe) type is also skipped.
The <code>positionUsesType</code> setting is used to specify in this variant whether or not the
- type is included when doing the equals test.
+ type is included when doing the equals test. Note that <code>typePriority</code> implies
+ <code>positionUsesType</code>.
</para>
</listitem>
</varlistentry>
@@ -524,7 +571,7 @@ startAt(begin, end, shifted) // same as
<varlistentry>
<term><emphasis role="strong">positionUsesType</emphasis></term>
<listitem>
- <para>default: the type of the bounding Feature Structure is ignored
+ <para>default: the type of the bounding Annotation is ignored
when determining bounds in bounded selects; only its begin and end position are used
</para>
</listitem>
@@ -532,26 +579,26 @@ startAt(begin, end, shifted) // same as
<varlistentry>
<term><emphasis role="strong">nonOverlapping</emphasis></term>
<listitem>
- <para>default: this mode is ignored. It corresponds to the "unambiguous" mode in Subiterators, so the
- default is "ambiguous".
+ <para>default: false; no Annotations are skipped because they overlap.
+ This corresponds to the "ambiguous" mode in Subiterators.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="strong">endWithinBounds</emphasis></term>
+ <term><emphasis role="strong">includeAnnotationsWithEndBeyondBounds</emphasis></term>
<listitem>
- <para>default: this mode is ignored. In any case, it only is used for <code>coveredBy</code> selections;
- the other subselect operations ignore it. This corresponds to Subiterator's "strict" option, so the
- default is "not strict".
+ <para>default: (only applies to <code>coveredBy</code> selections;
+ The default is to skip Annotations whose end position lies outside of the bounds;
+ this corresponds to Subiterator's "strict" option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="strong">skipEquals</emphasis></term>
+ <term><emphasis role="strong">useAnnotationEquals</emphasis></term>
<listitem>
- <para>default: only the single Feature Structure with the same _id() is skipped when doing sub selecting.
- Subiterators, in contrast, skip all Feature Structures which compare equal using the AnnotationIndex
- comparator.
+ <para>default: only the single Annotation with the same _id() is skipped when doing sub selecting.
+ Use this setting to expand the set of skipped Annotations to include all those equal to the
+ bound's begin and end (and maybe, type, if positionUsesType or typePriority specified).
</para>
</listitem>
</varlistentry>
@@ -562,20 +609,18 @@ startAt(begin, end, shifted) // same as
<section id="uv3.select.annot.follow_precede">
<title>Following or Preceding</title>
- <para>For an Annotation Index, you can specify all Annotations following or preceding a position.
- The position can be specified either as a Annotation, or by using begin and end values.
+ <para>For an sorted Index, you can specify all Feature Structures following or preceding a position.
+ The position can be specified either as a Feature Structure, or (for AnnotationIndexes only)
+ by using begin and end values.
The arguments are identical to those of the <code>startAt</code> specification, but are interpreted
differently.
</para>
-
- <para>The underlying iteration can be any of the kinds supported by the Annotation Index,
- except that <code>endWithinBounds</code> is forced on.</para>
-
+
<variablelist>
<varlistentry>
<term><emphasis role="strong">following</emphasis></term>
<listitem>
- <para>Position the iterator according to the argument, get that Feature Structure's <code>end</code>
+ <para>Position the iterator according to the argument, get that Annotation's <code>end</code>
value, and then move the iterator forwards until
the Annotation at that position has its begin value >= to the saved end value.
</para>
@@ -595,33 +640,42 @@ startAt(begin, end, shifted) // same as
</section>
</section>
- <section id="uv3.select.processing_actions">
- <title>Processing actions</title>
+ <section id="uv3.select.terminal_form_actions">
+ <title>Terminal Form actions</title>
<para>After the sources and selection and ordering options have been specified, one
- processing action may be specified. This can be an iterator, something that converts to an array or list,
- something that retrieves a single value with various extra checks, or a stream operation. A stream operation
- converts the object to a stream; from that point on, any stream operation may be used.</para>
+ terminal form action may be specified. This can be an getting an iterator, array or list,
+ or a single value with various extra checks, or a Java stream. Specifying any stream operation
+ (except limit) converts the object to a stream; from that point on, any stream operation may be used.</para>
- <figure id="uv3.select.fig.processing_actions">
- <title>Select Processing Actions</title>
+ <figure id="uv3.select.fig.terminal_form_actions">
+ <title>Select Terminal Form Actions</title>
<mediaobject>
<imageobject>
- <imagedata width="5.5in" format="PNG" fileref="&imgroot;select_processing_actions.png"/>
+ <imagedata width="5.5in" format="PNG" fileref="&imgroot;select_terminal_form_actions.png"/>
</imageobject>
- <textobject><phrase>Processing actions for select</phrase>
+ <textobject><phrase>Terminal form actions for select</phrase>
</textobject>
</mediaobject>
</figure>
- <section id="uv3.select.processing_actions.iterators">
+ <section id="uv3.select.terminal_form_actions.iterators">
<title>Iterators</title>
<variablelist>
<varlistentry>
+ <term><emphasis role="strong">(Iterable)</emphasis></term>
+ <listitem>
+ <para>The <code>SelectFSs</code> object directly implements <code>Iterable</code>, so it may be
+ used in the extended Java <code>for</code> loop.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><emphasis role="strong">fsIterator</emphasis></term>
<listitem>
- <para>returns a configured fsIterator or subIterator. This iterator implements <code>ListIterator</code> as well.
+ <para>returns a configured fsIterator or subIterator.
+ This iterator implements <code>ListIterator</code> as well (which, in turn,
+ implements Java <code>Iterator</code>).
Modifications to the list using <code>add</code> or <code>set</code> are not supported.
</para>
</listitem>
@@ -645,7 +699,7 @@ startAt(begin, end, shifted) // same as
</variablelist>
</section>
- <section id="uv3.select.processing_actions.arrays_lists">
+ <section id="uv3.select.terminal_form_actions.arrays_lists">
<title>Arrays and Lists</title>
<variablelist>
<varlistentry>
@@ -665,7 +719,7 @@ startAt(begin, end, shifted) // same as
</varlistentry>
</variablelist>
</section>
- <section id="uv3.select.processing_actions.single_items">
+ <section id="uv3.select.terminal_form_actions.single_items">
<title>Single Items</title>
<para>These methods return just a single item, according to the previously specified select configuration.
Variations may throw exceptions on empty or more than one item situations.</para>
@@ -675,7 +729,8 @@ startAt(begin, end, shifted) // same as
according to the arguments.</para>
<note>
- <para>Positioning arguments with a Feature Structure or begin and end require an Annotation Index.
+ <para>Positioning arguments with a Annotation or begin and end require an Annotation Index.
+ Positioning using a Feature Structure, by contrast, only require that the index being use be sorted.
</para>
</note>
@@ -710,7 +765,7 @@ startAt(begin, end, shifted) // same as
</varlistentry>
</variablelist>
</section>
- <section id="uv3.select.processing_actions.streams">
+ <section id="uv3.select.terminal_form_actions.streams">
<title>Streams</title>
<variablelist>
<varlistentry>
@@ -719,6 +774,31 @@ startAt(begin, end, shifted) // same as
<para>Select supports all the stream methods. The first occurance of a stream method converts the select
into a stream, using <code>spliterator</code>, and from then on, it behaves just like a stream object.
</para>
+
+ <para>For example, here's a somewhat contrived example:
+ you could do the following to collect the set of types appearing
+ within some bounding annotation, when considered in nonOverlapping style:
+
+ <informalexample> <?dbfo keep-together="always"?>
+<programlisting>Set<Type> foundTypes =
+ // items of MyType or subtypes
+ myIndex.select(MyType.class)
+ .coveredBy(myBoundingAnnotation)
+ .nonOverlapping()
+ .map(fs -> fs.getType())
+ .collect(Collectors.toCollection(TreeSet::new));
+</programlisting>
+</informalexample>
+Or, to collect by category a set of frequency values:
+<informalexample> <?dbfo keep-together="always"?>
+<programlisting>Map<Category, Integer> freqByCategory =
+ myIndex.select(MyType.class)
+ .collect(Collectors
+ .groupingBy(MyType::getCategory,
+ Collectors.summingInt(MyType::getFreq)));
+</programlisting>
+</informalexample>
+ </para>
</listitem>
</varlistentry>
</variablelist>
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/image-source/source.pptx
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/image-source/source.pptx?rev=1765359&r1=1765358&r2=1765359&view=diff
==============================================================================
Binary files - no diff available.