it.unimo.dbgroup.momis.XmlTools
Class XmlReader

java.lang.Object
  it.unimo.dbgroup.momis.XmlTools.BaseXmlTools
      it.unimo.dbgroup.momis.XmlTools.BaseObjectDomStreamer
          it.unimo.dbgroup.momis.XmlTools.XmlReader

public class XmlReader

extends BaseObjectDomStreamer

This class reads an Xml document produced by XmlWriter and deserializes any object encoutered.

XmlReader looks for "ObjectArchive" and other attributes in the XML root element to understand the serialization format used in the document.

You can create an XmlReader by passing an external input stream or by passing an existing DOM tree. If you pass an input stream, it will be parsed and a DOM tree is constructed before any of the readXXXX methods can be called.
On the other hand if you pass an existing DOM tree the readXXXX begins their process from a start element of your choice.

XmlReader mantains an internal cursor that points to the current position in the DOM tree, XML elements are processed in the same order they are defined in the original document.
Any readXXXX method will process the current element and all the child nodes (and sub-Elements). After a reading method is called the current position is updated, if you read past last element in the current sub-tree an exception will be thrown.

You can deserialze an object by calling the

readObject()

method, as you would do with an ObjectInputStream.

Customizing the serialization mechanism.
XmlReader is compatible with the standard Java serialization mechanism. You can implement Externalizable interface or a

private readObject(ObjectInputStream in);

method.
Please note that this compatibility is obtained through an ObjectInputStream wrapper (see XmlObjectInput), it is more efficient to implement XmlExternalizable interface or a

private readObject(XmlReader out);

method.
You can also implement a normal readObject(ObjectInputStream in) and obtain the XmlReader object used by the wrapper as follow:
cast the ObjectInputStream "in" parameter as a XmlObjectInput instance and call any readXXXX method directly.
When you use this technique pay attention to not collide with java standard deserialization: the 'in' parameter is a true XmlObjectInput instance only if you are using XmlReader or XmlObjectInput as deserializing tool.

These methods and interfaces work as described in Java Object Serialization Specification, please refer to that document for more details.

Version:

1.0b Cose da fare: - pulire il codice dai commenti superflui

Author:

Davide Lenzi - dic 2000

Nested Class Summary

private class

XmlReader.CallbackEntry Stores an object validator and the corresponding priority call.

Field Summary

private boolean	_balanced blanced flag read from the source document.
private boolean	_classNameAsTagName classNameAsTagName property value read from the source document.
protected org.w3c.dom.Document	_dox Current document being processed.
private boolean	_fullClassNameAsAttribute fullClassNameAsAttribute property value read from the source document.
private boolean	_fullJavaClassName fullJavaClassName property value read from the source document.
private java.io.ObjectInputStream	_inWrap Internal reference to an ObjectOutputStream wrapper.
private int	_readCount Internal counter, if greater than 0 then objects reading is in progress.
private static boolean	_requireDefConstructor Flag that indicate if default constructors are needed or not.
private java.util.Stack	_stacklists Stack used to store validaror lists.
private boolean	_suidCheck Internal value for the suidCheck property
protected java.util.HashMap	_suidMap Map with Class objects as keys and corresponding suid as values.
private java.util.ArrayList	_validators Current list of obect validators
protected javax.xml.parsers.DocumentBuilder	db Builder used to obtain DOM documents.
static javax.xml.parsers.DocumentBuilderFactory	dbf Factory used to obtain document builders.
protected boolean	def_active If true, the defaultRead() method is enabled.
protected java.lang.Class	def_cls defaultRead() cloacked argument.
protected java.lang.Object	def_obj defaultRead() cloacked argument.
protected DomNavigator	domNav Represent the current position in the DOM tree.
protected java.util.HashMap	objs_elem Map with elements' objectID as keys and corresponding elements as value.
protected java.util.HashMap	objs_read Cache with objects already processed by XmlReader.
private static java.lang.Class[]	parTypes Parameter type used when searching for a custom readObject method.
private static java.lang.Class[]	parTypesWrap Parameter type used when searching for a custom readObject method.
boolean	trimRight This field rules the way a java string is retreived from the DOM: if true any any character following the last "\n" (and the "\n" itself) will be removed from the returned string.

Fields inherited from class it.unimo.dbgroup.momis.XmlTools.BaseXmlTools

_debug, ATTR_TYPE, attrArrayLength, attrBalanced, attrClassName, attrClassNameAsTagName, attrDescr, attrField, attrFullClassNameAsAttribute, attrFullJavaClassName, attrObjectArchive, attrObjectID, attrObjectREF, attrSUID, attrValue, CDATA_TYPE, COMMENT_TYPE, DOCFRAG_TYPE, DOCTYPE_TYPE, DOCUMENT_TYPE, ELEMENT_TYPE, ENTITY_TYPE, ENTITYREF_TYPE, metaNameSpace, NOTATION_TYPE, PROCINSTR_TYPE, tagArray, tagBoolean, tagByte, tagChar, tagDouble, tagEndDefaultData, tagFloat, tagInt, tagLong, tagMapEntry, tagMeta, tagNull, tagObject, tagShort, tagSUIDEntry, tagSuperclass, TEXT_TYPE

Constructor Summary

XmlReader(org.w3c.dom.Document dox, org.w3c.dom.Element startElement)
Creates an XmlReader using an existing DOM tree.

XmlReader(java.io.InputStream in)
Creates a new XmlReader instance parsing an InputStream XML source.

Method Summary

private static java.lang.Object	AllocateObject(java.lang.Class cl) Allocates a new java instance for class cl.
protected java.lang.Object	allocateObjectInstance(org.w3c.dom.Element el, java.lang.Class cl) Given an object Element, this method allocates a new partially initialized instance.
protected boolean	CheckCustomization(java.lang.Object obj, java.lang.Class cl) Checks if an object declares a custom readObject method and possibly calls it.
protected void	createElementsMap() This methods scan the whole DOM and construct the objs_elem Map.
protected boolean	createSUIDTable(org.w3c.dom.Element el) Reads the 'meta' tag and constructs the suid table.
void	defaultRead() Implements the default serializing mechanism.
java.lang.String	denormalizeClassName(java.lang.String className) Decodes an encoded XML class name and returns a valid Java class name.
protected java.lang.Class	getClassFromElement(org.w3c.dom.Element el) Given an object Element, this method returns the corresponding Class object.
protected boolean	hasInterface(java.lang.Class cl, java.lang.Class Interface) Checks if the specified class declare the specified interface.
private boolean	isElement(org.w3c.dom.Node nd) Returns true if the DOM node nd is an Element instance.
protected boolean	isEndDefaultData(org.w3c.dom.Element el) Checks if the specified element is an end-default-data tag marker.
protected boolean	isMapEntry(org.w3c.dom.Element el) Returns true if the specified element represent a described map entry tag.
boolean	isNull(org.w3c.dom.Element el) Returns true if element el represent a "null" element, i.e.
protected boolean	isSuperclass(org.w3c.dom.Element el) Returns true if element el represents a superclass tag.
protected java.lang.reflect.Field	mapField(java.lang.Class cl, org.w3c.dom.Element el) Try to map an XML element to a class field.
protected void	rdArray(org.w3c.dom.Element el, java.lang.Object obj) Process an array element.
protected boolean	rdBoolean(org.w3c.dom.Element el) This method interpets a given element as a 'boolean' tag and return his value.
protected byte	rdByte(org.w3c.dom.Element el) This method interpets a given element as a 'byte' tag and return his value.
protected char	rdChar(org.w3c.dom.Element el) This method interpets a given element as a 'char' tag and return his value.
protected double	rdDouble(org.w3c.dom.Element el) This method interpets a given element as a 'double' tag and return his value.
protected void	rdField(org.w3c.dom.Element el, java.lang.Object obj, java.lang.Class cl) Process the element el, try to find a suitable field in class cl and assigns the retreived value to obj instance.
protected float	rdFloat(org.w3c.dom.Element el) This method interpets a given element as an 'float' tag and return his value.
protected int	rdInt(org.w3c.dom.Element el) This method interpets a given element as an 'int' tag and return his value.
protected java.lang.Object	rdKnown(org.w3c.dom.Element el, java.lang.Class cl) Checks and possibly process an element as a special known type.
protected long	rdLong(org.w3c.dom.Element el) This method interpets a given element as a 'long' tag and return his value.
protected java.lang.Object	rdObjectElement(org.w3c.dom.Element el) Process an element as an objec description element.
protected java.lang.Object	rdPrimitiveType(org.w3c.dom.Element el, java.lang.Class flc) This method will read a primitive element and wrap it to the corresponding primitive wrapper.
protected java.lang.Object	rdPrimitiveWrapper(org.w3c.dom.Element el, java.lang.Class cl) Interprets element el as an primitive wrapper element.
protected short	rdShort(org.w3c.dom.Element el) This method interpets a given element as a 'short' tag and return his value.
boolean	readBoolean() Process the current DOM element as a boolean element.
byte	readByte() Process the current DOM element as a byte element.
char	readChar() Process the current DOM element as a char element.
double	readDouble() Process the current DOM element as a 'double' element.
protected void	readFields(org.w3c.dom.Node nd, java.lang.Object obj) Deserializes all member fields for all the superclasses of obj.
float	readFloat() Process the current DOM element as a float element.
int	readInt() Process the current DOM element as an int element.
long	readLong() Process the current DOM element as a 'long' element.
java.lang.Object	readObject() Process the current Dom element as an object element and return the new allocated object.
protected void	readRootElement() Process the start element of the DOM tree and set various internal flags.
short	readShort() Process the current DOM element as a 'short' element.
private void	registerObject(org.w3c.dom.Element el, java.lang.Object obj) Inserts obj in the list of already processed objects (objs_read).
void	registerValidation(java.io.ObjectInputValidation obj, int priority) Registers an object validator.
void	setObjectInputWrapper(java.io.ObjectInputStream inWrap) Sets the a new ObjectInputStream wrapper that will be used when calling custom reading methods.
void	setSuidCheck(boolean value) Sets the suidCheck property value.
void	setTrimRight(boolean value) Sets the trimRight property value.

Methods inherited from class it.unimo.dbgroup.momis.XmlTools.BaseObjectDomStreamer

getClassDetails, getSerialVersionUID, isArray, isDeserializable, isPrimitiveWrapper, isPrimitiveWrapper, isSerializable

Methods inherited from class it.unimo.dbgroup.momis.XmlTools.BaseXmlTools

debug, getElementString, throwNodeException

Methods inherited from class java.lang.Object

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

Field Detail

_requireDefConstructor

private static boolean _requireDefConstructor

Flag that indicate if default constructors are needed or not.
XmlReader uses a native method to instantiate java objects even they doesn't define a default constructor.
When a XmlReader object is istantiated the system try to load a native dynamic library (Xrnm named "libXrnm.so" on Solaris systems or "Xrnm.dll" under win32), if this library can't be found no exceptions are thrown but any class that is being deserialized must define a default constructor.

You can found source code for the library in
XmlTools_XmlReader.c
XmlTools_XmlReader.h
files, please refer to your system documentation on how to create a dynamic library or look in the Java swing tutorial for some tips on Java Native interface (recommended if you are new to the argument).

_stacklists

private java.util.Stack _stacklists

Stack used to store validaror lists.

_validators

private java.util.ArrayList _validators

Current list of obect validators

dbf

public static javax.xml.parsers.DocumentBuilderFactory dbf

Factory used to obtain document builders.

You can assign your own factory object if you want to use others DOM compatible implementations.

db

protected javax.xml.parsers.DocumentBuilder db

Builder used to obtain DOM documents.

_dox

protected org.w3c.dom.Document _dox

Current document being processed.

_classNameAsTagName

private boolean _classNameAsTagName

classNameAsTagName property value read from the source document.

if true class names are used as tag name for object elements.

_fullClassNameAsAttribute

private boolean _fullClassNameAsAttribute

fullClassNameAsAttribute property value read from the source document.

if true, every object element has the attribute "class" with the full java class name as value.

_fullJavaClassName

private boolean _fullJavaClassName

fullJavaClassName property value read from the source document.

When java class names are used as object tags, it tells if the full name or the compact name should be used.

_balanced

private boolean _balanced

blanced flag read from the source document.

It tells if the DOM to be processed is a balanced DOM tree.

def_obj

protected java.lang.Object def_obj

defaultRead() cloacked argument.

It represents the instance where retreived field values must be assigned to.

def_cls

protected java.lang.Class def_cls

defaultRead() cloacked argument.

Class where to look for to map an XML element to a destination field.

def_active

protected boolean def_active

If true, the defaultRead() method is enabled. (cloacked argument.)

parTypes

private static java.lang.Class[] parTypes

Parameter type used when searching for a custom readObject method.

Internal use. DO NOT MODIFY!

parTypesWrap

private static java.lang.Class[] parTypesWrap

Parameter type used when searching for a custom readObject method.

Internal use. DO NOT MODIFY!

domNav

protected DomNavigator domNav

Represent the current position in the DOM tree.

objs_read

protected java.util.HashMap objs_read

Cache with objects already processed by XmlReader.

objs_elem

protected java.util.HashMap objs_elem

Map with elements' objectID as keys and corresponding elements as value.

This Map is istantiated only if the source XML is a balanced document (a balanceDOM() call was issued in XmlWriter that created it).
When an object reference element is encountered, a query to this Map occurs.

trimRight

public boolean trimRight

This field rules the way a java string is retreived from the DOM: if true any any character following the last "\n" (and the "\n" itself) will be removed from the returned string.

This variable is provided because when a DOM is constructed from a Xml file Jaxp add a "\n" and some white spaces that were not included in the original string.
On other hand when a DOM is constructed from scratch no "\n" is added so using this variable may be usefull if dealing with latter DOMs.

The default value is true.

_readCount

private int _readCount

Internal counter, if greater than 0 then objects reading is in progress.

_inWrap

private java.io.ObjectInputStream _inWrap

Internal reference to an ObjectOutputStream wrapper.

_suidCheck

private boolean _suidCheck

Internal value for the suidCheck property

_suidMap

protected java.util.HashMap _suidMap

Map with Class objects as keys and corresponding suid as values.

If source document doesn't define a suid table this variable is null.

Constructor Detail

XmlReader

public XmlReader(org.w3c.dom.Document dox,
                 org.w3c.dom.Element startElement)
          throws XmlToolsException

Creates an XmlReader using an existing DOM tree.

Parameters:

dox - An object that implemens the w3c Document interface, it is the DOM tree access object.

startElement - One of dox elements that acts as start element, usually this is the root element.

Throws:

XmlToolsException - if initialization falis.

XmlReader

public XmlReader(java.io.InputStream in)
          throws XmlToolsException

Creates a new XmlReader instance parsing an InputStream XML source.
The input stream must contain a valid XML document. After XML parsing a new DOM tree is constructed and used for further call to reading methods.

Parameters:

in - The input stream to parse and process.

Throws:

XmlToolsException - if initialization falis.

Method Detail

isElement

private boolean isElement(org.w3c.dom.Node nd)

Returns true if the DOM node nd is an Element instance.

Parameters:

nd - DOM node to check.

Returns:

true if nd is a DOM Element.

AllocateObject

private static java.lang.Object AllocateObject(java.lang.Class cl)
                                        throws java.lang.InstantiationException,
                                               java.lang.NoSuchMethodError,
                                               java.lang.ExceptionInInitializerError

Allocates a new java instance for class cl.

This is a native method that use JNI. It requires the Xrnm dynamic library.

Throws:

java.lang.InstantiationException

java.lang.NoSuchMethodError

java.lang.ExceptionInInitializerError

registerObject

private void registerObject(org.w3c.dom.Element el,
                            java.lang.Object obj)
                     throws XmlToolsException

Inserts obj in the list of already processed objects (objs_read).

If objs already exists in objs_read then an exception is thrown.

Parameters:

el - Element that describe the object obj.

obj - the object instance to be registered.

Throws:

XmlToolsException - if:

• Element el has an invalid objectID attribute
• an object is already present in objs_read with the same ID.

readRootElement

protected void readRootElement()
                        throws XmlToolsException

Process the start element of the DOM tree and set various internal flags.
This method must decide if the DOM tree is valid for deserialization pourpose.
XmlReader.readRootElement will throws an XmlTools exception if the start element doesn't contain the "ObjectArchive" element with a "true" value or if some of the following attributes are missing:

• classNameAsTagName
• fullJavaClassName
• fullClassNameAsAttribute

Throws:

XmlToolsExcpetion - if the start element is not valid.

XmlToolsException

createSUIDTable

protected boolean createSUIDTable(org.w3c.dom.Element el)
                           throws XmlToolsException

Reads the 'meta' tag and constructs the suid table.

If 'meta' tag is not present then _suidMap must be assigned a null value.

Parameters:

el - The 'meta' tag.

Returns:

true if 'meta' tag was present and a suid table was created, return false if 'meta' tag was not present.

Throws:

XmlToolsException - if any of the class specified in the suid.entry tags was not found.

createElementsMap

protected void createElementsMap()
                          throws XmlToolsException

This methods scan the whole DOM and construct the objs_elem Map.

Throws:

XmlToolsException - if the scan process fails.

rdArray

protected void rdArray(org.w3c.dom.Element el,
                       java.lang.Object obj)
                throws XmlToolsException,
                       java.lang.ClassNotFoundException

Process an array element.

This method decodes an array element by calling rdObjectElement or rdPrimitiveType for each array element and assign the retreived values to an array object.

Parameters:

el - The array element to process.

obj - Must be an array of a compatible type with elements that are being readed.

Throws:

XmlToolsException - if an error occurs during the process.

java.lang.ClassNotFoundException - if the some classes could not be loaded.

getClassFromElement

protected java.lang.Class getClassFromElement(org.w3c.dom.Element el)
                                       throws XmlToolsException,
                                              java.lang.ClassNotFoundException

Given an object Element, this method returns the corresponding Class object.

Parameters:

el - The object element to process.

Returns:

the Class object corresponding to el

Throws:

XmlToolsException - If the specified tag is not valid.

java.lang.ClassNotFoundException - if the class specified in el could not be loaded.

allocateObjectInstance

protected java.lang.Object allocateObjectInstance(org.w3c.dom.Element el,
                                                  java.lang.Class cl)
                                           throws XmlToolsException

Given an object Element, this method allocates a new partially initialized instance.
If _requireDefConstructor is false then in the returned object is called a no args constructor of the first non-serializable superclass.

Conversely if _requireDefConstructor is true the default constructor for the class is called. If no default constructor exists, an exception is thrown.

Value of _requireDefConstructor flag depends on the presence of Xrnm dynamic library.

Parameters:

el - Element that describe the instance

cl - Suggested class for the object. The cl value is based on a pre-processing of element el.

Returns:

The new created object of class cl.

Throws:

XmlToolsException - if:

• cl is an array and el has an invalid length attribute.
• istantiation falis, for some reason.
• no default constructor was defined for the first non serializable superclass.
• _requireDefConstructor is true and no default constructor was defined.
• cl is not deserializable.

rdPrimitiveWrapper

protected java.lang.Object rdPrimitiveWrapper(org.w3c.dom.Element el,
                                              java.lang.Class cl)
                                       throws XmlToolsException

Interprets element el as an primitive wrapper element.

Parameters:

el - An XML element that describe a java primitive wrapper.

cl - Class object for the primitive wrapper (obtained by a previous pre-processing of element el).

Returns:

A new object wrapper initialized with the correct value. If el is not a primitive wrapper this method returns null.

Throws:

XmlToolsException - if cl is not a Class object of a primitive wrapper (Integer, Boolean, Float ecc..).

rdObjectElement

protected java.lang.Object rdObjectElement(org.w3c.dom.Element el)
                                    throws XmlToolsException,
                                           java.lang.ClassNotFoundException

Process an element as an objec description element.

This mthod works as follow:

• Enables the registerValidation method.
• if el is an object reference element then try to resolve the rederence:
  • if an object with the same ID was already processed in the past then that object is returned.
  • if no object with the referred ID is found in cache then a out of order processing attempt is made. If this attempr falis an exception is thrown.
    Out of order processing is needed to support balanced DOM tree.
• if el is an object definition element:
  • if el is a 'null' tag then return null
  • Obtain the objectID value
  • If elemement el was already processed as an out of order object reference than the instance stored in cache is returned.
  • Obtain the Class object that el represents.
  • if suidCheck property is true (default) an a Class object was found then the serial version unique identifier (suid) of the serialized Class must equal that of the current class, else an exception is thrown.
  • call rdKnown to possibly process el if it is a known type
  • if rdKnown returns null and no Class object was found then an exception is thrown.
  • If Class retreived is a primitive wrapper then rdPrimitive wrapper is called and the returned object is added to the already processed objects and returns.
  • For ordinary serializable objects:
    • An object instance of the retreived class is allocated.
    • If the object's Class implements the XmlExternalizable then call readXmlExternal(this) else if the Externalizable interface is implemented call the readExternal method with an ObjectOutputStream wrapper (XmlObjectInput).
      Return the allocated instance.
    • call readFields to deserialize the object's fields.
    • return the deserialized instance.

Parameters:

el - XML element to be processed.

Returns:

The new deserialized object.

Throws:

XmlToolsException - if:

• an undefined or invalid object reference is found.
• a class versions conflict is detected (only id suidCheck is true)
• an external reading method fails.
• One of the called methods (described above) throws an XmlToolsException

java.lang.ClassNotFoundException - if the class pointed by Element el could not be found.

hasInterface

protected boolean hasInterface(java.lang.Class cl,
                               java.lang.Class Interface)

Checks if the specified class declare the specified interface.

Parameters:

cl - Class object to examine.

Interface - Class object of the interface to be looked for.

Returns:

true if cl declares the interface Interface.

isMapEntry

protected boolean isMapEntry(org.w3c.dom.Element el)

Returns true if the specified element represent a described map entry tag.

Parameters:

el - Element to be examined.

rdKnown

protected java.lang.Object rdKnown(org.w3c.dom.Element el,
                                   java.lang.Class cl)
                            throws XmlToolsException,
                                   java.lang.ClassNotFoundException

Checks and possibly process an element as a special known type.

This method is dual to the wrKnownField of XmlWriter.

This implementatio introduce support for the following class types:

• java.lang.String
• java.lang.StringBuffer
• Classes that implement the java.util.Map interface (only if the map was described and 'described' attribute is present)
• Classes that implement the java.util.Collection interface (only if the Collection was described and 'described' attribute is present)
• Class objects.

Parameters:

el - element to be examined.

cl - Suggested Class object for element el. Class cl is the suggested class by XmlReader, it may be null. Subclasses are free to ignore the Class parameter.

Returns:

This method must return null if it doesn't know how to process el, else it returns an instance of represented object.

Throws:

XmlToolsException - if el is a known type but for some reason deserialization could not be completed.

java.lang.ClassNotFoundException - due to recoursive calls to rdObjectElement.

CheckCustomization

protected boolean CheckCustomization(java.lang.Object obj,
                                     java.lang.Class cl)
                              throws XmlToolsException

Checks if an object declares a custom readObject method and possibly calls it.

This method checks in the order, for the following methods signatures (they must be declared exactly as follow):

private void readObject (XmlReader rdr);

private void readObject (ObjectInputStream in);

If both are presents only the first is called. You can write customized deserialization code by implementing one of these methods in your classes. While in this methods you can use the XmlReader.registerValidation or ObjectInputStream.registerValidation methods to request a callback after the whol objects graph is constructed.

Please note that readObject compatibility is obtained throughout an XmlReader wrapper that extends the ObjectInputStream class, usually an XmlObjectInput class, you can specify your own wrapper by calling the XmlReader.setObjectInputWrapper method.

Parameters:

obj - object instance whose methods must possibly be called.

cl - Class object to be examined.

Returns:

true if one of the methods above were called successfully.

Throws:

XmlToolsException - if an exception is raised by an invoked custom method or if they are not accessibles.

isEndDefaultData

protected boolean isEndDefaultData(org.w3c.dom.Element el)

Checks if the specified element is an end-default-data tag marker.

See alse BaseXmlTools.tagEndDefaultData.

Parameters:

el - The element to be examined.

Returns:

true id el represens an end default data marker.

isSuperclass

protected boolean isSuperclass(org.w3c.dom.Element el)

Returns true if element el represents a superclass tag.

Parameters:

el - The Element to be examined.

readFields

protected void readFields(org.w3c.dom.Node nd,
                          java.lang.Object obj)
                   throws XmlToolsException,
                          java.lang.ClassNotFoundException

Deserializes all member fields for all the superclasses of obj.

This method call custom readObject methods or default read for the obj's Class object and for all its superclasses.

Parameters:

nd - the DOM element to deserialize.

obj - the allocated target instance of the deserialization process.

Throws:

XmlToolsException

java.lang.ClassNotFoundException

mapField

protected java.lang.reflect.Field mapField(java.lang.Class cl,
                                           org.w3c.dom.Element el)
                                    throws XmlToolsException

Try to map an XML element to a class field.

A field is mapped if and only if it has the same name of the 'field' attribute of XML element, and has the same class type. No type conversion is performed.

Parameters:

el - XML element that should have the 'field' attribute

cl - Class object where to search for.

Returns:

the Field class corresponding to the XML element, null if no Field is found.

Throws:

XmlToolsException

rdInt

protected int rdInt(org.w3c.dom.Element el)
             throws XmlToolsException

This method interpets a given element as an 'int' tag and return his value.

Throws:

XmlToolsException

rdFloat

protected float rdFloat(org.w3c.dom.Element el)
                 throws XmlToolsException

This method interpets a given element as an 'float' tag and return his value.

Throws:

XmlToolsException

rdDouble

protected double rdDouble(org.w3c.dom.Element el)
                   throws XmlToolsException

This method interpets a given element as a 'double' tag and return his value.

Throws:

XmlToolsException

rdLong

protected long rdLong(org.w3c.dom.Element el)
               throws XmlToolsException

This method interpets a given element as a 'long' tag and return his value.

Throws:

XmlToolsException

rdByte

protected byte rdByte(org.w3c.dom.Element el)
               throws XmlToolsException

This method interpets a given element as a 'byte' tag and return his value.

Throws:

XmlToolsException

rdShort

protected short rdShort(org.w3c.dom.Element el)
                 throws XmlToolsException

This method interpets a given element as a 'short' tag and return his value.

Throws:

XmlToolsException

rdChar

protected char rdChar(org.w3c.dom.Element el)
               throws XmlToolsException

This method interpets a given element as a 'char' tag and return his value.

Throws:

XmlToolsException

rdBoolean

protected boolean rdBoolean(org.w3c.dom.Element el)
                     throws XmlToolsException

This method interpets a given element as a 'boolean' tag and return his value.

Throws:

XmlToolsException

rdPrimitiveType

protected java.lang.Object rdPrimitiveType(org.w3c.dom.Element el,
                                           java.lang.Class flc)
                                    throws XmlToolsException

This method will read a primitive element and wrap it to the corresponding primitive wrapper.

Parameters:

el - Element representing a primitive type to be processed.

flc - Primitive class type to wrap.

Returns:

An object wrapper for the primitive type initialized with the read value.

Throws:

XmlToolsException - if flc is not a primitive type Class object and if element el is an invalid primitive element.

rdField

protected void rdField(org.w3c.dom.Element el,
                       java.lang.Object obj,
                       java.lang.Class cl)
                throws XmlToolsException,
                       java.lang.ClassNotFoundException

Process the element el, try to find a suitable field in class cl and assigns the retreived value to obj instance.

This method first search in class cl a suitable field by calling the mapField, if mapping is successful then process element el and assigns the value to the mapped field. If no field can be mapped then this method returns.

The element can represent any java type, primitive or complex.
rdObjectElement is called to process object elements, rdPrimitiveType is called to process simple java types.

Parameters:

el - Element to be processed.

obj - Object instance where to assign the retreived value.

cl - obj's class or one of obj's superclasses, the field is searched in the declared fields of class cl only.

Throws:

XmlToolsException

java.lang.ClassNotFoundException

readObject

public java.lang.Object readObject()
                            throws XmlToolsException,
                                   java.lang.ClassNotFoundException

Process the current Dom element as an object element and return the new allocated object.

After the object and all its components are deserialized, readObject calls any object validator that was registered during the deserialization. Object validators are callback method and can be supplied by calling the registerValidation() method.

Returns:

The new deserialized object

Throws:

XmlToolsException - if:

• object validation fails
• if XML code doesn't represent valid object instance.
• Object is not deserializable.
• No object is avaiable for deserializing: this may occurs if current position element is not an object definition element or if current position is over the last element of the current sub-tree.

java.lang.ClassNotFoundException - if the class specified by the current DOM Element could not be loaded.

readBoolean

public boolean readBoolean()
                    throws XmlToolsException

Process the current DOM element as a boolean element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readByte

public byte readByte()
              throws XmlToolsException

Process the current DOM element as a byte element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readShort

public short readShort()
                throws XmlToolsException

Process the current DOM element as a 'short' element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readChar

public char readChar()
              throws XmlToolsException

Process the current DOM element as a char element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readLong

public long readLong()
              throws XmlToolsException

Process the current DOM element as a 'long' element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readFloat

public float readFloat()
                throws XmlToolsException

Process the current DOM element as a float element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readDouble

public double readDouble()
                  throws XmlToolsException

Process the current DOM element as a 'double' element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

readInt

public int readInt()
            throws XmlToolsException

Process the current DOM element as an int element.

Returns:

The read value.

Throws:

XmlToolsException - if an error occurs during the process.

denormalizeClassName

public java.lang.String denormalizeClassName(java.lang.String className)

Decodes an encoded XML class name and returns a valid Java class name.

Given a class name encoded with the XmlWriter.normalizeClassName method.
This method decodes the input string and return a full java class name. Please refer to XmlWriter.normalizeClassName for details on normalization process.

Parameters:

className - the input string, usually an XML tag name.

Returns:

the denormalized string.

isNull

public boolean isNull(org.w3c.dom.Element el)

Returns true if element el represent a "null" element, i.e. something like

Parameters:

el - The element to be examined.

defaultRead

public void defaultRead()
                 throws XmlToolsException,
                        java.lang.ClassNotFoundException

Implements the default serializing mechanism.
This method can be called only from a custom readObject implementation.
If called in other contexts an exception will be thrown.
This method takes no arguments to simplify custom implementation of readObject methods.
If you want to subclass XmlReader, please be aware that defaultRead has some hidden arguments stored in the following fields:

• def_active
• def_cls
• def_Obj

defaultRead must read all def_Obj fields for class def_cls beginning from the current position mantained by domNav object instance.

Throws:

XmlToolsException - If some object fields are not accessible or if defaultWrite is called outside a custom writeObject method.

java.lang.ClassNotFoundException

registerValidation

public void registerValidation(java.io.ObjectInputValidation obj,
                               int priority)
                        throws java.io.NotActiveException,
                               java.io.InvalidObjectException

Registers an object validator.

Call this method from your custom readXmlExternal or readObject methods to register a callback method.
When the whole graph is constructed but before XmlReader.readObject returns, registered callback are called in ascending priority oredr.

You can implement java.io.ObjectInputValidation interface in your serializable objects and use it to reopen file descriptors, streams, perform validity checks and so on...

Parameters:

obj - Object that implements ObjectInputValidation.

priority - validators with higher value are called earlier, use 0 as default value.

Throws:

java.io.NotActiveException - if XmlReader is not processing any object.

java.io.InvalidObjectException - if obj is null.

setSuidCheck

public void setSuidCheck(boolean value)

Sets the suidCheck property value.

This property is provided to avoid conflicts beetween different versions of the same class.

When this property is true, XmlReader compares the serial version unique identifier (suid) of any serialized class with the current suid for that class, if they differ, an exception will be thrown and graph reconstruction will be impossible.

If this property is set to false no version check is done and the serialized class is always considered compatible with the current class.

You may refer to the Java Object Serialization Specification for compatible class definition.
As described in the document above, please consider to declare a your own suid instead of setting this property to false: declaring a own suid is more reliable than disabling any suid check.

Default value for suidCheck property is true.

setObjectInputWrapper

public void setObjectInputWrapper(java.io.ObjectInputStream inWrap)

Sets the a new ObjectInputStream wrapper that will be used when calling custom reading methods.

Parameters:

inWrap - The new input wrapper.

setTrimRight

public void setTrimRight(boolean value)

Sets the trimRight property value.

This property rules the way a java string is retreived from the DOM: if true any any character following the last "\n" (and the "\n" itself) will be removed from the returned string.

This property is provided because when a DOM is constructed from a Xml file Jaxp add a "\n" and some white spaces that were not included in the original string.
On other hand when a DOM is constructed from scratch no "\n" is added so using this property may be usefull if dealing with latter DOMs.

The default value is true.