de.julielab.jcore.utility

Class JCoReFeaturePath

java.lang.Object

de.julielab.jcore.utility.JCoReFeaturePath

All Implemented Interfaces:

org.apache.uima.cas.FeaturePath

public class JCoReFeaturePath
extends 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.

Constructor Summary

Constructors

Constructor and Description
JCoReFeaturePath()

Method Summary

Modifier and Type	Method and Description
void	addFeature(org.apache.uima.cas.Feature feat)
void	clearReplacementCache() Important only if using value replacements.
protected Object	getArrayElement(org.apache.uima.cas.CommonArrayFS sa, Map<?,?> replacements, Method getter, Method setter, int index)
Boolean	getBooleanValue(org.apache.uima.cas.FeatureStructure fs)
Byte	getByteValue(org.apache.uima.cas.FeatureStructure fs)
Object	getDefaultReplacementValue()
Double	getDoubleValue(org.apache.uima.cas.FeatureStructure fs)
org.apache.uima.cas.Feature	getFeature(int i)
String	getFeaturePath()
protected Object	getFeatureValueFromFeatureStructure(org.apache.uima.cas.FeatureStructure fs, org.apache.uima.cas.Feature feature, Map<?,?> replacements) Returns the value of the feature feature of the feature structure fs.
Float	getFloatValue(org.apache.uima.cas.FeatureStructure fs)
org.apache.uima.cas.FeatureStructure	getFSValue(org.apache.uima.cas.FeatureStructure fs)
Integer	getIntValue(org.apache.uima.cas.FeatureStructure fs)
Long	getLongValue(org.apache.uima.cas.FeatureStructure fs)
protected String	getObjectValueAsString(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.
Short	getShortValue(org.apache.uima.cas.FeatureStructure fs)
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)
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.
String	getValueAsString(org.apache.uima.cas.FeatureStructure fs)
String	getValueAsString(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements) If using replacements, please note the comment at clearReplacementCache().
String[]	getValueAsStringArray(org.apache.uima.cas.FeatureStructure fs) Returns the feature path values without performing value replacements.
String[]	getValueAsStringArray(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements)
List<String>	getValueAsStringList(org.apache.uima.cas.FeatureStructure fs) Returns the feature path values without performing value replacements.
List<String>	getValueAsStringList(org.apache.uima.cas.FeatureStructure fs, boolean doReplacements)
void	initialize(String featurePath)
void	initialize(String featurePath, Map<?,?> replacements)
String	ll_getValueAsString(int fsRef, org.apache.uima.cas.impl.LowLevelCAS llCas)
void	loadReplacementsFromFile(String replacementsFile) Reads a replacement file with lines of the form originalValue=replacementValue and immediately populates the internal replacement table with those entries.
static Map<String,String>	readReplacementsFromFile(String replacementsFile) Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
static Map<String,String>	readReplacementsFromInputStream(InputStream is) Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.
Object	replaceValue(org.apache.uima.cas.FeatureStructure fs) When using this method, please note the comment at clearReplacementCache().
void	setDefaultReplacementValue(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(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(String featurePath,
                       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 Object replaceValue(org.apache.uima.cas.FeatureStructure fs)

When using this method, please note the comment at clearReplacementCache().

Parameters:

fs -

Returns:

getValue

public 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 Object getArrayElement(org.apache.uima.cas.CommonArrayFS sa,
                                 Map<?,?> replacements,
                                 Method getter,
                                 Method setter,
                                 int index)
                          throws IllegalAccessException,
                                 InvocationTargetException

Throws:

IllegalAccessException

InvocationTargetException

getFeatureValueFromFeatureStructure

protected Object getFeatureValueFromFeatureStructure(org.apache.uima.cas.FeatureStructure fs,
                                                     org.apache.uima.cas.Feature feature,
                                                     Map<?,?> replacements)

Returns the value of the feature feature of the feature structure fs.

Parameters:

fs -

feature -

replacements -

Returns:

getValueAsStringArray

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

getValueAsStringArray

public String[] getValueAsStringArray(org.apache.uima.cas.FeatureStructure fs)

Returns the feature path values without performing value replacements.

Parameters:

fs -

Returns:

getValueAsStringList

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

getValueAsStringList

public List<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 String getObjectValueAsString(Object objectValue)

Get a String representation for a single primitive value.

Parameters:

objectValue -

Returns:

getValueAsString

public String getValueAsString(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getValueAsString in interface org.apache.uima.cas.FeaturePath

getValueAsString

public 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 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 String getFeaturePath()

Specified by:

getFeaturePath in interface org.apache.uima.cas.FeaturePath

getStringValue

public String getStringValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getStringValue in interface org.apache.uima.cas.FeaturePath

getIntValue

public Integer getIntValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getIntValue in interface org.apache.uima.cas.FeaturePath

getBooleanValue

public Boolean getBooleanValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getBooleanValue in interface org.apache.uima.cas.FeaturePath

getByteValue

public Byte getByteValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getByteValue in interface org.apache.uima.cas.FeaturePath

getDoubleValue

public Double getDoubleValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getDoubleValue in interface org.apache.uima.cas.FeaturePath

getFloatValue

public Float getFloatValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getFloatValue in interface org.apache.uima.cas.FeaturePath

getLongValue

public Long getLongValue(org.apache.uima.cas.FeatureStructure fs)

Specified by:

getLongValue in interface org.apache.uima.cas.FeaturePath

getShortValue

public 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(String replacementsFile)
                              throws FileNotFoundException,
                                     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:

FileNotFoundException

IOException

readReplacementsFromFile

public static Map<String,String> readReplacementsFromFile(String replacementsFile)
                                                   throws FileNotFoundException,
                                                          IOException

Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.

Parameters:

replacementsFile -

Returns:

Throws:

FileNotFoundException

IOException

readReplacementsFromInputStream

public static Map<String,String> readReplacementsFromInputStream(InputStream is)
                                                          throws FileNotFoundException,
                                                                 IOException

Reads a replacement file with lines of the form originalValue=replacementValue and returns the respective map.

Parameters:

is -

Returns:

Throws:

FileNotFoundException

IOException

getDefaultReplacementValue

public Object getDefaultReplacementValue()

setDefaultReplacementValue

public void setDefaultReplacementValue(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.