org.mmbase.util.xml
Class DocumentReader

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

Direct Known Subclasses:

ApplicationReader, BuilderReader, DatabaseStorageLookup, DocumentWriter, MagicXMLReader, ModuleReader, StorageReader, XMLBasicReader, XmlEtxIndicesReader, XMLNodeReader

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,v 1.29 2006/06/19 05:53:58 michiel Exp $

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

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 validating, Class resolveBase) Constructs the document by reading it from a source.
	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
Iterator	getChildElements(Element e)
Iterator	getChildElements(Element e, String tag)
Iterator	getChildElements(String path)
Iterator	getChildElements(String path, String tag)
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)
Element	getElementByPath(Element e, String path)
Element	getElementByPath(String path)
String	getElementName(Element e)
String	getElementValue(Element e)
String	getElementValue(String path)
static String	getNodeTextValue(Node n) Return the text value of a node.
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 XMLEntityResolver.
static void	setNodeTextValue(Node n, String value)
void	setSystemId(String url)
static Document	toDocument(Element element) Utility method to make a document of an element.
protected 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

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 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

validating - whether to validate the document

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

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 XMLEntityResolver.

validate

protected 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

setNodeTextValue

public static void setNodeTextValue(Node n,
                                    String value)

Since:

MMBase-1.8.1

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;

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 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 String getElementValue(Element e)

Parameters:

e - Element

Returns:

Text value of element

getChildElements

public Iterator getChildElements(String path)

Parameters:

path - Path to the element

Returns:

Iterator of child elements

getChildElements

public Iterator getChildElements(Element e)

Parameters:

e - Element

Returns:

Iterator of child elements

getChildElements

public Iterator getChildElements(String path,
                                 String tag)

Parameters:

path - Path to the element

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

Returns:

Iterator of child elements with the given tag

getChildElements

public Iterator getChildElements(Element e,
                                 String tag)

Parameters:

e - Element

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

Returns:

Iterator of child elements with the given tag

To Do:

XXXX MM: Since we have changed the return type from 1.7 to 1.8 anyway, why don't we return a List then?

main

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

Throws:

Exception