Class 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
    See Also:
    Serialized Form
    • 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.
        Overrides:
        equals in class 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.
        Overrides:
        hashCode in class Object
        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.
        Overrides:
        toString in class Object
        Returns:
        a String representing this key object
      • clone

        public Object clone()
        Clone the value object.
        Overrides:
        clone in class 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
      • 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