org.mmbase.util.xml
Class DocumentReader

java.lang.Object
  org.mmbase.util.xml.DocumentReader

Direct Known Subclasses:

AbstractBuilderReader, ApplicationReader, DatabaseStorageLookup, DocumentWriter, MagicXMLReader, ModuleReader, NodeReader, StorageReader, XMLBasicReader, XmlEtxIndicesReader

public class DocumentReader
extends Object

The DocumentReader class provides methods for loading a xml document in memory. It serves as the base class for DocumentWriter (which adds ways to write a document), and XMLBasicReader, which adds path-like methods with which to retrieve elements. This can also be a class for general static dom utilities.

Since:

MMBase-1.7

Version:

$Id: DocumentReader.java 42843 2010-07-09 13:29:04Z michiel $

Author:

Case Roule, Rico Jansen, Pierre van Rooden, Michiel Meeuwissen

Field Summary

protected Document	document
static String	DTD_ERROR DTD respource filename of the most recent Error DTD
static String	DTD_ERROR_1_0 DTD resource filename of the Error DTD version 1.0
protected static String	FILENOTFOUND
static String	PUBLIC_ID_ERROR Public ID of the most recent Error DTD
static String	PUBLIC_ID_ERROR_1_0 Public ID of the Error DTD version 1.0
(package private) static UtilReader.PropertiesMap<String>	utilProperties

Constructor Summary

protected	DocumentReader() Creates an empty document reader.
	DocumentReader(Document doc)
	DocumentReader(InputSource source) Constructs the document by reading it from a source.
	DocumentReader(InputSource source, boolean validating) Constructs the document by reading it from a source.
	DocumentReader(InputSource source, boolean xsd, boolean validating, Class<?> resolveBase) Constructs the document by reading it from a source.
	DocumentReader(InputSource source, boolean validating, Class<?> resolveBase)
	DocumentReader(InputSource source, Class<?> resolveBase) Constructs the document by reading it from a source.

Method Summary

static void	appendChild(Element parent, Element newChild, String path) Appends a child to a parent at the right position.
static String	getAttribute(Element element, String nameSpace, String localName) Returns the value of a certain attribute, either an unqualified attribute or an attribute that fits in the passed namespace
static List<Element>	getChildElements(Element e)
static List<Element>	getChildElements(Element e, String tag)
List<Element>	getChildElements(String path)
List<Element>	getChildElements(String path, String tag)
Document	getDocument()
static DocumentBuilder	getDocumentBuilder() Creates a DocumentBuilder with default settings for handler, resolver, or validation, obtaining it from the cache if available.
static DocumentBuilder	getDocumentBuilder(boolean validating) Obtain a DocumentBuilder
static DocumentBuilder	getDocumentBuilder(boolean validating, boolean xsd, ErrorHandler handler, EntityResolver resolver) Creates a DocumentBuilder.
static DocumentBuilder	getDocumentBuilder(boolean validating, ErrorHandler handler, EntityResolver resolver) See getDocumentBuilder(boolean, ErrorHandler, EntityResolver)
String	getElementAttributeValue(Element e, String attr)
String	getElementAttributeValue(String path, String attr)
static Element	getElementByPath(Element e, String path)
Element	getElementByPath(String path)
String	getElementName(Element e)
static String	getElementValue(Element e)
String	getElementValue(String path)
static String	getNodeTextValue(Node n) Return the text value of a node.
static String	getNodeTextValue(Node n, boolean trim)
Element	getRootElement() Deprecated.
String	getSystemId() Returns the systemID of the InputSource used to read the document.
static boolean	hasAttribute(Element element, String nameSpace, String localName) Returns whether an element has a certain attribute, either an unqualified attribute or an attribute that fits in the passed namespace
static void	main(String[] argv)
static void	registerPublicIDs() Register the Public Ids for DTDs used by XMLBasicReader This method is called by EntityResolver.
static void	setNodeTextValue(Node n, String value)
static void	setPrefix(Document d, String ns, String prefix)
void	setSystemId(String url)
static Document	toDocument(Element element) Utility method to make a document of an element.
static boolean	validate() Returns the default setting for validation for DocumentReaders.
protected static boolean	validate(boolean requested) Whether to validate given a request for that.

Methods inherited from class java.lang.Object

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

Field Detail

FILENOTFOUND

protected static final String FILENOTFOUND

See Also:

Constant Field Values

PUBLIC_ID_ERROR_1_0

public static final String PUBLIC_ID_ERROR_1_0

Public ID of the Error DTD version 1.0

See Also:

Constant Field Values

DTD_ERROR_1_0

public static final String DTD_ERROR_1_0

DTD resource filename of the Error DTD version 1.0

See Also:

Constant Field Values

PUBLIC_ID_ERROR

public static final String PUBLIC_ID_ERROR

Public ID of the most recent Error DTD

See Also:

Constant Field Values

DTD_ERROR

public static final String DTD_ERROR

DTD respource filename of the most recent Error DTD

See Also:

Constant Field Values

document

protected Document document

utilProperties

static UtilReader.PropertiesMap<String> utilProperties

Constructor Detail

DocumentReader

protected DocumentReader()

Creates an empty document reader.

DocumentReader

public DocumentReader(InputSource source)

Constructs the document by reading it from a source.

Parameters:

source - the input source from which to read the document

DocumentReader

public DocumentReader(InputSource source,
                      boolean validating)

Constructs the document by reading it from a source.

Parameters:

source - the input source from which to read the document

validating - whether to validate the document

DocumentReader

public DocumentReader(InputSource source,
                      Class<?> resolveBase)

Constructs the document by reading it from a source. You can pass a resolve class to this constructor, allowing you to indicate the package in which the dtd of the document read is to be found. The dtd sould be in the resources package under the package of the class passed.

Parameters:

source - the input source from which to read the document

resolveBase - the base class whose package is used to resolve dtds, set to null if unknown

DocumentReader

public DocumentReader(InputSource source,
                      boolean xsd,
                      boolean validating,
                      Class<?> resolveBase)

Constructs the document by reading it from a source. You can pass a resolve class to this constructor, allowing you to indicate the package in which the dtd of the document read is to be found. The dtd sould be in the resources package under the package of the class passed.

Parameters:

source - the input source from which to read the document

xsd - the input source from which to read the document

validating - whether to validate the document

resolveBase - the base class whose package is used to resolve dtds, set to null if unknown

Since:

MMBase-1.9.2

DocumentReader

public DocumentReader(InputSource source,
                      boolean validating,
                      Class<?> resolveBase)

DocumentReader

public DocumentReader(Document doc)

Since:

MMBase-1.8

Method Detail

registerPublicIDs

public static void registerPublicIDs()

Register the Public Ids for DTDs used by XMLBasicReader This method is called by EntityResolver.

validate

public static final boolean validate()

Returns the default setting for validation for DocumentReaders.

Returns:

true if validation is on

validate

protected static final boolean validate(boolean requested)

Whether to validate given a request for that. So, the request is followed, unless it is configured to 'never' validate.

Since:

MMBase-1.8

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder()

Creates a DocumentBuilder with default settings for handler, resolver, or validation, obtaining it from the cache if available.

Returns:

a DocumentBuilder instance, or null if none could be created

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder(boolean validating)

Obtain a DocumentBuilder

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder(boolean validating,
                                                 ErrorHandler handler,
                                                 EntityResolver resolver)

See getDocumentBuilder(boolean, ErrorHandler, EntityResolver)

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder(boolean validating,
                                                 boolean xsd,
                                                 ErrorHandler handler,
                                                 EntityResolver resolver)

Creates a DocumentBuilder. DocumentBuilders that use the default error handler or entity resolver are cached (one for validating, one for non-validating document buidlers).

Parameters:

validating - if true, the documentbuilder will validate documents read

xsd - if true, validating will be done by an XML schema definiton.

handler - a ErrorHandler class to use for catching parsing errors, pass null to use the default handler

resolver - a EntityResolver class used for resolving the document's dtd, pass null to use the default resolver

Returns:

a DocumentBuilder instance, or null if none could be created

Since:

MMBase-1.8.

getNodeTextValue

public static String getNodeTextValue(Node n)

Return the text value of a node. It includes the contents of all child textnodes and CDATA sections, but ignores everything else (such as comments) The code trims excessive whitespace unless it is included in a CDATA section.

Parameters:

n - the Node whose value to determine

Returns:

a String representing the node's textual value

getNodeTextValue

public static String getNodeTextValue(Node n,
                                      boolean trim)

Since:

MMBase-1.8.5

setNodeTextValue

public static void setNodeTextValue(Node n,
                                    String value)

Since:

MMBase-1.8.1

setPrefix

public static void setPrefix(Document d,
                             String ns,
                             String prefix)

Since:

MMBase-1.8.5

hasAttribute

public static boolean hasAttribute(Element element,
                                   String nameSpace,
                                   String localName)

Returns whether an element has a certain attribute, either an unqualified attribute or an attribute that fits in the passed namespace

getAttribute

public static String getAttribute(Element element,
                                  String nameSpace,
                                  String localName)

Returns the value of a certain attribute, either an unqualified attribute or an attribute that fits in the passed namespace

toDocument

public static Document toDocument(Element element)

Utility method to make a document of an element.

Since:

MMBase-1.8

appendChild

public static void appendChild(Element parent,
                               Element newChild,
                               String path)

Appends a child to a parent at the right position. The right position is defined by a comma separated list of regular expressions. If the the child matches the last element of the path, then the child is appended after similer childs, if not, then it will be appended before them.

Parameters:

parent - The parent element, to which a new child will be added

newChild - this new child

path - The beforementioned comma separated list of regexps. See also Pattern; Namespace prefixes are ignored.

Since:

MMBase-1.8

getSystemId

public String getSystemId()

Returns the systemID of the InputSource used to read the document. This is generally the document's file path.

Returns:

the systemID as a String

Since:

MMBase-1.8

setSystemId

public void setSystemId(String url)

Since:

MMBase-1.8

getElementName

public String getElementName(Element e)

Parameters:

e - Element

Returns:

Tag name of the element

getElementAttributeValue

public String getElementAttributeValue(String path,
                                       String attr)

Parameters:

path - Path to the element

attr - Attribute name

Returns:

Value of attribute

getElementAttributeValue

public String getElementAttributeValue(Element e,
                                       String attr)

Parameters:

e - Element

attr - Attribute name

Returns:

Value of attribute

getRootElement

public Element getRootElement()

Deprecated.

Determine the root element of the contained document

Returns:

root element

getElementByPath

public Element getElementByPath(String path)

Parameters:

path - Dot-separated list of tags describing path from root element to requested element. NB the path starts with the name of the root element.

Returns:

Leaf element of the path

getElementByPath

public static Element getElementByPath(Element e,
                                       String path)

Parameters:

e - Element from which the "relative" path is starting. NB the path starts with the name of the root element.

path - Dot-separated list of tags describing path from root element to requested element

Returns:

Leaf element of the path

getElementValue

public String getElementValue(String path)

Parameters:

path - Path to the element

Returns:

Text value of element

getElementValue

public static String getElementValue(Element e)

Parameters:

e - Element

Returns:

Text value of element

getChildElements

public List<Element> getChildElements(String path)

Parameters:

path - Path to the element

Returns:

a List of child elements

getChildElements

public static List<Element> getChildElements(Element e)

Parameters:

e - Element

Returns:

a List of child elements

getChildElements

public List<Element> getChildElements(String path,
                                      String tag)

Parameters:

path - Path to the element

tag - tag to match ("*" means all tags")

Returns:

a List of child elements with the given tag

getChildElements

public static List<Element> getChildElements(Element e,
                                             String tag)

Parameters:

e - Element

tag - tag to match ("*" means all tags")

Returns:

a List of child elements with the given tag

getDocument

public Document getDocument()

Since:

MMBase-1.9

main

public static void main(String[] argv)
                 throws Exception

Throws:

Exception