uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Richard Eckart de Castilho (JIRA)" <...@uima.apache.org>
Subject [jira] [Commented] (UIMA-3724) Adding (J)CasUtil.selectCoveredSingle()
Date Mon, 14 Apr 2014 08:31:15 GMT

    [ https://issues.apache.org/jira/browse/UIMA-3724?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13968167#comment-13968167
] 

Richard Eckart de Castilho commented on UIMA-3724:
--------------------------------------------------

I was not meaning to replace selectCoveredSingle with the method that I suggested, rather
have selectCoveredSingle use the new method internally instead of the current unlimited selectCovered.

> Adding (J)CasUtil.selectCoveredSingle()
> ---------------------------------------
>
>                 Key: UIMA-3724
>                 URL: https://issues.apache.org/jira/browse/UIMA-3724
>             Project: UIMA
>          Issue Type: Improvement
>          Components: uimaFIT
>            Reporter: Ofer Bronstein
>            Assignee: Richard Eckart de Castilho
>            Priority: Minor
>              Labels: patch
>             Fix For: 2.0.1uimaFIT
>
>   Original Estimate: 5m
>  Remaining Estimate: 5m
>
> JCasUtil (and its equivalent CASUtil) have two very useful methods:
> - {{selectSingle(JCas jCas, Class<T> type)}}, retrieving all T type annotations
from the CAS, making sure only one exists, and returning it
> - {{selectCovered(JCas jCas, final Class<T> type, AnnotationFS coveringAnnotation)}},
retrieving all T type annotations from the CAS, that exist in the span defined by the covering
annotation.
> My request is to add a {{selectCoveredSingle}} method (I already implemented and tested,
written below). It would retrieve all T type annotation in the span of the covering annotation,
make sure there is only one, and return it.
> The uses for such a method would be really common, as this assists in performing something
very basic in UIMA - once you have some annotation, you want to retrieve other information
on it, and if it is a small unit, then you know in advance that many types of information
should only appear once for that annotation. Otherwise, it's an error.
> For instance, say I have linguistically annotated text, and I hold some intersting annotation
of a Token. Then I want to find out what is its Part Of Speech. Then I would simply call:
{{selectCoveredSingle(jcas, PartOfSpeech.class, token)}}, and get exactly one PartOfSpeech
annotation as I expected. If there is none or more then one, an exception is thrown.
> One could also use a method like {{selectCoveredSingleOptional}} (not implemented yet),
that does exactly the same, but returns null when no such annotation exists, instead of throwing
an exception. This makes sense when a token can have some optional attribute. In linguistics,
it could be when a Token may be a NamedEntity, but not necessarily.
> the implementation is made out of two methods - the first should be in JCasUtil, the
second should be in CASUtil.
> ===
> Implementation:
> ===
> 	/**
> 	 * Get the annotation of the given annotation type constrained by a 'covering' annotation.
> 	 * Iterates over all annotations of the given type to find the covered annotations.
> 	 * Does not use subiterators.
> 	 *
> 	 * @param <T>
> 	 *            the JCas type.
> 	 * @param jCas
> 	 *            a JCas containing the annotation.
> 	 * @param type
> 	 *            a UIMA type.
> 	 * @param coveringAnnotation
> 	 *            the covering annotation.
> 	 * @return the single instance of the given type.
> 	 * @throws IllegalArgumentException if not exactly one instance if the given type is
present
> 	 * 		   under the covering annotation.
> 	 * @see Subiterator
> 	 * 
> 	 * @author Ofer Bronstein
> 	 * @since April 2014
> 	 */
> 	@SuppressWarnings("unchecked")
> 	public static <T extends Annotation> T selectCoveredSingle(JCas jCas, final Class<T>
type,
> 			AnnotationFS coveringAnnotation) {
> 		return (T) selectCoveredSingle(jCas.getCas(), JCasUtil.getType(jCas, type),
> 				coveringAnnotation);
> 	}
> 	/**
> 	 * Get the annotation of the given annotation type constrained by a 'covering' annotation.
> 	 * Iterates over all annotations of the given type to find the covered annotations.
> 	 * Does not use subiterators.
> 	 *
> 	 * @param cas
> 	 *            a cas containing the annotation.
> 	 * @param type
> 	 *            a UIMA type.
> 	 * @param coveringAnnotation
> 	 *            the covering annotation.
> 	 * @return the single instance of the given type.
> 	 * @throws IllegalArgumentException if not exactly one instance if the given type is
present
> 	 * 		   under the covering annotation.
> 	 * @see Subiterator
> 	 * 
> 	 * @author Ofer Bronstein
> 	 * @since April 2014
> 	 */
> 	public static AnnotationFS selectCoveredSingle(CAS cas, Type type,
> 			AnnotationFS coveringAnnotation) {
> 		List<AnnotationFS> annotations = CasUtil.selectCovered(cas, type, coveringAnnotation);
> 		
> 		if (annotations.isEmpty()) {
> 			throw new IllegalArgumentException("CAS does not contain any [" + type.getName() +
"]");
> 		}
> 		if (annotations.size() > 1)  {
> 			throw new IllegalArgumentException("CAS contains more than one [" + type.getName()
> 					+ "]");
> 		}
> 		
> 		return annotations.get(0);
> 	}



--
This message was sent by Atlassian JIRA
(v6.2#6252)

Mime
View raw message