com.sapportals.wcm.protocol.webdav

Class DomElement

java.lang.Object
  com.sapportals.wcm.protocol.webdav.DomElement

public class DomElement
extends Object

Utility functions for working with Nodes.

Note: most methods are static, some are also available as non-static methods of DomElement (which in this case is only a container for a Document).

Copyright (c) SAP AG 2001-2007

Nested Class Summary

static class	DomElement.DomElementException
static class	DomElement.NotUniqueChildException
static class	DomElement.RequiredChildMissingException
static class	DomElement.UnexpectedChildException

Constructor Summary

DomElement(Document owner)

Method Summary

static void	addDavStatus(Element prop, String status) Adds a DAV:status child element with the given content.
static void	attachPropertyFlag(Element e, String flag, boolean value) Attaches property flag to a property.
static void	attachSoapArrayType(Element e, QualifiedName dt, int size) Attaches SOAP array type information to an element.
static void	attachXmlDataDataType(Element e, String dt) Attaches XML DATA datatype information to an element to support the special requirements of the Microsoft Webfolder client.
static void	attachXsdDataType(Element e, QualifiedName dt) Attaches XML Schema datatype information to an element.
static void	checkChildElementConstraints(Node parent, IName allowed)
static void	checkChildElementConstraints(Node parent, Set allowed)
static List	getChildren(Node parent, IName name) Gets all child element nodes with matching IName.
static List	getChildren(Node parent, String namespaceUri, String name) Get all children with matching namespace and name.
static NodeList	getElements(Element parent, IName name) Get NodeList containing all descendants with a certain element name.
static Node	getFirstChild(Node parent, IName name) Get first child element with given name.
static Node	getFirstChildOrDie(Node parent, IName name, boolean required) Get first child with specified name, throwing an exception when there are multiple.
static List	getHrefList(Node e)
static Set	getHrefs(Node e)
static IInternationalString	getInternationalText(Node e) Gets an IInternationalString from a node.
static String	getProcessingInstruction(Document doc, String target) Get the value of the first instance of a top-level processing instruction by name.
static String	getSingleHref(Node e)
static String	getSingleHref(Node e, boolean required)
static String	getText(Node e) Get the (concatenated) text content of an element (only visits direct children of type Node.TEXT_NODE and Node.CDATA_SECTION_NODE).
static Object	getTypedValue(Element e, DateFormat df) Gets the typed value from text content of an element based on it's xsi:type attribute.
static boolean	hasChild(Node parent, IName name) Determines if node has child with matching IName.
static boolean	hasElementChildrenInDavNs(Element elem) Checks whether there are Element children in the DAV: namespace.
static boolean	hasOnlyTextContent(Node e) Checks whether an element node contains only text content (being nodes of type Node.TEXT_NODE or Node.CDATA_SECTION_NODE}.
static Node	importNode(Document owner, Node imp, boolean deep) Wrapper method for Document.importNode(Node, boolean), providing logging of fatal errors (seen in early Xerces versions).
static void	inheritXmlAttributes(Element elem) Inherit all attributes in the XML namespace, according to Canonical XML
static Element	makeNew(Document doc, IName name) Create a new element node with the given name.
static Element	makeNew(Document doc, IName name, Object content) Create a new element node with the given name and optional content
static Element	makeNew(Document doc, QualifiedName name) Create a new element node with the given qualified name (respecting the namespace prefix).
static Element	makeNew(Document doc, QualifiedName name, Object content) Create a new element node with the given name (respecting the prefix) and optional content
static Element	makeNew(Document doc, String namespace, String name) Create a new element node
static Element	makeNew(Document doc, String namespace, String name, Object content) Create a new element node with optional content
static Element	makeNew(Document doc, String namespace, String prefix, String name, Object content) Create a new element node (with specific prefix) and optional content
Element	makeNew(IName name) Create a new element node
Element	makeNew(IName name, Object content) Create a new element node with optional content
static Comment	makeSafeComment(Document doc, String text)
static String	makeSafeXml(String val) Check the string's content for XML compliance (whether it can be used as value for a text node).
static boolean	match(Node n, IName name) Compare a node's namespace and name
static boolean	match(Node n, Set names)
static boolean	match(Node n, String namespace, String name) Compare a node's namespace and name
static void	setText(Element e, long val) Set the text element content of an element to a stringified long value, removing all previous content.
static void	setText(Element e, String val) Set the text element content of an element, allowing null and removing all previous content.
static void	setUnsafeText(Element e, String val) Set the text element content of an element, allowing null and removing all previous content.

Methods inherited from class java.lang.Object

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

Constructor Detail

DomElement

public DomElement(Document owner)

Method Detail

makeSafeComment

public static Comment makeSafeComment(Document doc,
                                      String text)

makeNew

public Element makeNew(IName name,
                       Object content)

Create a new element node with optional content

Parameters:

name - name for the element

content - optional content (content of type Element is added as a child node, IInternationalStrings are added as Text node while setting the attribute xml:lang, otherwise the string value is added as a Text node)

Returns:

newly created element

makeNew

public Element makeNew(IName name)

Create a new element node

Parameters:

name - name for the element

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              String namespace,
                              String prefix,
                              String name,
                              Object content)

Create a new element node (with specific prefix) and optional content

Parameters:

doc - the owner document

namespace - namespace name

name - element's local name

content - optional content (content of type Element is added as a child node, IInternationalStrings are added as Text node while setting the attribute xml:lang, otherwise the string value is added as a Text node)

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              String namespace,
                              String name)

Create a new element node

Parameters:

doc - the owner document

namespace - namespace name

name - element's local name

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              String namespace,
                              String name,
                              Object content)

Create a new element node with optional content

Parameters:

doc - the owner document

namespace - namespace name

name - element's local name

content - optional content (content of type Element is added as a child node, IInternationalStrings are added as Text node while setting the attribute xml:lang, otherwise the string value is added as a Text node)

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              IName name)

Create a new element node with the given name.

Parameters:

doc - the owner document

name - element's name

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              QualifiedName name)

Create a new element node with the given qualified name (respecting the namespace prefix).

Parameters:

doc - the owner document

name - element's name

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              IName name,
                              Object content)

Create a new element node with the given name and optional content

Parameters:

doc - the owner document

name - element's name

content - optional content (content of type Element is added as a child node, IInternationalStrings are added as Text node while setting the attribute xml:lang, otherwise the string value is added as a Text node)

Returns:

newly created element

makeNew

public static Element makeNew(Document doc,
                              QualifiedName name,
                              Object content)

Create a new element node with the given name (respecting the prefix) and optional content

Parameters:

doc - the owner document

name - element's name

content - optional content (content of type Element is added as a child node, IInternationalStrings are added as Text node while setting the attribute xml:lang, otherwise the string value is added as a Text node)

Returns:

newly created element

match

public static boolean match(Node n,
                            String namespace,
                            String name)

Compare a node's namespace and name

Parameters:

n - node

namespace - namespace name

name - name

Returns:

whether namespace and name match

match

public static boolean match(Node n,
                            IName name)

Compare a node's namespace and name

Parameters:

n - node

name - name

Returns:

whether namespaceUri is DAV: and the name matches

match

public static boolean match(Node n,
                            Set names)

attachXmlDataDataType

public static void attachXmlDataDataType(Element e,
                                         String dt)

Attaches XML DATA datatype information to an element to support the special requirements of the Microsoft Webfolder client.

Parameters:

e - the element to which the datatype should be attached

dt - the datatype

attachPropertyFlag

public static void attachPropertyFlag(Element e,
                                      String flag,
                                      boolean value)

Attaches property flag to a property.

Parameters:

e - the element to which the datatype should be attached

flag - name of flag

value - boolean value of flag

attachXsdDataType

public static void attachXsdDataType(Element e,
                                     QualifiedName dt)

Attaches XML Schema datatype information to an element.

Parameters:

e - the element to which the datatype should be attached

dt - the datatype

attachSoapArrayType

public static void attachSoapArrayType(Element e,
                                       QualifiedName dt,
                                       int size)

Attaches SOAP array type information to an element.

Parameters:

e - the element to wich the datatype should be attached

dt - the datatype

size - size of array

hasElementChildrenInDavNs

public static boolean hasElementChildrenInDavNs(Element elem)

Checks whether there are Element children in the DAV: namespace.

Parameters:

elem - the element to check

Returns:

whether or not elem has a child elem in the DAV: namespace

addDavStatus

public static void addDavStatus(Element prop,
                                String status)

Adds a DAV:status child element with the given content.

Parameters:

prop - Element to which the DAV:status shall be added

status - the HTTP status to set

getTypedValue

public static Object getTypedValue(Element e,
                                   DateFormat df)

Gets the typed value from text content of an element based on it's xsi:type attribute. Supported types are xs:boolean (mapped to Boolean), xs:dateTime (mapped to Date), xs:long (mapped to Long) and xs:int (mapped to Integer). Other types are treated as string values. If the text content can not be parsed according to the data type information, it's treated as string as well.

Parameters:

e - containing element

df - date format parser (for ISO8601 dates)

Returns:

typed value

getText

public static String getText(Node e)

Get the (concatenated) text content of an element (only visits direct children of type Node.TEXT_NODE and Node.CDATA_SECTION_NODE).

Parameters:

e - parent element

Returns:

text content (empty string when no text present)

getHrefs

public static Set getHrefs(Node e)

getHrefList

public static List getHrefList(Node e)

getSingleHref

public static String getSingleHref(Node e,
                                   boolean required)
                            throws DomElement.DomElementException

Throws:

DomElement.DomElementException

getSingleHref

public static String getSingleHref(Node e)
                            throws DomElement.DomElementException

Throws:

DomElement.DomElementException

getInternationalText

public static IInternationalString getInternationalText(Node e)

Gets an IInternationalString from a node. For non-elements, this is just the text content without language identification. For elements, an attempts is made to find an xml:lang attribute in scope to determine the language.

Parameters:

e - containing node

Returns:

text contents and laguage information as IInternationalString

hasOnlyTextContent

public static boolean hasOnlyTextContent(Node e)

Checks whether an element node contains only text content (being nodes of type Node.TEXT_NODE or Node.CDATA_SECTION_NODE}.

Parameters:

e - containing element

Returns:

true if only text content

getElements

public static NodeList getElements(Element parent,
                                   IName name)

Get NodeList containing all descendants with a certain element name.

Parameters:

parent - the parent of the elements to find

name - the name of the elements to find

Returns:

NodeList of matching child elements

getChildren

public static List getChildren(Node parent,
                               String namespaceUri,
                               String name)

Get all children with matching namespace and name.

Returns:

List of matching children (or empty list).

getFirstChildOrDie

public static Node getFirstChildOrDie(Node parent,
                                      IName name,
                                      boolean required)
                               throws DomElement.DomElementException

Get first child with specified name, throwing an exception when there are multiple.

Parameters:

parent - container element

name - name of requested child element

required - when true, an exception is thrown when the child element doesn't exist

Returns:

the child element or null when not present

Throws:

DomElement.NotUniqueChildException - when multiple childs present

DomElement.RequiredChildMissingException - when child not present and required was set to true

DomElement.DomElementException

checkChildElementConstraints

public static void checkChildElementConstraints(Node parent,
                                                IName allowed)
                                         throws DomElement.UnexpectedChildException

Throws:

DomElement.UnexpectedChildException

checkChildElementConstraints

public static void checkChildElementConstraints(Node parent,
                                                Set allowed)
                                         throws DomElement.UnexpectedChildException

Throws:

DomElement.UnexpectedChildException

getFirstChild

public static Node getFirstChild(Node parent,
                                 IName name)

Get first child element with given name.

Parameters:

parent - container element

name - specified name

Returns:

child node or null when not present

getChildren

public static List getChildren(Node parent,
                               IName name)

Gets all child element nodes with matching IName.

Parameters:

parent - parent node from hwere to match

name - element name to match for

Returns:

list of matching child elements (never null).

hasChild

public static boolean hasChild(Node parent,
                               IName name)

Determines if node has child with matching IName.

Parameters:

parent - parent node from hwere to match

name - element name to match for

Returns:

if matching children exist

getProcessingInstruction

public static String getProcessingInstruction(Document doc,
                                              String target)

Get the value of the first instance of a top-level processing instruction by name.

Parameters:

doc - to be checked

target - PI target

Returns:

the value or null

setUnsafeText

public static void setUnsafeText(Element e,
                                 String val)
                          throws DOMException

Set the text element content of an element, allowing null and removing all previous content. Checks for valid character content.

Parameters:

e - the element

val - the text content

Throws:

DOMException - with code DOMException.INVALID_CHARACTER_ERR when invalid content present

makeSafeXml

public static String makeSafeXml(String val)

Check the string's content for XML compliance (whether it can be used as value for a text node). Rejects the string when it includes invalid control characters or invalid surrogate pairs.

Parameters:

val - string value

Returns:

the string itself

Throws:

DOMException - with code DOMException.INVALID_CHARACTER_ERR when invalid content present

setText

public static void setText(Element e,
                           String val)

Set the text element content of an element, allowing null and removing all previous content.

Parameters:

e - the element

val - the text content

setText

public static void setText(Element e,
                           long val)

Set the text element content of an element to a stringified long value, removing all previous content.

Parameters:

e - the element

val - the long value

inheritXmlAttributes

public static void inheritXmlAttributes(Element elem)

Inherit all attributes in the XML namespace, according to Canonical XML

Parameters:

elem - anchor element (attributes are added)

importNode

public static Node importNode(Document owner,
                              Node imp,
                              boolean deep)

Wrapper method for Document.importNode(Node, boolean), providing logging of fatal errors (seen in early Xerces versions).

Parameters:

owner - owner document

imp - node to import

deep - true when importing recursively

Returns:

imported node

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] KMC-CM	[sap.com] tc/km/frwk	api	EP-KM-CM
[sap.com] KMC-WPC	[sap.com] tc/kmc/wpc/wpcfacade	api	EP-PIN-WPC-WCM