javolution.xml

Class XMLObjectReader

java.lang.Object

javolution.xml.XMLObjectReader

All Implemented Interfaces:

Reusable

public class XMLObjectReader
extends java.lang.Object
implements Reusable

This class restores objects which have been serialized in XML format using an XMLObjectWriter.

When the XML document is parsed, each elements are recursively processed and Java objects are created using the XMLFormat of the class as identified by the XMLBinding.

Multiple objects can be read from the same XML input. For example:

     XMLObjectReader reader = XMLObjectReader.newInstance(inputStream);
     while (reader.hasNext()) {
         Message message = reader.read("Message", Message.class);
     }
     reader.close(); // Reader is recycled, the underlying stream is closed.
     

Version:

4.0, September 4, 2006

Author:

Jean-Marie Dautelle

Constructor Summary

Constructors

Constructor and Description
XMLObjectReader() Default constructor.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this reader and its underlying input then reset this reader for potential reuse.
XMLStreamReader	getStreamReader() Returns the stream reader being used by this reader (it can be used to set prefix, read prologs, etc).
boolean	hasNext() Indicates if more elements can be read.
static XMLObjectReader	newInstance(java.io.InputStream in) Returns a XML object reader (potentially recycled) having the specified input stream as input.
static XMLObjectReader	newInstance(java.io.InputStream in, java.lang.String encoding) Returns a XML object reader (potentially recycled) having the specified input stream/encoding as input.
static XMLObjectReader	newInstance(java.io.Reader in) Returns a XML object reader (potentially recycled) having the specified reader as input.
<T> T	read() Returns the object corresponding to the next element/data.
<T> T	read(java.lang.String name) Returns the object corresponding to the next nested element only if it has the specified local name.
<T> T	read(java.lang.String name, java.lang.Class<T> cls) Returns the object corresponding to the next nested element only if it has the specified local name; the actual object type is identified by the specified class parameter.
<T> T	read(java.lang.String localName, java.lang.String uri) Returns the object corresponding to the next nested element only if it has the specified local name and namespace URI.
<T> T	read(java.lang.String localName, java.lang.String uri, java.lang.Class<T> cls) Returns the object corresponding to the next nested element only if it has the specified local name and namespace URI; the actual object type is identified by the specified class parameter.
static void	recycle(XMLObjectReader that) Recycles the specified XMLObjectReader.
void	reset() Resets this object reader for reuse.
XMLObjectReader	setBinding(XMLBinding binding) Sets the XML binding to use with this object reader.
XMLObjectReader	setInput(java.io.InputStream in) Sets the input stream source for this XML object reader (encoding retrieved from XML prolog if any).
XMLObjectReader	setInput(java.io.InputStream in, java.lang.String encoding) Sets the input stream source and encoding for this XML object reader.
XMLObjectReader	setInput(java.io.Reader in) Sets the reader input source for this XML stream reader.
XMLObjectReader	setReferenceResolver(XMLReferenceResolver referenceResolver) Sets the XML reference resolver to use with this object reader (the same resolver can be used accross multiple readers).

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLObjectReader

public XMLObjectReader()

Default constructor.

Method Detail

newInstance

public static XMLObjectReader newInstance(java.io.InputStream in)
                                   throws XMLStreamException

Returns a XML object reader (potentially recycled) having the specified input stream as input.

Parameters:

in - the input stream.

Throws:

XMLStreamException

newInstance

public static XMLObjectReader newInstance(java.io.InputStream in,
                                          java.lang.String encoding)
                                   throws XMLStreamException

Returns a XML object reader (potentially recycled) having the specified input stream/encoding as input.

Parameters:

in - the input stream.

encoding - the input stream encoding

Throws:

XMLStreamException

newInstance

public static XMLObjectReader newInstance(java.io.Reader in)
                                   throws XMLStreamException

Returns a XML object reader (potentially recycled) having the specified reader as input.

Parameters:

in - the reader source.

Throws:

XMLStreamException

recycle

public static void recycle(XMLObjectReader that)

Recycles the specified XMLObjectReader.

Parameters:

that - the instance to recycle.

getStreamReader

public XMLStreamReader getStreamReader()

Returns the stream reader being used by this reader (it can be used to set prefix, read prologs, etc).

Returns:

the stream reader.

setInput

public XMLObjectReader setInput(java.io.InputStream in)
                         throws XMLStreamException

Sets the input stream source for this XML object reader (encoding retrieved from XML prolog if any).

Parameters:

in - the source input stream.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamReaderImpl.setInput(InputStream)

setInput

public XMLObjectReader setInput(java.io.InputStream in,
                                java.lang.String encoding)
                         throws XMLStreamException

Sets the input stream source and encoding for this XML object reader.

Parameters:

in - the input source.

encoding - the associated encoding.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamReaderImpl.setInput(InputStream, String)

setInput

public XMLObjectReader setInput(java.io.Reader in)
                         throws XMLStreamException

Sets the reader input source for this XML stream reader.

Parameters:

in - the source reader.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamReaderImpl.setInput(Reader)

setBinding

public XMLObjectReader setBinding(XMLBinding binding)

Sets the XML binding to use with this object reader.

Parameters:

binding - the XML binding to use.

Returns:

this

setReferenceResolver

public XMLObjectReader setReferenceResolver(XMLReferenceResolver referenceResolver)

Sets the XML reference resolver to use with this object reader (the same resolver can be used accross multiple readers).

Parameters:

referenceResolver - the XML reference resolver.

Returns:

this

hasNext

public boolean hasNext()
                throws XMLStreamException

Indicates if more elements can be read. This method positions the reader at the start of the next element to be read (if any).

Returns:

true if more element/data to be read; false otherwise.

Throws:

XMLStreamException

See Also:

XMLFormat.InputElement.hasNext()

read

public <T> T read()
           throws XMLStreamException

Returns the object corresponding to the next element/data.

Returns:

the next nested object (can be null)

Throws:

XMLStreamException - if hasNext() == false

See Also:

XMLFormat.InputElement.getNext()

read

public <T> T read(java.lang.String name)
           throws XMLStreamException

Returns the object corresponding to the next nested element only if it has the specified local name.

Parameters:

name - the local name of the next element.

Returns:

the next content object or null if the local name does not match.

Throws:

XMLStreamException

See Also:

XMLFormat.InputElement.get(String)

read

public <T> T read(java.lang.String localName,
                  java.lang.String uri)
           throws XMLStreamException

Returns the object corresponding to the next nested element only if it has the specified local name and namespace URI.

Parameters:

localName - the local name.

uri - the namespace URI.

Returns:

the next content object or null if the name/uri does not match.

Throws:

XMLStreamException

See Also:

XMLFormat.InputElement.get(String, String)

read

public <T> T read(java.lang.String name,
                  java.lang.Class<T> cls)
           throws XMLStreamException

Returns the object corresponding to the next nested element only if it has the specified local name; the actual object type is identified by the specified class parameter.

Parameters:

name - the name of the element to match.

cls - the non-abstract class identifying the object to return.

Returns:

read(name, null, cls)

Throws:

XMLStreamException

read

public <T> T read(java.lang.String localName,
                  java.lang.String uri,
                  java.lang.Class<T> cls)
           throws XMLStreamException

Returns the object corresponding to the next nested element only if it has the specified local name and namespace URI; the actual object type is identified by the specified class parameter.

Parameters:

localName - the local name.

uri - the namespace URI.

cls - the non-abstract class identifying the object to return.

Returns:

the next content object or null if no match.

Throws:

XMLStreamException

close

public void close()
           throws XMLStreamException

Closes this reader and its underlying input then reset this reader for potential reuse.

Throws:

XMLStreamException

reset

public void reset()

Resets this object reader for reuse.

Specified by:

reset in interface Reusable