dsto.dfc.databeans.io
Class XmlDecodeContext

java.lang.Object
  extended by 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)


Copyright © 2008 Commonwealth of Australia