de.danielbechler.diff.node

Class DiffNode

java.lang.Object

de.danielbechler.diff.node.DiffNode

public class DiffNode
extends java.lang.Object

Represents a part of an object. It could be the object itself, one of its properties, an item in a collection or a map entry. A node may have one parent node and any number of children. It also provides methods to read and write the property represented by this node on any object of the same type as the original object. Last but not least, a node knows how the associated property has changed compared to the base object.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DiffNode.State The state of a DiffNode representing the difference between two objects.
static interface	DiffNode.Visitor Visitor to traverse a node graph.

Field Summary

Fields

Modifier and Type	Field and Description
static DiffNode	ROOT

Constructor Summary

Constructors

Constructor and Description
DiffNode(DiffNode parentNode, Accessor accessor)
DiffNode(DiffNode parentNode, Accessor accessor, java.lang.Class<?> valueType)

Method Summary

Modifier and Type	Method and Description
void	addCategories(java.util.Collection<java.lang.String> additionalCategories)
void	addChild(DiffNode node) Adds a child to this node and sets this node as its parent node.
java.lang.Object	canonicalGet(java.lang.Object target)
void	canonicalSet(java.lang.Object target, java.lang.Object value)
void	canonicalUnset(java.lang.Object target)
int	childCount()
boolean	equals(java.lang.Object o)
java.lang.Object	get(java.lang.Object target)
java.util.Set<java.lang.String>	getCategories() Returns an unmodifiable Set of String with the categories of this node.
DiffNode	getChild(ElementSelector elementSelector) Retrieve a child that matches the given path element relative to this node.
DiffNode	getChild(java.util.List<ElementSelector> selectors) Retrieve a child that matches the given path element relative to this node.
DiffNode	getChild(NodePath nodePath) Retrieve a child that matches the given absolute path, starting from the current node.
DiffNode	getChild(java.lang.String propertyName) Retrieve a child with the given property name relative to this node.
DiffNode	getCircleStartNode()
NodePath	getCircleStartPath()
ElementSelector	getElementSelector()
<T extends java.lang.annotation.Annotation> T	getFieldAnnotation(java.lang.Class<T> annotationClass)
java.util.Set<java.lang.annotation.Annotation>	getFieldAnnotations() If this node represents a bean property this method returns all annotations of its field.
DiffNode	getParentNode()
NodePath	getPath()
<T extends java.lang.annotation.Annotation> T	getPropertyAnnotation(java.lang.Class<T> annotationClass)
java.util.Set<java.lang.annotation.Annotation>	getPropertyAnnotations() If this node represents a bean property this method returns all annotations of its getter.
java.lang.String	getPropertyName() If this node represents a bean property, this method will simply return its name.
DiffNode.State	getState()
java.lang.Class<?>	getValueType()
TypeInfo	getValueTypeInfo()
boolean	hasChanges()
boolean	hasChildren()
int	hashCode()
boolean	isAdded() Convenience method for getState() == DiffNode.State.ADDED
boolean	isChanged() Convenience method for getState() == DiffNode.State.CHANGED
boolean	isCircular() Convenience method for getState() == DiffNode.State.CIRCULAR
boolean	isExcluded() Deprecated. This method was a shortcut to extract the "exclude" flag from the ObjectDiffProperty annotation. Since we found a better way to do that, it is not needed anymore and will be removed in future versions. The name is also misleading. It implies that here lies the truth about the exclusion, but only the InclusionService can tell for sure. This flag is just only little piece of the puzzle.
boolean	isIgnored() Convenience method for getState() == DiffNode.State.IGNORED
boolean	isPropertyAware() Returns true when this node represents a bean property and can therefore be queried for property specific information like annotations or property types.
boolean	isRemoved() Convenience method for getState() == DiffNode.State.REMOVED
boolean	isRootNode()
boolean	isUntouched() Convenience method for getState() == DiffNode.State.UNTOUCHED
boolean	matches(NodePath path)
static DiffNode	newRootNode()
static DiffNode	newRootNodeWithType(java.lang.Class<?> valueType)
void	set(java.lang.Object target, java.lang.Object value)
void	setChildIdentityStrategy(IdentityStrategy identityStrategy)
void	setCircleStartNode(DiffNode circleStartNode)
void	setCircleStartPath(NodePath circularStartPath)
protected void	setParentNode(DiffNode parentNode) Sets the parent node.
void	setState(DiffNode.State state)
void	setType(java.lang.Class<?> aClass) Allows to explicity set the type of this node.
void	setValueTypeInfo(TypeInfo typeInfo)
java.lang.String	toString()
void	unset(java.lang.Object target)
void	visit(DiffNode.Visitor visitor) Visit this and all child nodes.
protected void	visit(DiffNode.Visitor visitor, Visit visit)
void	visitChildren(DiffNode.Visitor visitor) Visit all child nodes but not this one.
void	visitParents(DiffNode.Visitor visitor)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final DiffNode ROOT

Constructor Detail

DiffNode

public DiffNode(DiffNode parentNode,
                Accessor accessor,
                java.lang.Class<?> valueType)

DiffNode

public DiffNode(DiffNode parentNode,
                Accessor accessor)

Method Detail

setChildIdentityStrategy

public void setChildIdentityStrategy(IdentityStrategy identityStrategy)

newRootNode

public static DiffNode newRootNode()

newRootNodeWithType

public static DiffNode newRootNodeWithType(java.lang.Class<?> valueType)

getState

public DiffNode.State getState()

Returns:

The state of this node.

setState

public void setState(DiffNode.State state)

Parameters:

state - The state of this node.

matches

public boolean matches(NodePath path)

hasChanges

public boolean hasChanges()

isAdded

public final boolean isAdded()

Convenience method for getState() == DiffNode.State.ADDED

isChanged

public final boolean isChanged()

Convenience method for getState() == DiffNode.State.CHANGED

isRemoved

public final boolean isRemoved()

Convenience method for getState() == DiffNode.State.REMOVED

isUntouched

public final boolean isUntouched()

Convenience method for getState() == DiffNode.State.UNTOUCHED

isCircular

public boolean isCircular()

Convenience method for getState() == DiffNode.State.CIRCULAR

getPath

public NodePath getPath()

Returns:

The absolute property path from the object root up to this node.

getElementSelector

public ElementSelector getElementSelector()

getValueType

public java.lang.Class<?> getValueType()

Returns:

Returns the type of the property represented by this node, or null if unavailable.

setType

public final void setType(java.lang.Class<?> aClass)

Allows to explicity set the type of this node. This will overshadow the type returned by getValueTypeInfo() as well as the one returned by the accessor.

Parameters:

aClass - The type of the value represented by this node.

getValueTypeInfo

public TypeInfo getValueTypeInfo()

setValueTypeInfo

public void setValueTypeInfo(TypeInfo typeInfo)

hasChildren

public boolean hasChildren()

Returns:

true if this node has children.

childCount

public int childCount()

getChild

public DiffNode getChild(java.lang.String propertyName)

Retrieve a child with the given property name relative to this node.

Parameters:

propertyName - The name of the property represented by the child node.

Returns:

The requested child node or null.

getChild

public DiffNode getChild(ElementSelector elementSelector)

Retrieve a child that matches the given path element relative to this node.

Parameters:

elementSelector - The path element of the child node to get.

Returns:

The requested child node or null.

getChild

public DiffNode getChild(NodePath nodePath)

Retrieve a child that matches the given absolute path, starting from the current node.

Parameters:

nodePath - The path from the object root to the requested child node.

Returns:

The requested child node or null.

getChild

public DiffNode getChild(java.util.List<ElementSelector> selectors)

Retrieve a child that matches the given path element relative to this node.

Parameters:

selectors - The path element of the child node to get.

Returns:

The requested child node or null.

addChild

public void addChild(DiffNode node)

Adds a child to this node and sets this node as its parent node.

Parameters:

node - The node to add.

visit

public final void visit(DiffNode.Visitor visitor)

Visit this and all child nodes.

Parameters:

visitor - The visitor to use.

visit

protected final void visit(DiffNode.Visitor visitor,
                           Visit visit)

visitChildren

public final void visitChildren(DiffNode.Visitor visitor)

Visit all child nodes but not this one.

Parameters:

visitor - The visitor to use.

visitParents

public final void visitParents(DiffNode.Visitor visitor)

getFieldAnnotations

public java.util.Set<java.lang.annotation.Annotation> getFieldAnnotations()

If this node represents a bean property this method returns all annotations of its field.

Only works for fields having a name that matches the name derived from the getter.

Returns:

The annotations of the field, or an empty set if there is no field with the name derived from the getter.

getFieldAnnotation

public <T extends java.lang.annotation.Annotation> T getFieldAnnotation(java.lang.Class<T> annotationClass)

Type Parameters:

T -

Parameters:

annotationClass - the annotation we are looking for

Returns:

The given annotation of the field, or null if not annotated or if there is no field with the name derived from the getter.

getPropertyAnnotations

public java.util.Set<java.lang.annotation.Annotation> getPropertyAnnotations()

If this node represents a bean property this method returns all annotations of its getter.

Returns:

A set of annotations of this nodes property getter or an empty set.

getPropertyAnnotation

public <T extends java.lang.annotation.Annotation> T getPropertyAnnotation(java.lang.Class<T> annotationClass)

getPropertyName

public java.lang.String getPropertyName()

If this node represents a bean property, this method will simply return its name. Otherwise it will return the property name of its closest bean property representing ancestor. This way intermediate nodes like those representing collection, map or array items will be semantically tied to their container objects.

That is especially useful for inclusion and exclusion rules. For example, when a List is explicitly included by property name, it would be weird if the inclusion didn't also apply to its items.

isPropertyAware

public final boolean isPropertyAware()

Returns true when this node represents a bean property and can therefore be queried for property specific information like annotations or property types. But there will also be nodes that represent collection items, map entries, etc. In those cases this method will return false.

isRootNode

public final boolean isRootNode()

isIgnored

public final boolean isIgnored()

Convenience method for getState() == DiffNode.State.IGNORED

isExcluded

@Deprecated
public boolean isExcluded()

Deprecated. This method was a shortcut to extract the "exclude" flag from the ObjectDiffProperty annotation. Since we found a better way to do that, it is not needed anymore and will be removed in future versions. The name is also misleading. It implies that here lies the truth about the exclusion, but only the InclusionService can tell for sure. This flag is just only little piece of the puzzle.

See Also:

TypePropertyAnnotationInclusionResolver

getCategories

public final java.util.Set<java.lang.String> getCategories()

Returns an unmodifiable Set of String with the categories of this node.

Returns:

an unmodifiable Set of String with the categories of this node

getParentNode

public DiffNode getParentNode()

Returns:

The parent node, if any.

setParentNode

protected final void setParentNode(DiffNode parentNode)

Sets the parent node.

Parameters:

parentNode - The parent of this node. May be null, if this is a root node.

get

public java.lang.Object get(java.lang.Object target)

set

public void set(java.lang.Object target,
                java.lang.Object value)

unset

public void unset(java.lang.Object target)

canonicalGet

public java.lang.Object canonicalGet(java.lang.Object target)

canonicalSet

public void canonicalSet(java.lang.Object target,
                         java.lang.Object value)

canonicalUnset

public void canonicalUnset(java.lang.Object target)

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

addCategories

public void addCategories(java.util.Collection<java.lang.String> additionalCategories)

getCircleStartPath

public NodePath getCircleStartPath()

Returns:

Returns the path to the first node in the hierarchy that represents the same object instance as this one. (Only if isCircular() returns true.

setCircleStartPath

public void setCircleStartPath(NodePath circularStartPath)

getCircleStartNode

public DiffNode getCircleStartNode()

setCircleStartNode

public void setCircleStartNode(DiffNode circleStartNode)