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

Fields

Modifier and Type	Field and Description
static OffsetComparator	OFFSET_COMPARATOR A single instance of OffsetComparator that can be used by any code that requires one.

Constructor Summary

Constructors

Constructor and Description
Utils()

Method Summary

Modifier and Type	Method and Description
static Integer	addAnn(AnnotationSet outSet, AnnotationSet spanSet, String type, FeatureMap fm) Add a new annotation to the output annotation set outSet, spanning the same region as spanSet, and having the given type and feature map.
static Integer	addAnn(AnnotationSet outSet, Annotation spanAnn, String type, FeatureMap fm) Add a new annotation to the output annotation set outSet, covering the same region as the annotation spanAnn, and having the given type and feature map.
static Integer	addAnn(AnnotationSet outSet, long startOffset, long endOffset, String type, FeatureMap fm) Add a new annotation to the output annotation set outSet, spanning the given offset range, and having the given type and feature map.
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 String	expandUriString(String toExpand, Map<String,String> prefixes) Expand both namespace prefixes and base-uris, if possible.
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	getCoextensiveAnnotations(AnnotationSet source, Annotation coextAnn) Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation.
static AnnotationSet	getCoextensiveAnnotations(AnnotationSet source, AnnotationSet coextSet) Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation set.
static AnnotationSet	getCoextensiveAnnotations(AnnotationSet source, AnnotationSet coextSet, String type) Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation set and are of the specified type.
static AnnotationSet	getCoextensiveAnnotations(AnnotationSet source, Annotation coextAnn, String type) Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation and have the specified type.
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.
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.
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 Annotation	getOnlyAnn(AnnotationSet annset) Returns the only annotation that annset is expected to contains, throws an exception if there is not exactly one 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.
static AnnotationSet	intersect(AnnotationSet origSet, Annotation... others) Return the subset from the original set that matches one of the given annotations.
static AnnotationSet	intersect(AnnotationSet origSet, Collection<Annotation> others)
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	loadPlugin(File pluginDir) Load a plugin from the specified directory.
static void	loadPlugin(String dirName) Deprecated.
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 AnnotationSet	minus(AnnotationSet origSet, Annotation... except) Return the given set with the given annotations removed.
static AnnotationSet	minus(AnnotationSet origSet, Collection<Annotation> exceptions) Return the given set with the given annotations removed.
static AnnotationSet	plus(AnnotationSet origSet, Annotation... toAdd) Return the given set with the given annotations added.
static AnnotationSet	plus(AnnotationSet origSet, Collection<Annotation> toAdd) Return the given set with the given annotations added.
static String	replaceVariablesInString(String string, Object... sources) This will replace all occurrences of variables of the form $env{name}, $prop{name}, $doc{featname}, $pr_parm{inputAS} or $$env{name} etc in a String.
static String	shortenUriString(String uriString, Map<String,String> prefixes) Compact an URI String using base URI and namespace prefixes.
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.
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.

getOnlyAnn

public static Annotation getOnlyAnn(AnnotationSet annset)

Returns the only annotation that annset is expected to contains, throws an exception if there is not exactly one annotation. This is useful when a binding set is expected to contain exactly one interesting annotation.

Parameters:

annset - the annotation set that is expected to contain exactly one annotation

Returns:

the one annotation or throws an exception if there are 0 or more than one annotations

addAnn

public static Integer addAnn(AnnotationSet outSet,
                             AnnotationSet spanSet,
                             String type,
                             FeatureMap fm)

Add a new annotation to the output annotation set outSet, spanning the same region as spanSet, and having the given type and feature map. The start and end nodes of the new annotation will be new nodes. This method will convert the checked InvalidOffsetException that can be raised by AnnotationSet.add to a GateRuntimeException.

Parameters:

outSet - the annotation set where the new annotation will be added

spanSet - an annotation set representing the span of the new annotation

type - the annotation type of the new annotation

fm - the feature map to use for the new annotation

Returns:

Returns the Id of the added annotation

addAnn

public static Integer addAnn(AnnotationSet outSet,
                             long startOffset,
                             long endOffset,
                             String type,
                             FeatureMap fm)

Add a new annotation to the output annotation set outSet, spanning the given offset range, and having the given type and feature map. The start and end nodes of the new annotation will be new nodes. This method will convert the checked InvalidOffsetException that can be raised by AnnotationSet.add to a GateRuntimeException.

Parameters:

outSet - outSet the annotation set where the new annotation will be added

startOffset - the start offset of the new annotation

endOffset - the end offset of the new annotation

type - the annotation type of the new annotation

fm - the feature map to use for the new annotation

Returns:

Returns the Id of the added annotation

addAnn

public static Integer addAnn(AnnotationSet outSet,
                             Annotation spanAnn,
                             String type,
                             FeatureMap fm)

Add a new annotation to the output annotation set outSet, covering the same region as the annotation spanAnn, and having the given type and feature map. The start and end nodes of the new annotation will be new nodes. This method will convert the checked InvalidOffsetException that can be raised by AnnotationSet.add to a GateRuntimeException.

Parameters:

outSet - the annotation set where the new annotation will be added

spanAnn - an annotation representing the span of the new annotation

type - the annotation type of the new annotation

fm - the feature map to use for the new annotation

Returns:

Returns the Id of the added annotation

expandUriString

public static String expandUriString(String toExpand,
                                     Map<String,String> prefixes)

Expand both namespace prefixes and base-uris, if possible. This will expand the String toExpand according to the following rules:

• if toExpand is a qName and does start with a name prefix in the form "somens:" or ":", then the name prefix is looked up in the prefixes map and replaced with the URI prefix found there. If the prefix could not be found a GateRuntimeException is thrown.
• if toExpand does not start with a name prefix, the entry with an empty string as the key is retrieved from the prefixes map and used as a baseURI: the result is the baseURI and the toExpand String concatenated. If no entry with an empty string is found in the map, a GateRuntimeException is thrown. *

This method can therefore be used to expand both base uris and namespaces.

If the map only contains a basename uri (if the only entry is for the empty string key) then name space prefixes are not checked: in this case, the toExpand string may contain an unescaped colon. If the map does not contain a basename URI (if there is no entry for the empty string key) then all toExpand strings are expected to be qNames.

NOTE: the name prefixes in the prefixes map must include the trailing colon!

Parameters:

toExpand - the URI portion to expand as a String

prefixes - a map from name prefixes to URI prefixes

Returns:

a String with name prefixes or base URI expanded

shortenUriString

public static String shortenUriString(String uriString,
                                      Map<String,String> prefixes)

Compact an URI String using base URI and namespace prefixes. The prefixes map, which maps name prefixes of the form "ns:" or the empty string to URI prefixes is searched for the first URI prefix in the value set that matches the beginning of the uriString. The corresponding name prefix is then used to replace that URI prefix. In order to control which URI prefix is matched first if the map contains several prefixes which can all match some URIs, a LinkedHashMap can be used so that the first matching URI prefix will be deterministic.

Parameters:

uriString - a full URI String that should get shortened using prefix names or a base URI

prefixes - a map containing name prefixes mapped to URI prefixes (same as for expandUriString)

Returns:

a shortened URI where the URI prefix is replaced with a prefix name or the empty string

getCoextensiveAnnotations

public static AnnotationSet getCoextensiveAnnotations(AnnotationSet source,
                                                      AnnotationSet coextSet)

Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation set.

Parameters:

source - the annotation set from which to select

coextSet - the annotation set from which to take the start and end offsets

Returns:

the AnnotationSet containing all annotations exactly coextensive with coextSet

getCoextensiveAnnotations

public static AnnotationSet getCoextensiveAnnotations(AnnotationSet source,
                                                      AnnotationSet coextSet,
                                                      String type)

Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation set and are of the specified type.

Parameters:

source - the annotation set from which to select

coextSet - the annotation set from which to take the start and end offsets

type - the desired annotation type of the annotations to return

Returns:

the AnnotationSet containing all annotations exactly coextensive with coextSet and of the specified type

getCoextensiveAnnotations

public static AnnotationSet getCoextensiveAnnotations(AnnotationSet source,
                                                      Annotation coextAnn)

Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation.

Parameters:

source - the annotation set from which to select

coextAnn - the annotation from which to take the start and end offsets

Returns:

the AnnotationSet containing all annotations exactly coextensive with coextAnn

getCoextensiveAnnotations

public static AnnotationSet getCoextensiveAnnotations(AnnotationSet source,
                                                      Annotation coextAnn,
                                                      String type)

Get all the annotations from the source annotation set that start and end at exactly the same offsets as the given annotation and have the specified type.

Parameters:

source - the annotation set from which to select

coextAnn - the annotation from which to take the start and end offsets

Returns:

the AnnotationSet containing all annotations exactly coextensive with coextAnn and having the specified type.

replaceVariablesInString

public static String replaceVariablesInString(String string,
                                              Object... sources)

This will replace all occurrences of variables of the form $env{name}, $prop{name}, $doc{featname}, $pr_parm{inputAS} or $$env{name} etc in a String. The source for replacing the variable can be environment variables, system properties, or arbitrary maps or resources specified when calling the method.

Examples:

• replaceVariablesInString("text $env{GATE_HOME} more text"): returns "text /path/to/gate more text" if the environment variable "GATE_HOME" was set to "/path/to/gate"
• replaceVariablesInString("text $pr{myfeature1} more text",pr1): returns "myvalue1" if the feature map of the processing resource pr1 contains an entry with key "myfeature" and value "myvalue"
• replaceVariablesInString("text ${somekey} more text",map1,map2,resource1,map3): this will find the value of an entry with key "somekey" in the first Map object specified in the parameter list of the method.

The possible sources for finding values for a variable are:

• System.getenv(): for variables of the form $env{name}
• System.getProperties(): for variables of the form $prop{name}
• Resource: the feature map of any resource which is specified in the list of objects is used for variables of the form $resource{name} or for variables of the form $corpus{name} if the resource is a corpus, for $pr{name} if the resource is a processing resource and so on. If the resource is a processing resource its
• FeatureMap or Map: any feature map or Map which can be used to look up String keys can be specified as a source and will be used for variables of the form ${name}.

The value substituted is converted to a string using the toString() method of whatever object is stored in the map. If the value returned by Map.get(key) is null, no substitution is carried out and the variable is left unchanged in the string.

The following variable constructs are supported:

• $env{name} will be replaced with the value from the environment variables map from System.getenv() and nothing else.
• $prop{name} will be replaced with the value of the properties map from System.getProperties() and nothing else.
• $controller{name} will be replaced with the value of a feature from the FeatureMap of the first resource of type Controller found in the argument list.
• $corpus{name} will be replaced with the value of a feature from the FeatureMap of the first resource of type Corpus found in the argument list.
• $pr{name} will be replaced with the value of a feature from the FeatureMap of the first resource of type ProcessingResource found in the argument list.
• $pr_parm{name} will be replaced with the value of the parameter 'name' of the first resource of type ProcessingResource found in the argument list. This can be especially useful to replace a variable in one parameter with the value of another, potentially hidden, parameter of the same PR.
• $doc{name} will be replaced with the value of a feature from the FeatureMap of the first resource of type Document found in the argument list.
• $resource{name} will be replaced with the value of a feature from the FeatureMap of the first resource of type Resource found in the argument list.

If two dollar characters are used instead of one, the replacement string will in turn be subject to replacement, e.g. $$env{abc} could get replaced with the replacement string '$corpus{f1}' which would in turn get replaced with the value of the feature 'f1' from the feature set of the first corpus in the parameter list that has a value for that feature.

loadPlugin

@Deprecated
public static void loadPlugin(String dirName)

Deprecated.

Load a plugin from the default GATE plugins directory. This will load the plugin with the specified directory name from the default GATE plugins path, if GATE knows its own location.

Parameters:

dirName - The directory name of the plugin within the standard GATE plugins directory.

loadPlugin

public static void loadPlugin(File pluginDir)

Load a plugin from the specified directory. This will load the plugin from the directory path specified as a File object.

minus

public static AnnotationSet minus(AnnotationSet origSet,
                                  Annotation... except)

Return the given set with the given annotations removed. This returns a new immutable annotation set, which contains all the annotations from origSet except the given annotations. The removal is not based on equality but on the id of the annotation: an annotation in origSet which has the same id as the annotation except is removed in the returned set.

NOTE: Annotation ids are only unique within a document, so you should never mix annotations from different documents when using this method!

Parameters:

origSet - The annotation set from which to remove the given annotation

except - The annotation to remove from the given set

Returns:

A new immutable annotation set with the given annotation removed from the original set

minus

public static AnnotationSet minus(AnnotationSet origSet,
                                  Collection<Annotation> exceptions)

Return the given set with the given annotations removed. This returns a new immutable annotation set, which contains all the annotations from origSet except the annotations given in the collection of exceptions. The removal is not based on equality but on the id of the annotations: an annotation in origSet which has the same id as an annotation from the exceptions is removed in the returned set.

NOTE: Annotation ids are only unique within a document, so you should never mix annotations from different documents when using this method!

Parameters:

origSet - The annotation set from which to remove the given exceptions

exceptions - The annotations to remove from the given set

Returns:

A new immutable annotation set with the exceptions removed from the original set

plus

public static AnnotationSet plus(AnnotationSet origSet,
                                 Annotation... toAdd)

Return the given set with the given annotations added. This returns a new immutable annotation set, which contains all the annotations from origSet plus the given annotations to add. The addition is not based on equality but on the id of the annotations: any new annotation is added if its annotation id differs from all the ids already in the set.

NOTE: Annotation ids are only unique within a document, so you should never mix annotations from different documents when using this method!

Parameters:

origSet - The annotation set from which to remove the given exceptions

toAdd - The annotations to add to the given set

Returns:

A new immutable annotation set with the given annotations added

plus

public static AnnotationSet plus(AnnotationSet origSet,
                                 Collection<Annotation> toAdd)

Return the given set with the given annotations added. This returns a new immutable annotation set, which contains all the annotations from origSet plus the given annotations added. The addition is not based on equality but on the id of the annotations: any new annotation is added if its annotation id differs from all the ids already in the set.

NOTE: Annotation ids are only unique within a document, so you should never mix annotations from different documents when using this method!

Parameters:

origSet - The annotation set from which to remove the given exceptions

toAdd - A collection of annotations to add to the original set

Returns:

A new immutable annotation set with the annotations from the collection added.

intersect

public static AnnotationSet intersect(AnnotationSet origSet,
                                      Annotation... others)

Return the subset from the original set that matches one of the given annotations. This returns a new immutable annotation set, which contains all the annotations from origSet which are also among the annotations given. The check for matching annotations is not based on equality but on the id of the annotations: an annotation from the original set is included in the returned set if its annotation id matches the annotation id of any of the annotations given.

NOTE: Annotation ids are only unique within a document, so you should never mix annotations from different documents when using this method!

Parameters:

origSet - The annotation set from which to select only the given annotations.

others - the given annotations

Returns:

A new immutable annotation set with the interesection between original set and given annotations

intersect

public static AnnotationSet intersect(AnnotationSet origSet,
                                      Collection<Annotation> others)