wyvern.kernel.properties
Class XMLWrapper

java.lang.Object
  wyvern.kernel.properties.XMLWrapper

public final class XMLWrapper

extends java.lang.Object

This class hides some of the sordid details of the underlying XML parser. A client of this class still needs to be aware of the standard XML DOM API, so that it can traverse the parse tree. However, this class shields them from having to know how the individual parser implementation handles streams, files, etc.

The primary reason for having this class is that we don't want to store an absolute path or URL to the map.dtd and arch.dtd files used to validate the archetype & map xml files. The dtd files are relative to the game installation tree, so we need to insert the appropriate XML entity reference at the head of the input stream for each archetype & mapfile before handing them over to the parser.

Version:

1.0, Jul 10, 1999

Author:

Steve Yegge

Method Summary

static java.lang.String	constructXMLDoc(java.lang.String dtdPath, java.lang.String data) Constructs an XML document on the fly, given the path to the DTD and the XML data for the document.
static java.lang.String	encodeXMLStream(java.lang.String input) Escapes any latin-1 characters or Unicode characters.
static org.w3c.dom.Node	getCDATASectionNode(org.w3c.dom.Node node) Goes through the children of the passed node until it finds a CDATASection node, and returns it.
static org.w3c.dom.Element	getFirstChildElement(org.w3c.dom.Node node) Removes and returns the first child element of this node, if any.
static java.util.LinkedList	getTextFromNode(org.w3c.dom.Node node) Returns a list of lines of text contained by this Node.
static org.w3c.dom.Element	getXMLBeanDocumentRoot(java.lang.Object obj, org.w3c.dom.Node bean) High-level utility method for SelfExternalizable beans.
static void	main(java.lang.String[] args) Tests the class.
static org.w3c.dom.Document	parseArchetypeFile(java.lang.String archfile) Parses a Wyvern archetype file into a DOM tree.
static org.w3c.dom.Document	parseCustomXMLDocument(java.lang.String input) Utility function to parse an XML document in a string.
static org.w3c.dom.Document	parseMapFile(java.lang.String mapfile) Parses a Wyvern map file into a DOM tree.
static org.w3c.dom.Document	parseXMLNoValidation(java.lang.String input) Parses some XML with no DTD.
static org.w3c.dom.Document	parseXMLString(java.lang.String input) Parses an XML definition using the game's "arch.dtd".
static java.lang.String	print(org.w3c.dom.Node node) Prints the specified node, recursively.

Methods inherited from class java.lang.Object

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

Method Detail

parseCustomXMLDocument

public static org.w3c.dom.Document parseCustomXMLDocument(java.lang.String input)
                                                   throws java.lang.Exception

Utility function to parse an XML document in a string. If the XML document includes an external DTD reference, the reference must include the absolute path to the .dtd file.

Parameters:

input - an XML document to parse

Throws:

java.lang.Exception

parseXMLString

public static org.w3c.dom.Document parseXMLString(java.lang.String input)
                                           throws java.lang.Exception

Parses an XML definition using the game's "arch.dtd".

Parameters:

input - the input string

Returns:

a Document object representing the root of the parse tree.

Throws:

java.lang.Exception

parseArchetypeFile

public static org.w3c.dom.Document parseArchetypeFile(java.lang.String archfile)
                                               throws java.lang.Exception

Parses a Wyvern archetype file into a DOM tree.

Parameters:

archfile - - the absolute path to the archetype to parse.

Returns:

a Document object representing the root of the parse tree.

Throws:

java.lang.Exception

parseMapFile

public static org.w3c.dom.Document parseMapFile(java.lang.String mapfile)
                                         throws java.lang.Exception

Parses a Wyvern map file into a DOM tree.

Parameters:

mapfile - - the full path to the map file to parse

Returns:

a Document object representing the root of the parse tree.

Throws:

java.lang.Exception

getFirstChildElement

public static org.w3c.dom.Element getFirstChildElement(org.w3c.dom.Node node)

Removes and returns the first child element of this node, if any. Skips any non-element children.

Parameters:

node - the DOM Node to check for element children

Returns:

the first Element child, which is also removed from the node's child list. If no Element child is found, returns null.

getCDATASectionNode

public static org.w3c.dom.Node getCDATASectionNode(org.w3c.dom.Node node)

Goes through the children of the passed node until it finds a CDATASection node, and returns it.

Returns:

the first CDATASection child node, or null if none is found.

getTextFromNode

public static java.util.LinkedList getTextFromNode(org.w3c.dom.Node node)

Returns a list of lines of text contained by this Node. Skips any non-TEXT_NODE children.

Parameters:

node - a DOM Node to grab the text from

Returns:

the list of lines of text comprising the node

print

public static java.lang.String print(org.w3c.dom.Node node)

Prints the specified node, recursively. Code taken from IBM's sample DOMWriter class.

constructXMLDoc

public static java.lang.String constructXMLDoc(java.lang.String dtdPath,
                                               java.lang.String data)

Constructs an XML document on the fly, given the path to the DTD and the XML data for the document. Note: you probably don't need to use this. You don't want to use DTDs, at least as long as we're using the DOM model.

Parameters:

dtdPath - the location of the DTD file within the Wyvern directory structure (an absolute path that should be constructed by calling wyvern.common.config.Wyvern to get the absolute part of the path).

data - the XML data

parseXMLNoValidation

public static org.w3c.dom.Document parseXMLNoValidation(java.lang.String input)
                                                 throws java.lang.Exception

Parses some XML with no DTD.

Parameters:

input - the input XML snippet

Returns:

a Document containing the XML

Throws:

java.lang.Exception

getXMLBeanDocumentRoot

public static org.w3c.dom.Element getXMLBeanDocumentRoot(java.lang.Object obj,
                                                         org.w3c.dom.Node bean)
                                                  throws java.lang.Exception

High-level utility method for SelfExternalizable beans. Assumes the XML data is in a CDATA section and has no associated DTD (so the bean will decide whether it likes the elements the parser finds). Pulls the text data out of the CDATA section, passes it to a non-validating XML parser, and retrieves the resulting document's root element. The bean just has to enumerate the child nodes to get at its data.

Parameters:

bean - an XML node for a SelfExternalizable bean

obj - the Bean object, for error-reporting purposes

Returns:

a parsed XML document (can be null, if there was no data) containing arbitrary XML elements

Throws:

java.lang.Exception

encodeXMLStream

public static java.lang.String encodeXMLStream(java.lang.String input)

Escapes any latin-1 characters or Unicode characters. Also escapes XML characters: &, <, >, ' and "

main

public static void main(java.lang.String[] args)

Tests the class.