Common
Class myXML

java.lang.Object
  Common.myXML

All Implemented Interfaces:

java.io.Serializable

public class myXML
extends java.lang.Object
implements java.io.Serializable

Title: XML parser/generator

Description: WEB applet for X10 Linux Universal Device Drivers
Copyright: Copyright (c) 2003
License: GPL
Summary:This is a poor man's version of a DOM like XML reader/writer written specifically so that it is very small and ideal for an applet.

The format supported is as followed:

<?xml version="1.0" standalone="yes"?>
<!-- Comment -->
<rootname>
<tag>
<tag attribute1="value" attribute2="value">elementvalue</tag>
</tag>
</rootname>

The following are not supported:

• Processing Instructions
• Namespace

How to create XML tree in memory to write to disk:

1. Create the root node with a name (myXML root = new myXML("roottag");)
2. Create subelements
   1. If subelement will have subelements (branch), use the form without a value (myXML subelement = roottag.addElement("subelement");)
   2. If the subelement will not have subelements (leaf), add the element with a value (myXML subelement = roottag.addElement("element",value);)
   3. For each subelement (branch and leaf) add attributes (subelement.Attribute.add("name",value);) or (root.Attribute.add("name",value);)
3. Continue this until you have completed the tree
4. Write it to a PrintWriter stream to generate XML

Example:

• myXML root = new myXML("root");
• myXML sub1 = root.addElement("element1",value1);
• sub1.Attribute.add("attribute1",att1);
• sub1.Attribute.add("attribute2",att2);
• myXML sub2 = root.addElement("element2");
• sub2.Attribute.add("attribute20",att20);
• myXML sub21 = sub1.addElement("element21");
• sub21.Attribute.add("attribute21",value21);
• root.serialize(pw);

Results in the following:

<?xml version="1.0" standalone="yes"?>
<root>
<element1 attribute1="att1" attribute2="att2">value1</element1>
<element2 attribute20="att20">
<element21 attribute21="att21">value21</element21>
</element2>
</root>

Values for Elements and Attributes can be any type of object but will be converted to String by calling toString() before storing the value.

How to load XML tree from disk:

1. Open a BufferedReader (in = new BufferedReader(file);)
2. Create a new myXML(BufferedReader) object passing it the BufferedReader (xmlroot = new myXML((BufferedReader)in);)

How to walk through the XML tree:

• myXML.getTag(): Returns the tag name of the myXML object
• myXML.getValue(): Returns the value of the myXML object
• myXML.getElement(int): Returns the myXML sub-object at the specified index
• myXML.findElement(String tag): Returns the first myXML object with the name tag
• myXML.findElement(String tag, Attribute name): Returns the first myXML object with the name tag and attribute name
• myXML.Attribute.find(String name): Returns the attribute value associated with name

Version:

1.1.0

Author:

Scott Hiles

See Also:

Serialized Form

Nested Class Summary

class	myXML.Attribute Attributes associated with element tags.
static class	myXML.myXMLEncodingException Signals that the XML being parsed has an error in the encoding.
static class	myXML.myXMLException Signals that a general exception has occurred.
static class	myXML.myXMLIOException Signals that an I/O excetion has occurred.

Field Summary

myXML.Attribute

Attribute

Constructor Summary

myXML()

myXML(java.io.BufferedReader in)
Read the XML tree in from the specified stream.

myXML(java.lang.String tag)
Create new myXML object with no subelements, no attributes, and no value

Method Summary

myXML	addElement(java.lang.String tag) Add a subelement which will be used as a branch in the XML tree to the this element of the form: <tag attr1="attr1value attr2="attr2value" ...
myXML	addElement(java.lang.String tag, java.lang.Object value) Add a leaf element to the XML tree of the form: <tag attr1="attr1value attr2="attr2value" ...
boolean	contains(myXML element) Tests if the specified element is a subelement of this element
myXML	findattribute(java.lang.String name) Find and retrieve the first element that has the specified attribute name.
myXML	findElement(java.lang.String tag) Find and retrieve the first element that has the specified tag name The search starts with this object and follows all branch and leaf nodes in the XML tree.
myXML	findElement(java.lang.String tag, java.lang.String attname) Find and retrieve the first element that has the specified tag name and the specified attribute name.
myXML	getElement(int index) Retrieve the element object at the specified index.
java.lang.String	getTag() Retrieve the name/tag
java.lang.String	getValue() Retrieve the data value for this element in String form
boolean	isEmpty() Tests if this parent has no subelements
boolean	removeAllElements() Removes all subelements from the specified parent
boolean	removeElement(myXML element) Remove subelement (element) from list of objects for a parent element
void	serialize(java.io.PrintWriter out) Write the XML tree to an output stream in text form.
int	size() Retrieve the number of elements attached to this element
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

Attribute

public myXML.Attribute Attribute

Constructor Detail

myXML

public myXML(java.lang.String tag)

Create new myXML object with no subelements, no attributes, and no value

Parameters:

tag - initial name for the XML element or null for empty element

myXML

public myXML()

myXML

public myXML(java.io.BufferedReader in)
      throws myXML.myXMLException,
             myXML.myXMLEncodingException,
             java.io.IOException

Read the XML tree in from the specified stream. The stream can be anything that can be opened as a BufferedReader which includes URLs and files. The XML tree will be stored in a tree of myXML objects and the root object will be returned.

Parameters:

in - BufferedReader input stream

Throws:

myXML.myXMLException

myXML.myXMLEncodingException

java.io.IOException

Method Detail

getTag

public java.lang.String getTag()

Retrieve the name/tag

Returns:

null if no name set
String object: for the text of the XML element

getValue

public java.lang.String getValue()

Retrieve the data value for this element in String form

Returns:

null if no value set
String object: for the text of the XML element

size

public int size()

Retrieve the number of elements attached to this element

Returns:

int value

findElement

public myXML findElement(java.lang.String tag)

Find and retrieve the first element that has the specified tag name The search starts with this object and follows all branch and leaf nodes in the XML tree.

Returns:

null: no object with the specified tag found
myXML object: First object found with the matching tag

removeElement

public boolean removeElement(myXML element)
                      throws myXML.myXMLException

Remove subelement (element) from list of objects for a parent element

Parameters:

element - element to be removed from object list of parent

Returns:

boolean value set to true if the element was found and removed from the parent

Throws:

myXML.myXMLException

contains

public boolean contains(myXML element)
                 throws myXML.myXMLException

Tests if the specified element is a subelement of this element

Parameters:

element - element to test

Returns:

boolean value set to true if element is found to be subelement

Throws:

myXML.myXMLException

removeAllElements

public boolean removeAllElements()

Removes all subelements from the specified parent

Returns:

boolean value set to true if all subelements removed

isEmpty

public boolean isEmpty()

Tests if this parent has no subelements

Returns:

boolean value set to true if size is zero

findattribute

public myXML findattribute(java.lang.String name)

Find and retrieve the first element that has the specified attribute name. The search starts with this object and follows all branch and leaf nodes in the XML tree.

Returns:

null: No element found with the specified attribute name
myXML object: First object found with the matching attribute name

findElement

public myXML findElement(java.lang.String tag,
                         java.lang.String attname)

Find and retrieve the first element that has the specified tag name and the specified attribute name. The search starts with this object and follows all branch and leaf nodes in the XML tree.

Returns:

null: No element found with the specified tag name and attribute name
myXML object: First object found matching both the tag name and attribute name

getElement

public myXML getElement(int index)

Retrieve the element object at the specified index. The branche and leaf nodes in the XML tree are stored in a Vector and each index represents a node in the tree. Indicies start at 0 and count up to the length of the Vector.

Parameters:

index - integer indicating the branch or leaf of the this XML object

Returns:

null: if index is out of bounds
myXML object: element at the specified index.

addElement

public myXML addElement(java.lang.String tag)
                 throws myXML.myXMLException

Add a subelement which will be used as a branch in the XML tree to the this element of the form:

<tag attr1="attr1value attr2="attr2value" ... >
...
</tag>

Parameters:

tag - String used to identify the element

Returns:

myXML object: the newly created element

Throws:

myXML.myXMLException

addElement

public myXML addElement(java.lang.String tag,
                        java.lang.Object value)
                 throws myXML.myXMLException

Add a leaf element to the XML tree of the form:

<tag attr1="attr1value attr2="attr2value" ... >value</tag>

Parameters:

tag - String used to identify the element

value - Object to use for the element value (Note that the object will be converted to a String before storing in the XML tree.

Returns:

myXML object: the newly created element

Throws:

myXML.myXMLException

serialize

public void serialize(java.io.PrintWriter out)
               throws java.io.IOException

Write the XML tree to an output stream in text form.

Parameters:

out - A PrintWriter object to be used as the output stream for the XML tree.

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object