dsto.dfc.databeans.io
Class XmlDecodeContext

java.lang.Object
  dsto.dfc.databeans.io.XmlDecodeContext

public class XmlDecodeContext
extends Object

Stores context information (eg ID -> value mapping) during an XML decode session. Also mediates decoding via decode(Element).

XmlDecoder clients receive an instance via XmlDecoder.decode(XmlDecodeContext, Element).

Version:

$Revision$

Author:

mpp

Nested Class Summary

static interface

XmlDecodeContext.IdCallback Callback interface for clients that wish to use forward references.

Constructor Summary

protected

XmlDecodeContext(LazyElementMap xmlDecoders, TypeMap textDecoders, Map typeAliases)

Method Summary

String	aliasToType(String alias) Map an alias to it's a type value if it has one.
void	callbackWithObjectForId(XmlDecodeContext.IdCallback callback, org.jdom.Element element, String id, Object extraData) Register a callback to be invoked when a value becomes available for a given ID.
Object	decode(org.jdom.Element element) Mediates the decoding of an element.
Class	decodeType(String typeName) Decode an encoded type into the original Class.
protected void	doPostDecode()
String	getAliasType(String alias) Get the type name for an alias.
Object	getProperty(Object name) Get a custom property defined by setProperty(Object, Object).
TextDecoder	getTextDecoder(Class type) Get the text decoder for a given value type.
Object	getValue(String id) Get a value registered with a given ID.
XmlDecoder	getXmlDecoder(String elementName) Get the decoder registered for a given element type.
void	registerValue(org.jdom.Element element, Object value) Register a value for an ID if one is specified on an element.
void	registerValue(String id, Object value) Register a value with a given ID.
protected void	setProperties(Map properties) Set all custom properties.
void	setProperty(Object name, Object value) Define a custom property that will be accessible during this session via getProperty(Object).

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlDecodeContext

protected XmlDecodeContext(LazyElementMap xmlDecoders,
                           TypeMap textDecoders,
                           Map typeAliases)

Method Detail

doPostDecode

protected void doPostDecode()

setProperties

protected void setProperties(Map properties)

Set all custom properties. Used by XmlInput.

See Also:

setProperty(Object, Object)

setProperty

public void setProperty(Object name,
                        Object value)

Define a custom property that will be accessible during this session via getProperty(Object).

See Also:

XmlInput.setProperty(Object, Object)

getProperty

public Object getProperty(Object name)

Get a custom property defined by setProperty(Object, Object).

decode

public Object decode(org.jdom.Element element)
              throws ClassNotFoundException,
                     IllegalArgumentException

Mediates the decoding of an element. This method should be used in preference to a direct call to the registered XmlDecoder for the element since it adds automatic management of id/refid.

Parameters:

element - The element to decode.

Returns:

The decoded value.

Throws:

ClassNotFoundException - if a class referenced by the element tree is not found.

IllegalArgumentException - if there is a logical error in the element tree.

getXmlDecoder

public XmlDecoder getXmlDecoder(String elementName)
                         throws IllegalArgumentException

Get the decoder registered for a given element type. Clients will not usually need to call this: it is used by decode(Element).

Parameters:

elementName - The element name (eg from element.getName ()).

Returns:

XmlDecoder The decoder registered for the element.

Throws:

IllegalArgumentException - if there is no decoder for the element.

getTextDecoder

public TextDecoder getTextDecoder(Class type)

Get the text decoder for a given value type.

getValue

public Object getValue(String id)
                throws IllegalArgumentException

Get a value registered with a given ID. Clients will not usually need to call this: it is used by decode(Element).

Parameters:

id - The value ID.

Returns:

The value.

Throws:

IllegalArgumentException - if no value for ID.

See Also:

registerValue(String, Object)

registerValue

public void registerValue(org.jdom.Element element,
                          Object value)

Register a value for an ID if one is specified on an element. This is called automatically by decode(Element) after invoking an XmlDecoder, but a decoder may choose to call this as soon as it creates its value so that any child decoders can reference it.

Parameters:

element - The element. If the element has no "id" attribute, this call does nothing.

value - The value to register.

registerValue

public void registerValue(String id,
                          Object value)
                   throws IllegalArgumentException

Register a value with a given ID. Clients will not usually need to call this: it is used by decode(Element).

Parameters:

id - The ID.

value - The value.

Throws:

IllegalArgumentException - if ID is already in use by another value.

See Also:

getValue(String)

getAliasType

public String getAliasType(String alias)

Get the type name for an alias.

Parameters:

alias - The alias.

Returns:

The type (class) name for the alias, or null if it does not have one.

See Also:

aliasToType(String)

aliasToType

public String aliasToType(String alias)

Map an alias to it's a type value if it has one. Similar to getAliasType(String) except it returns the parameter if no alias mapping is found.

Parameters:

alias - The alias/type name.

Returns:

The type value for typeName. If there is no type value for the alias, the alias is returned.

decodeType

public Class decodeType(String typeName)
                 throws ClassNotFoundException

Decode an encoded type into the original Class.

Throws:

ClassNotFoundException

See Also:

XmlEncodeContext.encodeType(Class)

callbackWithObjectForId

public void callbackWithObjectForId(XmlDecodeContext.IdCallback callback,
                                    org.jdom.Element element,
                                    String id,
                                    Object extraData)

Register a callback to be invoked when a value becomes available for a given ID. This can be used if a client wants to refer to an ID for a value that may not have been decoded yet. When an value is defined the client will be notified via XmlDecodeContext.IdCallback.objectForIdCallback(XmlDecodeContext, Element, Object, Object). The callback will be invoked immediately if an ID is already available.

Parameters:

callback - The callback target.

element - The element param to be passed to the callback.

id - The id for which a value is needed.

extraData - Any extra data to be passed to the callback (may be null).

See Also:

XmlDecodeContext.IdCallback.objectForIdCallback(XmlDecodeContext, Element, Object, Object), callbackWithObjectForId(IdCallback, Element, String, Object)