com.ercato.core.xml
Class XOperator

java.lang.Object
  com.ercato.core.xml.XOperator

public class XOperator
extends java.lang.Object

XOperator is a class implementing a simple algebra between XML documents.

Copyright notice: © 2004-2009 Living Pages Research GmbH, Munich, Germany.

URL: living-pages.de

XOperations are normally defined for entire documents. Additionally, operations are offered to be applied to elements where this is convenient, too.

The following relations should all hold true (all expressions must be read left to right!):

1. a + b != a , for a != b (in general)
2. a + b != b + a , for a != b (in general)
3. a + b + b = a + b
4. a + b - b = a
5. a + a = a (in consequence)
6. a == a

Operations "+", "-" and "==0" are implemented accordingly.

The main intention is to consider a and b as two documents playing different roles:

• Document b: A base document, containing generic or shared content.
• Document a: A special document meant to contain specifications with respect to a, eg. data or added content.

The sum a + b of both documents can be considered a more specific version of the more general base, the difference a - b between documents can be regarded the difference set of how a is more specific than b.

A special case is when a and b are completely unrelated: Then a + b and a - b both return a which is in accordance with above equations and a consequence of equation (3).

The following special markup in documents a and b is available to fine-tune how this class works:

Namespaces recognized:

abbreviation:	xml namespace:
erc	http://ercato.com/xmlns/ErcatoCore

Deriving document markup (the left side, "a"):

attribute:	description:
erc:inherit="expand"	The attributes and child elements are all considered additional.
erc:inherit="match"	The attributes and child elements are compared to b. When they can be matched, the content of both will be merged where additional content in b goes first.
erc:inherit="matchtext"	Same as "match", but the value of text nodes is now considered significant in deciding a match.
erc:inherit="override"	Corresponding content in b will be overridden.
erc:inherit="delete"	Corresponding content in b will be deleted. In order to mark a single attribute rather than an entire element for deletion, it may be given a value of 'erc:inherit=delete'.
erc:inherit="none"	Content in a is unrelated to content in b. However, the algorithm may ignore this relationship if it can compute a match.
erc:inherit="auto"	Correspondance is computed automatically. This is the default. A node in a is regarded as matching a node in b if it has compatible position and a does not lack structure of b.
erc:inherit-tag="'name'"	Sometimes, it is necessary to expand a tag by a tag with a different tagname, eg., if a tagname represents sort of typename. This is possible by providing the tagname in b as 'name'. Namespaces must be equal. Note that this rule is ignored if no matching tag with 'name' can be found!

Base document markup (the right side, "b"):

attribute:	description:
erc:inherited-as="scalar"	The element with given tagname exists only once and may be matched by tagname.
erc:inherited-as="option"	The element with given tagname exists at most once and may be matched by tagname.
erc:inherited-as="vector"	The element with given tagname is position-independent and serves as base for any element with same tagname which may therefore be matched by tagname too.
erc:name="'name'"	The element with given tagname and name 'name' exists only once and may be matched by those. Note that the property 'erc:name' (ie., its namespace and its attribute name) is configurable.

Note that "base document markup" is not contained in the difference and "deriving document markup" is not contained in the sum.

A trivial example may clarify the above.

Assume derived document a looks like:

    <account xmlns:erc="http://ercato.com/xmlns/ErcatoCore">
      <erc:id>example</erc:id>
      <balance>4365</balance>
    </account>
  

Assume base document b looks like:

    <account xmlns:erc="http://ercato.com/xmlns/ErcatoCore">
      <erc:id/>
      <balance unit="Euro"/>
    </account>
  

Assume you compute the addition (a + b) with the following setting of: xop.setDefaultInherit (CORRESPONDS);, you should obtain:

    <account xmlns:erc="http://ercato.com/xmlns/ErcatoCore">
      <erc:id>example</erc:id>
      <balance unit="Euro">4365</balance>
    </account>
  

Note that this example defines the erc: namespace too. Enjoy!

Version:

1.3

Author:

Falk Langhammer

Field Summary

static short	AUTOMATIC No possible return value of howRelates.
static short	CORRESPONDS Possible return value of howRelates.
static short	DELETES Possible return value of howRelates.
static short	EQUALS Possible return value of howRelates.
static java.lang.String	ERCNS
static java.lang.String	ERCPP
static short	EXPANDS Possible return value of howRelates.
protected static short	IA_BYNAME
protected static short	IA_COPY
protected static short	IA_IGNORED
protected static short	IA_PLAIN
protected static short	IA_SCALAR
protected static short	IA_TEXT
protected static short	IA_VECTOR
static short	MATCHTEXT No possible return value of howRelates.
protected static short	NULL Impossible internal value for dummy tests.
static short	OVERRIDES Possible return value of howRelates.
static short	UNRELATED Possible return value of howRelates.

Constructor Summary

XOperator()

Method Summary

org.w3c.dom.Document	addition(org.w3c.dom.Document a, org.w3c.dom.Document b) 'may_return_a' defaults to false - a document different to 'a' is always returned.
org.w3c.dom.Document	addition(org.w3c.dom.Document a, org.w3c.dom.Document b, boolean may_return_a) addition computes the sum of two documents a and b.
org.w3c.dom.Element[]	addition(org.w3c.dom.Element a, org.w3c.dom.Element b, org.w3c.dom.Document doc) addition computes the sum of two elements a and b.
protected org.w3c.dom.Element[]	addition0(org.w3c.dom.Element a, org.w3c.dom.Element b, org.w3c.dom.Document dom, short abrel)
protected short	classifyBaseElement(org.w3c.dom.Element b)
protected short	classifyDerivedElement(org.w3c.dom.Element a)
static short	classifyInherit(org.w3c.dom.Element a, short default_read_inherit)
org.w3c.dom.Document	difference(org.w3c.dom.Document a, org.w3c.dom.Document b) 'may_return_a' defaults to false - a document different to 'a' is always returned.
org.w3c.dom.Document	difference(org.w3c.dom.Document a, org.w3c.dom.Document b, boolean may_return_a) difference computes the difference between two documents a and b.
org.w3c.dom.Element	difference(org.w3c.dom.Element a, org.w3c.dom.Element b, org.w3c.dom.Document doc) difference computes the difference between two elements a and b.
protected org.w3c.dom.Element	difference0(org.w3c.dom.Element a, org.w3c.dom.Element b, org.w3c.dom.Document dom, short abrel)
short	getDefaultInheritOnDiff()
short	getDefaultInheritOnRead()
protected static java.lang.String	getMatchingName(org.w3c.dom.Element a)
short	howRelates(org.w3c.dom.Node a, org.w3c.dom.Node b) howRelates computes the relationship between two nodes a and b in two separate documents.
protected short	howRelates0(org.w3c.dom.Element a, org.w3c.dom.Node b)
boolean	isNull(org.w3c.dom.Document a) isNull computes whether a document may be considered zero.
static void	removeElement(org.w3c.dom.Element e) removeElement removes an element in its Document together with surrounding whitespace.
void	setDefaultInherit(short inherit) Sets the default inherit property when no annotation is found at an element.
void	setMatchingName(java.lang.String namespace, java.lang.String attrname) Configures the rule by which xml elements are matched by name.

Methods inherited from class java.lang.Object

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

Field Detail

ERCNS

public static final java.lang.String ERCNS

See Also:

Constant Field Values

ERCPP

public static final java.lang.String ERCPP

See Also:

Constant Field Values

EQUALS

public static final short EQUALS

Possible return value of howRelates. Corresponds to no inherit annotation.

See Also:

Constant Field Values

EXPANDS

public static final short EXPANDS

Possible return value of howRelates. Corresponds to the inherit="expand" annotation.

See Also:

Constant Field Values

OVERRIDES

public static final short OVERRIDES

Possible return value of howRelates. Corresponds to the inherit="override" annotation.

See Also:

Constant Field Values

DELETES

public static final short DELETES

Possible return value of howRelates. Corresponds to the inherit="delete" annotation.

See Also:

Constant Field Values

CORRESPONDS

public static final short CORRESPONDS

Possible return value of howRelates. Corresponds to the inherit="match" annotation.

See Also:

Constant Field Values

MATCHTEXT

public static final short MATCHTEXT

No possible return value of howRelates. Corresponds to the inherit="matchtext" annotation.

See Also:

Constant Field Values

UNRELATED

public static final short UNRELATED

Possible return value of howRelates. Corresponds to the inherit="none" annotation.

See Also:

Constant Field Values

AUTOMATIC

public static final short AUTOMATIC

No possible return value of howRelates. Corresponds to the inherit="auto" annotation.

See Also:

Constant Field Values

NULL

protected static final short NULL

Impossible internal value for dummy tests.

See Also:

Constant Field Values

IA_PLAIN

protected static final short IA_PLAIN

See Also:

Constant Field Values

IA_BYNAME

protected static final short IA_BYNAME

See Also:

Constant Field Values

IA_SCALAR

protected static final short IA_SCALAR

See Also:

Constant Field Values

IA_VECTOR

protected static final short IA_VECTOR

See Also:

Constant Field Values

IA_TEXT

protected static final short IA_TEXT

See Also:

Constant Field Values

IA_COPY

protected static final short IA_COPY

See Also:

Constant Field Values

IA_IGNORED

protected static final short IA_IGNORED

See Also:

Constant Field Values

Constructor Detail

XOperator

public XOperator()

Method Detail

setDefaultInherit

public void setDefaultInherit(short inherit)

Sets the default inherit property when no annotation is found at an element. The intended use is to only call this method with AUTOMATIC (the default) or CORRESPONDS.

getDefaultInheritOnRead

public short getDefaultInheritOnRead()

getDefaultInheritOnDiff

public short getDefaultInheritOnDiff()

setMatchingName

public void setMatchingName(java.lang.String namespace,
                            java.lang.String attrname)

Configures the rule by which xml elements are matched by name.

Parameters:

namespace - the namespace of the attribute name or its enclosing element (defaults to ERCNS, null namespace is allowed).

attrname - the name of the attribute (defaults to "name").

howRelates

public short howRelates(org.w3c.dom.Node a,
                        org.w3c.dom.Node b)

howRelates computes the relationship between two nodes a and b in two separate documents. It is supposed that one document is derived from (aka expands) a base document. Typically, this method is never publicly be called, or only called for Documents.

Parameters:

a - a node in the derived document.

b - a node in the base document.

Returns:

the relationship, which is a static constant as defined in this class.

difference

public org.w3c.dom.Document difference(org.w3c.dom.Document a,
                                       org.w3c.dom.Document b,
                                       boolean may_return_a)

difference computes the difference between two documents a and b. It is supposed that one document is derived from (aka expands) a base document.

Parameters:

a - the derived document.

b - the base document.

may_return_a - boolean whether it is allowed to return 'a' rather than a copy of 'a' where this is an option.

Returns:

the document representing the difference, which is denoted (a - b) elsewhere in this documentation.

difference

public org.w3c.dom.Document difference(org.w3c.dom.Document a,
                                       org.w3c.dom.Document b)

'may_return_a' defaults to false - a document different to 'a' is always returned.

difference

public org.w3c.dom.Element difference(org.w3c.dom.Element a,
                                      org.w3c.dom.Element b,
                                      org.w3c.dom.Document doc)

difference computes the difference between two elements a and b.

Parameters:

a - an element in the derived document.

b - an element in the base document.

doc - document to become the owner document of the difference-element.

Returns:

the element representing the difference (a - b) of elements.

addition

public org.w3c.dom.Document addition(org.w3c.dom.Document a,
                                     org.w3c.dom.Document b,
                                     boolean may_return_a)

addition computes the sum of two documents a and b. This operation is not commutative! It is supposed that one document is derived from (aka expands) a base document.

Parameters:

a - the derived document.

b - the base document.

may_return_a - boolean whether it is allowed to return 'a' rather than a copy of 'a' where this is an option.

Returns:

the document representing the sum or merger of both, which is denoted (a + b) elsewhere in this documentation.

addition

public org.w3c.dom.Document addition(org.w3c.dom.Document a,
                                     org.w3c.dom.Document b)

'may_return_a' defaults to false - a document different to 'a' is always returned.

addition

public org.w3c.dom.Element[] addition(org.w3c.dom.Element a,
                                      org.w3c.dom.Element b,
                                      org.w3c.dom.Document doc)

addition computes the sum of two elements a and b. This operation is not commutative!

Parameters:

a - an element in the derived document.

b - an element in the base document.

doc - document to become the owner document of the addition-elements.

Returns:

the elements representing the sum or merger of both (a + b); this may be an array containing zero, one, or two elements, depending on whether a deletes b, a and b correspond, or do not, resp.

isNull

public boolean isNull(org.w3c.dom.Document a)

isNull computes whether a document may be considered zero. It is supposed that one document is derived from (aka expands) a base document.

Parameters:

a - the difference of both, or any document.

Returns:

true if document a consists of at most one node and at most namesapce and inherit attributes, which is denoted (a == 0) elsewhere in this documentation. Likewise, (a == b) is defined as ((a - b) == 0) and (a != b) as (!(a == b)).

removeElement

public static void removeElement(org.w3c.dom.Element e)

removeElement removes an element in its Document together with surrounding whitespace. This is important when elements are repeatedly added and removed with indenting in place. Indenting may have added whitespace before andafter the element. A parent with a single child becomes empty.

Parameters:

e - The Element to be removed.

classifyInherit

public static short classifyInherit(org.w3c.dom.Element a,
                                    short default_read_inherit)

classifyDerivedElement

protected final short classifyDerivedElement(org.w3c.dom.Element a)

getMatchingName

protected static java.lang.String getMatchingName(org.w3c.dom.Element a)

classifyBaseElement

protected final short classifyBaseElement(org.w3c.dom.Element b)

addition0

protected final org.w3c.dom.Element[] addition0(org.w3c.dom.Element a,
                                                org.w3c.dom.Element b,
                                                org.w3c.dom.Document dom,
                                                short abrel)

difference0

protected final org.w3c.dom.Element difference0(org.w3c.dom.Element a,
                                                org.w3c.dom.Element b,
                                                org.w3c.dom.Document dom,
                                                short abrel)

howRelates0

protected final short howRelates0(org.w3c.dom.Element a,
                                  org.w3c.dom.Node b)