Package de.julielab.jcore.utility

Class JCoReFeaturePath

  • All Implemented Interfaces:
    org.apache.uima.cas.FeaturePath
    public class JCoReFeaturePath
extends java.lang.Object
implements org.apache.uima.cas.FeaturePath
    This class is an implementation of the UIMA FeaturePath interface and adds some capabilities to it. Note that it also is currently missing some capabilities, most importantly it only does not implement a range of interface methods. However, it is able to query arbitrary feature values through its getValue(FeatureStructure, int) method, even if the methods to retrieve specific types of feature values (integers, floats, bytes etc) are currently not implemented. The JCoReFeaturePath uses the the same syntax as traditional UIMA feature paths but is also able to address specific indices in multi-valued features. Suppose you have a Gene annotation and want to create feature paths to access various information of the annotation. Then you could specify the following feature paths in the constructor of a new JCoReFeaturePath:
    • /specificType: Returns the string value of the specificType feature
    • /resourceEntryList: Returns the FSArray holding the ResourceEntry instances of the gene (a resource entry is a pointer into a database which is the 'resource')
    • /resourceEntryList/entryId: Returns the entryId feature values of all ResourceEntry instances as an array
    • /resourceEntryList[0]/entryId: Returns the entryId feature value of the first ResourceEntry instance
    • /resourceEntryList[-1]/entryId: Returns the entryId feature value of the last ResourceEntry instance
    Additionally, JCoReFeaturePath supports the following built-in functions:
    • coveredText(): Calls Annotation.getCoveredText on the annotation pointed to with the feature path
    • typeName(): Calls Object.getClass().getName() on the annotation pointed to by the feature path.
    Built-in functions are used by specifying a feature path like illustrated above, appending a colon (:) and then one of the built-in functions of the above. Suppose you have an EventMention with two Argument annotatations and want to get the covered text of the first argument. Then create a JCoReFeaturePath with the following feature path and execute it on the EventMention:
    • /arguments[0]/:coveredText(): Returns the document text covered by the first Argument of the EventMention.
    It might also be possible that your EventMention instances may have arguments of different types, e.g. Gene and miRNA. To get the name of the actual argument type, use:
    • /arguments[0]/:typeName(): Returns the name of type - or class - of the first argument
    Finally, it is also possible to execute built-in functions directly on the annotation the feature path is executed upon:
    • /:coveredText(): Returns the covered text of the input annotation and thus is equivalent to annotation.getCoveredText() Feature Value Replacement
    An entire new capability of JCoReFeaturePath in comparison to the default UIMA feature paths is its capability to replace existing feature values with a new value. For this purpose, the JCoReFeaturePath is given a map of replacements. This map can be read from a two-column file with the = character as the separator. Lines beginning with # will be ignored. Alternatively, the replacement map can be set directly. When replacing values, JCoReFeaturePath will navigate to the feature pointed to by the given feature path and look up the found feature value in the replacement map. If found, the mapped value from the map is placed to the feature instead of the original value. If the feature value is not found in the map, a preconfigured default value can be used or the feature value is left untouched.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addFeature​(org.apache.uima.cas.Feature feat)  
      void clearReplacementCache()
      Important only if using value replacements.
      protected java.lang.Object getArrayElement​(org.apache.uima.cas.CommonArrayFS sa, java.util.Map<?,​?> replacements, java.lang.reflect.Method getter, java.lang.reflect.Method setter, int index)  
      java.lang.Boolean getBooleanValue​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.Byte getByteValue​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.Object getDefaultReplacementValue()  
      java.lang.Double getDoubleValue​(org.apache.uima.cas.FeatureStructure fs)  
      org.apache.uima.cas.Feature getFeature​(int i)  
      java.lang.String getFeaturePath()  
      protected java.lang.Object getFeatureValueFromFeatureStructure​(org.apache.uima.cas.FeatureStructure fs, org.apache.uima.cas.Feature feature, java.util.Map<?,​?> replacements)
      Returns the value of the feature feature of the feature structure fs.
      java.lang.Float getFloatValue​(org.apache.uima.cas.FeatureStructure fs)  
      org.apache.uima.cas.FeatureStructure getFSValue​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.Integer getIntValue​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.Long getLongValue​(org.apache.uima.cas.FeatureStructure fs)  
      protected java.lang.String getObjectValueAsString​(java.lang.Object objectValue)
      Get a String representation for a single primitive value.
      boolean getReplaceUnmappedValues()
      Returns true if feature values not contained in the replacement map are to be replaced by a default value.
      java.lang.Short getShortValue​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.String getStringValue​(org.apache.uima.cas.FeatureStructure fs)  
      org.apache.uima.cas.TypeClass getTypClass​(org.apache.uima.cas.FeatureStructure fs)  
      org.apache.uima.cas.Type getType​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.Object getValue​(org.apache.uima.cas.FeatureStructure fs, int startFeatureIndex)
      Begins to traverse the feature path from position startFeatureIndex and returns whatever values lie at the end of the feature path.
      java.lang.String getValueAsString​(org.apache.uima.cas.FeatureStructure fs)  
      java.lang.String getValueAsString​(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements)
      If using replacements, please note the comment at clearReplacementCache().
      java.lang.String[] getValueAsStringArray​(org.apache.uima.cas.FeatureStructure fs)
      Returns the feature path values without performing value replacements.
      java.lang.String[] getValueAsStringArray​(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements)  
      java.util.List<java.lang.String> getValueAsStringList​(org.apache.uima.cas.FeatureStructure fs)
      Returns the feature path values without performing value replacements.
      java.util.List<java.lang.String> getValueAsStringList​(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements)  
      void initialize​(java.lang.String featurePath)  
      void initialize​(java.lang.String featurePath, java.util.Map<?,​?> replacements)  
      java.lang.String ll_getValueAsString​(int fsRef, org.apache.uima.cas.impl.LowLevelCAS llCas)  
      void loadReplacementsFromFile​(java.lang.String replacementsFile)
      Reads a replacement file with lines of the form originalValue=replacementValue and immediately populates the internal replacement table with those entries.
      static java.util.Map<java.lang.String,​java.lang.String> readReplacementsFromFile​(java.lang.String replacementsFile)
      Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
      static java.util.Map<java.lang.String,​java.lang.String> readReplacementsFromInputStream​(java.io.InputStream is)
      Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
      java.lang.Object replaceValue​(org.apache.uima.cas.FeatureStructure fs)
      When using this method, please note the comment at clearReplacementCache().
      void setDefaultReplacementValue​(java.lang.Object defaultReplacementValue)
      Sets a default replacement value to be used when there is no replacement for a feature value and replaceUnmappedValues is set to true.
      void setReplaceUnmappedValues​(boolean replaceWithNullValues)
      For the work with replacements, please note the comment of clearReplacementCache().
      int size()  
      void typeInit​(org.apache.uima.cas.Type featurePathType)  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • JCoReFeaturePath

        public JCoReFeaturePath()

    • Method Detail

      • size

        public int size()
        Specified by:
        size in interface org.apache.uima.cas.FeaturePath

      • getFeature

        public org.apache.uima.cas.Feature getFeature​(int i)
        Specified by:
        getFeature in interface org.apache.uima.cas.FeaturePath

      • addFeature

        public void addFeature​(org.apache.uima.cas.Feature feat)
        Specified by:
        addFeature in interface org.apache.uima.cas.FeaturePath

      • initialize

        public void initialize​(java.lang.String featurePath)
                throws org.apache.uima.cas.CASException
        Specified by:
        initialize in interface org.apache.uima.cas.FeaturePath
        Throws:
        org.apache.uima.cas.CASException

      • initialize

        public void initialize​(java.lang.String featurePath,
                       java.util.Map<?,​?> replacements)
                throws org.apache.uima.cas.CASException
        Throws:
        org.apache.uima.cas.CASException

      • typeInit

        public void typeInit​(org.apache.uima.cas.Type featurePathType)
              throws org.apache.uima.cas.CASException
        Specified by:
        typeInit in interface org.apache.uima.cas.FeaturePath
        Throws:
        org.apache.uima.cas.CASException

      • replaceValue

        public java.lang.Object replaceValue​(org.apache.uima.cas.FeatureStructure fs)
        When using this method, please note the comment at clearReplacementCache().
        Parameters:
        fs -
        Returns:

      • getValue

        public java.lang.Object getValue​(org.apache.uima.cas.FeatureStructure fs,
                                 int startFeatureIndex)
        Begins to traverse the feature path from position startFeatureIndex and returns whatever values lie at the end of the feature path. This includes FeatureStructures, primitive values or even array-typed values.
        Parameters:
        fs -
        startFeatureIndex -
        Returns:

      • getArrayElement

        protected java.lang.Object getArrayElement​(org.apache.uima.cas.CommonArrayFS sa,
                                           java.util.Map<?,​?> replacements,
                                           java.lang.reflect.Method getter,
                                           java.lang.reflect.Method setter,
                                           int index)
                                    throws java.lang.IllegalAccessException,
                                           java.lang.reflect.InvocationTargetException
        Throws:
        java.lang.IllegalAccessException
        java.lang.reflect.InvocationTargetException

      • getFeatureValueFromFeatureStructure

        protected java.lang.Object getFeatureValueFromFeatureStructure​(org.apache.uima.cas.FeatureStructure fs,
                                                               org.apache.uima.cas.Feature feature,
                                                               java.util.Map<?,​?> replacements)
        Returns the value of the feature feature of the feature structure fs.
        Parameters:
        fs -
        feature -
        replacements -
        Returns:

      • getValueAsStringArray

        public java.lang.String[] getValueAsStringArray​(org.apache.uima.cas.FeatureStructure fs,
                                                boolean doReplacements)

      • getValueAsStringArray

        public java.lang.String[] getValueAsStringArray​(org.apache.uima.cas.FeatureStructure fs)
        Returns the feature path values without performing value replacements.
        Parameters:
        fs -
        Returns:

      • getValueAsStringList

        public java.util.List<java.lang.String> getValueAsStringList​(org.apache.uima.cas.FeatureStructure fs,
                                                             boolean doReplacements)

      • getValueAsStringList

        public java.util.List<java.lang.String> getValueAsStringList​(org.apache.uima.cas.FeatureStructure fs)
        Returns the feature path values without performing value replacements. The returned list is not held by this object and can be modified in the application without side effects.
        Parameters:
        fs -
        Returns:

      • getObjectValueAsString

        protected java.lang.String getObjectValueAsString​(java.lang.Object objectValue)
        Get a String representation for a single primitive value.
        Parameters:
        objectValue -
        Returns:

      • getValueAsString

        public java.lang.String getValueAsString​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getValueAsString in interface org.apache.uima.cas.FeaturePath

      • getValueAsString

        public java.lang.String getValueAsString​(org.apache.uima.cas.FeatureStructure fs,
                                         boolean doReplacements)
        If using replacements, please note the comment at clearReplacementCache().
        Parameters:
        fs -
        doReplacements -
        Returns:

      • setReplaceUnmappedValues

        public void setReplaceUnmappedValues​(boolean replaceWithNullValues)
        For the work with replacements, please note the comment of clearReplacementCache().
        Parameters:
        replaceWithNullValues -

      • getReplaceUnmappedValues

        public boolean getReplaceUnmappedValues()
        Returns true if feature values not contained in the replacement map are to be replaced by a default value.
        Returns:

      • ll_getValueAsString

        public java.lang.String ll_getValueAsString​(int fsRef,
                                            org.apache.uima.cas.impl.LowLevelCAS llCas)
        Specified by:
        ll_getValueAsString in interface org.apache.uima.cas.FeaturePath

      • getType

        public org.apache.uima.cas.Type getType​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getType in interface org.apache.uima.cas.FeaturePath

      • getTypClass

        public org.apache.uima.cas.TypeClass getTypClass​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getTypClass in interface org.apache.uima.cas.FeaturePath

      • getFeaturePath

        public java.lang.String getFeaturePath()
        Specified by:
        getFeaturePath in interface org.apache.uima.cas.FeaturePath

      • getStringValue

        public java.lang.String getStringValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getStringValue in interface org.apache.uima.cas.FeaturePath

      • getIntValue

        public java.lang.Integer getIntValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getIntValue in interface org.apache.uima.cas.FeaturePath

      • getBooleanValue

        public java.lang.Boolean getBooleanValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getBooleanValue in interface org.apache.uima.cas.FeaturePath

      • getByteValue

        public java.lang.Byte getByteValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getByteValue in interface org.apache.uima.cas.FeaturePath

      • getDoubleValue

        public java.lang.Double getDoubleValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getDoubleValue in interface org.apache.uima.cas.FeaturePath

      • getFloatValue

        public java.lang.Float getFloatValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getFloatValue in interface org.apache.uima.cas.FeaturePath

      • getLongValue

        public java.lang.Long getLongValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getLongValue in interface org.apache.uima.cas.FeaturePath

      • getShortValue

        public java.lang.Short getShortValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getShortValue in interface org.apache.uima.cas.FeaturePath

      • getFSValue

        public org.apache.uima.cas.FeatureStructure getFSValue​(org.apache.uima.cas.FeatureStructure fs)
        Specified by:
        getFSValue in interface org.apache.uima.cas.FeaturePath

      • loadReplacementsFromFile

        public void loadReplacementsFromFile​(java.lang.String replacementsFile)
                              throws java.io.FileNotFoundException,
                                     java.io.IOException
        Reads a replacement file with lines of the form originalValue=replacementValue and immediately populates the internal replacement table with those entries.
        Parameters:
        replacementsFile -
        Throws:
        java.io.FileNotFoundException
        java.io.IOException

      • readReplacementsFromFile

        public static java.util.Map<java.lang.String,​java.lang.String> readReplacementsFromFile​(java.lang.String replacementsFile)
                                                                                       throws java.io.FileNotFoundException,
                                                                                              java.io.IOException
        Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
        Parameters:
        replacementsFile -
        Returns:
        Throws:
        java.io.FileNotFoundException
        java.io.IOException

      • readReplacementsFromInputStream

        public static java.util.Map<java.lang.String,​java.lang.String> readReplacementsFromInputStream​(java.io.InputStream is)
                                                                                              throws java.io.FileNotFoundException,
                                                                                                     java.io.IOException
        Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
        Parameters:
        is -
        Returns:
        Throws:
        java.io.FileNotFoundException
        java.io.IOException

      • getDefaultReplacementValue

        public java.lang.Object getDefaultReplacementValue()

      • setDefaultReplacementValue

        public void setDefaultReplacementValue​(java.lang.Object defaultReplacementValue)
        Sets a default replacement value to be used when there is no replacement for a feature value and replaceUnmappedValues is set to true. Defaults to null.
        Parameters:
        defaultReplacementValue -

      • clearReplacementCache

        public void clearReplacementCache()
        Important only if using value replacements. Clears the cache of already replaced feature structures. This has to be reset after each CAS in order to avoid collisions between different annotations from different CASes, which may happen due to the fact that the hash codes may collide and that the internal annotation addresses within a case are only unique within a CAS. Thus, the next CAS could have an annotation that doesn't get its value replaced because this annotation allegedly was already replaced due to an identity collision.