com.purplehillsbooks.xml

Class Mel

java.lang.Object

com.purplehillsbooks.xml.Mel

Direct Known Subclasses:

Schema, SchemaDef, ValidationResults

public class Mel
extends java.lang.Object

Mel = Mendocino Element The purpose of this class is to be a base class to classes which are designed to be interfaced to DOM trees. If you have a DOM tree, and you want to directly reflect that out to the program as structured data, you create a file that has getters and setters for the various members. This base class containes convenient methods for manipulating the DOM tree, and keeping it in sync with the external representation you are presenting. GETTERS: pull values directly from child dom elements. Useful when a particular member is gotten only a few times any reading of the file. If this is a heavily used member, prefectch that to a cache member, and use that. SETTERS: put value directly into child dom elements. If you have decided to use a cache member for fast access, don't forget to update both the cache and the dom tree. Author: Keith Swenson Copyright: Keith Swenson, all rights reserved License: This code is made available under the GNU Lesser GPL license.

Constructor Summary

Constructors

Constructor and Description
Mel(org.w3c.dom.Document doc, org.w3c.dom.Element ele) Standard constructor for a Mel on an existing XML tree.

Method Summary

Modifier and Type	Method and Description
Mel	addChild(java.lang.String elementName) Creates a child element of the Mel class.
<T extends Mel> T	addChild(java.lang.String elementName, java.lang.Class<T> childClass) Creates a child element of your own class that extends the Mel class
void	addVectorValue(java.lang.String memberName, java.lang.String value) If a containing tag has multiple child value tags you append a value to that set of values.
static java.lang.String	assureValidXMLChars(java.lang.String input)
boolean	attributeEquals(java.lang.String attrName, java.lang.String testValue) Retrieves an attribute value from a tag, and compares it to a given value, returning true if they are equal.
static <T extends Mel> T	construct(java.lang.Class<T> childClass, org.w3c.dom.Document doc, org.w3c.dom.Element ele) Constructs an instance of an extended class.
<T extends Mel> T	convertClass(java.lang.Class<T> desiredClass) Constructs an instance of an extended class.
protected static org.w3c.dom.Document	convertInputStreamToDocument(java.io.InputStream is)
protected static org.w3c.dom.Document	createDocument(java.lang.String rootNodeName) This method creates a new Document Object.
static <T extends Mel> T	createEmpty(java.lang.String rootElement, java.lang.Class<T> rootClass) Use this to create a brand new base of the tree of the file.
void	eliminateCData()
<T extends Mel> T	findChild(java.lang.String elementName, java.lang.String attributeName, java.lang.String keyValue, java.lang.Class<T> childClass) Returns a child object of specific class with a specified name, attribute, and value
java.util.Vector<java.lang.String>	getAllAttributeNames()
java.util.Vector<Mel>	getAllChildren() getAllChildren will return a vector of Mels, one for each existing child element, as well as one for each existing data value.
java.lang.String	getAttribute(java.lang.String attrName) If a containing tag has an attribute, getAttribute will return the string value of that attribute.
long	getAttributeLong(java.lang.String attrName) If a containing tag has an attribute, and that attribute contains an integer string value, then getAttribute will return the long value of that attribute.
Mel	getChild(java.lang.String elementName, int index) Returns a child Mel object with a specified name.
<T extends Mel> T	getChild(java.lang.String elementName, int index, java.lang.Class<T> childClass) Returns a child object of the specified class with a specified name.
java.util.Vector<Mel>	getChildren(java.lang.String elementName)
<T extends Mel> java.util.Vector<T>	getChildren(java.lang.String elementName, java.lang.Class<T> childClass)
java.lang.String	getDataValue() If you call "getAllChildren" you will get Mels that represent containers, as well as ones that represent data.
org.w3c.dom.Document	getDocument()
org.w3c.dom.Element	getElement() Avoid using this, but provided for interfacing to external libraries
java.lang.String	getFormattedString() You really don't want to ever have XML in a string.
java.lang.String	getName() The name of the data element that this object represents.
java.lang.String	getPrefix() This returns the namespace prefix, if there is one.
static void	getRawChildren(org.w3c.dom.Element parent, java.lang.StringBuffer sb, java.lang.String place)
java.lang.String	getRawDOM()
java.lang.String	getScalar(java.lang.String memberName) If a containing tag has a child value tag getScalar will find that tag, and return the string value.
java.util.Vector<java.lang.String>	getVector(java.lang.String memberName) If a containing tag has multiple child value tags you can access all the values at once, retrieving a vector of string values.
boolean	isContainer() Generally a Mel is a container, meaning it can have children which are either more Mel or data values.
static <T extends Mel> T	parseString(java.lang.String input, java.lang.Class<T> rootClass) You really should never use this.
static <T extends Mel> T	readFile(java.io.File inFile, java.lang.Class<T> rootClass) Given a File object (that points to a real existing MDS file) This global static method will read the file and return a Mel for the base of the tree of the file.
static <T extends Mel> T	readInputStream(java.io.InputStream is, java.lang.Class<T> rootClass) Given a byte stream (that points to a real existing MDS file) this global static method will read the stream and return a Mel for the base of the tree of the file.
void	reformatXML()
void	removeAllNamedChild(java.lang.String elementName)
void	removeChild(Mel mele)
static int	safeConvertInt(java.lang.String val) designed primarily for returning date long values works only for positive integer (long) values considers all numeral, ignores all letter and punctuation never throws an exception if you give this something that is not a number, you get surprising result.
static long	safeConvertLong(java.lang.String val) designed primarily for returning date long values works only for positive integer (long) values considers all numeral, ignores all letter and punctuation never throws an exception if you give this something that is not a number, you get surprising result.
void	setAttribute(java.lang.String attrName, java.lang.String value) Sets an attribute and value on a tag.
void	setAttributeInt(java.lang.String attrName, int value)
void	setAttributeLong(java.lang.String attrName, long value) Sets an attribute and an integer (long) value on a tag.
void	setScalar(java.lang.String memberName, java.lang.String value) setScalar will create a child value tag of a specified name and value for the containing element.
void	setVector(java.lang.String memberName, java.util.Vector<java.lang.String> values) If a containing tag has multiple child value tags you can access and set all the values at once using a vector of string values.
static void	writeShortLiteralValue(java.lang.StringBuffer sb, java.lang.String value)
void	writeToFile(java.io.File outFile) As you might have guessed from the name, the writeToFile method will write the entire tree out to a file.
void	writeToOutputStream(java.io.OutputStream out) writeToOutputStream streams the entire XML output that reflects the entire tree to an output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mel

public Mel(org.w3c.dom.Document doc,
           org.w3c.dom.Element ele)

Standard constructor for a Mel on an existing XML tree. If you have a XML document which you know is a MDS file you can use this constructor to make a single Mel that wraps an XML element. Children elements are not created until asked for.

Method Detail

construct

public static <T extends Mel> T construct(java.lang.Class<T> childClass,
                                          org.w3c.dom.Document doc,
                                          org.w3c.dom.Element ele)
                                   throws java.lang.Exception

Constructs an instance of an extended class. This is used by all the methods that take a class name and return elements of specific subclasses.

Throws:

java.lang.Exception

convertClass

public <T extends Mel> T convertClass(java.lang.Class<T> desiredClass)
                               throws java.lang.Exception

Constructs an instance of an extended class. This is used by all the methods that take a class name and return elements of specific subclasses.

Throws:

java.lang.Exception

readFile

public static <T extends Mel> T readFile(java.io.File inFile,
                                         java.lang.Class<T> rootClass)
                                  throws java.lang.Exception

Given a File object (that points to a real existing MDS file) This global static method will read the file and return a Mel for the base of the tree of the file.

Throws:

java.lang.Exception

readInputStream

public static <T extends Mel> T readInputStream(java.io.InputStream is,
                                                java.lang.Class<T> rootClass)
                                         throws java.lang.Exception

Given a byte stream (that points to a real existing MDS file) this global static method will read the stream and return a Mel for the base of the tree of the file. Encoding is always UTF-8.

Throws:

java.lang.Exception

parseString

public static <T extends Mel> T parseString(java.lang.String input,
                                            java.lang.Class<T> rootClass)
                                     throws java.lang.Exception

You really should never use this. XML should only be handled as a stream of bytes and NEVER as a string, however, sometimes particular poorly designed API will pass around XML as a string, and this convenient method will parse it for you.

Throws:

java.lang.Exception

createEmpty

public static <T extends Mel> T createEmpty(java.lang.String rootElement,
                                            java.lang.Class<T> rootClass)
                                     throws java.lang.Exception

Use this to create a brand new base of the tree of the file.

Throws:

java.lang.Exception

writeToOutputStream

public void writeToOutputStream(java.io.OutputStream out)
                         throws java.lang.Exception

writeToOutputStream streams the entire XML output that reflects the entire tree to an output stream. Encoding is always UTF-8.

Throws:

java.lang.Exception

getFormattedString

public java.lang.String getFormattedString()
                                    throws java.lang.Exception

You really don't want to ever have XML in a string. XML should always be a byte stream and only the values turned into Strings when needed, but there are times that you need the XML as a string to pass to some other processing unit. This allows getting the XML formatted as a string. Try not to ever use this.

Throws:

java.lang.Exception

writeToFile

public void writeToFile(java.io.File outFile)
                 throws java.lang.Exception

As you might have guessed from the name, the writeToFile method will write the entire tree out to a file. You must pass in a valid full path to a file name.

To assure atomic writing, the file is first output to a temporary file that is the same name, but with a "tmp-###" appended to the end of the name. Only when the entire tree is successfully output to the file, then the file is renamed to the desired name.

If there was a file already there with that name, then that file will be deleted, just before the temporary file is renamed to the desired name.

If your program crashes for any reason before the entire file is output, the result will be that the previous version of the file will still be there, and there will be a partially written file with a "tmp-###" appended to the end. Since these are most likely fragments of the entire file, they are not valid XML files, and can not be parsed. They should be discarded, and the cause of the crash researched. There are no normal situation that these files should be seen left in the file system.

Here is a specific example. If you want to write to a file with the path "c:/data/MyConfig.cfg" the folder "c:/data" must exist. The output routine will choose a random number, for example '137' and will write the contents of the tree to "c:/data/MyConfig.cfg-tmp-137". Once the file is completely output to disk, the old file "MyConfig.cfg" is deleted, and the temp file is renamed to "MyConfig.cfg".

With this approach you are most likely to always have a valid file with the desired name. There is an extremely small possibility that the program might crash between the deletion of the old file, and the renaming of the temp file, leaving you with no file at all with the desired name. There is a very small window of time between these two operations where another program or another thread might find the file missing from the file system. This seems to be a limitation that we have to live with until Java offer an atomic rename-and-delete-previous-file operation.

Throws:

java.lang.Exception

getName

public java.lang.String getName()

The name of the data element that this object represents.

getPrefix

public java.lang.String getPrefix()

This returns the namespace prefix, if there is one. Returns an empty string if not.

isContainer

public boolean isContainer()

Generally a Mel is a container, meaning it can have children which are either more Mel or data values. When retrieving a data value (either scalar or vector), the methods return the value directly. But some methods return all children as a single collection, including both data values and containers. This is convenient for traversing the tree and generating output. In those situations you need to call this method "isContainer" to determine if this particular node contains only text, or whether it can have structured children. Note: there is one situation where it is impossible to know whether it is a container or not, and that is when the tag is completely empty and it has no attributes. In this case it might be a data value without any data, or it might be a container without any contents. Either way it is empty. This function returns false in this ambiguous case, thus an element that is normally a container will return false (not a container) if it is completely empty.

getDataValue

public java.lang.String getDataValue()

If you call "getAllChildren" you will get Mels that represent containers, as well as ones that represent data. If the "isContainer" method returns false, then it represents a data element, and this method will return the string value for that data element.

getAttribute

public java.lang.String getAttribute(java.lang.String attrName)

If a containing tag has an attribute, getAttribute will return the string value of that attribute. attrName: the name of the attribute holding a data value returns: a string values

getAttributeLong

public long getAttributeLong(java.lang.String attrName)

If a containing tag has an attribute, and that attribute contains an integer string value, then getAttribute will return the long value of that attribute. A "forgiving" conversion is used which does not complain if non-numeral characters are included, it simply uses any numerals it finds to return the result as if it was only numerals. If there are no numerals at all, or if the attribute does not have a value, it simply returns zero. The reason for using this is because MDF files are designed for interchange between systems. If the value contains an integer then this conversion will proceed correctly, but if the file generated by some other program has the wrong value in the attribute, the problem is essentially ignored. This approach allows commas (or periods) to group thousands and they will be ignored. It successfully ignores all currency symbols or other unit indicators that might be there. Most importantly, it does not throw exceptions ever. attrName: the name of the attribute holding a data value returns: a long value

setAttribute

public void setAttribute(java.lang.String attrName,
                         java.lang.String value)

Sets an attribute and value on a tag. This will replace any value that already exists there. attrName: the name of the attribute holding a data value value: a string value

setAttributeLong

public void setAttributeLong(java.lang.String attrName,
                             long value)

Sets an attribute and an integer (long) value on a tag. This will replace any value that already exists there. attrName: the name of the attribute holding a data value value: a long value

setAttributeInt

public void setAttributeInt(java.lang.String attrName,
                            int value)

attributeEquals

public boolean attributeEquals(java.lang.String attrName,
                               java.lang.String testValue)
                        throws java.lang.Exception

Retrieves an attribute value from a tag, and compares it to a given value, returning true if they are equal. This is convenient when looking through a list of data elements to find one with a particular attribute value. The most common use for this is an "id" attribute. This is convenient for finding a particular data element with a particular id value. attrName: the name of the attribute holding a data value testValue: a string value to test against

Throws:

java.lang.Exception

getAllAttributeNames

public java.util.Vector<java.lang.String> getAllAttributeNames()

getScalar

public java.lang.String getScalar(java.lang.String memberName)

If a containing tag has a child value tag getScalar will find that tag, and return the string value. memberName: the name of the tag holding a data value returns: a string value

setScalar

public void setScalar(java.lang.String memberName,
                      java.lang.String value)

setScalar will create a child value tag of a specified name and value for the containing element. setScalar will also remove the child value tag if you pass a null for the value parameter. memberName: the name of the tag holding a data value value: a string value to put in the tag.

getVector

public java.util.Vector<java.lang.String> getVector(java.lang.String memberName)

If a containing tag has multiple child value tags you can access all the values at once, retrieving a vector of string values. Call getVector with the name of the tag(s) that hold the data. Each such tag will be accessed, and the value included in the vector in the same order. memberName: the name of the tag holding a data value returns: a Vector of string values

setVector

public void setVector(java.lang.String memberName,
                      java.util.Vector<java.lang.String> values)

If a containing tag has multiple child value tags you can access and set all the values at once using a vector of string values. Construct a vector will all of the string value in the correct order. Call setVector, and a child tag and value will be created in the DOM tree for each value in the vector. Any previous values will be removed. memberName: the name of the tag holding a data value values: a Vector of string values

addVectorValue

public void addVectorValue(java.lang.String memberName,
                           java.lang.String value)

If a containing tag has multiple child value tags you append a value to that set of values. memberName: the name of the tag holding a data value value: a string value to be added

addChild

public <T extends Mel> T addChild(java.lang.String elementName,
                                  java.lang.Class<T> childClass)
                           throws java.lang.Exception

Creates a child element of your own class that extends the Mel class

Throws:

java.lang.Exception

addChild

public Mel addChild(java.lang.String elementName)
             throws java.lang.Exception

Creates a child element of the Mel class. Use this when you don't have a custom Mel class to handle that part of the document.

Throws:

java.lang.Exception

removeChild

public void removeChild(Mel mele)
                 throws java.lang.Exception

Throws:

java.lang.Exception

removeAllNamedChild

public void removeAllNamedChild(java.lang.String elementName)
                         throws java.lang.Exception

Throws:

java.lang.Exception

getChild

public Mel getChild(java.lang.String elementName,
                    int index)
             throws java.lang.Exception

Returns a child Mel object with a specified name. If you pass an index of 0, it will return the first element found.

Throws:

java.lang.Exception

getChild

public <T extends Mel> T getChild(java.lang.String elementName,
                                  int index,
                                  java.lang.Class<T> childClass)
                           throws java.lang.Exception

Returns a child object of the specified class with a specified name. If you pass an index of 0, it will return the first element found.

Throws:

java.lang.Exception

findChild

public <T extends Mel> T findChild(java.lang.String elementName,
                                   java.lang.String attributeName,
                                   java.lang.String keyValue,
                                   java.lang.Class<T> childClass)
                            throws java.lang.Exception

Returns a child object of specific class with a specified name, attribute, and value

Throws:

java.lang.Exception

getChildren

public java.util.Vector<Mel> getChildren(java.lang.String elementName)
                                  throws java.lang.Exception

Throws:

java.lang.Exception

getChildren

public <T extends Mel> java.util.Vector<T> getChildren(java.lang.String elementName,
                                                       java.lang.Class<T> childClass)
                                                throws java.lang.Exception

Throws:

java.lang.Exception

getAllChildren

public java.util.Vector<Mel> getAllChildren()
                                     throws java.lang.Exception

getAllChildren will return a vector of Mels, one for each existing child element, as well as one for each existing data value. This is a rare case that data is returned not as a string, but as a Mel. You must use "isContainer" method to determine whether this element is a data value or not.

Throws:

java.lang.Exception

getElement

public org.w3c.dom.Element getElement()

Avoid using this, but provided for interfacing to external libraries

getDocument

public org.w3c.dom.Document getDocument()

safeConvertLong

public static long safeConvertLong(java.lang.String val)

designed primarily for returning date long values works only for positive integer (long) values considers all numeral, ignores all letter and punctuation never throws an exception if you give this something that is not a number, you get surprising result. Zero if no numerals at all.

safeConvertInt

public static int safeConvertInt(java.lang.String val)

designed primarily for returning date long values works only for positive integer (long) values considers all numeral, ignores all letter and punctuation never throws an exception if you give this something that is not a number, you get surprising result. Zero if no numerals at all.

reformatXML

public void reformatXML()
                 throws java.lang.Exception

Throws:

java.lang.Exception

eliminateCData

public void eliminateCData()
                    throws java.lang.Exception

Throws:

java.lang.Exception

createDocument

protected static org.w3c.dom.Document createDocument(java.lang.String rootNodeName)
                                              throws java.lang.Exception

This method creates a new Document Object. Pass in the name of the root node, since you ALWAYS need a root node, and attaching this to the document is not like other children. Retrieve the root element with the standard getDocumentElement.

Throws:

java.lang.Exception

convertInputStreamToDocument

protected static org.w3c.dom.Document convertInputStreamToDocument(java.io.InputStream is)
                                                            throws java.lang.Exception

Throws:

java.lang.Exception

assureValidXMLChars

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

getRawDOM

public java.lang.String getRawDOM()

getRawChildren

public static void getRawChildren(org.w3c.dom.Element parent,
                                  java.lang.StringBuffer sb,
                                  java.lang.String place)

writeShortLiteralValue

public static void writeShortLiteralValue(java.lang.StringBuffer sb,
                                          java.lang.String value)