org.inria.ns.reflex.xml
Class XMLHelper

java.lang.Object
  extended by org.inria.ns.reflex.xml.XMLHelper

public abstract class XMLHelper
extends Object

Useful tools for XML processing.

Author:
Philippe Poulard

Field Summary
static XFactory DEFAULT_XFACTORY
          The default XFactory.
static MasterXOperator MASTER_XOPERATOR
          The master X-operator that processes XML operations (XPath crossing and XML updating).
 
Method Summary
static boolean booleanValueOf(Object value)
          Provides the boolean value of the given object.
static InputSource bufferInput(InputSource input)
          Create a new input source that use buffers for the character stream or the byte stream, so that the input can be marked and re-read.
static InputSource bufferInput(InputSource input, int size)
          Create a new input source that use buffers for the character stream or the byte stream, so that the input can be marked and re-read.
static Attr createAttribute(QName name)
          Return a new XML attribute with the given name and no value.
static Attr createAttribute(String namespaceURI, String qualifiedName)
          Return a new XML attribute with the given name and no value.
static CDATASection createCDataSection(String text)
          Return a new XML CDATA section with the given text.
static Comment createComment(String comment)
          Return a new XML comment with the given data.
static Element createElement(QName name)
          Return a new XML element with the given name.
static Element createElement(String namespaceURI, String qualifiedName)
          Return a new XML element.
static DocumentFragment createFragment()
          Return a new empty XML fragment.
static ProcessingInstruction createProcessingInstruction(String target, String data)
          Return a new XML processing instruction with the given target.
static Text createText(String text)
          Return a new XML text with the given text.
static InputSource ensureInput(InputSource input)
          Ensure the content of an input.
static Element findElement(Node node)
          Finds the nested Element of a Node.
static String findNamespaceURIForPrefix(Element element, String prefix)
          Retrieve the namespace URI corresponding to a prefix if the element or its nearest ancestor declares it.
static InputSource getInputSource(XFile base, Object input)
          Create an input source from an input.
static InputSource getInputSource(XFile base, Object input, String systemId, String publicId)
          Create an input source from an input.
static Document getOwnerDocument(Node node)
          Return the owner document of a node, or the node itself if it is a document.
static Node getRoot(Node node)
          Return the root node.
static Object getValue(Object object)
          Return the value of an object, that is to say the value of an object that has a name and a value.
static Node importNode(Document host, Node node)
          Import a node safely.
static Node importNode(Document host, Node node, Element parent, boolean deep)
          Import a node safely.
static void insertXMLBefore(Node parent, Node node, Object content)
          Insert a content before a given node; this method works with various content : XML attributes : are ignored ; other XML nodes : are inserted before the node ; Map : is ignored ; Map.Entry : behave like attributes ; List : each item is processed separatly ; NodeList : each item is processed separatly.
static boolean isRoot(Node node)
          Indicates whether a node is root or not.
static boolean isWhitespace(char c)
          Indicates whether a character is an XML whitespace.
static boolean isWhitespace(char[] ch, int start, int length)
          Indicates whether a character sequence is an XML whitespace.
static boolean isWhitespace(Node node)
          Indicates whether a node is an XML whitespace or not.
static boolean isWhitespace(String text)
          Indicates whether a string is an XML whitespace.
static boolean isXMLMimeType(String mimeType)
          Indicates if the given MIME type is related to XML or not.
static Number numberValueOf(Object value)
          Return the number evaluation of a value, given by the XPath number() function.
static Map parseStylesheets(File directory)
          Automatically load and parse all files found in a directory and its subdirectories as stylesheets.
static QName qnameValueOf(Object value, XPathContext context)
          Return the QName value of a value.
static Attr setAttribute(Element element, QName name, String value)
          Set to an element a new XML attribute with the given name and no value.
static void setXMLContent(Node node, Object content)
          Set the content of a node; this method works with various content : XML attributes : are setting like attributes on elements other XML nodes : are appending to the child node list Map (each Map.Entry is processed separatly) Map.Entry (behave like attributes) List (each item is processed separatly) NodeList (each item is processed separatly) Other content are appended as strings.
static void setXMLContent(Node node, Object content, XMLListener listener)
          Set the content of a node with an optimistic strategy ; this method works with various content : XML attributes : are setting like attributes on elements other XML nodes : are appending to the child node list Map (each Map.Entry is processed separatly) Map.Entry (behave like attributes) List (each item is processed separatly) NodeList (each item is processed separatly) Other content are appended as strings.
static String stringValueOf(Object value)
          Return the string evaluation of a value, given by the XPath string() function.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_XFACTORY

public static final XFactory DEFAULT_XFACTORY
The default XFactory.


MASTER_XOPERATOR

public static final MasterXOperator MASTER_XOPERATOR
The master X-operator that processes XML operations (XPath crossing and XML updating).

Method Detail

createAttribute

public static Attr createAttribute(QName name)
Return a new XML attribute with the given name and no value.

Parameters:
name - The qualified name of the attribute to create.
Returns:
The new attribute.

createAttribute

public static Attr createAttribute(String namespaceURI,
                                   String qualifiedName)
Return a new XML attribute with the given name and no value.

Parameters:
namespaceURI - The namespace URI of the attribute.
qualifiedName - The qualified name of the attribute to create.
Returns:
The new attribute.

setAttribute

public static Attr setAttribute(Element element,
                                QName name,
                                String value)
Set to an element a new XML attribute with the given name and no value.

Parameters:
element - The host element of the new attribute.
name - The qualified name of the attribute to create.
value - The value of the attribute.
Returns:
The new attribute.

createComment

public static Comment createComment(String comment)
Return a new XML comment with the given data.

Parameters:
comment - The comment to create.
Returns:
The new comment.

createElement

public static Element createElement(QName name)
Return a new XML element with the given name.

Parameters:
name - The qualified name of the element to create.
Returns:
The new element.

createElement

public static Element createElement(String namespaceURI,
                                    String qualifiedName)
Return a new XML element.

Parameters:
namespaceURI - The namespace URI of the element.
qualifiedName - The qualified name of the element to create.
Returns:
The new element.

createProcessingInstruction

public static ProcessingInstruction createProcessingInstruction(String target,
                                                                String data)
Return a new XML processing instruction with the given target.

Parameters:
target - The target of the processing instruction.
data - The datas of the processing instruction.
Returns:
The new processing instruction.

createText

public static Text createText(String text)
Return a new XML text with the given text.

Parameters:
text - The text to create.
Returns:
The new text node.

createFragment

public static DocumentFragment createFragment()
Return a new empty XML fragment.

Returns:
An empty fragment, that can be safely cast to List.

createCDataSection

public static CDATASection createCDataSection(String text)
Return a new XML CDATA section with the given text.

Parameters:
text - The text to create.
Returns:
The new CDATA section.

setXMLContent

public static void setXMLContent(Node node,
                                 Object content)
Set the content of a node; this method works with various content :

Other content are appended as strings.

Parameters:
node - The referent node.
content - The content to set.

setXMLContent

public static void setXMLContent(Node node,
                                 Object content,
                                 XMLListener listener)
Set the content of a node with an optimistic strategy ; this method works with various content :

Other content are appended as strings.

Parameters:
node - The referent node.
content - The content to set.
listener - The listener that is notified of the changes on the node.

insertXMLBefore

public static void insertXMLBefore(Node parent,
                                   Node node,
                                   Object content)
Insert a content before a given node; this method works with various content :

Other content are ignored.

Parameters:
parent - The parent of the target node.
node - The node to insert before.
content - The content to insert.

findElement

public static Element findElement(Node node)
Finds the nested Element of a Node. If the node is an element, it is returned. If the node is a document, the document element is returned. If the node is an attribute, its element is returned. And so on...

Parameters:
node - The Node for which the appropriate Element will be find.
Returns:
The Element required.

booleanValueOf

public static boolean booleanValueOf(Object value)
Provides the boolean value of the given object.

Parameters:
value - The value to evaluate as a boolean.
Returns:
The boolean value of the given object.

numberValueOf

public static Number numberValueOf(Object value)
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 and parsed to a number.

Parameters:
value - The object to convert to a number.
Returns:
The number value of the object.

qnameValueOf

public static QName qnameValueOf(Object value,
                                 XPathContext context)
Return the QName value of a value.

Parameters:
value - The value to cast to a QName.
context - The context that may help for resolving prefixes.
Returns:
A QName.

stringValueOf

public static String stringValueOf(Object value)
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.

Parameters:
value - The object to convert to string.
Returns:
The non-null string value of the object.

getValue

public static Object getValue(Object object)
Return the value of an object, that is to say the value of an object that has a name and a value. Other objects are returned as-is.

Parameters:
object - The object for which to get the value.
Returns:
The value of the object, or the object itself.

isRoot

public static boolean isRoot(Node node)
Indicates whether a node is root or not.

Parameters:
node - The node to test.
Returns:
true if the node is a document or a document fragment, false otherwise.
See Also:
Document, DocumentFragment

isWhitespace

public static boolean isWhitespace(String text)
Indicates whether a string is an XML whitespace.

Parameters:
text - The string to test.
Returns:
true if the string contains only XML whitespaces, false otherwise.

isWhitespace

public static boolean isWhitespace(char[] ch,
                                   int start,
                                   int length)
Indicates whether a character sequence is an XML whitespace.

Parameters:
ch - The char sequence.
start - The start position.
length - The end position.
Returns:
true if the character sequence contains only XML whitespaces, false otherwise.

isWhitespace

public static boolean isWhitespace(char c)
Indicates whether a character is an XML whitespace.

Parameters:
c - The character.
Returns:
true if the character is an XML whitespace, false otherwise.

isXMLMimeType

public static boolean isXMLMimeType(String mimeType)
Indicates if the given MIME type is related to XML or not.

XML MIME types :

Non-XML MIME types :

Parameters:
mimeType - The MIME type to test.
Returns:
true if the MIME type contains the string "xml" not followed by "-", false otherwise.

isWhitespace

public static boolean isWhitespace(Node node)
Indicates whether a node is an XML whitespace or not.

Parameters:
node - The node to test.
Returns:
true if the node is an XML whitespaces, false otherwise.

findNamespaceURIForPrefix

public static String findNamespaceURIForPrefix(Element element,
                                               String prefix)
Retrieve the namespace URI corresponding to a prefix if the element or its nearest ancestor declares it.

Parameters:
element - The element used for namespace resolution.
prefix - The prefix to lookup, maybe null or the empty string.
Returns:
The namespace URI bounded to the prefix, or null if not found.

getOwnerDocument

public static Document getOwnerDocument(Node node)
Return the owner document of a node, or the node itself if it is a document.

Parameters:
node - The node for which the document owner is expected.
Returns:
The owner document.

importNode

public static Node importNode(Document host,
                              Node node)
Import a node safely. If the node is an element (or contain elements), the namespace declarations are also imported (they could have been declared at a higher level of the tree). The content is imported too.

Parameters:
host - The target document that will host the node imported.
node - The node for which the document owner is expected.
Returns:
The node imported.

importNode

public static Node importNode(Document host,
                              Node node,
                              Element parent,
                              boolean deep)
Import a node safely. If the node is an element (or contain elements), the namespace declarations are also imported (they could have been declared at a higher level of the tree), except if the parent target is specified and already define the same namespace URI. If the node is a text node, following adjacent text nodes are merged with it into a new node.

Parameters:
host - The target document that will host the node imported.
node - The node for which the document owner is expected.
parent - The parent target, may be null. The imported node is NOT added to the parent target.
Returns:
The node imported.

parseStylesheets

public static Map parseStylesheets(File directory)
Automatically load and parse all files found in a directory and its subdirectories as stylesheets. Non-stylesheet files are ignored.

Parameters:
directory - A directory that may contain stylesheets.
Returns:
A non-null map of stylesheets (Templates) and submaps. The key of each entry is a file/directory name. The value of each entry is a parsed stylesheet or a submap.
See Also:
Templates

ensureInput

public static InputSource ensureInput(InputSource input)
                               throws IOException
Ensure the content of an input. If the input has neither character stream nor byte stream, one is set from the file pointed by the system ID. If possible, its encoding is those specified in the input or in the file.

Parameters:
input - The input to test.
Returns:
The input, that has at least either a character stream or a byte stream.
Throws:
IOException

bufferInput

public static InputSource bufferInput(InputSource input,
                                      int size)
                               throws IOException
Create a new input source that use buffers for the character stream or the byte stream, so that the input can be marked and re-read. The input is ensured before to have a byte stream or a character stream.

Parameters:
input - The input.
size - The size of the buffers ; if necessary, buffers of the size specified are added until reset() is invoked.
Returns:
A new input source that wraps either a NoCloseInputStream that wraps an ExtensibleBufferedInputStream, or a NoCloseReader that wraps an ExtensibleBufferedReader. The input source is marked for buffering.
Throws:
IOException
See Also:
ensureInput(InputSource), InputStream.reset(), Reader.reset(), ExtensibleBufferedInputStream, NoCloseInputStream, ExtensibleBufferedReader, NoCloseReader

bufferInput

public static InputSource bufferInput(InputSource input)
                               throws IOException
Create a new input source that use buffers for the character stream or the byte stream, so that the input can be marked and re-read. The input is ensured before to have a byte stream or a character stream. The buffers size is 2048 ; if necessary, buffers are added until reset() is invoked.

Parameters:
input - The input.
Returns:
A new input source that wraps either a NoCloseInputStream that wraps an ExtensibleBufferedInputStream, or a NoCloseReader that wraps an ExtensibleBufferedReader. The input source is marked for buffering.
Throws:
IOException
See Also:
bufferInput(InputSource, int), ensureInput(InputSource), InputStream.reset(), ExtensibleBufferedInputStream, NoCloseInputStream, ExtensibleBufferedReader, NoCloseReader

getInputSource

public static InputSource getInputSource(XFile base,
                                         Object input)
                                  throws FileSystemException
Create an input source from an input. The URI of the input (if any), is preserved.

Parameters:
base - The base used to resolve URI, or null.
input - An object, that is either :
  • an input stream,
  • a reader,
  • or converted to an XFile.
Returns:
An input source from the input.
Throws:
FileSystemException - When an I/O error occurs.
See Also:
getInputSource(XFile, Object, String, String)

getInputSource

public static InputSource getInputSource(XFile base,
                                         Object input,
                                         String systemId,
                                         String publicId)
                                  throws FileSystemException
Create an input source from an input.

Parameters:
base - The base used to resolve URI, or null.
input - An object, that is either :
  • an input stream,
  • a reader,
  • or converted to an XFile.
systemId - The system ID to set to the input source, or null to preserve the URI (if any) of the input.
publicId - The public ID to set to the input source, or null.
Returns:
An input source from the input.
Throws:
FileSystemException - When an I/O error occurs.
See Also:
XFile.getXFile(Object), InputStream, Reader

getRoot

public static Node getRoot(Node node)
Return the root node.

Parameters:
node - The non-null node.
Returns:
The ancestor-or-self node that has no parent.
See Also:
Document, DocumentFragment