net.sf.practicalxml

Class XmlUtil

java.lang.Object

net.sf.practicalxml.XmlUtil

public class XmlUtil
extends Object

A collection of static methods for manipulating XML as text.

Constructor Summary

Constructors

Constructor and Description
XmlUtil()

Method Summary

Methods

Modifier and Type	Method and Description
static String	escape(String s) Escapes the passed string, converting the five reserved XML characters into their entities: &, <, >, ', and ".
static String	formatXsdBoolean(boolean value) Converts a boolean value to the literal strings "true" or "false" (XML Schema boolean fields also allow "1" or "0").
static String	formatXsdDatetime(Date date) Converts a Java Date object to a string, using the format specified by XML Schema for dateTime elements.
static String	formatXsdDecimal(double value) Converts a Java double to a string, using the format specified by XML Schema for decimal elements.
static String	formatXsdDecimal(Number value) Converts a Java double to a string, using the format specified by XML Schema for decimal elements.
static boolean	isLegal(String s) Determines whether the passed string contains any illegal characters, per section 2.2 of the XML spec.
static boolean	parseXsdBoolean(String value) Parses an XML Schema boolean value, accepting any of the legal formats and trimming whitespace.
static Date	parseXsdDatetime(String value) Parses an XML Schema dateTime value, accepting any of the legal formats.
static BigDecimal	parseXsdDecimal(String value) Parses an XML Schema decimal value.
static String	stripIllegals(String s) Removes all illegal characters from the passed string.
static String	unescape(String s) Unescapes the passed string, converting the five XML entities (&, <, >, ', and ") into their correspinding characters.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlUtil

public XmlUtil()

Method Detail

isLegal

public static boolean isLegal(String s)

Determines whether the passed string contains any illegal characters, per section 2.2 of the XML spec. This is a rare occurrence, typically limited to strings that contain ASCII control characters. The Xerces parser will reject such input, even if escaped as an entity. However, the Xalan transformer will happily generate such entities.

Note: at present, marks characters from the UTF-16 "surrogate blocks" as illegal. The XML specification allows code points from the "higher planes" of Unicde, but disallows the surrogate blocks used to contruct code points in these planes. Rather than allow code points from the surrogate block, and get hurt by a bozo transformer that doesn't know that Java strings are UTF-16, I took the conservative (and wrong) approach. On the other hand, if you're using characters from outside the BMP, you probably don't have ASCII control characters in your text, and don't need this method at all.

Returns:

true if this string does not contain any illegal characters.

stripIllegals

public static String stripIllegals(String s)

Removes all illegal characters from the passed string. If the string does not contain illegal characters, returns it unchanged.

formatXsdDatetime

public static String formatXsdDatetime(Date date)

Converts a Java Date object to a string, using the format specified by XML Schema for dateTime elements. Output is UTC time, and omits timezone specifier.

See Also:

XML Schema

parseXsdDatetime

public static Date parseXsdDatetime(String value)
                             throws XmlException

Parses an XML Schema dateTime value, accepting any of the legal formats. Note that this method can also be used to parse a generic ISO-8601 date.

Throws:

XmlException - if unable to parse.

formatXsdDecimal

public static String formatXsdDecimal(double value)

Converts a Java double to a string, using the format specified by XML Schema for decimal elements. This method wraps the value and calls formatXsdDecimal(Number), so call that method if you already have an object.

Since:

1.0.3

formatXsdDecimal

public static String formatXsdDecimal(Number value)

Converts a Java double to a string, using the format specified by XML Schema for decimal elements. If passed null, returns an empty string.

Since:

1.0.3

parseXsdDecimal

public static BigDecimal parseXsdDecimal(String value)

Parses an XML Schema decimal value. Note that the return type is BigDecimal: this provides us exact representation where necessary, and meets the spec's minimum requirement of 18 digits of precision. Use .toLong(), toDouble(), or equivalent to create the type that you want.

Since:

1.1.19

formatXsdBoolean

public static String formatXsdBoolean(boolean value)

Converts a boolean value to the literal strings "true" or "false" (XML Schema boolean fields also allow "1" or "0").

Since:

1.1

parseXsdBoolean

public static boolean parseXsdBoolean(String value)

Parses an XML Schema boolean value, accepting any of the legal formats and trimming whitespace.

Throws:

XmlException - the passed value, after trimming, is not one of the 4 legal representations of boolean data under XML Schema.

Since:

1.1

escape

public static String escape(String s)

Escapes the passed string, converting the five reserved XML characters into their entities: &, <, >, ', and ". If the string does not contain any of these characters, it will be returned unchanged. If passed null, returns an empty string.

Yes, this method is available elsewhere, eg Jakarta Commons. I'm trying to minimize external dependencies from this library, so am reinventing a few small wheels (but they're round!).

Since:

1.0.1

unescape

public static String unescape(String s)

Unescapes the passed string, converting the five XML entities (&, <, >, ', and ") into their correspinding characters. Also converts any numeric entities into their characters. If the string does not contain any convertable entities, it will be returned unchanged. If passed null, returns an empty string.

Yes, this method is available elsewhere, eg Jakarta Commons.

Since:

1.0.1