com.tangosol.run.xml
Class IterableAdapter

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.util.BitHelper
          com.tangosol.util.ExternalizableHelper
              com.tangosol.run.xml.PropertyAdapter
                  com.tangosol.run.xml.IterableAdapter

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ArrayAdapter, CollectionAdapter, MapAdapter, PrimitiveArrayAdapter

public abstract class IterableAdapter
extends PropertyAdapter

An IterableAdapter is the base class for any data type that must be iterated over to serialize/deserialize, such as arrays, collections and maps.

 <property>
   <name>People</name>
   <xml-name>people</xml-name>         <!-- optional, empty name indicates anonymous element -->
   <adapter>...</adapter>              <!-- optional -->
   <type>...</type>                    <!-- defaults via reflection -->
   <class>...</class>                  <!-- defaults to <type> -->
   <sparse>true</sparse>               <!-- defaults to false -->
   <empty-is-null>true</empty-is-null> <!-- defaults to false -->
   <element>                       <!-- optional, depends on the adapter -->
     <xml-name>person</xml-name>   <!-- optional, nests the elements -->
   </element>
 <property>

 Example of collection/array nested within collection tags:

   <doc>
     <people>
       <person>...</person>
       <person>...</person>
       ...
     </people>
   </doc>

 Example of collection/array nested directly within the document:

   <doc>
     <person>...</person>
     <person>...</person>
     ...
   </doc>

 Example of map nested within collection tags:

   <doc>
     <people>
       <person>
         <name>...</name>
         <number>...</number>
       </person>
       <person>
         <name>...</name>
         <number>...</number>
       </person>
       ...
     </people>
   </doc>

 Example of map nested directly within the document:

   <doc>
     <person>
       <name>...</name>
       <number>...</number>
     </person>
     <person>
       <name>...</name>
       <number>...</number>
     </person>
     ...
   </doc>
 

Version:

1.00 2001.03.18

Author:

cp

Field Summary

protected boolean	m_fEmptyIsNull Empty-is-null option: Empty iterable values are not stored in the serialized form of the XmlBean nor in the XML form of the XmlBean.
protected boolean	m_fSparse Sparse array storage option.
protected String	m_sElement Name used for each element of the array when formatted into XML.

Fields inherited from class com.tangosol.run.xml.PropertyAdapter

m_clzType, m_fAttribute, m_infoBean, m_methodClone, m_methodGet, m_methodSet, m_sName, m_sNmsPrefix, m_sNmsUri, m_sXml, NOPARAMS

Constructor Summary

IterableAdapter(XmlBean.BeanInfo infoBean, Class clzType, String sName, String sXml, XmlElement xml)
Construct a IterableAdapter.

Method Summary

protected PropertyAdapter	findAdapter(XmlBean.BeanInfo infoBean, XmlElement xml) Obtain a PropertyAdapapter for a map entry key or value
Object	fromXml(XmlElement xml) Deserialize an object from an XML element.
String	getElementName()
boolean	isCloneRequired() Determine if the property value must be deep-cloned.
boolean	isEmptyIsNull()
boolean	isNested()
boolean	isSparse()
protected abstract Object	readElements(XmlElement xml)
XmlElement	toXml(Object o) Serialize an object into an XML element.
protected abstract void	writeElements(XmlElement xml, Object o)

Methods inherited from class com.tangosol.run.xml.PropertyAdapter

clone, equalsValue, findAttribute, findElement, fromUri, get, getAccessor, getBeanInfo, getCloner, getElements, getLocalXmlName, getMutator, getName, getNamespacePrefix, getNamespaceUri, getType, getXmlName, hash, isAnonymous, isAttribute, isElementMatch, isEmpty, readExternal, readXml, set, setNamespacePrefix, toString, toUri, writeExternal, writeXml

Methods inherited from class com.tangosol.util.BitHelper

countBits, countBits, countBits, indexOfLSB, indexOfLSB, indexOfLSB, indexOfMSB, indexOfMSB, indexOfMSB, toBitString, toBitString, toBitString

Field Detail

m_fSparse

protected boolean m_fSparse

Sparse array storage option.

m_fEmptyIsNull

protected boolean m_fEmptyIsNull

Empty-is-null option: Empty iterable values are not stored in the serialized form of the XmlBean nor in the XML form of the XmlBean.

m_sElement

protected String m_sElement

Name used for each element of the array when formatted into XML. If null, then the elements are placed directly into the document using the adapter's XML name.

Constructor Detail

IterableAdapter

public IterableAdapter(XmlBean.BeanInfo infoBean,
                       Class clzType,
                       String sName,
                       String sXml,
                       XmlElement xml)

Construct a IterableAdapter.

Parameters:

infoBean - BeanInfo for a bean containing this property

clzType - the type of the property

sName - the property name

sXml - the XML tag name

xml - additional XML information

Method Detail

isCloneRequired

public boolean isCloneRequired()

Description copied from class: PropertyAdapter

Determine if the property value must be deep-cloned. Typically, a property value must be deep-cloned if it is a mutable reference type, e.g. StringBuffer, Date, byte[].

Specified by:

isCloneRequired in class PropertyAdapter

Returns:

true if the property value must be "deep" cloned when the containing object is cloned

isSparse

public boolean isSparse()

Returns:

true if the iterable data should be stored in a sparse format in XML

isEmptyIsNull

public boolean isEmptyIsNull()

Returns:

true if the iterable data should not be stored at all if it is empty, such as a zero-length array or empty collection

getElementName

public String getElementName()

Returns:

the local XML name of the individual array elements (null if the array elements are nested directly within the document)

isNested

public boolean isNested()

Returns:

true only if this adapter creates a single XML element on writeXml and reads from a single XML element on readXml

fromXml

public Object fromXml(XmlElement xml)

Deserialize an object from an XML element.

Overrides:

fromXml in class PropertyAdapter

Parameters:

xml - the XML element to deserialize from

Returns:

the object deserialized from the XML element

Throws:

UnsupportedOperationException - if the property cannot be read from a single XML element

toXml

public XmlElement toXml(Object o)

Serialize an object into an XML element.

Overrides:

toXml in class PropertyAdapter

Parameters:

o - the object to serialize

Returns:

the XML element representing the serialized form of the passed object

Throws:

UnsupportedOperationException - if the property cannot be written to a single XML element

readElements

protected abstract Object readElements(XmlElement xml)

Parameters:

xml - the XML element containing the XML elements to deserialize from

Returns:

the object deserialized from the XML (not null)

writeElements

protected abstract void writeElements(XmlElement xml,
                                      Object o)

Parameters:

xml - the XML element to which the iterable elements are written

o - the object to serialize (not null)

findAdapter

protected PropertyAdapter findAdapter(XmlBean.BeanInfo infoBean,
                                      XmlElement xml)

Obtain a PropertyAdapapter for a map entry key or value

Parameters:

infoBean - BeanInfo for a bean containing this property

xml - the information about the map entry key or value

Returns:

a PropertyAdapter for the map entry key or value