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

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 String	cleanString(String input) Return a cleaned version of the input String.
static String	cleanStringFor(Document doc, AnnotationSet anns) Return the cleaned document text as a String covered by the given annotation set.
static String	cleanStringFor(Document doc, Long start, Long end) Return the cleaned document text between the provided offsets.
static String	cleanStringFor(Document doc, SimpleAnnotation ann) Return the cleaned document text as a String corresponding to the annotation.
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 AnnotationSet	getCoveringAnnotations(AnnotationSet sourceAnnotationSet, Annotation coveredAnnotation) Get all the annotations from the source annotation set that cover the range of the specified annotation.
static AnnotationSet	getCoveringAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet coveredAnnotationSet) Get all the annotations from the source annotation set that cover the range of the specified annotation set.
static AnnotationSet	getCoveringAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet coveredAnnotationSet, String targetType) Get all the annotations from the source annotation set with a type equal to targetType that cover the range of the specified annotation set.
static AnnotationSet	getCoveringAnnotations(AnnotationSet sourceAnnotationSet, Annotation coveredAnnotation, String targetType) Get all the annotations of type targetType from the source annotation set that cover the range of the specified annotation.
static AnnotationSet	getOverlappingAnnotations(AnnotationSet sourceAnnotationSet, Annotation overlappedAnnotation) Get all the annotations from the source annotation set that partly or totally overlap the range of the specified annotation.
static AnnotationSet	getOverlappingAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet overlappedAnnotationSet) Get all the annotations from the source annotation set that overlap the range of the specified annotation set.
static AnnotationSet	getOverlappingAnnotations(AnnotationSet sourceAnnotationSet, AnnotationSet overlappedAnnotationSet, String targetType) Get all the annotations from the source annotation set with a type equal to targetType that partly or completely overlap the range of the specified annotation set.
static AnnotationSet	getOverlappingAnnotations(AnnotationSet sourceAnnotationSet, Annotation overlappedAnnotation, String targetType) Get all the annotations of type targetType from the source annotation set that partly or totally overlap the range of the specified annotation.
static RunningStrategy	getRunningStrategy(Controller controller, ProcessingResource pr) Return the running strategy of the PR in the controller, if the controller is a conditional controller.
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	isEnabled(Controller controller, ProcessingResource pr) This method can be used to check if a ProcessingResource has a chance to be run in the given controller with the current settings.
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.

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.

cleanStringFor

public static String cleanStringFor(Document doc,
                                    SimpleAnnotation ann)

Return the cleaned document text as a String corresponding to the annotation. (Delete leading and trailing whitespace; normalize internal whitespace to single spaces.)

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

cleanStringFor

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

Return the cleaned document text between the provided offsets. (Delete leading and trailing whitespace; normalize internal whitespace to single spaces.)

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.

cleanStringFor

public static String cleanStringFor(Document doc,
                                    AnnotationSet anns)

Return the cleaned document text as a String covered by the given annotation set. (Delete leading and trailing whitespace; normalize internal whitespace to single spaces.)

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.

cleanString

public static String cleanString(String input)

Return a cleaned version of the input String. (Delete leading and trailing whitespace; normalize internal whitespace to single spaces; return an empty String if the input contains nothing but whitespace, but null if the input is null.)

Returns:

a cleaned version of the input String.

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

getCoveringAnnotations

public static AnnotationSet getCoveringAnnotations(AnnotationSet sourceAnnotationSet,
                                                   Annotation coveredAnnotation)

Get all the annotations from the source annotation set that cover the range of the specified annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

coveredAnnotation - the annotation whose range must equal or lie within the selected annotations

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the coveredAnnotation

getCoveringAnnotations

public static AnnotationSet getCoveringAnnotations(AnnotationSet sourceAnnotationSet,
                                                   Annotation coveredAnnotation,
                                                   String targetType)

Get all the annotations of type targetType from the source annotation set that cover the range of the specified annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

coveredAnnotation - the annotation whose range must be covered

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

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the coveredAnnotation

getCoveringAnnotations

public static AnnotationSet getCoveringAnnotations(AnnotationSet sourceAnnotationSet,
                                                   AnnotationSet coveredAnnotationSet)

Get all the annotations from the source annotation set that cover the range of the specified annotation set. If the covered annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

coveredAnnotationSet - the annotation set whose range must be covered by the selected annotations

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the containingAnnotationSet

getCoveringAnnotations

public static AnnotationSet getCoveringAnnotations(AnnotationSet sourceAnnotationSet,
                                                   AnnotationSet coveredAnnotationSet,
                                                   String targetType)

Get all the annotations from the source annotation set with a type equal to targetType that cover the range of the specified annotation set. If the specified annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

coveredAnnotationSet - the annotation set whose range must be covered by the selected annotations

targetType - the type the selected annotations must have

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the containingAnnotationSet

getOverlappingAnnotations

public static AnnotationSet getOverlappingAnnotations(AnnotationSet sourceAnnotationSet,
                                                      Annotation overlappedAnnotation)

Get all the annotations from the source annotation set that partly or totally overlap the range of the specified annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

overlappedAnnotation - the annotation whose range the selected annotations must overlap

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the coveredAnnotation

getOverlappingAnnotations

public static AnnotationSet getOverlappingAnnotations(AnnotationSet sourceAnnotationSet,
                                                      Annotation overlappedAnnotation,
                                                      String targetType)

Get all the annotations of type targetType from the source annotation set that partly or totally overlap the range of the specified annotation.

Parameters:

sourceAnnotationSet - the annotation set from which to select

overlappedAnnotation - the annotation whose range the selected annotations must overlap

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

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the coveredAnnotation

getOverlappingAnnotations

public static AnnotationSet getOverlappingAnnotations(AnnotationSet sourceAnnotationSet,
                                                      AnnotationSet overlappedAnnotationSet)

Get all the annotations from the source annotation set that overlap the range of the specified annotation set. If the overlapped annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

overlappedAnnotationSet - the annotation set whose range must be overlapped by the selected annotations

Returns:

the AnnotationSet containing all annotations that fully cover the offset range of the containingAnnotationSet

getOverlappingAnnotations

public static AnnotationSet getOverlappingAnnotations(AnnotationSet sourceAnnotationSet,
                                                      AnnotationSet overlappedAnnotationSet,
                                                      String targetType)

Get all the annotations from the source annotation set with a type equal to targetType that partly or completely overlap the range of the specified annotation set. If the specified annotation set is empty, an empty set is returned.

Parameters:

sourceAnnotationSet - the annotation set from which to select

overlappedAnnotationSet - the annotation set whose range must be overlapped by the selected annotations

targetType - the type the selected annotations must have

Returns:

the AnnotationSet containing all annotations that partly or fully overlap 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.

isEnabled

public static boolean isEnabled(Controller controller,
                                ProcessingResource pr)

This method can be used to check if a ProcessingResource has a chance to be run in the given controller with the current settings.

That means that for a non-conditional controller, the method will return true if the PR is part of the controller. For a conditional controller, the method will return true if it is part of the controller and at least once (if the same PR is contained multiple times) it is not disabled.

Parameters:

controller -

pr -

Returns:

true or false depending on the conditions explained above.

getRunningStrategy

public static RunningStrategy getRunningStrategy(Controller controller,
                                                 ProcessingResource pr)

Return the running strategy of the PR in the controller, if the controller is a conditional controller. If the controller is not a conditional controller, null is returned. If the controller is a conditional controller and the PR is contained multiple times, the running strategy for the first occurrence the is found is returned.

Parameters:

controller -

pr -

Returns:

A RunningStrategy object or null

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.