ecologylab.xml
Class XMLTools

java.lang.Object
  ecologylab.generic.Debug
      ecologylab.xml.types.scalar.TypeRegistry
          ecologylab.xml.XMLTools

All Implemented Interfaces:

CharacterConstants, SpecialCharacterEntities

public class XMLTools
extends TypeRegistry
implements CharacterConstants, SpecialCharacterEntities

Static helper methods that are used during the translation of java objects to XML and back. The XML files can also be compressed by using the compression variable. For compression to work, the developer should provide a abbreviation table in the format listed in the code.

Version:

0.5

Author:

Andruid Kerne, Madhur Khandelwal

Field Summary

Fields inherited from interface ecologylab.xml.CharacterConstants

CR, LF, TAB

Fields inherited from interface ecologylab.xml.SpecialCharacterEntities

ALEFSYM, AND, ANG, ANOTHER_DBL_QUOTE, ANOTHER_QUOTE, ASYMP, BDQUO, BULL, CAP, CIRC, CLUBS, CONG, CRARR, CUP, DAGGER, DAGGER_D, DARR, DARR_D, DBLRARR, DIAMS, EMPTY, EMSP, ENSP, EQUIV, EURO, EXIST, FORALL, FRASL, GE, HARR, HARR_D, HEARTS, HELLIP, IMAGE, INFIN, INT, ISIN, LANG, LARR, LARR_D, LCEIL, LDQUO, LE, LFLOOR, LOWAST, LOZ, LRM, LSAQUO, LSQUO, MDASH, MINUS, NABLA, NDASH, NE, NI, NOTIN, NSUB, OELIG, OELIG_S, OLINE, OPLUS, OR, OTIMES, PART, PERMIL, PERP, PRIME, PRIME_U, PROD, PROP, RADIC, RANG, RARR, RARR_D, RCEIL, RDQUO, REAL, RFLOOR, RLM, RSAQUO, RSQUO, SBQUO, SCARON, SCARON_S, SDOT, SIM, SPADES, SPECIAL_CHARACTER_ENTITIES, SUB, SUBE, SUM, SUP, SUPE, THERE4, THINSP, TILDE, TRADE, UARR, UARR_D, WEIERP, YUML, ZWJ, ZWNJ

Constructor Summary

XMLTools()

Method Summary

static java.lang.String	classNameFromElementName(java.lang.String elementName) This method generates a name for an ElementState object, given an XML element name.
static boolean	equivalentClassAndVarNames(java.lang.reflect.Field field)
static void	escapeXML(java.lang.Appendable appendable, java.lang.CharSequence stringToEscape)
static void	escapeXML(java.lang.StringBuilder buffy, java.lang.CharSequence stringToEscape) Replaces characters that may be confused by a HTML parser with their equivalent character entity references.
static java.lang.String	fieldNameFromElementName(java.lang.String elementName) This method generates a name for an ElementState object, given an XML attribute name.
static java.lang.String	fieldNameFromNodeName(java.lang.String nodeName)
static java.lang.String	fieldNameFromObject(ElementState elementState) This method generates a field name from a reference type nested object.
java.lang.String	getClassName() This method gets the name of this class.
static java.lang.String	getClassName(java.lang.Class thatClass) This method returns the abbreviated name of the class, without the package qualifier.
static java.lang.String	getClassName(java.lang.Object o) This method returns the abbreviated name of the class, without the package qualifier.
static java.util.Collection	getCollection(java.lang.Object object)
static org.w3c.dom.Document	getDocument(java.lang.String contents) Deprecated.
static javax.xml.parsers.DocumentBuilder	getDocumentBuilder()
static java.lang.String[]	getFormatAnnotation(java.lang.reflect.Field field) Seek an @xml_format annotaion on the Field object.
static <T> T	getInstance(java.lang.Class<T> thatClass) Get an instance; generate an XmlTranslationException if there's a problem.
java.lang.String	getPackageName() This method gets the package name of thisJava class.
static java.lang.String	getPackageName(java.lang.Class thatClass) This method gets the package name of a give Java class.
static java.lang.String	getPackageName(java.lang.Object o) This method gets the package name of a give Java class.
static java.lang.String	getXmlTagAnnotationIfPresent(ElementState.xml_tag tagAnnotation)
static java.lang.String	getXmlTagName(java.lang.Class<?> thatClass, java.lang.String suffix) This method generates a name for the xml tag given a reference type java object.
static java.lang.String	getXmlTagName(java.lang.reflect.Field thatField) This method generates a name for the xml tag given a reference type java object.
static java.lang.String	getXmlTagName(java.lang.String className, java.lang.String suffix) This method generates a name for the xml tag given a reference type java object.
static boolean	isScalarValue(java.lang.reflect.Field field)
static java.lang.String	javaNameFromElementName(java.lang.String elementName, boolean capsOn) Generate the name of a Java class (capitalized) or field (starts with lower case), given the name of an XML tag or attribute.
static void	main(java.lang.String[] a)
static java.lang.String	methodNameFromTagName(java.lang.String tagName) This method generates a name for the *setter* method for a given Java primitive type.
static java.lang.String	nameVal(java.lang.String label, boolean val)
static java.lang.String	nameVal(java.lang.String label, float val)
static java.lang.String	nameVal(java.lang.String label, long val)
static java.lang.String	nameVal(java.lang.String label, java.lang.String val)
static java.lang.String	nameVal(java.lang.String label, java.net.URL val)
static void	oldEscapeXML(java.lang.StringBuilder result, java.lang.CharSequence stringToEscape) Replaces characters that may be confused by a HTML parser with their equivalent character entity references.
static void	propagateFields(java.lang.Object src, java.lang.Object dest) This method propages the values of all the primitive types from the source object to the destination object.
static boolean	representAsCollection(java.lang.reflect.Field field)
static boolean	representAsCollectionOrMap(java.lang.reflect.Field field)
static boolean	representAsLeaf(java.lang.reflect.Field field)
static boolean	representAsMap(java.lang.reflect.Field field)
static boolean	representAsNested(java.lang.reflect.Field field)
static boolean	representAsText(java.lang.reflect.Field field)
java.lang.String	toString()
static java.lang.String	toString(java.lang.Object o)
static java.lang.String	toString(java.lang.StringBuilder buffer) Use this method to efficiently get a String from a StringBuilder on those occassions when you plan to keep using the StringBuilder, and want an efficiently made copy.
static java.lang.String	unescapeXML(java.lang.String s) Translate XML named entity special characters into their Unicode char equivalents.
static void	unescapeXML(java.lang.StringBuilder buffy)
static void	unescapeXML(java.lang.StringBuilder buffy, int startPos) Translate XML named entity special characters into their Unicode char equivalents.
static java.lang.String	wrapInHTMLTags(java.lang.String htmlFragmentString) Wrap the passed in argument in HTML tags, so it can be parsed as XML.
static void	writePrettyXML(org.w3c.dom.Document xmlDoc, java.io.File outFile) Pretty printing XML, properly indented according to hierarchy.
static void	writePrettyXML(org.w3c.dom.Document xmlDoc, java.io.OutputStream outputStream) Pretty print XML, properly indented according to hierarchy.
static java.lang.String	xmlHeader()
static java.lang.String	xmlTagFromObject(java.lang.Object obj, java.lang.String suffix) This method generates a name for the xml tag given a reference type java object.

Methods inherited from class ecologylab.xml.types.scalar.TypeRegistry

contains, contains, getType, getType, getType, register

Methods inherited from class ecologylab.generic.Debug

classSimpleName, closeLoggingFile, debug, debug, debug, debug, debugA, debugA, debugA, debugI, debugI, debugI, error, error, getInteractive, getPackageName, initialize, level, level, level, logToFile, print, print, println, println, println, println, println, println, printlnA, printlnA, printlnA, printlnI, printlnI, printlnI, printlnI, setLoggingFile, show, show, superString, toggleInteractive, warning, warning, weird, weird

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLTools

public XMLTools()

Method Detail

xmlTagFromObject

public static java.lang.String xmlTagFromObject(java.lang.Object obj,
                                                java.lang.String suffix)

This method generates a name for the xml tag given a reference type java object. This is used during the translation of Java to xml. Part of this is to translate mixed case class name word separation into "_" word separtion.

Parameters:

obj - a java reference type object

suffix - string to remove from class name, null if nothing to be removed

Returns:

name of the xml tag (element)

getXmlTagName

public static java.lang.String getXmlTagName(java.lang.Class<?> thatClass,
                                             java.lang.String suffix)

This method generates a name for the xml tag given a reference type java object. This is used during the translation of Java to xml. Part of this is to translate mixed case class name word separation into "_" word separtion.

Parameters:

thatClass - Class object to translate.

suffix - string to remove from class name, null if nothing to be removed

Returns:

name of the xml tag (element)

getXmlTagName

public static java.lang.String getXmlTagName(java.lang.reflect.Field thatField)

This method generates a name for the xml tag given a reference type java object. This is used during the translation of Java to xml. Part of this is to translate mixed case class name word separation into "_" word separtion.

Parameters:

describedClass - Class object to translate.

suffix - string to remove from class name, null if nothing to be removed

Returns:

name of the xml tag (element)

getXmlTagAnnotationIfPresent

public static java.lang.String getXmlTagAnnotationIfPresent(ElementState.xml_tag tagAnnotation)

getXmlTagName

public static java.lang.String getXmlTagName(java.lang.String className,
                                             java.lang.String suffix)

This method generates a name for the xml tag given a reference type java object. This is used during the translation of Java to xml. Part of this is to translate mixed case class name word separation into "_" word separtion.

Parameters:

className - class name of a java reference type object

suffix - string to remove from class name, null if nothing to be removed

Returns:

name of the xml tag (element)

classNameFromElementName

public static java.lang.String classNameFromElementName(java.lang.String elementName)

This method generates a name for an ElementState object, given an XML element name. It is used during translation of XML to Java. Using the returned class name, the appropriate class can be instantiated using reflection.

Parameters:

elementName - the name of the XML element

Returns:

the name of the Java class corresponding to the elementName

fieldNameFromElementName

public static java.lang.String fieldNameFromElementName(java.lang.String elementName)

This method generates a name for an ElementState object, given an XML attribute name. It is used during translation of XML to Java. Using the returned class name, the appropriate class can be instantiated using reflection.

Parameters:

elementName - the name of the XML element attribute

Returns:

the name of the Java class corresponding to the elementName

javaNameFromElementName

public static java.lang.String javaNameFromElementName(java.lang.String elementName,
                                                       boolean capsOn)

Generate the name of a Java class (capitalized) or field (starts with lower case), given the name of an XML tag or attribute. Used during translation of XML to Java.

Parameters:

elementName - the name of the XML element or tag

capsOn - true if the first letter of output should be capitalized.

Returns:

the name of the Java class corresponding to the elementName

fieldNameFromNodeName

public static java.lang.String fieldNameFromNodeName(java.lang.String nodeName)

methodNameFromTagName

public static java.lang.String methodNameFromTagName(java.lang.String tagName)

This method generates a name for the *setter* method for a given Java primitive type. For example, for the attribute intensity , it will generate a setter method named setIntensity . It is used during translation of xml to Java. Using this method name, the appropriate field is populated.

Parameters:

tagName - the name of the xml element or tag

Returns:

the name of the *setter* method corresponding to the tagName

fieldNameFromObject

public static java.lang.String fieldNameFromObject(ElementState elementState)

This method generates a field name from a reference type nested object. It just converts the camelcase name to the lowercase. This is used while generating xml from Java.

Parameters:

elementState - the reference type field for which a field field name needs to be generated

Returns:

field name for the given reference type field

getClassName

public static java.lang.String getClassName(java.lang.Class thatClass)

This method returns the abbreviated name of the class, without the package qualifier. It also puts the name into a hashtable, so that next time the function is called for the same class, the class name can be retrieved quickly from the hashtable. Used while generating xml from Java.

Parameters:

thatClass - the Class type of an object

Returns:

the abbreviated name of the class - without the package qualifier

getPackageName

public static java.lang.String getPackageName(java.lang.Class thatClass)

This method gets the package name of a give Java class. It also puts the name into a hashtable, so that next time the function is called for the same class, the package name can be retrieved quickly from the hashtable. Used while generating Java class from xml.

Parameters:

thatClass - the Class type of an object

Returns:

the package name of the class, with an extra "." at the end.

getClassName

public static java.lang.String getClassName(java.lang.Object o)

This method returns the abbreviated name of the class, without the package qualifier.

Parameters:

o - the object

Returns:

the abbreviated name of the class - without the package qualifier.

getClassName

public java.lang.String getClassName()

This method gets the name of this class.

Overrides:

getClassName in class Debug

Returns:

the abbreviated name of this class - without the package qualifier

getPackageName

public static java.lang.String getPackageName(java.lang.Object o)

This method gets the package name of a give Java class. Used while generating Java class from xml.

Parameters:

o - the Class type of an object

Returns:

the package name of the class

getPackageName

public java.lang.String getPackageName()

This method gets the package name of thisJava class.

Overrides:

getPackageName in class Debug

Returns:

the package name of the class

toString

public java.lang.String toString()

Overrides:

toString in class Debug

getFormatAnnotation

public static java.lang.String[] getFormatAnnotation(java.lang.reflect.Field field)

Seek an @xml_format annotaion on the Field object. If there is one with a non-zero length, return it.

Parameters:

field -

Returns:

An array of Strings with format info in them, or null if there wasn't one or it was empty.

getInstance

public static <T> T getInstance(java.lang.Class<T> thatClass)
                     throws XMLTranslationException

Get an instance; generate an XmlTranslationException if there's a problem.

Parameters:

thatClass - The type of the object to translate in to.

Returns:

The resulting object.

Throws:

XMLTranslationException - If the constructor fails, or if that class lacks a constructor that takes no parameters.

toString

public static java.lang.String toString(java.lang.Object o)

nameVal

public static java.lang.String nameVal(java.lang.String label,
                                       java.lang.String val)

nameVal

public static java.lang.String nameVal(java.lang.String label,
                                       java.net.URL val)

nameVal

public static java.lang.String nameVal(java.lang.String label,
                                       long val)

nameVal

public static java.lang.String nameVal(java.lang.String label,
                                       boolean val)

nameVal

public static java.lang.String nameVal(java.lang.String label,
                                       float val)

propagateFields

public static void propagateFields(java.lang.Object src,
                                   java.lang.Object dest)

This method propages the values of all the primitive types from the source object to the destination object.

Parameters:

src - source object from the values need to be copies

dest - destination object to which the values need to be copied

toString

public static final java.lang.String toString(java.lang.StringBuilder buffer)

Use this method to efficiently get a String from a StringBuilder on those occassions when you plan to keep using the StringBuilder, and want an efficiently made copy. In those cases, much better than new String(StringBuilder)

xmlHeader

public static java.lang.String xmlHeader()

unescapeXML

public static java.lang.String unescapeXML(java.lang.String s)

Translate XML named entity special characters into their Unicode char equivalents.

unescapeXML

public static void unescapeXML(java.lang.StringBuilder buffy)

unescapeXML

public static void unescapeXML(java.lang.StringBuilder buffy,
                               int startPos)

Translate XML named entity special characters into their Unicode char equivalents.

oldEscapeXML

public static void oldEscapeXML(java.lang.StringBuilder result,
                                java.lang.CharSequence stringToEscape)

Replaces characters that may be confused by a HTML parser with their equivalent character entity references.

Parameters:

stringToEscape - original string which may contain some characters which are confusing to the HTML parser, for eg. < and >

escapeXML

public static void escapeXML(java.lang.StringBuilder buffy,
                             java.lang.CharSequence stringToEscape)

Replaces characters that may be confused by a HTML parser with their equivalent character entity references.

Parameters:

stringToEscape - original string which may contain some characters which are confusing to the HTML parser, for eg. < and >

escapeXML

public static void escapeXML(java.lang.Appendable appendable,
                             java.lang.CharSequence stringToEscape)
                      throws java.io.IOException

Throws:

java.io.IOException

getDocument

public static org.w3c.dom.Document getDocument(java.lang.String contents)

Deprecated.

Generate a DOM tree from a given String in the XML form.

Uses the deprecated StringBufferInputStream class.

Parameters:

contents - the string for which the DOM needs to be constructed.

Returns:

the DOM tree representing the XML string.

getDocumentBuilder

public static javax.xml.parsers.DocumentBuilder getDocumentBuilder()
                                                            throws javax.xml.parsers.ParserConfigurationException

Throws:

javax.xml.parsers.ParserConfigurationException

writePrettyXML

public static void writePrettyXML(org.w3c.dom.Document xmlDoc,
                                  java.io.File outFile)
                           throws XMLTranslationException

Pretty printing XML, properly indented according to hierarchy.

Parameters:

xmlDoc -

outputStreamWriter -

Throws:

java.io.FileNotFoundException

XMLTranslationException

writePrettyXML

public static void writePrettyXML(org.w3c.dom.Document xmlDoc,
                                  java.io.OutputStream outputStream)
                           throws XMLTranslationException

Pretty print XML, properly indented according to hierarchy.

Parameters:

xmlDoc -

out -

Throws:

XMLTranslationException

java.io.IOException

equivalentClassAndVarNames

public static boolean equivalentClassAndVarNames(java.lang.reflect.Field field)

Parameters:

field -

Returns:

true if the class name and variable name for the field are equivalent. This is the case when the variable name is capitalized, it equals the class name.

getCollection

public static java.util.Collection getCollection(java.lang.Object object)

Parameters:

object - which might be representable as a collection. Must not be null.

Returns:

if the Object passed in is of Collection or Map type, return a Collection representing it.
else return null.

representAsLeaf

public static boolean representAsLeaf(java.lang.reflect.Field field)

representAsText

public static boolean representAsText(java.lang.reflect.Field field)

representAsNested

public static boolean representAsNested(java.lang.reflect.Field field)

representAsCollectionOrMap

public static boolean representAsCollectionOrMap(java.lang.reflect.Field field)

representAsMap

public static boolean representAsMap(java.lang.reflect.Field field)

representAsCollection

public static boolean representAsCollection(java.lang.reflect.Field field)

isScalarValue

public static boolean isScalarValue(java.lang.reflect.Field field)

Parameters:

field -

Returns:

true if the Field is one translated by the Type system.

wrapInHTMLTags

public static java.lang.String wrapInHTMLTags(java.lang.String htmlFragmentString)

Wrap the passed in argument in HTML tags, so it can be parsed as XML.

Parameters:

htmlFragmentString - A piece of valid XHTML.

Returns:

main

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