gate
Class Utils

java.lang.Object
  gate.Utils

public class Utils
extends Object

Various utility methods to make often-needed tasks more easy and using up less code. In Java code (or JAPE grammars) you may wish to import static gate.Utils.* to access these methods without having to qualify them with a class name. In Groovy code, this class can be used as a category to inject each utility method into the class of its first argument, e.g.

 Document doc = // ...
 Annotation ann = // ...
 use(gate.Utils) {
   println "Annotation has ${ann.length()} characters"
   println "and covers the string \"${doc.stringFor(ann)}\""
 }
 

Author:

Johann Petrak, Ian Roberts

Field Summary

private static Set<String>	alreadyLoggedMessages
static OffsetComparator	OFFSET_COMPARATOR A single instance of OffsetComparator that can be used by any code that requires one.

Constructor Summary

Utils()

Method Summary

static DocumentContent	contentFor(SimpleDocument doc, AnnotationSet anns) Return the DocumentContent covered by the given annotation set.
static DocumentContent	contentFor(SimpleDocument doc, SimpleAnnotation ann) Return the DocumentContent corresponding to the annotation.
static Long	end(AnnotationSet as) Get the end offset of an annotation set.
static Long	end(SimpleAnnotation a) Get the end offset of an annotation.
static Long	end(SimpleDocument d) Get the end offset of a document.
static FeatureMap	featureMap(Object... values) Create a feature map from an array of values.
static AnnotationSet	getAnnotationsAtOffset(AnnotationSet annotationSet, Long atOffset) Return a the subset of annotations from the given annotation set that start exactly at the given offset.
static AnnotationSet	getContainedAnnotations(AnnotationSet sourceAnnotationSet, Annotation containingAnnotation) Get all the annotations from the source annotation set that lie within the range of the containing annotation.
static AnnotationSet	getContainedAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet containingAnnotationSet) Get all the annotations from the source annotation set that lie within the range of the containing annotation set, i.e. within the offset range between the start of the first annotation in the containing set and the end of the last annotation in the annotation set.
static AnnotationSet	getContainedAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet containingAnnotationSet, String targetType) Get all the annotations from the source annotation set with a type equal to targetType that lie within the range of the containing annotation set, i.e. within the offset range between the start of the first annotation in the containing set and the end of the last annotation in the annotation set.
static AnnotationSet	getContainedAnnotations(AnnotationSet sourceAnnotationSet, Annotation containingAnnotation, String targetType) Get all the annotations of type targetType from the source annotation set that lie within the range of the containing annotation.
static List<Annotation>	inDocumentOrder(AnnotationSet as) Return a List containing the annotations in the given annotation set, in document order (i.e. increasing order of start offset).
static boolean	isLoggedOnce(String message) Check if a message has already been logged or shown.
static int	length(Document doc) Return the length of the document as an int -- if the content is too long for an int, the method will throw a GateRuntimeException.
static int	length(SimpleAnnotation ann) Return the length of the document content covered by an Annotation as an int -- if the content is too long for an int, the method will throw a GateRuntimeException.
static long	lengthLong(Document doc) Return the length of the document as a long.
static long	lengthLong(SimpleAnnotation ann) Return the length of the document content covered by an Annotation as a long.
static void	logOnce(org.apache.log4j.Logger logger, org.apache.log4j.Level level, String message) Issue a message to the log but only if the same message has not been logged already in the same GATE session.
static Long	start(AnnotationSet as) Get the start offset of an annotation set.
static Long	start(SimpleAnnotation a) Get the start offset of an annotation.
static Long	start(SimpleDocument d) Get the start offset of a document (i.e. 0L).
static String	stringFor(Document doc, AnnotationSet anns) Return the document text as a String covered by the given annotation set.
static String	stringFor(Document doc, Long start, Long end) Returns the document text between the provided offsets.
static String	stringFor(Document doc, SimpleAnnotation ann) Return the document text as a String corresponding to the annotation.
static FeatureMap	toFeatureMap(Map map) Create a feature map from an existing map (typically one that does not itself implement FeatureMap).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OFFSET_COMPARATOR

public static final OffsetComparator OFFSET_COMPARATOR

A single instance of OffsetComparator that can be used by any code that requires one.

alreadyLoggedMessages

private static final Set<String> alreadyLoggedMessages

Constructor Detail

Utils

public Utils()

Method Detail

length

public static int length(SimpleAnnotation ann)

Return the length of the document content covered by an Annotation as an int -- if the content is too long for an int, the method will throw a GateRuntimeException. Use getLengthLong(SimpleAnnotation ann) if this situation could occur.

Parameters:

ann - the annotation for which to determine the length

Returns:

the length of the document content covered by this annotation.

lengthLong

public static long lengthLong(SimpleAnnotation ann)

Return the length of the document content covered by an Annotation as a long.

Parameters:

ann - the annotation for which to determine the length

Returns:

the length of the document content covered by this annotation.

length

public static int length(Document doc)

Return the length of the document as an int -- if the content is too long for an int, the method will throw a GateRuntimeException. Use getLengthLong(Document doc) if this situation could occur.

Parameters:

doc - the document for which to determine the length

Returns:

the length of the document content.

lengthLong

public static long lengthLong(Document doc)

Return the length of the document as a long.

Parameters:

doc - the document for which to determine the length

Returns:

the length of the document content.

contentFor

public static DocumentContent contentFor(SimpleDocument doc,
                                         SimpleAnnotation ann)

Return the DocumentContent corresponding to the annotation.

Note: the DocumentContent object returned will also contain the original content which can be accessed using the getOriginalContent() method.

Parameters:

doc - the document from which to extract the content

ann - the annotation for which to return the content.

Returns:

a DocumentContent representing the content spanned by the annotation.

stringFor

public static String stringFor(Document doc,
                               SimpleAnnotation ann)

Return the document text as a String corresponding to the annotation.

Parameters:

doc - the document from which to extract the document text

ann - the annotation for which to return the text.

Returns:

a String representing the text content spanned by the annotation.

stringFor

public static String stringFor(Document doc,
                               Long start,
                               Long end)

Returns the document text between the provided offsets.

Parameters:

doc - the document from which to extract the document text

start - the start offset

end - the end offset

Returns:

document text between the provided offsets

contentFor

public static DocumentContent contentFor(SimpleDocument doc,
                                         AnnotationSet anns)

Return the DocumentContent covered by the given annotation set.

Note: the DocumentContent object returned will also contain the original content which can be accessed using the getOriginalContent() method.

Parameters:

doc - the document from which to extract the content

anns - the annotation set for which to return the content.

Returns:

a DocumentContent representing the content spanned by the annotation set.

stringFor

public static String stringFor(Document doc,
                               AnnotationSet anns)

Return the document text as a String covered by the given annotation set.

Parameters:

doc - the document from which to extract the document text

anns - the annotation set for which to return the text.

Returns:

a String representing the text content spanned by the annotation set.

start

public static Long start(SimpleAnnotation a)

Get the start offset of an annotation.

start

public static Long start(AnnotationSet as)

Get the start offset of an annotation set.

start

public static Long start(SimpleDocument d)

Get the start offset of a document (i.e. 0L).

end

public static Long end(SimpleAnnotation a)

Get the end offset of an annotation.

end

public static Long end(AnnotationSet as)

Get the end offset of an annotation set.

end

public static Long end(SimpleDocument d)

Get the end offset of a document.

getAnnotationsAtOffset

public static AnnotationSet getAnnotationsAtOffset(AnnotationSet annotationSet,
                                                   Long atOffset)

Return a the subset of annotations from the given annotation set that start exactly at the given offset.

Parameters:

annotationSet - the set of annotations from which to select

atOffset - the offset where the annoation to be returned should start

Returns:

an annotation set containing all the annotations from the original set that start at the given offset

getContainedAnnotations

public static AnnotationSet getContainedAnnotations(AnnotationSet sourceAnnotationSet,
                                                    Annotation containingAnnotation)

Get all the annotations from the source annotation set that lie within the range of the containing annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

containingAnnotation - the annotation whose range must contain the selected annotations

Returns:

the AnnotationSet containing all annotations fully contained in the offset range of the containingAnnotation

getContainedAnnotations

public static AnnotationSet getContainedAnnotations(AnnotationSet sourceAnnotationSet,
                                                    Annotation containingAnnotation,
                                                    String targetType)

Get all the annotations of type targetType from the source annotation set that lie within the range of the containing annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

containingAnnotation - the annotation whose range must contain the

targetType - the type the selected annotations must have. If the empty string, no filtering on type is done.

Returns:

the AnnotationSet containing all annotations fully contained in the offset range of the containingAnnotation

getContainedAnnotations

public static AnnotationSet getContainedAnnotations(AnnotationSet sourceAnnotationSet,
                                                    AnnotationSet containingAnnotationSet)

Get all the annotations from the source annotation set that lie within the range of the containing annotation set, i.e. within the offset range between the start of the first annotation in the containing set and the end of the last annotation in the annotation set. If the containing annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

containingAnnotationSet - the annotation set whose range must contain the selected annotations

Returns:

the AnnotationSet containing all annotations fully contained in the offset range of the containingAnnotationSet

getContainedAnnotations

public static AnnotationSet getContainedAnnotations(AnnotationSet sourceAnnotationSet,
                                                    AnnotationSet containingAnnotationSet,
                                                    String targetType)

Get all the annotations from the source annotation set with a type equal to targetType that lie within the range of the containing annotation set, i.e. within the offset range between the start of the first annotation in the containing set and the end of the last annotation in the annotation set. If the containing annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

containingAnnotationSet - the annotation set whose range must contain the selected annotations

targetType - the type the selected annotations must have

Returns:

the AnnotationSet containing all annotations fully contained in the offset range of the containingAnnotationSet

inDocumentOrder

public static List<Annotation> inDocumentOrder(AnnotationSet as)

Return a List containing the annotations in the given annotation set, in document order (i.e. increasing order of start offset).

Parameters:

as - the annotation set

Returns:

a list containing the annotations from as in document order.

featureMap

public static FeatureMap featureMap(Object... values)

Create a feature map from an array of values. The array must have an even number of items, alternating keys and values i.e. [key1, value1, key2, value2, ...].

Parameters:

values - an even number of items, alternating keys and values.

Returns:

a feature map containing the given items.

toFeatureMap

public static FeatureMap toFeatureMap(Map map)

Create a feature map from an existing map (typically one that does not itself implement FeatureMap).

Parameters:

map - the map to convert.

Returns:

a new FeatureMap containing the same mappings as the source map.

logOnce

public static void logOnce(org.apache.log4j.Logger logger,
                           org.apache.log4j.Level level,
                           String message)

Issue a message to the log but only if the same message has not been logged already in the same GATE session. This is intended for explanations or warnings that should not be repeated every time the same situation occurs.

Parameters:

logger - - the logger instance to use

level - - the severity level for the message

message - - the message itself

isLoggedOnce

public static boolean isLoggedOnce(String message)

Check if a message has already been logged or shown. This does not log or show anything but only stores the message as one that has been shown already if necessary and returns if the message has been shown or not.

Parameters:

message - - the message that should only be logged or shown once

Returns:

- true if the message has already been logged or checked with this method.