it.unimo.dbgroup.momis.XmlTools
Class XmlWriter

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

public class XmlWriter

extends BaseObjectDomStreamer

This class create a DOM tree representing a description or serialization of any Java object passed as input.
Depending on the value of various properties the output can be an object description or an object serialization. An object can be serialized by simply call writeObject method, just like the normal serialization mechanism.

writeObject(Foo);

When any of writeXXXX methods is called no output is generated, but the associated DOM document will be updated.

This implementation does not provide any methods to write the associated DOM document to an output stream.
There is a valid reason for that:
DOM Level 1, 2 specifications don't support a standard way to accomplish this operation.
In JAXP 1.0.1 implementation by Sun Micorsystems writing a DOM to an OutputStream can be easely implemented by casting the org.w3c.dom.Document as com.sun.xml.tree.XmlDocument and calling XmlDocument's write() method. as follows:

public void writeToStream(OutputStream out) {


((XmlDocument)A_DomDocument).write(out);


}

To obtain an org.w3c.dom.Document from XmlWriter simply call the getDocument() method.

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

private writeObject(ObjectOutputStream out);

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

private writeObject(XmlWriter out);

method.
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: - Togliere le ridondanze (superclass vuoti, usare valori 0 di default) - fare in modo che nei riferimenti non sia necessario il nome della classe - rendere opzionale l'aggiunta degli xmlns - implementare writeComment(String);

Author:

Davide Lenzi nov. 2000

See Also:

XmlObjectOutput, XmlExternalizable

Field Summary

private boolean	_classNameAsTagName internal value for the classNameAsTagName property.
private boolean	_collEnabled internal value for the collectionDescription property.
private org.w3c.dom.Node	_curnd Internal reference to the current position in the DOM tree.
private boolean	_customCall defaultWrite() cloacked argument.
protected javax.xml.parsers.DocumentBuilder	_db Builder used to obtain a new DOM tree.
protected boolean	_def_active When true, defaultWrite() method is enabled. Calling defaultWrite when it is disabled will cause an exception.
protected java.lang.Class	_defClass defaultWrite() cloacked argument
protected org.w3c.dom.Node	_defNode defaultWrite() cloacked argument
protected java.lang.Object	_defObj defaultWrite() cloacked argument
protected org.w3c.dom.Document	_dox DOM tree reference.
private boolean	_fullClassNameAsAttribute internal value for the fullClassNameAsAttribute property.
private boolean	_fullJavaClassName internal value for the fullJavaClassName property.
private boolean	_IgnoreSerializable internal value for the ignoreSerializable property.
protected org.w3c.dom.Node	_lastnd A reference to the last created DOM node.
private boolean	_mapEnabled internal value for the mapDescription property.
private boolean	_ObjectArchive internal value for the ObjectArchive flag.
private java.io.ObjectOutputStream	_outWrap Internal reference to an ObjectOutputStream wrapper.
protected org.w3c.dom.Element	_startElement Starting element where all writer methods begin to write.
private boolean	_suidCheck Internal value for the suidCheck property
protected java.util.HashMap	_suidMap Map with Class objects as keys and suid as values
private org.w3c.dom.Element	_suidMapElement Element that contains the suid table
static javax.xml.parsers.DocumentBuilderFactory	dbf public factory used to generate DocumentBuilder.
protected ObjectsList	objs_written Data structure that is used internally to manage object reference elements.
private static java.lang.Class[]	parTypes Parameter type used when searching for a custom writeObject method.
private static java.lang.Class[]	parTypesWrap Parameter type used when searching for a custom writeObject method.

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

XmlWriter()
XmlWriter default constructor.

XmlWriter(org.w3c.dom.Document dox, org.w3c.dom.Element startElement)
Use this contructor to supply a Document object to XmlWriter.

Method Summary

protected void	addFieldAttribute(org.w3c.dom.Element el, java.lang.String field) This simple method add the field attribute to an object tag.
protected void	addToSUIDTable(java.lang.Object obj) Add a new class to the suid table.
void	balanceDOM() When is called, elements in the DOM tree are rearranged to produce a balanced tree.
protected boolean	CheckCustomization(org.w3c.dom.Node nd, java.lang.Object obj, java.lang.Class cl) Checks if an object, passed as argument, define the writeObject method to customize writing process.
protected org.w3c.dom.Element	createObjectTag(java.lang.String field, java.lang.Object obj, java.lang.Integer object_id) Creates a DOM element with the specified parameters representing an XML object start tag.
protected org.w3c.dom.Element	createObjRefTag(java.lang.String field, java.lang.Object obj, java.lang.Integer object_id) Creates an object reference element.
protected org.w3c.dom.Node	createRootElement(java.lang.String tagName) If XmlWriter is created with an empty DOM tree, createRootElement is called to provide a XML root element.
void	defaultWrite() Implements the default serializing mechanism.
org.w3c.dom.Element	getCurrentElement() Returns the Xml element that is being created.
org.w3c.dom.Document	getDocument() Retreive the DOM tree used by writer methods.
org.w3c.dom.Element	getLastCreatedElement() Returns the last created element by a writer method.
private void	Initialize() Performs initializations common to all constructors.
java.lang.String	normalizeClassName(java.lang.String className) Convert a full java class name in a form that can be used as tag name.
void	setClassNameAsTagName(boolean value) Sets the classNameAsTagName property value.
void	setCollectionDescription(boolean value) Sets the collectionDescription property value.
void	setFullClassNameAsAttribute(boolean value) Sets the fullClassNameAsAttribute property value.
void	setFullJavaClassName(boolean value) Sets the fullJavaClassName property value.
void	setIgnoreSerializable(boolean value) Sets the ignoreSerializable property value.
void	setMapDescription(boolean value) Sets the mapDescription property value.
private void	setObjectArchive(boolean value) Sets the _ObjectArchive flag and updates the start element element.
void	setObjectOutputWrapper(java.io.ObjectOutputStream outWrap) Sets a new wrapper to call custom writeObject or writeExternal methods.
void	setSuidCheck(boolean value) Sets the suidCheck property value.
protected void	swapElementsID_REF(org.w3c.dom.Element id, org.w3c.dom.Element ref) Swaps an object definition element with a reference element that has the same ID.
protected org.w3c.dom.Node	wrArrayField(org.w3c.dom.Node nd, java.lang.String field, java.lang.Object obj) Writes an array in the DOM tree.
protected org.w3c.dom.Node	wrField(org.w3c.dom.Node nd, java.lang.String field, java.lang.Object obj) Examines an object and call the proper method to convert it in a DOM element.
void	writeBoolean(boolean v) Writes a boolean value to the current position in the DOM tree.
void	writeByte(byte v) Writes a byte value to the current position in the DOM tree.
protected void	writeCDATASection(org.w3c.dom.Node nd, java.lang.String data) Writes a string as a CDATA section.
void	writeChar(char v) Writes a char value to the current position in the DOM tree.
void	writeComment(java.lang.String message) Puts an XML comment in the DOM tree.
void	writeDouble(double v) Writes a double value to the current position in the DOM tree.
protected void	writeEndDefaultDataMarker(org.w3c.dom.Node nd) Writes the end-default-data marker tag inside node nd.
org.w3c.dom.Node	writeField(java.lang.String field, java.lang.Object obj) Same as writeObject but it adds the field name information.
void	writeFloat(float v) Writes a float value to the current position in the DOM tree.
void	writeInt(int v) Writes an int value to the current position in the DOM tree.
void	writeLong(long v) Writes a long value to the current position in the DOM tree.
void	writeObject(java.lang.Object obj) Writes passed object to the current position in the DOM tree.
void	writeShort(short v) Writes a short value to the current position in the DOM tree.
protected org.w3c.dom.Node	wrKnownField(org.w3c.dom.Node nd, java.lang.String field, java.lang.Object obj) Check if obj is a known object (strings, HashMap ecc) and return a DOM element with a customized description.
protected org.w3c.dom.Node	wrNull(org.w3c.dom.Node nd, java.lang.String field) Writes a <null> element for the passed field.
private void	wrObjFields(org.w3c.dom.Node nd, java.lang.Object obj) Writes inside DOM the internal fields of an object.
protected org.w3c.dom.Node	wrPrimitiveField(org.w3c.dom.Node nd, java.lang.String field, java.lang.Class primitiveType, java.lang.Object value) Writes a primitive field in the DOM.
protected org.w3c.dom.Node	wrWrapperField(org.w3c.dom.Node nd, java.lang.String field, java.lang.Object wrapper) Writes a primitive wrapper field in the DOM.

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

_outWrap

private java.io.ObjectOutputStream _outWrap

Internal reference to an ObjectOutputStream wrapper.

dbf

public static javax.xml.parsers.DocumentBuilderFactory dbf

public factory used to generate DocumentBuilder.
Users can customize this field so that XmlWriter can use other kind of factories.
If this field is null a new standar factory is allocated at the first constructor call.

objs_written

protected ObjectsList objs_written

Data structure that is used internally to manage object reference elements.
The objects in the list are objects that have already been written to the DOM.

_customCall

private boolean _customCall

defaultWrite() cloacked argument.
if true a tagEndDefaultData is written after all data fields.

When defaultWrite is called by a custom writeObject method then a tagEndDefaultData must be written to mark the end of default data block.
When defaultWrite is called internally to write out object fields no end marker is written.

_defClass

protected java.lang.Class _defClass

defaultWrite() cloacked argument

Represents the class that defaultWrite must write to the DOM.

_defNode

protected org.w3c.dom.Node _defNode

defaultWrite() cloacked argument

Represents the DOM entry point where defaultWrite must write.

_defObj

protected java.lang.Object _defObj

defaultWrite() cloacked argument

Represents the object instance that defaultWrite is going to write to the DOM.

_def_active

protected boolean _def_active

When true, defaultWrite() method is enabled.
Calling defaultWrite when it is disabled will cause an exception.

_lastnd

protected org.w3c.dom.Node _lastnd

A reference to the last created DOM node.

This member variable is updated by all methods that write to the DOM and represent the last created element.

_db

protected javax.xml.parsers.DocumentBuilder _db

Builder used to obtain a new DOM tree.
If no existing Document is supplied to XmlWriter then this Builder is used to obtain a new DOM Document instance.

_dox

protected org.w3c.dom.Document _dox

DOM tree reference.

This is the target of all writer methods.

_startElement

protected org.w3c.dom.Element _startElement

Starting element where all writer methods begin to write.

_curnd

private org.w3c.dom.Node _curnd

Internal reference to the current position in the DOM tree.

_classNameAsTagName

private boolean _classNameAsTagName

internal value for the classNameAsTagName property.

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

_fullClassNameAsAttribute

private boolean _fullClassNameAsAttribute

internal value for the fullClassNameAsAttribute property.

if true for every object element is added the attribute "class" with the full java class name as value.

_fullJavaClassName

private boolean _fullJavaClassName

internal value for the fullJavaClassName property.

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

_ObjectArchive

private boolean _ObjectArchive

internal value for the ObjectArchive flag.
When true the Xml document produced can be deserialized.

_suidCheck

private boolean _suidCheck

Internal value for the suidCheck property

_IgnoreSerializable

private boolean _IgnoreSerializable

internal value for the ignoreSerializable property.

parTypes

private static java.lang.Class[] parTypes

Parameter type used when searching for a custom writeObject method.

Internal use. DO NOT MODIFY!

parTypesWrap

private static java.lang.Class[] parTypesWrap

Parameter type used when searching for a custom writeObject method.

Internal use. DO NOT MODIFY!

_mapEnabled

private boolean _mapEnabled

internal value for the mapDescription property.

_collEnabled

private boolean _collEnabled

internal value for the collectionDescription property.

_suidMap

protected java.util.HashMap _suidMap

Map with Class objects as keys and suid as values

_suidMapElement

private org.w3c.dom.Element _suidMapElement

Element that contains the suid table

Constructor Detail

XmlWriter

public XmlWriter()
          throws javax.xml.parsers.ParserConfigurationException,
                 java.io.IOException

XmlWriter default constructor.
When using this constructor a new empty Document is allocated. If no factory was supplied for Document generation then a new one is allocated first.
By default XmlWriter is configured to produce a deserializable representation of objects that will be passed to writeObject method.

Please see setClassNameAsTagName, setFullJavaClassName or setFullClassNameAsAttribute methods for more details.

Throws:

javax.xml.parsers.ParserConfigurationException - If document builder factory is not properly configured.

java.io.IOException

XmlWriter

public XmlWriter(org.w3c.dom.Document dox,
                 org.w3c.dom.Element startElement)
          throws javax.xml.parsers.ParserConfigurationException,
                 java.io.IOException

Use this contructor to supply a Document object to XmlWriter.
If no factory was supplied for Document generation then a new one is allocated first.

Parameters:

dox - The document that will be used for writing operations.

startElement - starting element, all write methods will insert its data as child elements of startElement.

Throws:

javax.xml.parsers.ParserConfigurationException - If document builder factory is not properly configured.

java.io.IOException

Method Detail

Initialize

private void Initialize()
                 throws java.io.IOException

Performs initializations common to all constructors. This also set some properties default values.

Throws:

java.io.IOException

wrObjFields

private void wrObjFields(org.w3c.dom.Node nd,
                         java.lang.Object obj)
                  throws XmlToolsException

Writes inside DOM the internal fields of an object.
This method check if the passed object is serializable by calling isSerializable() according to the ignoreSerializable property value.
At first the object fields are written, then the internal fields for each superclass are written in the DOM.
This method write a <superclass> to divide each superclass type from the others and call defaultWrite() to actually write field values. Note that defaultWrite() is called only if obj doen't define its own writeObject() method.

Parameters:

nd - The DOM node where fields are added.

obj - Object those fields must be written

Throws:

XmlToolsException - if one of the internal method called falis.

setObjectArchive

private void setObjectArchive(boolean value)

Sets the _ObjectArchive flag and updates the start element element.

This method is called internally by setClassNameAsTagName, setFullJavaClassName and setFullClassNameAsAttribute methods.

swapElementsID_REF

protected void swapElementsID_REF(org.w3c.dom.Element id,
                                  org.w3c.dom.Element ref)
                           throws XmlToolsException

Swaps an object definition element with a reference element that has the same ID.

This methods modifies the DOM to exchange two elements with the same object ID. The two element must be an object definition element and an object reference element.

Parameters:

id - The object definition element (must have attribute objectID).

ref - The object reference element (must have attribute objectREF).

Throws:

XmlToolsException - if the passed parameters are not valid object ID and REF elements

createRootElement

protected org.w3c.dom.Node createRootElement(java.lang.String tagName)

If XmlWriter is created with an empty DOM tree, createRootElement is called to provide a XML root element.

Parameters:

tagName - Name of the root tag.

Returns:

The created Element.

createObjRefTag

protected org.w3c.dom.Element createObjRefTag(java.lang.String field,
                                              java.lang.Object obj,
                                              java.lang.Integer object_id)

Creates an object reference element.
Override this method if you want to customize object reference elements.

Parameters:

field - Field name.

obj - Object instance to reference.

object_id - object ID for the instance.

Returns:

The created element.

createObjectTag

protected org.w3c.dom.Element createObjectTag(java.lang.String field,
                                              java.lang.Object obj,
                                              java.lang.Integer object_id)
                                       throws XmlToolsException

Creates a DOM element with the specified parameters representing an XML object start tag.
First this method check id obj implements the FullXmlExternalizable interface and eventually invokes the
createObjectTag method. If FullXmlExternalizable is not implemented, then a standar object element is created.

The layout of the element created may vary accordig to the values of suidCheck, classNameAsTagName, fullJavaClassName and fullClassNameAsAttribute property values.

Parameters:

field - The field name.

obj - object instance being descibed.

object_id - Integer wrapper of the object ID value. This value is univoke in the whole DOM tree.

Returns:

The just created DOM Element.

Throws:

XmlToolsException - If errors are encoutered during invocation of a custom createObjectTag method or if if the returned element from a custom createObjectTag is null.

addFieldAttribute

protected void addFieldAttribute(org.w3c.dom.Element el,
                                 java.lang.String field)

This simple method add the field attribute to an object tag.
<... field="fieldname" ...>

Override this method if you want to change the standard way XmlWriter uses.

Please, note that XmlReader use the field attribute to map XML data into object fields.
If field is an empty string then no attribute is added.

Parameters:

el - DOM Element where the attribute must be added.

field - Name of the field that is being written.

wrNull

protected org.w3c.dom.Node wrNull(org.w3c.dom.Node nd,
                                  java.lang.String field)

Writes a <null> element for the passed field.

Null elements represent the null java value for an object reference.

Parameters:

nd - DOM node where the new created element must be added.

field - Field name for the null element.

Returns:

the new created 'null' element.

writeEndDefaultDataMarker

protected void writeEndDefaultDataMarker(org.w3c.dom.Node nd)

Writes the end-default-data marker tag inside node nd.

The end-default-Data-Marker is a special tag that tells XmlReader.defaultRead() that normal data ends here.

Parameters:

nd - destination Node where the tag must be added.

CheckCustomization

protected boolean CheckCustomization(org.w3c.dom.Node nd,
                                     java.lang.Object obj,
                                     java.lang.Class cl)
                              throws XmlToolsException

Checks if an object, passed as argument, define the writeObject method to customize writing process.
this methods look for the following method in obj's class:

private void writeObject(XmlWriter out) throws XmlToolsException;

If writeObject is found it is invoked.

Parameters:

nd - DOM node where custom data should be written.

obj - object instance to check.

cl - may be one of the obj's superclasses or obj's class itself. writeObject is espected to write fields of class cl only.

Returns:

true if writeObject is found and it is ivoked successfully.
false in other cases.

Throws:

XmlToolsException - if some errors occur during writeObject invocation.

wrPrimitiveField

protected org.w3c.dom.Node wrPrimitiveField(org.w3c.dom.Node nd,
                                            java.lang.String field,
                                            java.lang.Class primitiveType,
                                            java.lang.Object value)

Writes a primitive field in the DOM.

This method convert a primitive object wrapper (Integer, Boolean and so on...) in a DOM Element.

Parameters:

nd - destination node where the primitive element tag must be written.

field - Field name.

primitiveType - Java class object corresponding to a primitive type.

value - is a primitive wrapper that contains value to write.

Returns:

the new created element.

wrWrapperField

protected org.w3c.dom.Node wrWrapperField(org.w3c.dom.Node nd,
                                          java.lang.String field,
                                          java.lang.Object wrapper)
                                   throws XmlToolsException

Writes a primitive wrapper field in the DOM.

This method will register the passed wrapper as a know object so that future references will produce obly an objcet reference element.

Parameters:

nd - Destination node where the new tag must be written.

field - Field name.

wrapper - The object wrapper that must be written.

Returns:

The new created node.

Throws:

XmlToolsException - if object registration fails or the DOM destination is invalid.

writeCDATASection

protected void writeCDATASection(org.w3c.dom.Node nd,
                                 java.lang.String data)

Writes a string as a CDATA section.

Parameters:

nd - Destination where the CDATA section must be added.

data - string that must be converted.

wrKnownField

protected org.w3c.dom.Node wrKnownField(org.w3c.dom.Node nd,
                                        java.lang.String field,
                                        java.lang.Object obj)
                                 throws XmlToolsException

Check if obj is a known object (strings, HashMap ecc) and return a DOM element with a customized description.

This method supply a support for the following java types:

• String
• StringBuffer
• Map (described)
• Collection (described)
• Class

If obj is unknown then this method MUST return null. Descendants of XmlWriter can override this method to change the way a standard Java object is written into DOM.

Descendant method looks like:

protected Node wrKnownField(Node nd, String field, Object obj){
if (IknowStandardObj(obj)) {
your customized code...
} else return super.wrKnownField(nd,field,obj);

NOTE: Do not override this method to support your customized class, you can use yourClass.writeObject or you can implement XmlExternalizable interface instead.

Parameters:

nd - Destination node where obj must be written.

field - Field name.

obj - Object that must be written.

Returns:

The new created element if obj is a known type else this method must return null.

Throws:

XmlToolsException

wrArrayField

protected org.w3c.dom.Node wrArrayField(org.w3c.dom.Node nd,
                                        java.lang.String field,
                                        java.lang.Object obj)
                                 throws XmlToolsException

Writes an array in the DOM tree.

Parameters:

nd - DOM node where array is inserted.

field - Field name.

obj - An instance of an array type.

Returns:

The created element representing the array.

Throws:

XmlToolsException - if errors are encountered.

wrField

protected org.w3c.dom.Node wrField(org.w3c.dom.Node nd,
                                   java.lang.String field,
                                   java.lang.Object obj)
                            throws XmlToolsException

Examines an object and call the proper method to convert it in a DOM element.

The objects writing feature of XmlWriter is supplied with this method, it works as follows:

• If obj is null then write a null element tag.
• If obj is an object that it was already written in the DOM then a object reference element is created via createObjRefTag() method.
• If obj is an array then wrArrayField is called to accomplish the task and returns.
• Call wrKnownField() to see if obj is a speical object type (Strings, Maps and Collections are written in XmlWriter.wrKnownField().
• If wrKnownField return null, this method checks if obj represent a primitive wrapper and, in case, it calls wrWrapperField.
• If none of the above conditions is true, then obj represents a standard java object and it is processed:
  • If obj is not Serializable an exception is thrown.
  • obj is registered in the known object instances set.
  • createObjectElement is called.
  • If obj implements XmlExternalizable interface then the writing process is accomplished by obj.writeXmlExternal(...)
  • Else wrObjFields(...) is called to write all serializable object fields.

Throws:

XmlToolsException

addToSUIDTable

protected void addToSUIDTable(java.lang.Object obj)
                       throws java.io.NotSerializableException

Add a new class to the suid table.

This method will add the obj's Class object and suid to the suid table.

suid table must be always mantained, it is inserted into the DOM tree only if suidCheck property is true.

Parameters:

obj - the obj.getClass() is used to update the suid table.

Throws:

java.io.NotSerializableException - if obj's Class implements none of the Serializable, Externalizable or XmlExternalizable interfaces.

defaultWrite

public void defaultWrite()
                  throws XmlToolsException

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

• _def_active
• _defClass
• _defObj
• _defNode

defaultWrite must write all _defObj fields for class _defClass in the DOM node _defNode

Throws:

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

normalizeClassName

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

Convert a full java class name in a form that can be used as tag name.
This method compacts the class name according to the value of fullJavaClassName property and it converts the following characters in other forms that can be used as XML tag names:

• '$' in '_S'
• '_' in '__'
• '[' in '_Q'
• ';' in '_V'

Parameters:

className - full name to compact.

Returns:

String with the normalized compact name.

getDocument

public org.w3c.dom.Document getDocument()

Retreive the DOM tree used by writer methods.
This is the 'output' of XmlWriter.

Returns:

DOM tree used by writer methods.

writeObject

public void writeObject(java.lang.Object obj)
                 throws XmlToolsException

Writes passed object to the current position in the DOM tree.

Call this method to serialize or to describe an object.

Parameters:

obj - The java object to be serialized.

Throws:

XmlToolsException - if an error occurs during the process.

writeBoolean

public void writeBoolean(boolean v)
                  throws XmlToolsException

Writes a boolean value to the current position in the DOM tree.

Parameters:

v - The boolean value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeByte

public void writeByte(byte v)
               throws XmlToolsException

Writes a byte value to the current position in the DOM tree.

Parameters:

v - The byte value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeShort

public void writeShort(short v)
                throws XmlToolsException

Writes a short value to the current position in the DOM tree.

Parameters:

v - The short value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeChar

public void writeChar(char v)
               throws XmlToolsException

Writes a char value to the current position in the DOM tree.

Parameters:

v - The char value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeInt

public void writeInt(int v)
              throws XmlToolsException

Writes an int value to the current position in the DOM tree.

Parameters:

v - The int value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeLong

public void writeLong(long v)
               throws XmlToolsException

Writes a long value to the current position in the DOM tree.

Parameters:

v - The long value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeFloat

public void writeFloat(float v)
                throws XmlToolsException

Writes a float value to the current position in the DOM tree.

Parameters:

v - The float value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

writeDouble

public void writeDouble(double v)
                 throws XmlToolsException

Writes a double value to the current position in the DOM tree.

Parameters:

v - The double value to be written.

Throws:

XmlToolsException - if an error occurs during the process.

getLastCreatedElement

public org.w3c.dom.Element getLastCreatedElement()

Returns the last created element by a writer method.

getCurrentElement

public org.w3c.dom.Element getCurrentElement()

Returns the Xml element that is being created.

writeField

public org.w3c.dom.Node writeField(java.lang.String field,
                                   java.lang.Object obj)
                            throws XmlToolsException

Same as writeObject but it adds the field name information.

Data written by this method can be read usig XmlReader.ReadObject() method.

Parameters:

field - Field name.

obj - The java object to be serialized.

Returns:

The new added element to the DOM tree.

Throws:

XmlToolsException - if an error occurs during the process.

setClassNameAsTagName

public void setClassNameAsTagName(boolean value)

Sets the classNameAsTagName property value.
If value is true, class names are used as tag name for object elements.

If the new state is a meaningful object archive then the ObjectArchive flag is set. Note that only archive with ObjectArchive = true can be succesfully deserialized.

Default value for this property is false

Valid properties values for ObjectArchive=true are:
default:
classNameAsTagName = false
fullJavaClassName = true | false
fullClassNameAsAttribute = true

Example:
<object objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = false
fullClassNameAsAttribute = true

Example:
<String objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = true
fullClassNameAsAttribute = flase

Example:
<java.lang.String objectID="1" field="value">

Parameters:

value - property value to assign.

setFullClassNameAsAttribute

public void setFullClassNameAsAttribute(boolean value)

Sets the fullClassNameAsAttribute property value.
If value is true, for every object element is added the attribute "class" with the full java class name as value.

If the new state is a meaningful object archive then the ObjectArchive flag is set. Note that only archive with ObjectArchive = true can be succesfully deserialized.

Default value for this property is true

Valid properties values for ObjectArchive=true are:
default:
classNameAsTagName = false
fullJavaClassName = true | false
fullClassNameAsAttribute = true

Example:
<object objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = false
fullClassNameAsAttribute = true

Example:
<String objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = true
fullClassNameAsAttribute = flase

Example:
<java.lang.String objectID="1" field="value">

Parameters:

value - property value to assign.

setFullJavaClassName

public void setFullJavaClassName(boolean value)

Sets the fullJavaClassName property value.

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

If the new state is a meaningful object archive then the ObjectArchive flag is set. Note that only archive with ObjectArchive = true can be succesfully deserialized.

Default value for this property is false

Valid properties values for ObjectArchive=true are:
default:
classNameAsTagName = false
fullJavaClassName = true | false
fullClassNameAsAttribute = true

Example:
<object objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = false
fullClassNameAsAttribute = true

Example:
<String objectID="1" class="java.lang.String" field="value">

classNameAsTagName = true
fullJavaClassName = true
fullClassNameAsAttribute = flase

Example:
<java.lang.String objectID="1" field="value">

Parameters:

value - property value to assign.

setIgnoreSerializable

public void setIgnoreSerializable(boolean value)

Sets the ignoreSerializable property value.

Parameters:

value - If true even objects that doesn't implement the Serializable interface are serialized or described.

setMapDescription

public void setMapDescription(boolean value)

Sets the mapDescription property value.

If property is set to true, all objects that implements an Map interface are described in Xml format as a list of key-value pairs. If property is set to false all objects that implement a Map interface are processed as ordinary objects. Default value for this porperty is false. Note that map description doesn't preserve the load factor or the threshold values for hash maps.

setCollectionDescription

public void setCollectionDescription(boolean value)

Sets the collectionDescription property value.

Parameters:

value - If value is true then every object that implements the Collection interface is described as an objects list.

Default value for this property is false

setSuidCheck

public void setSuidCheck(boolean value)

Sets the suidCheck property value.

When this property is true, a 'meta' tag is present as first child of the start element and a suid table is stored inside. Default value for suidCheck property is true.

balanceDOM

public void balanceDOM()
                throws XmlToolsException

When is called, elements in the DOM tree are rearranged to produce a balanced tree.
This method rearrange elements in the following way:
for each object definition element (those with objectID attribute),
if a reference element exists and it has a lower depth then a swap will occur. When algotithm ends no reference Element has lower depth of corresponding definition element.

Throws:

XmlToolsException - if an error occurs during the process.

setObjectOutputWrapper

public void setObjectOutputWrapper(java.io.ObjectOutputStream outWrap)

Sets a new wrapper to call custom writeObject or writeExternal methods.

Parameters:

outWrap - The new wrapper.

writeComment

public void writeComment(java.lang.String message)

Puts an XML comment in the DOM tree.

Parameters:

message - The comment message to be written.