org.granite.util
Class XMap

java.lang.Object
  org.granite.util.XMap

All Implemented Interfaces:

Serializable

public class XMap
extends Object
implements Serializable

Utility class that makes XML fragment tree manipulation easier.
This class relies on JDK DOM & XPath built-in implementations.

Author:

Franck WOLFF

See Also:

Serialized Form

Field Summary

protected static String	DEFAULT_ROOT_NAME
static XMap	EMPTY_XMAP An empty and unmodifiable XMap instance.

Constructor Summary

	XMap() Constructs a new XMap instance.
protected	XMap(DOM dom, Element root, boolean clone) Constructs a new XMap instance.
	XMap(Element root) Constructs a new XMap instance.
	XMap(InputStream input) Constructs a new XMap instance from an XML input stream.
	XMap(InputStream input, EntityResolver resolver) Constructs a new XMap instance from an XML input stream.
	XMap(String root) Constructs a new XMap instance.
	XMap(XMap map) Constructs a new XMap instance based on an existing XMap and clone its content.

Method Summary

boolean	containsKey(String key) Returns true if the supplied key XPath expression matches at least one element, attribute or text in the root element of this XMap.
String	get(String key) Returns the text value of the element (or attribute or text) that matches the supplied XPath expression.
<T> T	get(String key, Class<T> clazz, T defaultValue)
<T> T	get(String key, Class<T> clazz, T defaultValue, boolean required, boolean warn)
List<XMap>	getAll(String key) Returns a list of XMap instances with all elements that match the supplied XPath expression.
protected DOM	getDom() Returns the DOM instance of this XMap (one is created if it is null).
XMap	getOne(String key) Returns a new XMap instance with the first element that matches the supplied XPath expression or null if this XMap root element is null, or if XPath evaluation result is null, or this result is not an Element.
Element	getRoot() Allows direct manipulation of the root element.
String	put(String key, String value) Creates or updates the text value of the element (or text or attribute) matched by the supplied XPath expression.
String	put(String key, String value, boolean append) Creates or updates the text value of the element (or text or attribute) matched by the supplied XPath expression.
String	remove(String key) Removes the element, text or attribute that matches the supplied XPath expression.
String	toString() Returns a "pretty" XML representation of the root element of this XMap (may be null).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ROOT_NAME

protected static final String DEFAULT_ROOT_NAME

See Also:

Constant Field Values

EMPTY_XMAP

public static final XMap EMPTY_XMAP

An empty and unmodifiable XMap instance.

Constructor Detail

XMap

public XMap()

Constructs a new XMap instance.

XMap

public XMap(String root)

Constructs a new XMap instance.

Parameters:

root - the name of the root element (may be null).

XMap

public XMap(InputStream input)
     throws IOException,
            SAXException

Constructs a new XMap instance from an XML input stream.

Parameters:

input - an XML input stream.

Throws:

IOException

SAXException

XMap

public XMap(InputStream input,
            EntityResolver resolver)
     throws IOException,
            SAXException

Constructs a new XMap instance from an XML input stream.

Parameters:

input - an XML input stream.

Throws:

IOException

SAXException

XMap

public XMap(Element root)

Constructs a new XMap instance.

Parameters:

root - a DOM element (may be null).

XMap

public XMap(XMap map)

Constructs a new XMap instance based on an existing XMap and clone its content.

Parameters:

map - the map to duplicate (root element is cloned so modification to this new instance won't modify the original XMap).

XMap

protected XMap(DOM dom,
               Element root,
               boolean clone)

Constructs a new XMap instance.

Parameters:

root - the root element (may be null).

clone - should we clone the root element (prevent original node modification).

Method Detail

getRoot

public Element getRoot()

Allows direct manipulation of the root element.

Returns:

the root element of this XMap instance.

getDom

protected DOM getDom()

Returns the DOM instance of this XMap (one is created if it is null).

Returns:

the DOM instance of this XMap.

containsKey

public boolean containsKey(String key)

Returns true if the supplied key XPath expression matches at least one element, attribute or text in the root element of this XMap.

Parameters:

key - an XPath expression.

Returns:

true if the supplied key XPath expression matches at least one element, attribute or text in the root element of this XMap, false otherwise.

Throws:

RuntimeException - if the XPath expression isn't correct.

get

public String get(String key)

Returns the text value of the element (or attribute or text) that matches the supplied XPath expression.

Parameters:

key - an XPath expression.

Returns:

the text value of the matched element or null if the element does not exist or have no value.

Throws:

RuntimeException - if the XPath expression isn't correct.

get

public <T> T get(String key,
                 Class<T> clazz,
                 T defaultValue)

get

public <T> T get(String key,
                 Class<T> clazz,
                 T defaultValue,
                 boolean required,
                 boolean warn)

getAll

public List<XMap> getAll(String key)

Returns a list of XMap instances with all elements that match the supplied XPath expression. Note that XPath result nodes that are not instance of Element are ignored. Note also that returned XMaps contain original child elements of the root element of this XMap so modifications made to child elements affect this XMap instance as well.

Parameters:

key - an XPath expression.

Returns:

an unmodifiable list of XMap instances.

Throws:

RuntimeException - if the XPath expression isn't correct.

getOne

public XMap getOne(String key)

Returns a new XMap instance with the first element that matches the supplied XPath expression or null if this XMap root element is null, or if XPath evaluation result is null, or this result is not an Element. Returned XMap contains original child element of the root element of this XMap so modifications made to the child element affect this XMap instance as well.

Parameters:

key - an XPath expression.

Returns:

a single new XMap instance.

Throws:

RuntimeException - if the XPath expression isn't correct.

put

public String put(String key,
                  String value)

Creates or updates the text value of the element (or text or attribute) matched by the supplied XPath expression. If the matched element (or text or attribute) does not exist, it is created with the last segment of the XPath expression (but its parent must already exist).

Parameters:

key - an XPath expression.

value - the value to set (may be null).

Returns:

the previous value of the matched element (may be null).

Throws:

RuntimeException - if the root element of this XMap is null, if the XPath expression is not valid, or (creation case) if the parent node does not exist or is not an element instance.

put

public String put(String key,
                  String value,
                  boolean append)

Creates or updates the text value of the element (or text or attribute) matched by the supplied XPath expression. If the matched element (or text or attribute) does not exist or if append is true, it is created with the last segment of the XPath expression (but its parent must already exist).

Parameters:

key - an XPath expression.

value - the value to set (may be null).

append - should the new element be appended (created) next to a possibly existing element(s) of the same name?

Returns:

the previous value of the matched element (may be null).

Throws:

RuntimeException - if the root element of this XMap is null, if the XPath expression is not valid, or (creation case) if the parent node does not exist or is not an element instance.

remove

public String remove(String key)

Removes the element, text or attribute that matches the supplied XPath expression.

Parameters:

key - an XPath expression.

Returns:

the previous value of the matched node if any.

Throws:

RuntimeException - if the XPath expression isn't valid.

toString

public String toString()

Returns a "pretty" XML representation of the root element of this XMap (may be null).

Overrides:

toString in class Object

Returns:

a "pretty" XML representation of the root element of this XMap (may be null).