org.inria.ns.reflex.xml.operator
Class XMaster

java.lang.Object
  org.inria.ns.reflex.xml.operator.XMaster

public class XMaster
extends Object

The entry point for processing any XML and X-operable object.

Each method is a switch to the relevant XOperator method according to the object type. Never use directly XOperator methods, use the static methods of this class ; null is also supported in each method.

Any basic operation is supplied with a static method. Use the most suitable operation each time it is possible instead of using a more general mean ; for example, if you have to get the position of a node, use the relevant method, do not use the list of children and look for the item to retrieve the position : the best strategy that depends on the object type will be applied.

Author:

Philippe Poulard

Method Summary

static void	append(Object referent, Object operand) Append a child to an item.
static boolean	booleanValueOf(Object referent) Return the boolean evaluation of a value, given by the XPath boolean() function.
static Map	extractNamespaces(Map attributes) Extract the namespace declarations defined in an attribute map.
static Map	getAttributes(Object referent) Return the attributes of a node.
static List	getChildren(Object referent) Return the list of children of a node.
static Object	getCommentAt(Object referent, int index) Return the child comment at the index specified.
static Object	getElementAt(Object referent, int index) Return the child element at the index specified.
static Object	getElementById(QName elementId, Object referent) Return the element whose ID is given by elementId.
static Iterator	getElementsByName(Object referent, QName nodeName) Return the elements with a specific name.
static int	getFamilyIndex(Object referent) Return the intrinsic position of this item amongs items of the same family ; for an element <f:foo>, the XPath pattern f:*[n] would use this method in order to test its position.
static int	getFamilySize(Object referent)
static XFile	getInScopeBaseFile(Object node, XFile base) Return the base file property of a node, given by the @xml:base attribute of the node or one of its ancestor.
static String	getInScopeLang(Object node) Return the in-scope language property of a node, given by the @xml:lang attribute of the node or one of its ancestor.
static Map	getInScopeNamespaces(Object node) Return the in-scope namespaces of a node, that is to say the namespace declarations set on the node and its ancestor.
static Object	getNamedElementAt(Object referent, int index, QName qname) Return the child element at the index specified.
static Object	getNamedProcessingInstructionAt(Object referent, int index, QName target) Return the child PI at the index specified.
static int	getNameIndex(Object referent) Return the intrinsic position of this item amongs items of the same name ; for an element <foo>, the XPath pattern foo[n] would use this method in order to test its position.
static int	getNameSize(Object referent)
static Map	getNamespaces(Object referent) Return the namespaces defined explicitely by a node.
static int	getNaturalIndex(Object referent) Return the intrinsic position of this item ; for an element <foo>, the XPath pattern node()[n] would use this method in order to test its position.
static int	getNaturalSize(Object referent) Return the intrinsic size of an object.
static Object	getNodeAt(Object referent, int index) Return the child at the index specified.
static XOperator	getNullOperator() Return the null operator.
static Object	getParent(Object referent) Return the parent of a node.
static Object	getProcessingInstructionAt(Object referent, int index) Return the child PI at the index specified.
static QName	getQName(Object referent) Return the QName of a referent if any.
static Object	getRoot(Object referent) Return the root in the hierarchy.
static Object	getTextAt(Object referent, int index) Return the child text at the index specified.
static int	getTypeIndex(Object referent) Return the intrinsic position of this item amongs items of the same type ; for an element <foo>, the XPath pattern *[n] would use this method in order to test its position.
static QName	getTypeName(Object referent) Return the type name of the referent.
static int	getTypeSize(Object referent) Return the intrinsic size of this item amongs items of the same type.
static short	getXMLType(Object referent) Return the XML type of the given referent.
static XOperator	getXOperator(Object referent) Lookup for the XOperator of an object.
static boolean	isAttribute(Object referent) Indicate if the referent is an attribute.
static boolean	isComment(Object referent) Indicate if the referent is a comment.
static boolean	isDocument(Object referent) Indicate if the referent is a document.
static boolean	isElement(Object referent) Indicate if the referent is an element.
static boolean	isFallbackOperator(XOperator op) Indicates whether the given operator is the fallback operator or not.
static boolean	isParentNode(Object referent) Indicate if the referent is a parent node, that is to say if it can have children.
static boolean	isProcessingInstruction(Object referent) Indicate if the referent is a PI.
static boolean	isText(Object referent) Indicate if the referent is a text.
static Number	numberValueOf(Object referent) Return the number evaluation of a value, given by the XPath number() function.
void	register(Class clazz, XOperator operator) Register a class to the master operator.
static void	remove(Object referent, Object parent) Remove an item from its collection.
static void	rename(Object referent, Object parent, QName newName) Rename an item.
static String	stringValueOf(Object referent) Return the string evaluation of a value, given by the XPath string() function.
static Object	valueOf(Object referent)

Methods inherited from class java.lang.Object

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

Method Detail

getNullOperator

public static XOperator getNullOperator()

Return the null operator.

Returns:

The null operator.

register

public void register(Class clazz,
                     XOperator operator)

Register a class to the master operator.

Parameters:

clazz - The class to register.

operator - The operator that can perform XML-oriented operations.

Throws:

IllegalStateException - If there is an operator already registered for the class.

getXOperator

public static XOperator getXOperator(Object referent)

Lookup for the XOperator of an object.

Parameters:

referent - The object, may be null.

Returns:

A non-null XOperator.

isFallbackOperator

public static boolean isFallbackOperator(XOperator op)

Indicates whether the given operator is the fallback operator or not.

Parameters:

op - The XOperator to test.

Returns:

true if it is the fallback operator, false otherwise.

getParent

public static Object getParent(Object referent)

Return the parent of a node.

The XOperator of the referent is involved in this operation if it is not a ChildItem.

Parameters:

referent - The referent, may be null.

Returns:

Its parent, or null.

See Also:

ChildItem

getChildren

public static List getChildren(Object referent)

Return the list of children of a node. Before invoking this method, do check if one of the other static methods is not more suitable.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent, may be null.

Returns:

Its non-null list of children.

getAttributes

public static Map getAttributes(Object referent)

Return the attributes of a node.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent, may be null.

Returns:

Its non-null map of attributes as {QName, Map.Entry}.

getElementById

public static Object getElementById(QName elementId,
                                    Object referent)

Return the element whose ID is given by elementId.

The XOperator of the referent is involved in this operation.

Parameters:

referent - A node that belongs to a document to look inside.

elementId - The unique ID for an element.

Returns:

The element or null.

getElementsByName

public static Iterator getElementsByName(Object referent,
                                         QName nodeName)

Return the elements with a specific name.

The XOperator of the referent is involved in this operation.

Parameters:

referent - A node that belongs to a document to look inside.

elementId - The unique ID for an element.

Returns:

The element or null.

getElementAt

public static Object getElementAt(Object referent,
                                  int index)

Return the child element at the index specified. Other kind of nodes are ignored and not counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

Returns:

The element or null.

getNodeAt

public static Object getNodeAt(Object referent,
                               int index)

Return the child at the index specified.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

Returns:

The item or null.

getTextAt

public static Object getTextAt(Object referent,
                               int index)

Return the child text at the index specified. Other kind of nodes are ignored and not counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

Returns:

The text or null.

getCommentAt

public static Object getCommentAt(Object referent,
                                  int index)

Return the child comment at the index specified. Other kind of nodes are ignored and not counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

Returns:

The comment or null.

getProcessingInstructionAt

public static Object getProcessingInstructionAt(Object referent,
                                                int index)

Return the child PI at the index specified. Other kind of nodes are ignored and not counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

Returns:

The PI or null.

getNamedElementAt

public static Object getNamedElementAt(Object referent,
                                       int index,
                                       QName qname)

Return the child element at the index specified. Only the elements that has the given name are counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

The - name of the element.

Returns:

The element or null.

getNamedProcessingInstructionAt

public static Object getNamedProcessingInstructionAt(Object referent,
                                                     int index,
                                                     QName target)

Return the child PI at the index specified. Only the PIs that has the given target are counted.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The parent referent.

index - The index.

target - The PI targetn as an NCName.

Returns:

The PI or null.

getQName

public static QName getQName(Object referent)

Return the QName of a referent if any.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

Its non-null QName.

See Also:

QName.QNULL

isDocument

public static boolean isDocument(Object referent)

Indicate if the referent is a document.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is a document, false otherwise.

isElement

public static boolean isElement(Object referent)

Indicate if the referent is an element.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is an element, false otherwise.

isAttribute

public static boolean isAttribute(Object referent)

Indicate if the referent is an attribute.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is an attribute, false otherwise.

isText

public static boolean isText(Object referent)

Indicate if the referent is a text.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is a text, false otherwise.

isComment

public static boolean isComment(Object referent)

Indicate if the referent is a comment.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is a comment, false otherwise.

isProcessingInstruction

public static boolean isProcessingInstruction(Object referent)

Indicate if the referent is a PI.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is a PI, false otherwise.

isParentNode

public static boolean isParentNode(Object referent)

Indicate if the referent is a parent node, that is to say if it can have children.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

true if it is a parent node, false otherwise.

getXMLType

public static short getXMLType(Object referent)

Return the XML type of the given referent.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The referent.

Returns:

See Also:

XType

getTypeName

public static QName getTypeName(Object referent)

Return the type name of the referent.

Parameters:

referent - The referent.

Returns:

The non-null type name. It can be a QName built with the class name of the referent as NCName.

getNamespaces

public static Map getNamespaces(Object referent)

Return the namespaces defined explicitely by a node.

Changes made on the map are not reflected on the referent object. Act on the attribute map instead.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The node.

Returns:

A non-null map of { QName, Map.Entry }. The string value of the attribute is the namespace URI of the namespace node.

See Also:

QName, getInScopeNamespaces(Object), getAttributes(Object)

extractNamespaces

public static Map extractNamespaces(Map attributes)

Extract the namespace declarations defined in an attribute map.

Each attribute that is a namespace declaration will be in the output result in the same form. That is to say the QName keeps the form of the original attribute : xmlns:prefix or xmlns.

Parameters:

referent - The referent object.

Returns:

A non-null map of {QName, ChildItem}.

See Also:

XMLNames.XMLNS_NAMESPACE_URI, QName, ChildItem, getInScopeNamespaces(Object), getNamespaces(Object)

stringValueOf

public static String stringValueOf(Object referent)

Return the string evaluation of a value, given by the XPath string() function. Objects other than those usually processed by the XPath string() function are converted with their own toString() method.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The object to convert to string.

Returns:

The non-null string value of the object.

numberValueOf

public static Number numberValueOf(Object referent)

Return the number evaluation of a value, given by the XPath number() function. Objects other than those usually processed by the XPath number() function are converted with their own toString() method then with the number() function to the result string.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The object to convert to number.

Returns:

The non-null number value of the object, can be NaN.

booleanValueOf

public static boolean booleanValueOf(Object referent)

Return the boolean evaluation of a value, given by the XPath boolean() function. Objects other than those usually processed by the XPath boolean() function are converted with their own toString() method then with the boolean() function to the result string.

The XOperator of the referent is involved in this operation.

Parameters:

referent - The object to convert to boolean.

Returns:

The boolean value of the object.

valueOf

public static Object valueOf(Object referent)

getRoot

public static Object getRoot(Object referent)

Return the root in the hierarchy.

The XOperator of the referent is involved in this operation.

Parameters:

referent - Where to start.

Returns:

The root of the hierarchy, or the referent if it doesn't have a parent or it is unreachable.

remove

public static void remove(Object referent,
                          Object parent)

Remove an item from its collection.

The XOperator of the referent is involved in this operation if it is not a Removable.

Parameters:

referent - The item to remove.

parent - Its parent.

See Also:

Removable

rename

public static void rename(Object referent,
                          Object parent,
                          QName newName)

Rename an item.

The XOperator of the referent is involved in this operation if it is not a Renamable.

Parameters:

referent - The item to rename.

parent - Its parent.

newName - Its new name.

See Also:

Renamable

append

public static void append(Object referent,
                          Object operand)

Append a child to an item.

The XOperator of the referent is involved in this operation if it is not an Appendable.

Parameters:

referent - The item to which the child will be append.

operand - The child to append.

See Also:

Appendable

getInScopeLang

public static String getInScopeLang(Object node)

Return the in-scope language property of a node, given by the @xml:lang attribute of the node or one of its ancestor.

Parameters:

node - The node that might contain the @xml:lang attribute ; may be null.

Returns:

The language in scope, or null if not specified.

getInScopeNamespaces

public static Map getInScopeNamespaces(Object node)

Return the in-scope namespaces of a node, that is to say the namespace declarations set on the node and its ancestor.

If the node is an element, there is always at least one entry in this map : xmlns:xml="http://www.w3.org/XML/1998/namespace"

xmlns="" is not present in the result, since it is a declaration used for undeclaring the default namespace.

Parameters:

node - The node.

Returns:

A set of { QName, Map.Entry }.

See Also:

QName, getNamespaces(Object)

getInScopeBaseFile

public static XFile getInScopeBaseFile(Object node,
                                       XFile base)
                                throws FileSystemException

Return the base file property of a node, given by the @xml:base attribute of the node or one of its ancestor.

Parameters:

node - The node that might contain the @xml:base attribute ; may be null.

base - The base to use for absolutizing a relative reference.

Returns:

The base file in scope, or null if not specified.

Throws:

FileSystemException

getNaturalIndex

public static int getNaturalIndex(Object referent)

Return the intrinsic position of this item ; for an element <foo>, the XPath pattern node()[n] would use this method in order to test its position.

Parameters:

referent - The referent object.

Returns:

The intrinsic position of this item.

See Also:

getNaturalSize(Object), getTypeIndex(Object), getFamilyIndex(Object), getNameIndex(Object)

getNaturalSize

public static int getNaturalSize(Object referent)

Return the intrinsic size of an object.

Parameters:

referent - The referent object.

Returns:

Its natural size.

See Also:

getNaturalIndex(Object), getTypeSize(Object), getFamilySize(Object), getNameSize(Object)

getTypeIndex

public static int getTypeIndex(Object referent)

Return the intrinsic position of this item amongs items of the same type ; for an element <foo>, the XPath pattern *[n] would use this method in order to test its position.

Parameters:

referent - The referent object.

Returns:

The intrinsic position of this item.

getTypeSize

public static int getTypeSize(Object referent)

Return the intrinsic size of this item amongs items of the same type.

Parameters:

referent - The referent object.

Returns:

Its type size.

getFamilyIndex

public static int getFamilyIndex(Object referent)

Return the intrinsic position of this item amongs items of the same family ; for an element <f:foo>, the XPath pattern f:*[n] would use this method in order to test its position.

Parameters:

referent - The referent object.

Returns:

The intrinsic position of this item.

getFamilySize

public static int getFamilySize(Object referent)

Parameters:

referent - The referent object.

Returns:

getNameIndex

public static int getNameIndex(Object referent)

Return the intrinsic position of this item amongs items of the same name ; for an element <foo>, the XPath pattern foo[n] would use this method in order to test its position.

Parameters:

referent - The referent object.

Returns:

The intrinsic position of this item.

getNameSize

public static int getNameSize(Object referent)

Parameters:

referent - The referent object.

Returns: