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, ASYMP, BDQUO, BULL, CAP, CIRC, CLUBS, CONG, CRARR, CUP, DAGGER, DAGGER_D, DARR, DARR_D, 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	attrNameFromField(java.lang.reflect.Field field, boolean compression) This method name for the attribute given a field name, which is a primitive java type.
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.
void	generateNameVal(java.lang.StringBuilder result, java.lang.reflect.Field field, java.lang.Object obj)
static void	generateNameVal(java.lang.StringBuilder result, java.lang.reflect.Field field, java.lang.Object obj, int floatingValuePrecision) This method generates a name value pair corresponding to the primitive Jave field.
static void	generateNameVal(java.lang.StringBuilder buffy, ScalarType type, java.lang.reflect.Field field, java.lang.Object context, int floatingValuePrecision) This method generates a name value pair corresponding to the primitive Jave field.
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 <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	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.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 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.
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 java.lang.StringBuilder	unescapeXML(java.lang.StringBuilder sb, 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, 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

clone, equals, finalize, 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.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)

attrNameFromField

public static java.lang.String attrNameFromField(java.lang.reflect.Field field,
                                                 boolean compression)

This method name for the attribute given a field name, which is a primitive java type. This is used during the translation from Java to xml.

Parameters:

field - the field(primitive type) in the state-class

compression - if the name of the field should be abbreviated

Returns:

name of the attribute for the xml

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

generateNameVal

public static void generateNameVal(java.lang.StringBuilder result,
                                   java.lang.reflect.Field field,
                                   java.lang.Object obj,
                                   int floatingValuePrecision)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalAccessException

This method generates a name value pair corresponding to the primitive Jave field. Returns an empty string if the field contains a default value, which means that there is no need to emit that field. Used while translation of Java to xml.

For efficiency, the result is passed back in the StringBuilder passed in.

Parameters:

result - StringBuilder to append result to. Result is name-value pair of the attribute, nothing if the field has a default value.

field - A ScalarValued Field object.

obj - The object which contains the field

floatingValuePrecision - Allows truncation of floating point precision for shorter XML.

Throws:

java.lang.IllegalAccessException

java.lang.IllegalArgumentException

generateNameVal

public static void generateNameVal(java.lang.StringBuilder buffy,
                                   ScalarType type,
                                   java.lang.reflect.Field field,
                                   java.lang.Object context,
                                   int floatingValuePrecision)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalAccessException

This method generates a name value pair corresponding to the primitive Jave field. Returns an empty string if the field contains a default value, which means that there is no need to emit that field. Used while translation of Java to xml.

For efficiency, the result is passed back in the StringBuilder passed in.

Parameters:

buffy - StringBuilder to append result to. Result is name-value pair of the attribute, nothing if the field has a default value.

field - A ScalarValued Field object.

context - The object which contains the field

floatingValuePrecision - Allows truncation of floating point precision for shorter XML.

Throws:

java.lang.IllegalAccessException

java.lang.IllegalArgumentException

generateNameVal

public void generateNameVal(java.lang.StringBuilder result,
                            java.lang.reflect.Field field,
                            java.lang.Object obj)
                     throws java.lang.IllegalArgumentException,
                            java.lang.IllegalAccessException

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

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

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 java.lang.StringBuilder unescapeXML(java.lang.StringBuilder sb,
                                                  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.

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: