org.eclipse.webdav.dom
Class ElementEditor

java.lang.Object
  extended by org.eclipse.webdav.dom.ElementEditor
Direct Known Subclasses:
ActiveLock, BaselineControl, Conflict, ConflictReportResponse, HrefSet, Label, LockEntry, LockInfo, Mkworkspace, MultiStatus, Owner, Prop, Property, PropertyBehavior, PropertyUpdate, PropertyUpdate.Directive, PropFind, PropStat, ResponseBody, Update

public abstract class ElementEditor
extends Object

Abstract superclass of all element editors. An element editor is a convenience for manipulating DOM elements. Specific subclasses declared in this package correspond to the major DOM element types for the WebDAV protocol; e.g., the class ResponseBody corresponds to <DAV:response>.

Element editors contain no state of their own; all they they hang onto is a single DOM Element; all information is stored in the DOM itself. Thus element editors are really just lightweight, throw-away wrappers.

Element editors assume that they are working with elements that are "up to spec". When an element editor encounters an element that is not how it should be, it throws a MalformedElementException (a checked exception). The editor does not provide any further diagnosis of what's wrong. Clients catching this exception will generally conclude that they're talking to a non-compliant (or malfunctioning) WebDAV server.

Fully-capable element editors can be written using the DOM API. No access is required to any concrete implementation of the DOM. The element editors in this package all have this property.

This class also provides rudimentary XML namespace support and element navigation and manipulation methods that are useful when writing element editors.

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.


Field Summary
protected static String DAV_NS
           
protected  Element root
           
protected static String XML_NS_NAME
           
protected static String XML_NS_PREFIX
           
protected static String XML_PREFIX
           
 
Constructor Summary
protected ElementEditor(Element root)
          Constructs a new element editor for the given element.
protected ElementEditor(Element root, String expectedType)
          Constructs a new element editor for the given element.
 
Method Summary
static void addChild(Element parent, Element child, String[] names, boolean firstToLast)
          Adds the given child element as a child of the given parent.
static Element addChild(Element parent, String name, String[] names, boolean firstToLast)
          Creates a WebDAV element with the given name and adds it as a child of the given parent.
static Element addChild(Element parent, String name, String data, String[] names, boolean firstToLast)
          Creates a WebDAV element with the given name and adds it as a child of the given parent.
static Element appendChild(Element parent, String name)
          Creates a WebDAV element with the given name and appends it as a child of the given parent.
static Element appendChild(Element parent, String name, String data)
          Creates a WebDAV element with the given name and appends it as a child of the given parent.
static Node cloneNode(Document document, Node node)
          Returns a clone of the given node.
static Element create(Document document, String name)
          Creates a WebDAV element with the given name and adds it as the root of the given document.
static void declareNS(Element element, String prefix, String namespaceUrl)
          Adds a namespace declaration to the given element.
static String decodeHref(String href)
          Decodes the given href from a form that is safe for transport.
static String encodeHref(String href)
          Encodes the given href to a form that is safe for transport.
protected static void ensure(boolean value, String message)
          Ensures that the given value is true.
protected static void ensure(String message, boolean value)
          Deprecated.  
protected static void ensureDAVElement(Node node, String name, String message)
          Ensures that the given node is a WebDAV element with the given name.
protected static Element ensureDAVElement(String message, Node node, String name)
          Deprecated.  
protected static void ensureNotNull(String message, Object object)
          Ensures that the given object is not null.
protected static void ensureNull(String message, Object object)
          Ensures that the given object is null.
protected static Text ensureText(String message, Node node)
          Ensures that the given node is a text node, returning it as a Text node if it is.
static Element extractElement(Document document, Element element)
          Clones the given element, and its subtrees, and sets it as the root of the given document.
static Node extractNode(Node parent, Node node)
          Clones the given node, and its subtrees, and sets it as the root of the given parent node.
static Element getChild(Element parent, String name, String[] names, boolean firstToLast)
          Returns the child WebDAV element of the given parent that is nearest in position to a WebDAV element with the given name, or null if no such child exists.
static Element getChildElement(Element parent, boolean firstToLast)
          Returns the first child element of the given parent element, or null if no such child exists.
static String getChildText(Element parent, String name, boolean firstToLast)
          Returns the data of the first child text node of the first WebDAV child with the given name of the given parent, or the empty String if no such child text node exists, or null if no such child exists.
static Element getDAVChild(Element parent)
          Returns the first WebDAV child of the given parent, or null if no such child exists.
 Element getElement()
          Returns the root element upon which this editor is based.
static Element getFirstChild(Element parent, String name)
          Returns the first child of the given parent that is a WebDAV element with the given name, or null if no such child exists.
static Element getFirstChild(Element parent, String[] names)
          Returns the first child of the given parent that is a WebDAV element with one of the given names, or null if no such child exists.
static String getFirstText(Element parent)
          Returns the data of the given parent's first text node, or the empty String if no such text node exists.
static Element getLastChild(Element parent, String name)
          Returns the last child of the given parent that is a WebDAV element with the given name, or null if no such child exists.
static Namespaces getNamespaces(Element element)
          Returns the given element's namespace declarations.
protected static Namespaces getNamespaces(Element element, Namespaces namespaces, boolean removeDuplicateNSDeclarations)
          Returns the given element's namespace declarations.
static Element getNextSibling(Element element)
          Returns the next sibling element of the given element, or null if no such sibling exists.
static Element getNextSibling(Element element, String name)
          Returns the next WebDAV sibling of the given element that has the given name, or null if no such sibling exists.
static Element getNextSibling(Element element, String[] names)
          Returns the first WebDAV sibling of the given element that has one of the given names, or null if no such sibling exists.
static String getNSLocalName(Element element)
          Returns the local part of the name of the given element, or null if its name has no local part.
static String getNSLocalName(String name)
          Returns the local part of the given name, or null if its name has no local part.
static String getNSName(Element element)
          Returns the URL of the given element's namespace, or null if it has no namespace.
static String getNSPrefix(Element element)
          Returns the namespace prefix part of the name of the given element, or null if its name has no prefix.
static String getNSPrefix(String name)
          Returns the namespace prefix part of the given name, or null if its name has no prefix.
static QualifiedName getQualifiedName(Element element)
          Returns a qualified name that is formed from the given element's namespace name and namespace local name.
static Element getSibling(Element element, String name, boolean firstToLast)
          Deprecated.  
static String getText(Element parent, boolean firstToLast)
          Deprecated.  
static Element getTwin(Element element, boolean firstToLast)
          Returns the first WebDAV sibling of the given element that has the same name as the element, or null if no such sibling exists.
static boolean hasChild(Element parent, QualifiedName childName)
           
static Element insertBefore(Element sibling, String name)
          Creates a WebDAV element with the given name and inserts it before the given sibling.
static Element insertBefore(Element sibling, String name, String data)
          Creates a WebDAV element with the given name and inserts it before the given sibling.
static boolean isDAVElement(Node node)
          Returns a boolean indicating whether or not the given node is a WebDAV element.
static boolean isDAVElement(Node node, String name)
          Returns a boolean indicating whether or not the given node is a WebDAV element with the given name.
static boolean isElement(Node node)
          Returns a boolean indicating whether or not the given node is an element.
static boolean isText(Node node)
          Returns a boolean indicating whether or not the given node is a text node.
static void makeNSStandalone(Element element)
           
static Element reduceNS(Element element)
          Removes redundant namespace declarations from this element and all its children to maximum depth.
static Node reduceNS(Node node, Namespaces parentNamespaces)
          Removes redundant namespace declarations from the given node and all its children to maximum depth.
static String resolve(String prefix, Element element)
          Resolves the given namespace prefix in the namespace of the given element.
static void setChild(Element parent, Element child, String[] names, boolean firstToLast)
          Sets the given child element as a child of the given parent.
static Element setChild(Element parent, String name, String[] names, boolean firstToLast)
          Creates a WebDAV element with the given name and sets it as a child of the given parent.
static Element setChild(Element parent, String name, String data, String[] names, boolean firstToLast)
          Creates a WebDAV element with the given name and sets it as a child of the given parent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

root

protected Element root

DAV_NS

protected static final String DAV_NS
See Also:
Constant Field Values

XML_PREFIX

protected static final String XML_PREFIX
See Also:
Constant Field Values

XML_NS_PREFIX

protected static final String XML_NS_PREFIX
See Also:
Constant Field Values

XML_NS_NAME

protected static final String XML_NS_NAME
See Also:
Constant Field Values
Constructor Detail

ElementEditor

protected ElementEditor(Element root)
                 throws MalformedElementException
Constructs a new element editor for the given element. The element must not be null.

Parameters:
root - the element to be edited
Throws:
MalformedElementException - if the element is not null

ElementEditor

protected ElementEditor(Element root,
                        String expectedType)
                 throws MalformedElementException
Constructs a new element editor for the given element. The element must not be null.

Parameters:
root - the element to be edited
Throws:
MalformedElementException - if the element is not null
Method Detail

addChild

public static Element addChild(Element parent,
                               String name,
                               String[] names,
                               boolean firstToLast)

Creates a WebDAV element with the given name and adds it as a child of the given parent. Returns the child element.

Children are positioned in the order specified by the given names. If children with the same name as the child already exist, the child is inserted after the rightmost child. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child's name must not be null. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
name - the name of the child which is created and added to the parent
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children
Returns:
the child element that is created

addChild

public static Element addChild(Element parent,
                               String name,
                               String data,
                               String[] names,
                               boolean firstToLast)

Creates a WebDAV element with the given name and adds it as a child of the given parent. In addition, a text node created from the given data is created and appended to the child. Returns the child element.

Children are positioned in the order specified by the given names. If children with the same name as the child already exist, the child is inserted after the rightmost child. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child's name and data must not be null. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
name - the name of the child which is created and added to the parent
data - the data of the text node which is created and added to the child
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children
Returns:
the child element that is created

addChild

public static void addChild(Element parent,
                            Element child,
                            String[] names,
                            boolean firstToLast)
Adds the given child element as a child of the given parent.

Children are positioned in the order specified by the given names. If children with the same name as the child already exist, the child is inserted after the rightmost child. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child must not be null and its namespace prefix must resolve to the WebDAV namespace URL in the parent. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
child - the child which is added to the parent
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children

appendChild

public static Element appendChild(Element parent,
                                  String name)
Creates a WebDAV element with the given name and appends it as a child of the given parent. Returns the child element. The parent must not be null and must be a WebDAV element. The name of the child must not be null.

Parameters:
parent - the parent element to which the child is added
name - the name of the child element that is created and added as a child of the parent
Returns:
the child element that is created

appendChild

public static Element appendChild(Element parent,
                                  String name,
                                  String data)
Creates a WebDAV element with the given name and appends it as a child of the given parent. In addition, a text node created from the given data is created and appended to the child. Returns the child element. The parent must not be null and must be a WebDAV element. The name of the child must not be null. The data must not be null.

Parameters:
parent - the parent element to which the child is added
name - the name of the child element that is created and added as a child of the parent
data - the data of the text node which is created and added to the child
Returns:
the child element that is created

cloneNode

public static Node cloneNode(Document document,
                             Node node)
Returns a clone of the given node. The given document becomes the owner document of the clone.

Parameters:
document - the owner document of the clone
node - the node to clone
Returns:
a clone of the given node

create

public static Element create(Document document,
                             String name)
Creates a WebDAV element with the given name and adds it as the root of the given document. In addition, the WebDAV namespace is declared on the new element. Returns the new element. The document must not be null and must not already have a root element. The name of the element to be created must not be null.

Parameters:
document - the document in which the new element is rooted
name - the name of the element to be created
Returns:
the rooted element

declareNS

public static void declareNS(Element element,
                             String prefix,
                             String namespaceUrl)
Adds a namespace declaration to the given element. If only the prefix is null, a default namespace is declared. If the prefix and the namespaceUrl are null the default namespace is removed. The element must not be null. If the namespaceUrl is null, the prefix must also be null.

Parameters:
element - the element to receive the namespace attribute
prefix - the prefix to be used (without a colon); for example, "D", or null
namespaceUrl - the URL of the namespace; for example, "DAV:", or null

decodeHref

public static String decodeHref(String href)
Decodes the given href from a form that is safe for transport.

Parameters:
href - the href to be decoded

encodeHref

public static String encodeHref(String href)
Encodes the given href to a form that is safe for transport.

Parameters:
href - the href to be encoded

ensure

protected static void ensure(String message,
                             boolean value)
                      throws MalformedElementException
Deprecated. 

Ensures that the given value is true.

Parameters:
message - the message for the exception that is thrown if the given value is false
value - a boolean indicating whether or not a malformed element exception should be thrown
Throws:
MalformedElementException - with the given message if the given value is false

ensure

protected static void ensure(boolean value,
                             String message)
                      throws MalformedElementException
Ensures that the given value is true.

Parameters:
message - the message for the exception that is thrown if the given value is false
value - a boolean indicating whether or not a malformed element exception should be thrown
Throws:
MalformedElementException - with the given message if the given value is false

ensureDAVElement

protected static Element ensureDAVElement(String message,
                                          Node node,
                                          String name)
                                   throws MalformedElementException
Deprecated. 

Ensures that the given node is a WebDAV element with the given name, returning it as an Element if it is.

Parameters:
message - the message for the exception that is thrown if the node is not a WebDAV element with the given name
node - the node, or null
name - the expected local name of the WebDAV element
Throws:
MalformedElementException - with the given message if it is not a WebDAV element with the given name

ensureDAVElement

protected static void ensureDAVElement(Node node,
                                       String name,
                                       String message)
                                throws MalformedElementException
Ensures that the given node is a WebDAV element with the given name.

Parameters:
node - the node, or null
name - the expected local name of the WebDAV element
message - the message for the exception that is thrown if the node is not a WebDAV element with the given name
Throws:
MalformedElementException - with the given message if it is not a WebDAV element with the given name

ensureNotNull

protected static void ensureNotNull(String message,
                                    Object object)
                             throws MalformedElementException
Ensures that the given object is not null.

Parameters:
message - the message for the exception that is thrown if the object is null
object - the object, or null
Throws:
MalformedElementException - if the given object is null

ensureNull

protected static void ensureNull(String message,
                                 Object object)
                          throws MalformedElementException
Ensures that the given object is null.

Parameters:
message - the message for the exception that is thrown if the object is not null
object - the object, or null
Throws:
MalformedElementException - if the given object is not null

ensureText

protected static Text ensureText(String message,
                                 Node node)
                          throws MalformedElementException
Ensures that the given node is a text node, returning it as a Text node if it is.

Parameters:
message - the message for the exception that is thrown if the node is not a Text node
node - the node, or null
Throws:
MalformedElementException - if the node is null or not a text node

extractElement

public static Element extractElement(Document document,
                                     Element element)
                              throws MalformedElementException
Clones the given element, and its subtrees, and sets it as the root of the given document. Returns the cloned element. The document must not have a root and must not be null. The element must not be null.

Parameters:
document - the document that will become the owner and parent of the cloned element
element - the element to be cloned
Throws:
MalformedElementException - if an element exists in the subtree to be cloned whose namespace can't be resolved

extractNode

public static Node extractNode(Node parent,
                               Node node)
                        throws MalformedElementException
Clones the given node, and its subtrees, and sets it as the root of the given parent node. Returns the cloned node. The parent node and the node to be cloned must not be null.

Parameters:
parent - the node that will become the parent of the cloned node
node - the node to be cloned
Throws:
MalformedElementException - if an element exists in the subtree to be cloned whose namespace can't be resolved

getChild

public static Element getChild(Element parent,
                               String name,
                               String[] names,
                               boolean firstToLast)

Returns the child WebDAV element of the given parent that is nearest in position to a WebDAV element with the given name, or null if no such child exists.

Children are expected to be in the order specified by the given names. If firstToLast is true, the search for the child starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The name of the child to search for must not be null. The parent's valid child names must not be null, and must contain the name of the child being searched for.

The returned child is as follows:

Parameters:
parent - the parent of the child being searched for
name - the name of the child being searched for
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the specified child among the parent's children
Returns:
a child of the parent, or null

getChildElement

public static Element getChildElement(Element parent,
                                      boolean firstToLast)
Returns the first child element of the given parent element, or null if no such child exists. If firstToLast is true, the search for the child starts at the parent's first child, otherwise, the search starts at the parent's last child. The parent must not be null.

Parameters:
parent - the parent of the child element to search for
firstToLast - a boolean specifying the direction to search for the child element among the parent's children
Returns:
the child element, or null if no such child exists

getChildText

public static String getChildText(Element parent,
                                  String name,
                                  boolean firstToLast)
Returns the data of the first child text node of the first WebDAV child with the given name of the given parent, or the empty String if no such child text node exists, or null if no such child exists. If firstToLast is true, the search for the child starts at the parent's first child, otherwise, the search starts at the parent's last child. The parent must not be null and must be a WebDAV element. The name of the child must not be null.

Parameters:
parent - the parent of the child with the child text node to search for
name - the name of the child with the child text node to search for
firstToLast - a boolean specifying the direction to search for the specified child among the parent's children
Returns:
the data of the child's child text node, or the empty String if no such child exists, or null if no such child exists

getDAVChild

public static Element getDAVChild(Element parent)
Returns the first WebDAV child of the given parent, or null if no such child exists. The parent must not be null and must be a WebDAV element.

Parameters:
parent - the parent of the child to search for
Returns:
the first WebDAV child of the parent, or null

getElement

public Element getElement()
Returns the root element upon which this editor is based. It cannot be assumed that this element necessarily conforms to the appropriate specification.

Returns:
the root element upon which this editor is based

getFirstChild

public static Element getFirstChild(Element parent,
                                    String[] names)
Returns the first child of the given parent that is a WebDAV element with one of the given names, or null if no such child exists.

The search for the child starts at the parent's first child. The parent must not be null and must be a WebDAV element. The names of children to search for must not be null.

Parameters:
parent - the parent of the child to search.
names - all possible names of the child to search for.
Returns:
the specified child of the parent, or null if no such child exists.

getFirstChild

public static Element getFirstChild(Element parent,
                                    String name)
Returns the first child of the given parent that is a WebDAV element with the given name, or null if no such child exists.

The search for the child starts at the parent's first child. The parent must not be null and must be a DAV: namespace element. The name of the child to search for must not be null.

Parameters:
parent - the parent of the child to search.
name - the name of the child to search for.
Returns:
the specified child of the parent, or null if no such child exists.

getFirstText

public static String getFirstText(Element parent)
Returns the data of the given parent's first text node, or the empty String if no such text node exists. The search for the text node starts at the parent's first child. The parent must not be null.

Parameters:
parent - the parent of the text node to search for
Returns:
the data of the text node being searched for, or the empty String if no such text node exists

getLastChild

public static Element getLastChild(Element parent,
                                   String name)
Returns the last child of the given parent that is a WebDAV element with the given name, or null if no such child exists.

The search starts at the parent's last child. The parent must not be null and must be a DAV: namespace element. The name of the child to search for must not be null.

Parameters:
parent - the parent of the child to search.
name - the name of the child to search for.
Returns:
the specified child of the parent, or null if no such child exists.

getNamespaces

public static Namespaces getNamespaces(Element element)
Returns the given element's namespace declarations. The element must not be null.

Parameters:
element - the element whose namespace declarations are returned
Returns:
the element's namespace declarations

getNamespaces

protected static Namespaces getNamespaces(Element element,
                                          Namespaces namespaces,
                                          boolean removeDuplicateNSDeclarations)
Returns the given element's namespace declarations. The given namespace declarations should be the element's parent's, or null if the element has no parent. If removeDuplicateNSDeclarations is true, duplicate namespace declarations are removed from the element's attributes. The element must not be null.

Parameters:
element - the element whose namespace declaration is returned
namespaces - the namespace declarations for the element's parent's or null if it has no parent
removeDuplicateNSDeclarations - a boolean indicating whether duplicate namespace declarations should be removed from the element's attributes
Returns:
the given element's namespace declarations

getNextSibling

public static Element getNextSibling(Element element)
Returns the next sibling element of the given element, or null if no such sibling exists. Only the sibling's next children are searched. The element must not be null.

Parameters:
element - the element whose sibling element is being searched for
Returns:
the sibling element, or null

getNextSibling

public static Element getNextSibling(Element element,
                                     String[] names)
Returns the first WebDAV sibling of the given element that has one of the given names, or null if no such sibling exists. Only the sibling's next children (not the previous children) are searched. The element must not be null and must be a WebDAV element. The possible names of the sibling to search for must not be null.

Parameters:
element - the element whose sibling is being searched for
names - the possible names of the sibling being search for
Returns:
the sibling with the specified name, or null

getNextSibling

public static Element getNextSibling(Element element,
                                     String name)
Returns the next WebDAV sibling of the given element that has the given name, or null if no such sibling exists. Only the sibling's next children are searched. The element must not be null and must be a WebDAV element. The name of the sibling to search for must not be null.

Parameters:
element - the element whose sibling is being searched for
name - the name of the sibling being search for
Returns:
the sibling with the given name, or null

getNSLocalName

public static String getNSLocalName(String name)
Returns the local part of the given name, or null if its name has no local part. The name must not be null.
Example
name local name
D:foo foo
foo foo
D: null
:foo foo
: null

Parameters:
name - the name whose local part is returned
Returns:
the name's local part, or null

getNSLocalName

public static String getNSLocalName(Element element)
Returns the local part of the name of the given element, or null if its name has no local part. The element must not be null.
Example
tag name local name
D:foo foo
foo foo
D: null
:foo foo
: null

Parameters:
element - the element whose local name is returned
Returns:
the element's local name, or null

getNSName

public static String getNSName(Element element)
                        throws MalformedElementException
Returns the URL of the given element's namespace, or null if it has no namespace. The element must not be null.

Parameters:
element - the element whose namespace is returned
Returns:
the namespace of the element, or null
Throws:
MalformedElementException - if the name of the given element has a namespace prefix which could not be resolved

getNSPrefix

public static String getNSPrefix(String name)
Returns the namespace prefix part of the given name, or null if its name has no prefix. The name must not be null.
Example
name namespace prefix
D:foo D
foo null
D: D
:foo null
: null

Parameters:
name - the name whose namespace prefix is returned
Returns:
the name's namespace prefix, or null

getNSPrefix

public static String getNSPrefix(Element element)
Returns the namespace prefix part of the name of the given element, or null if its name has no prefix. The element must not be null.
Example
tag name namespace prefix
D:foo D
foo null
D: D
:foo null
: null

Parameters:
element - the element whose namespace prefix is returned
Returns:
the element's namespace prefix, or null

getQualifiedName

public static QualifiedName getQualifiedName(Element element)
                                      throws MalformedElementException
Returns a qualified name that is formed from the given element's namespace name and namespace local name. The qualified name's qualifier is the element's namespace name and the qualified name's local name is the element's local name. The element must not be null.

Parameters:
element - the element whose qualified name is returned
Returns:
the qualified name that is formed from the given element's namespace name and namespace local name
Throws:
MalformedElementException - if the name of the element has a namespace prefix which could not be resolved, or the element does not have a local name

getSibling

public static Element getSibling(Element element,
                                 String name,
                                 boolean firstToLast)
Deprecated. 

Returns the first WebDAV sibling of the given element that has the given name, or null if no such sibling exists. If firstToLast is true, only the sibling's next children are searched, otherwise, only the siblings previous children are searched. The element must not be null and must be a WebDAV element. The name of the sibling to search for must not be null.

Parameters:
element - the element whose sibling is being searched for
name - the name of the sibling being search for
firstToLast - a boolean specifying the direction to search for the sibling among the element's siblings
Returns:
the sibling with the given name, or null

getText

public static String getText(Element parent,
                             boolean firstToLast)
Deprecated. 

Returns the data of the given parent's first text node, or the empty String if no such text node exists. If firstToLast is true, the search for the text node starts at the parent's first child, otherwise, the search starts at the parent's last child. The parent must not be null.

Parameters:
parent - the parent of the text node to search for
firstToLast - a boolean specifying the direction to search for the text node among the parent's children
Returns:
the data of the text node being searched for, or the empty String if no such text node exists

getTwin

public static Element getTwin(Element element,
                              boolean firstToLast)
Returns the first WebDAV sibling of the given element that has the same name as the element, or null if no such sibling exists. If firstToLast is true, only the sibling's next children are searched, otherwise, only the siblings previous children are searched. The element must not be null and must be a WebDAV element.

Parameters:
element - the element whose sibling is being searched for
firstToLast - a boolean specifying the direction to search for the sibling among the element's siblings
Returns:
the sibling with the same name as the given element, or null if no such element exists

hasChild

public static boolean hasChild(Element parent,
                               QualifiedName childName)
                        throws MalformedElementException
Throws:
MalformedElementException

insertBefore

public static Element insertBefore(Element sibling,
                                   String name)
Creates a WebDAV element with the given name and inserts it before the given sibling. Returns the new sibling. The sibling must not be null and must be a WebDAV element. The name of the new sibling must not be null.

Parameters:
sibling - the existing sibling element
name - the name of the new sibling element that is created and inserted before the existing sibling element
Returns:
the new sibling element that is created

insertBefore

public static Element insertBefore(Element sibling,
                                   String name,
                                   String data)
Creates a WebDAV element with the given name and inserts it before the given sibling. In addition, a text node created from the given data and appended to the new sibling. Returns the new sibling. The sibling must not be null and must be a WebDAV element. The name of the new sibling must not be null. The data must not be null.

Parameters:
sibling - the existing sibling element
name - the name of the sibling element that is created and inserted before the existing sibling element
data - the data of the text node which is created and appended to the new sibling
Returns:
the new sibling element that is created

isDAVElement

public static boolean isDAVElement(Node node)
Returns a boolean indicating whether or not the given node is a WebDAV element. The node may be null in which case false is returned.

Parameters:
node - a node, or null
Returns:
a boolean indicating whether or not the given node is a WebDAV element

isDAVElement

public static boolean isDAVElement(Node node,
                                   String name)
Returns a boolean indicating whether or not the given node is a WebDAV element with the given name. The node may be null in which case false is returned. The name must not be null.

Parameters:
node - a node, or null
Returns:
a boolean indicating whether or not the given node is a WebDAV element with the given name

isElement

public static boolean isElement(Node node)
Returns a boolean indicating whether or not the given node is an element. The node may be null in which case false is returned.

Parameters:
node - a node, or null
Returns:
a boolean indicating whether or not the given node is an element

isText

public static boolean isText(Node node)
Returns a boolean indicating whether or not the given node is a text node. The node may be null in which case false is returned.

Parameters:
node - a node, or null
Returns:
a boolean indicating whether or not the given node is a text node

makeNSStandalone

public static void makeNSStandalone(Element element)

reduceNS

public static Element reduceNS(Element element)
                        throws MalformedElementException
Removes redundant namespace declarations from this element and all its children to maximum depth. The element must not be null.

Parameters:
element - the element whose namespace declarations are to be reduced
Returns:
the element, or a new element with an equivalent qualified name but whose tag name has changed
Throws:
MalformedElementException - if the name of the given element, or one of its attributes, has a namespace prefix which could not be resolved

reduceNS

public static Node reduceNS(Node node,
                            Namespaces parentNamespaces)
                     throws MalformedElementException
Removes redundant namespace declarations from the given node and all its children to maximum depth. The node must not be null.

Parameters:
node - the node whose namespace declarations are to be reduced
Returns:
the node, or a new node (element) with an equivalent qualified name but whose tag name has changed
Throws:
MalformedElementException - if the name of the given node (element), or one of its attributes, has a namespace prefix which could not be resolved

resolve

public static String resolve(String prefix,
                             Element element)
Resolves the given namespace prefix in the namespace of the given element. If the given prefix is null, the default namespace is resolved. Returns the URL of the namespace, or null if the prefix could not be resolved.

Parameters:
prefix - the namespace prefix to be resolved, or null for the default namespace
element - the element supplying the namespace
Returns:
the URL of the namespace, or null if the prefix could not be resolved

setChild

public static Element setChild(Element parent,
                               String name,
                               String[] names,
                               boolean firstToLast)

Creates a WebDAV element with the given name and sets it as a child of the given parent. Returns the child element.

Children are positioned in the order specified by the given names. If a child with the same name as the child already exist, the child is replaced. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child's name must not be null. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
name - the name of the child which is created and added to the parent
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children
Returns:
the child element that is created

setChild

public static Element setChild(Element parent,
                               String name,
                               String data,
                               String[] names,
                               boolean firstToLast)

Creates a WebDAV element with the given name and sets it as a child of the given parent. In addition, a text node created from the given data is created and appended to the child. Returns the child element.

Children are positioned in the order specified by the given names. If a child with the same name already exists, it is replaced. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child's name and data must not be null. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
name - the name of the child which is created and added to the parent
data - the data of the text node which is created and added to the child
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children
Returns:
the child element that is created

setChild

public static void setChild(Element parent,
                            Element child,
                            String[] names,
                            boolean firstToLast)

Sets the given child element as a child of the given parent.

Children are positioned in the order specified by the given names. If a child with the same name already exists, it is replaced. If firstToLast is true, the search for the child's position starts at the parent's first child, otherwise, the search starts at the parent's last child.

The parent must not be null and must be a WebDAV element. The child must not be null and its namespace prefix must resolve to the WebDAV namespace URL in the parent. The parent's valid child names must not be null, and must contain the name of the child.

Parameters:
parent - the parent to which the child is added
child - the child which is added to the parent
names - the ordered collection of valid child names for the parent
firstToLast - a boolean specifying the direction to search for the child's position among the parent's children


Copyright © 2001-2014 JBoss by Red Hat. All Rights Reserved.