uimafit-doc/src/main/asciidoc/tools.uimafit.casutil.adoc - uima-uimafit - Git at Google

 // 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.

 [[_ugr.tools.uimafit.casutil]]
 = CAS Utilities

 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.

 == Access methods

 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).

 * `select(cas, type)` - fetch all annotations of the given type from the CAS/JCas. Variants of this method also exist to fetch annotations from a [type]``FSList`` or [type]``FSArray``.
 * `selectAll(cas)` - fetch all annotations from the CAS or fetch all feature structures from the JCas.
 * ``selectBetween(type, annotation1, annotation2)``* - fetch all annotations between the given two annotations.
 * ``selectCovered(type, annotation)``* - fetch all annotations covered by the given annotation. If this operation is used intensively, `indexCovered(...)` should be used to pre-calculate annotation covering information.
 * `selectCovering(type, annotation)*` - fetch all annotations covering the given annotation. If this operation is used intensively, `indexCovering(...)` should be used to pre-calculate annotation covering information.
 * `selectByIndex(cas, type, n)` - fetch the n-th feature structure of the given type.
 * `selectSingle(cas, type)` - fetch the single feature structure of the given type. An exception is thrown if there is not exactly one feature structure of the type.
 * `selectSingleRelative(type, annotation, n)`* - fetch a single annotation relative to the given annotation. A positive [parameter]``n`` fetches the n-th annotation right of the specified annotation, while the a negative [parameter]``n`` fetches to the left.
 * `selectPreceding(type, annotation, n)`* - fetch the n annotations preceding the given annotation. If there are less then n preceding annotations, all preceding annotations are returned.
 * `selectFollowing(type, annotation, n)`* - fetch the n annotations following the given annotation. If there are less then n following annotations, all following annotations are returned.


 [NOTE]
 ====
 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.
 ====

 [NOTE]
 ====
 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 ``FSIterator``s as well.
 ====

 Depending on whether one works with a CAS or JCas, the respective methods are available from the JCasUtil or CasUtil classes.

 JCasUtil expect a JCas wrapper class for the [parameter]``type`` argument, e.g. `select(jcas, Token.class)` 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`` instance.
 For conveniently getting these, CasUtil offers the methods `getType(CAS, Class<?>)` or `getType(CAS, String)` which fetch a type either by its JCas wrapper class or by its name.

 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``, 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. ``selectFS``.

 Examples:

 [source,java]
 ----
 // 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)) {
   ...
 }
 ----
	// 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.

	[[_ugr.tools.uimafit.casutil]]
	= CAS Utilities

	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.

	== Access methods

	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).

	* `select(cas, type)` - fetch all annotations of the given type from the CAS/JCas. Variants of this method also exist to fetch annotations from a [type]``FSList`` or [type]``FSArray``.
	* `selectAll(cas)` - fetch all annotations from the CAS or fetch all feature structures from the JCas.
	* ``selectBetween(type, annotation1, annotation2)``* - fetch all annotations between the given two annotations.
	* ``selectCovered(type, annotation)``* - fetch all annotations covered by the given annotation. If this operation is used intensively, `indexCovered(...)` should be used to pre-calculate annotation covering information.
	* `selectCovering(type, annotation)*` - fetch all annotations covering the given annotation. If this operation is used intensively, `indexCovering(...)` should be used to pre-calculate annotation covering information.
	* `selectByIndex(cas, type, n)` - fetch the n-th feature structure of the given type.
	* `selectSingle(cas, type)` - fetch the single feature structure of the given type. An exception is thrown if there is not exactly one feature structure of the type.
	* `selectSingleRelative(type, annotation, n)`* - fetch a single annotation relative to the given annotation. A positive [parameter]``n`` fetches the n-th annotation right of the specified annotation, while the a negative [parameter]``n`` fetches to the left.
	* `selectPreceding(type, annotation, n)`* - fetch the n annotations preceding the given annotation. If there are less then n preceding annotations, all preceding annotations are returned.
	* `selectFollowing(type, annotation, n)`* - fetch the n annotations following the given annotation. If there are less then n following annotations, all following annotations are returned.


	[NOTE]
	====
	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.
	====

	[NOTE]
	====
	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 ``FSIterator``s as well.
	====

	Depending on whether one works with a CAS or JCas, the respective methods are available from the JCasUtil or CasUtil classes.

	JCasUtil expect a JCas wrapper class for the [parameter]``type`` argument, e.g. `select(jcas, Token.class)` 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`` instance.
	For conveniently getting these, CasUtil offers the methods `getType(CAS, Class<?>)` or `getType(CAS, String)` which fetch a type either by its JCas wrapper class or by its name.

	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``, 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. ``selectFS``.

	Examples:

	[source,java]
	----
	// 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)) {
	...
	}
	----