com.tangosol.run.xml
Class XmlBean

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

All Implemented Interfaces:

ExternalizableLite, XmlSerializable, Externalizable, Serializable, Cloneable

public abstract class XmlBean
extends ExternalizableHelper
implements Cloneable, Externalizable, ExternalizableLite, XmlSerializable

This is a base class for building XmlSerializable value objects.

The following property types are supported using standard property adapters:

   1)  XmlValue types:
           TYPE_BOOLEAN  - boolean, java.lang.Boolean
           TYPE_INT      - byte, char, short, int, java.lang.Byte,
                           java.lang.Character, java.lang.Short,
                           java.lang.Integer
           TYPE_LONG     - long, java.lang.Long
           TYPE_DOUBLE   - float, double, java.lang.Float, java.lang.Double
           TYPE_DECIMAL  - java.math.BigDecimal, java.math.BigInteger
           TYPE_STRING   - java.lang.String
           TYPE_BINARY   - com.tangosol.util.Binary, byte[]
           TYPE_DATE     - java.sql.Date
           TYPE_TIME     - java.sql.Time
           TYPE_DATETIME - java.sql.Timestamp, java.util.Date

   2)  Objects implementing XmlSerializable (including XmlBean subclasses)

   3)  Objects implementing Serializable

   4)  Collections of any of the above:
           Java arrays
           java.util.Collection
           java.util.Set
           java.util.List
           java.util.Map
           java.util.SortedSet
           java.util.SortedMap
 

Each XmlBean must have a corresponding XML declaration file that provides the necessary information to parse XML into the XML bean and to format the XML bean into XML. The declaration file should be located in the same package (directory) as the class itself.

For example, here is an XmlBean subclass with an int property "Id" and a String property "Name":

 public class Person extends XmlBean {
   public Person(int nId, String sName) {...}
   public int getId() {...}
   public void setId(int nId) {...}
   public String getName() {...}
   public void setName(String sName) {...}
 }
 

The Person XML bean example above would have an XML declaration file that resembles the following:

 <xml-bean>
   <name>person</name>
   <property>
     <name>Id</name>
     <xml-name>person-id</xml-name>
   </property>
   <property>
     <name>Name</name>
     <xml-name>full-name</xml-name>
   </property>
 </xml-bean>
 

Consider the following code:

System.out.println(new Person(15, "John Smith").toString());

The output would be:

 <person>
   <person-id>15</person-id>
   <full-name>John Smith</full-name>
 </person>
 

To specify namespace information for an XML bean, add an "xmlns" element to the bean's descriptor:

 <xml-bean>
   <name>person</name>
   <xmlns>
     <uri>the-schema-URI-goes-here</uri>
     <prefix>the-default-namespace-prefix-goes-here</prefix>
   <xmlns>
   <property>
     ...
   </property>
 </xml-bean>
 

Version:

1.2

Author:

cp 2000.11.10, gg 2002.05.17 anonymous element and XML Namespaces support, cp 2003.03.27 ExternalizableLite support

Nested Class Summary

static class

XmlBean.BeanInfo A BeanInfo contains information about the XML bean and its properties.

Constructor Summary

protected

XmlBean() Construct a value object.

Method Summary

protected void	adopt(Collection coll) Helper to adopt a Collection of XmlBean objects.
protected void	adopt(Iterator iter) Helper to adopt a collection of XmlBean objects.
protected void	adopt(Map map) Helper to adopt a Map of XmlBean objects.
protected void	adopt(Object[] ao) Helper to adopt a collection of XmlBean objects.
protected void	adopt(XmlBean child) When an XmlBean adds a contained XmlBean, it should invoke this method to relate the contained XmlBean with this XmlBean.
protected void	checkMutable() Verify that this XmlBean is mutable.
Object	clone() Clone the value object.
XmlBean	ensureMutable() Make sure that this XML bean is mutable.
void	ensureReadOnly() Make sure that this value is read-only (immutable).
boolean	equals(Object o) Determine if this value object is equal to the passed value object.
void	fromXml(XmlElement xml) Deserialize the object from an XmlElement.
PropertyAdapter[]	getAdapters() Obtain the PropertyAdapter objects for this XmlBean.
XmlBean.BeanInfo	getBeanInfo() Obtain the BeanInfo for this XmlBean object, or create and configure a BeanInfo if one does not exist.
protected int	getHashCode() Get the cached hash code.
XmlBean	getParentXmlBean() Obtain the XmlBean that contains this XmlBean.
int	hashCode() Determine a hash code for this value object.
protected static void	init(Class clz, String sName, String[] asProp) For backwards compatibility only - loads reflection info.
protected XmlBean.BeanInfo	initBeanInfo() Initialize the Object, loading the XML Bean design information if necessary.
boolean	isMutable() Determine if this value can be modified.
void	readExternal(DataInput in) Restore the contents of this object by loading the object's state from the passed DataInput object.
void	readExternal(ObjectInput in) The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
protected void	setHashCode(int nHash) Set the cached hash code.
protected void	setMutable(boolean fMutable) Specify whether this value can be modified or not.
protected void	setParentXmlBean(XmlBean parent) Specify the XmlBean that contains this XmlBean.
String	toString() To assist in debugging, provide a clear indication of the key's state.
XmlElement	toXml() Serialize the object into an XmlElement.
void	writeExternal(DataOutput out) Save the contents of this object by storing the object's state into the passed DataOutput object.
void	writeExternal(ObjectOutput out) The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

Methods inherited from class com.tangosol.util.BitHelper

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

Constructor Detail

XmlBean

protected XmlBean()

Construct a value object.

Method Detail

getParentXmlBean

public XmlBean getParentXmlBean()

Obtain the XmlBean that contains this XmlBean.

Returns:

the containing XmlBean, or null if there is none

setParentXmlBean

protected void setParentXmlBean(XmlBean parent)

Specify the XmlBean that contains this XmlBean.

Parameters:

parent - the XmlBean that contains this XmlBean

adopt

protected void adopt(Map map)

Helper to adopt a Map of XmlBean objects.

Parameters:

map - a Map that may contain keys and/or values that are XmlBeans

adopt

protected void adopt(Collection coll)

Helper to adopt a Collection of XmlBean objects.

Parameters:

coll - a Collection that may contain XmlBeans

adopt

protected void adopt(Iterator iter)

Helper to adopt a collection of XmlBean objects.

Parameters:

iter - an Iterator that may contain XmlBeans

adopt

protected void adopt(Object[] ao)

Helper to adopt a collection of XmlBean objects.

Parameters:

ao - an array that may contain XmlBeans

adopt

protected void adopt(XmlBean child)

When an XmlBean adds a contained XmlBean, it should invoke this method to relate the contained XmlBean with this XmlBean.

Parameters:

child - the XmlBean that is being contained within this XmlBean

isMutable

public boolean isMutable()

Determine if this value can be modified. If the value can not be modified, all mutating methods are required to throw an UnsupportedOperationException.

Returns:

true if this value can be modified, otherwise false to indicate that this value is read-only

setMutable

protected void setMutable(boolean fMutable)

Specify whether this value can be modified or not.

Parameters:

fMutable - true to allow this value to be modified, otherwise false to indicate that this value is read-only

ensureMutable

public XmlBean ensureMutable()

Make sure that this XML bean is mutable.

Returns:

this XmlBean if it is mutable, otherwise a mutable copy of this XmlBean

ensureReadOnly

public void ensureReadOnly()

Make sure that this value is read-only (immutable).

checkMutable

protected void checkMutable()

Verify that this XmlBean is mutable. This method is designed to be called by all mutator methods of an XmlBean to ensure that the bean fulfills the contract provided by the Mutable property.

getHashCode

protected int getHashCode()

Get the cached hash code. Value objects whose hash code is supposed to change must override the hashCode implementation.

Returns:

the cached hash code

setHashCode

protected void setHashCode(int nHash)

Set the cached hash code. Value objects whose hash code is supposed to change must override the hashCode implementation.

Parameters:

nHash - the hash code

getBeanInfo

public XmlBean.BeanInfo getBeanInfo()

Obtain the BeanInfo for this XmlBean object, or create and configure a BeanInfo if one does not exist.

Returns:

the BeanInfo that describes this XmlBean

getAdapters

public PropertyAdapter[] getAdapters()

Obtain the PropertyAdapter objects for this XmlBean.

Returns:

the PropertyAdapter objects that handle the properties of this XmlBean

equals

public boolean equals(Object o)

Determine if this value object is equal to the passed value object.

Parameters:

o - the other value object to compare to

Returns:

true if the other value object is equal to this

hashCode

public int hashCode()

Determine a hash code for this value object. For value objects with multiple properties, the hash code is calculated from the xor of the hash codes for each property.

Returns:

a hash code for this value object

toString

public String toString()

To assist in debugging, provide a clear indication of the key's state.

Returns:

a String representing this key object

clone

public Object clone()

Clone the value object.

Returns:

a clone of this object

toXml

public XmlElement toXml()

Serialize the object into an XmlElement.

Specified by:

toXml in interface XmlSerializable

Returns:

an XmlElement that contains the serialized form of the object

fromXml

public void fromXml(XmlElement xml)

Deserialize the object from an XmlElement. This method can throw one of several RuntimeExceptions.

Specified by:

fromXml in interface XmlSerializable

Parameters:

xml - an XmlElement that contains the serialized form of the object

Throws:

UnsupportedOperationException

IllegalStateException

IllegalArgumentException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.

Specified by:

readExternal in interface Externalizable

Parameters:

in - the stream to read data from in order to restore the object

Throws:

IOException - if I/O errors occur

ClassNotFoundException - if the class for an object being restored cannot be found.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - the stream to write the object to

Throws:

IOException - includes any I/O exceptions that may occur

readExternal

public void readExternal(DataInput in)
                  throws IOException

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

init

protected static void init(Class clz,
                           String sName,
                           String[] asProp)

For backwards compatibility only - loads reflection info. This method is intended to be called by the static initializer of each concrete sub-class.

Parameters:

clz - the class to initialize

sName - the name of the value object

asProp - the property names that make up the value object

initBeanInfo

protected XmlBean.BeanInfo initBeanInfo()

Initialize the Object, loading the XML Bean design information if necessary.

Returns:

a BeanInfo object