| <!-- |
| 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.tools.uimafit.casutil"> |
| <title>CAS Utilities</title> |
| <para>uimaFIT facilitates working with the CAS and JCas by offering various convenient methods for |
| accessing and navigating annotations and feature structures. Additionally, the the convenience |
| methods for JCas access are fully type-safe and return the JCas type or a collection of the JCas |
| type which you wanted to access.</para> |
| <section> |
| <title>Access methods</title> |
| <para>uimaFIT supports the following convenience methods for accessing CAS and JCas structures. |
| All methods respect the UIMA index definitions and return annotations or feature structures in |
| the order defined by the indexes. Unless the default UIMA index for annotations has been |
| overwritten, annotations are returned sorted by begin (increasing) and end |
| (decreasing).</para> |
| <itemizedlist> |
| <listitem> |
| <para><code>select(cas, type)</code> - fetch all annotations of the given type from the |
| CAS/JCas. Variants of this method also exist to fetch annotations from a |
| <type>FSList</type> or <type>FSArray</type>.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectAll(cas)</code> - fetch all annotations from the CAS or fetch all feature |
| structures from the JCas.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectBetween(type, annotation1, annotation2)</code>* - fetch all annotations |
| between the given two annotations.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectCovered(type, annotation)</code>* - fetch all annotations covered by the |
| given annotation. If this operation is used intensively, <code>indexCovered(...)</code> |
| should be used to pre-calculate annotation covering information.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectCovering(type, annotation)*</code> - fetch all annotations covering the |
| given annotation. If this operation is used intensively, <code>indexCovering(...)</code> |
| should be used to pre-calculate annotation covering information.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectByIndex(cas, type, n)</code> - fetch the n-th feature structure of the |
| given type.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectSingle(cas, type)</code> - fetch the single feature structure of the given |
| type. An exception is thrown if there is not exactly one feature structure of the type. |
| </para> |
| </listitem> |
| <listitem> |
| <para><code>selectSingleRelative(type, annotation, n)</code>* - fetch a single annotation |
| relative to the given annotation. A positive <parameter>n</parameter> fetches the n-th |
| annotation right of the specified annotation, while the a negative |
| <parameter>n</parameter> fetches to the left.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectPreceding(type, annotation, n)</code>* - fetch the n annotations preceding |
| the given annotation. If there are less then n preceding annotations, all preceding |
| annotations are returned.</para> |
| </listitem> |
| <listitem> |
| <para><code>selectFollowing(type, annotation, n)</code>* - fetch the n annotations following |
| the given annotation. If there are less then n following annotations, all following |
| annotations are returned.</para> |
| </listitem> |
| </itemizedlist> |
| <note> |
| <para>For historical reasons, the method marked with * also exist in a version that accepts a |
| CAS/JCas as the first argument. These may not work as expected when the annoation arguments |
| provided to the method are from a different CAS/JCas/view. Also, for any method accepting |
| two annotations, these should come from the same CAS/JCas/view. In future, the potentially |
| problematic signatures may be deprecated, removed, or throw exeptions if these conditions |
| are not met.</para> |
| </note> |
| <note> |
| <para>You should expect the structures returned by these methods to be backed by the CAS/JCas |
| contents. In particular, if you remove any feature structures from the CAS while iterating |
| over these structures may cause failures. For this reason, you should also not hold on to |
| these structures longer than necessary, as is the case for UIMA <code>FSIterator</code>s as |
| well.</para> |
| </note> |
| <para>Depending on whether one works with a CAS or JCas, the respective methods are available |
| from the JCasUtil or CasUtil classes. </para> |
| <para>JCasUtil expect a JCas wrapper class for the <parameter>type</parameter> argument, e.g. |
| <code>select(jcas, Token.class)</code> and return this type or a collection using this |
| generic type. Any subtypes of the specified type are returned as well. CasUtil expects a UIMA |
| <type>Type</type> instance. For conveniently getting these, CasUtil offers the methods |
| <code>getType(CAS, Class<?>)</code> or <code>getType(CAS, String)</code> which fetch a |
| type either by its JCas wrapper class or by its name.</para> |
| <para>Unless annotations are specifically required, e.g. because begin/end offsets are required, |
| the JCasUtil methods can be used to access any feature structure inheriting from |
| <type>TOP</type>, not only annotations. The CasUtil methods generally work only on |
| annotations. Alternative methods ending in "FS" are provided for accessing arbitrary feature |
| structures, e.g. <code>selectFS</code>.</para> |
| <para>Examples:</para> |
| <programlisting>// CAS version |
| Type tokenType = CasUtil.getType(cas, "my.Token"); |
| for (AnnotationFS token : CasUtil.select(cas, tokenType)) { |
| ... |
| } |
| |
| // JCas version |
| for (Token token : JCasUtil.select(jcas, Token.class)) { |
| ... |
| }</programlisting> |
| </section> |
| </chapter> |