org.biopax.paxtools.controller
Class PropertyReasoner

java.lang.Object
  org.biopax.paxtools.controller.Traverser
      org.biopax.paxtools.controller.AbstractTraverser
          org.biopax.paxtools.controller.PropertyReasoner

All Implemented Interfaces:

Visitor

public class PropertyReasoner
extends AbstractTraverser

A tool to set or infer a particular BioPAX property for an object and all its children. For best (consistent) results, it's recommended to generally start from a "root" element, or, at least, - the parent-most one that have given propertyName. However, for some (if not - most) BioPAX properties, except for, e.g., 'dataSource', 'xref', 'organism', 'cellularLocation', - using of this tool does NOT make sense; i.e., one should not normally "infer" (apply to children elements) such properties as 'displayName', 'ph', 'nextStep' (for sure!), etc.. Tip: use with care; write tests for your case!

Author:

rodche

Field Summary

Fields inherited from class org.biopax.paxtools.controller.Traverser

editorMap, filters, log, visitor

Constructor Summary

PropertyReasoner(java.lang.String property, EditorMap editorMap)
Constructor, which additionally sets a BioPAX property filter for traverse(BioPAXElement, Model) to call visit(Object, BioPAXElement, Model, PropertyEditor) for each *object* property, except for 'nextStep'.

PropertyReasoner(java.lang.String propertyName, EditorMap editorMap, Filter<PropertyEditor>... propertyFilters)

Method Summary

void	clearProperty(BioPAXElement element) For the element and its children, where it's desired (in domains) and possible, it sets the propertyName values to "unknown".
java.lang.String	getPropertyName()
void	inferPropertyValue(BioPAXElement element) For the element and its children, where it's empty, desired (in domains) and allowed, it adds or sets the propertyName from parents's (if they have any valueStack)
void	inferPropertyValue(BioPAXElement element, java.lang.Object addValue) For the element and its children, where it's empty, desired (in domains) and allowed, it adds or sets the propertyName from parents's (if the top-most, a parent element that has this propertyName, does not have any valueStack, then given valueStack will be set, and children may inherit it)
boolean	isGenerateComments()
boolean	isOverride()
void	resetPropertyValue(BioPAXElement element, java.lang.Object defaultValue) For the element and its children, where it's desired (in domains) and allowed (by BioPAX), it forces the given propertyName valueStack replace existing ones.
protected void	run(BioPAXElement element, java.lang.Object defaultValue) Basic, universal method (used by others in this class) - updates the propertyName valueStack of a BioPAX element and its children.
void	setDomains(java.lang.Class<? extends BioPAXElement>... domains) When set (not empty list), only instances of the listed types can be updated by run(BioPAXElement, Object) method, although the propertyName property valueStack of every element (where apply) can be still considered for its children (of the specified type).
void	setGenerateComments(boolean generateComments)
protected void	setOverride(boolean override) Sets the override mode.
void	setPropertyName(java.lang.String propertyName)
void	traverse(BioPAXElement bpe, Model model) This traverse method, first, takes care about the propertyName we are interested in, then proceeds- as the basic Traverser.traverse(BioPAXElement, Model) would normally do (i.e., - delivering to the method visit(Object, BioPAXElement, Model, PropertyEditor) for all properties without any predefined order).
protected void	visit(java.lang.Object range, BioPAXElement bpe, Model model, PropertyEditor editor) Simply, calls traverse(BioPAXElement, Model) and goes deeper when the propertyName's range/valueStack is a BioPAX object.

Methods inherited from class org.biopax.paxtools.controller.AbstractTraverser

getVisited, visit

Methods inherited from class org.biopax.paxtools.controller.Traverser

filter, getVisitor, setVisitor

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertyReasoner

public PropertyReasoner(java.lang.String propertyName,
                        EditorMap editorMap,
                        Filter<PropertyEditor>... propertyFilters)

PropertyReasoner

public PropertyReasoner(java.lang.String property,
                        EditorMap editorMap)

Constructor, which additionally sets a BioPAX property filter for traverse(BioPAXElement, Model) to call visit(Object, BioPAXElement, Model, PropertyEditor) for each *object* property, except for 'nextStep'.

Parameters:

property -

editorMap -

Method Detail

getPropertyName

public java.lang.String getPropertyName()

Returns:

the BioPAX property name

setPropertyName

public void setPropertyName(java.lang.String propertyName)

Parameters:

propertyName - the BioPAX property name to use

setDomains

public void setDomains(java.lang.Class<? extends BioPAXElement>... domains)

When set (not empty list), only instances of the listed types can be updated by run(BioPAXElement, Object) method, although the propertyName property valueStack of every element (where apply) can be still considered for its children (of the specified type).

Parameters:

domains - (optional) the types to modify (others won't be affected)

isOverride

public boolean isOverride()

Returns:

the override

See Also:

setOverride(boolean), run(BioPAXElement, Object)

setOverride

protected void setOverride(boolean override)

Sets the override mode. Following the A,B,C example in the run(BioPAXElement, Object) method: - when override is true, and propertyName is a functional BioPAX property: A, B and C all get the X valueStack TODO ???(if default valueStack was null, otherwise - they get the default valueStack). - when override is false, and propertyName is a functional BioPAX property: A, B - stay unmodified, C acquires Y valueStack (B's). - when override is false, and propertyName is a multiple cardinality property: - B and C will have both X and Y values!

Parameters:

override - the override mode to set (see the above explanation)

See Also:

run(BioPAXElement, Object)

isGenerateComments

public boolean isGenerateComments()

Returns:

the generateComments

setGenerateComments

public void setGenerateComments(boolean generateComments)

Parameters:

generateComments - true/false to generate BioPAX comments on all changes

traverse

public void traverse(BioPAXElement bpe,
                     Model model)

This traverse method, first, takes care about the propertyName we are interested in, then proceeds- as the basic Traverser.traverse(BioPAXElement, Model) would normally do (i.e., - delivering to the method visit(Object, BioPAXElement, Model, PropertyEditor) for all properties without any predefined order).

Overrides:

traverse in class Traverser

Parameters:

bpe - BioPAX element to be traversed

model - to be traversed, but not necessarily (depends on the Visitor implementation).

visit

protected void visit(java.lang.Object range,
                     BioPAXElement bpe,
                     Model model,
                     PropertyEditor editor)

Simply, calls traverse(BioPAXElement, Model) and goes deeper when the propertyName's range/valueStack is a BioPAX object.

Specified by:

visit in class AbstractTraverser

Parameters:

range - is property value

bpe - is parent BioPAX element

editor - is the property editor

run

protected void run(BioPAXElement element,
                   java.lang.Object defaultValue)

Basic, universal method (used by others in this class) - updates the propertyName valueStack of a BioPAX element and its children. The root element (first parameter) does not necessarily have the propertyName though. For example, if X is the propertyName valueStack of A; Y - of B; and C has unknown valueStack; and A has "child" B, which in turn has C (not necessarily immediate); and A, B, C are instances of one of classes listed in domains (if any), then the following results are expected (note: even if, e.g., B would not pass the domains filter, the results for A and C will be the same): - valueStack X will be considered a replacement/addition to Y for B, and both X and Y - for C. The result depends on override, the default valueStack and the propertyName's cardinality. A default valueStack (or a Set or values, object or primitive) is to apply when both current and parent's propertyName values are yet unknown. However, if override is true, the default valueStack, if given, will unconditionally replace all existing. Warning: when defaultValue is null or empty set, and override==true, it will clear the propertyName values of all corresponding elements.

Parameters:

element -

defaultValue - a default valueStack or set of values

See Also:

setDomains(Class...), setOverride(boolean)

clearProperty

public void clearProperty(BioPAXElement element)

For the element and its children, where it's desired (in domains) and possible, it sets the propertyName values to "unknown".

Parameters:

element -

See Also:

run(BioPAXElement, Object)

resetPropertyValue

public void resetPropertyValue(BioPAXElement element,
                               java.lang.Object defaultValue)

For the element and its children, where it's desired (in domains) and allowed (by BioPAX), it forces the given propertyName valueStack replace existing ones.

Parameters:

element -

defaultValue -

See Also:

run(BioPAXElement, Object)

inferPropertyValue

public void inferPropertyValue(BioPAXElement element,
                               java.lang.Object addValue)

For the element and its children, where it's empty, desired (in domains) and allowed, it adds or sets the propertyName from parents's (if the top-most, a parent element that has this propertyName, does not have any valueStack, then given valueStack will be set, and children may inherit it)

Parameters:

element -

addValue -

See Also:

run(BioPAXElement, Object)

inferPropertyValue

public void inferPropertyValue(BioPAXElement element)

For the element and its children, where it's empty, desired (in domains) and allowed, it adds or sets the propertyName from parents's (if they have any valueStack)

Parameters:

element -

See Also:

run(BioPAXElement, Object)