Utils (GATE JavaDoc)

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.

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

Constructors
Constructor and Description
`Utils()`

Method Summary

Methods
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. 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 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. increasing order of start offset).
`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)` Load a plugin from the default GATE plugins directory.
`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. 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.
  - 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
```
public static void loadPlugin(String dirName)
```
    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)
```

Class Utils

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

OFFSET_COMPARATOR

Constructor Detail

Utils

Method Detail

length

lengthLong

length

lengthLong

contentFor

stringFor

cleanStringFor

stringFor

cleanStringFor

contentFor

stringFor

cleanStringFor

cleanString

start

start

start

end

end

end

getAnnotationsAtOffset

getContainedAnnotations

getContainedAnnotations

getContainedAnnotations

getContainedAnnotations

getCoveringAnnotations

getCoveringAnnotations

getCoveringAnnotations

getCoveringAnnotations

getOverlappingAnnotations

getOverlappingAnnotations

getOverlappingAnnotations

getOverlappingAnnotations

inDocumentOrder

featureMap

toFeatureMap

isEnabled

getRunningStrategy

logOnce

isLoggedOnce

getOnlyAnn

addAnn

addAnn

addAnn

expandUriString

shortenUriString

getCoextensiveAnnotations

getCoextensiveAnnotations

getCoextensiveAnnotations

getCoextensiveAnnotations

replaceVariablesInString

loadPlugin

loadPlugin

minus

minus

plus

plus

intersect

intersect