dsto.dfc.databeans.io
Class XmlInput

java.lang.Object
  dsto.dfc.databeans.io.XmlInput

public class XmlInput
extends Object

Manages decoding of data bean objects from XML.

Basic usage:

   Reader reader = new FileReader ("file.dbxml");
 
   Object decodedObject = xmlInput.read (reader);
    
   reader.close ();
 

Version:

$Revision$

Author:

mpp

Constructor Summary

XmlInput()
Create a new instance using the default XML reader.

XmlInput(String xmlReaderClass)
Create a new instance.

Method Summary

void	finished() Signal reading is finished.
static String	getDefaultXmlReaderClass()
int	getMajorVersion()
int	getMinorVersion()
Object	getProperty(Object name) Get a custom property defined by setProperty(Object, Object).
XmlDecoder	getXmlDecoder(String elementType) Look up a decoder registered with registerXmlDecoder(String, XmlDecoder).
boolean	isMultiObject() See setMultiObject(boolean).
Object	read(org.jdom.Document document) Read an object from a JDOM document.
Object	read(org.jdom.Element root) Read an object from a JDOM root element.
Object	read(Reader stream) Read an object from an XML stream.
org.jdom.Document	readDocument(Reader stream) Read a document from an XML stream using the JDOM SAX reader.
org.jdom.Element	readElement(Reader reader) Shortcut to read the XML and return the root element.
Object	readFile(String filename) Shortcut to read an object from a DBXML file.
static void	registerGlobalTextDecoder(String valueType, String decoderClassName) Register a TextDecoder for this input object.
static void	registerGlobalTextDecoder(String valueType, TextDecoder decoder) Register a TextDecoder for this input object.
static void	registerGlobalXmlDecoder(String elementType, XmlDecoder decoder) Register a global XmlDecoder.
void	registerTextDecoder(String valueType, String decoderClassName) Register a TextDecoder for this input object.
void	registerTextDecoder(String valueType, TextDecoder decoder) Register a TextDecoder for this input object.
void	registerXmlDecoder(String elementType, XmlDecoder decoder) Register an XmlDecoder for this input object.
static void	setDefaultXmlReaderClass(String className) Set the default SAX driver class that will be used by JDOM.
void	setMultiObject(boolean newValue) If set to true (default = false), then multiple elements may be decoded by calling the decode () methods multiple times while sharing the same context.
void	setProperty(Object name, Object value) Define a custom property that will be accessible during this session via getProperty(Object) and XmlDecodeContext.getProperty(Object).

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlInput

public XmlInput()

Create a new instance using the default XML reader. Use read(Reader) to read objects.

XmlInput

public XmlInput(String xmlReaderClass)

Create a new instance. Use read(Reader) to read objects.

Parameters:

xmlReaderClass - The class name of a SAX XMLReader.

Method Detail

setDefaultXmlReaderClass

public static void setDefaultXmlReaderClass(String className)

Set the default SAX driver class that will be used by JDOM. Use null for system default.

getDefaultXmlReaderClass

public static String getDefaultXmlReaderClass()

setProperty

public void setProperty(Object name,
                        Object value)

Define a custom property that will be accessible during this session via getProperty(Object) and XmlDecodeContext.getProperty(Object).

getProperty

public Object getProperty(Object name)

Get a custom property defined by setProperty(Object, Object).

isMultiObject

public boolean isMultiObject()

See setMultiObject(boolean).

setMultiObject

public void setMultiObject(boolean newValue)

If set to true (default = false), then multiple elements may be decoded by calling the decode () methods multiple times while sharing the same context. Reusing the decode context means that if an object decoded by one decode () call references objects defined in another call, the links will resolve. This intended for the case where you might wish to have two object trees encoded separately into two XML documents.

IMPORTANT: If this option is enabled, it is up to the client to call finished() when the decode session is complete, otherwise outstanding links may not be resolved.

finished

public void finished()

Signal reading is finished. Only needed if you enable multi object decoding (@link #setMultiObjectDecode(boolean)}, otherwise this is done automatically after each decode () call.

read

public Object read(Reader stream)
            throws org.jdom.JDOMException,
                   IOException,
                   ClassNotFoundException

Read an object from an XML stream. Reads a serialized JDOM document using readDocument(Reader) and then decodes the document using read(Document). If a DBXML header is present, the major/minor version numbers are read and the first child of the header is read.

Parameters:

stream - The stream to read from.

Returns:

The deserialized value.

Throws:

org.jdom.JDOMException - If the JDOM document builder encounters an error.

ClassNotFoundException - If a class referenced by the serialized stream cannot be found.

IOException

readDocument

public org.jdom.Document readDocument(Reader stream)
                               throws org.jdom.JDOMException,
                                      IOException

Read a document from an XML stream using the JDOM SAX reader.

Parameters:

stream - The stream to read from.

Returns:

The document.

Throws:

org.jdom.JDOMException - If the JDOM SAX document builder encounters an error.

IOException

See Also:

readElement(Reader), read(Reader)

readElement

public org.jdom.Element readElement(Reader reader)
                             throws org.jdom.JDOMException,
                                    IOException

Shortcut to read the XML and return the root element.

Throws:

org.jdom.JDOMException

IOException

readFile

public Object readFile(String filename)
                throws ClassNotFoundException,
                       IOException,
                       IllegalArgumentException

Shortcut to read an object from a DBXML file.

Throws:

ClassNotFoundException

IOException

IllegalArgumentException

read

public Object read(org.jdom.Document document)
            throws IllegalArgumentException,
                   ClassNotFoundException

Read an object from a JDOM document.

Parameters:

document - The document to read from.

Returns:

The decoded value.

Throws:

IllegalArgumentException - if an error is found in the structure of the document.

ClassNotFoundException - If a class referenced by the document cannot be found.

See Also:

read(Element), readDocument(Reader)

read

public Object read(org.jdom.Element root)
            throws IllegalArgumentException,
                   ClassNotFoundException

Read an object from a JDOM root element.

Parameters:

root - The root element to read from.

Returns:

The decoded value.

Throws:

IllegalArgumentException - if an error is found in the structure of the document.

ClassNotFoundException - If a class referenced by the document cannot be found.

See Also:

read(Document), read(Reader)

getMajorVersion

public int getMajorVersion()

getMinorVersion

public int getMinorVersion()

registerXmlDecoder

public void registerXmlDecoder(String elementType,
                               XmlDecoder decoder)

Register an XmlDecoder for this input object.

Parameters:

elementType - The element type. The decoder will be used to decode all element's that have this name.

decoder - The decoder.

See Also:

registerGlobalXmlDecoder(String, XmlDecoder)

getXmlDecoder

public XmlDecoder getXmlDecoder(String elementType)

Look up a decoder registered with registerXmlDecoder(String, XmlDecoder).

registerTextDecoder

public void registerTextDecoder(String valueType,
                                String decoderClassName)

Register a TextDecoder for this input object.

Parameters:

valueType - The value type. The decoder will be used to decode all element's that are compatible with this type as defined by TypeMap.

decoderClassName - The decoder class name. The decoder class will be instantiated when/if an object of the specified type is encountered.

See Also:

registerGlobalTextDecoder(String, String)

registerTextDecoder

public void registerTextDecoder(String valueType,
                                TextDecoder decoder)

Register a TextDecoder for this input object.

Parameters:

valueType - The value type. The decoder will be used to decode all element's that are compatible with this type as defined by TypeMap.

decoder - The decoder.

See Also:

registerGlobalTextDecoder(String, String)

registerGlobalXmlDecoder

public static void registerGlobalXmlDecoder(String elementType,
                                            XmlDecoder decoder)

Register a global XmlDecoder. All XmlInput instances created after this call will use the registered decoder by default.

Parameters:

elementType - The element type. The decoder will be used to decode all element's that have this name.

decoder - The decoder.

See Also:

registerXmlDecoder(String, XmlDecoder)

registerGlobalTextDecoder

public static void registerGlobalTextDecoder(String valueType,
                                             String decoderClassName)

Register a TextDecoder for this input object. All XmlInput instances created after this call will use the registered decoder by default.

Parameters:

valueType - The value type. The decoder will be used to decode all element's that are compatible with this type as defined by TypeMap.

decoderClassName - The decoder class name. The decoder class will be instantiated when/if an object of the specified type is encountered.

See Also:

registerTextDecoder(String, TextDecoder)

registerGlobalTextDecoder

public static void registerGlobalTextDecoder(String valueType,
                                             TextDecoder decoder)

Register a TextDecoder for this input object. All XmlInput instances created after this call will use the registered decoder by default.

Parameters:

valueType - The value type. The decoder will be used to decode all element's that are compatible with this type as defined by TypeMap.

decoder - The decoder.

See Also:

registerTextDecoder(String, String)