J avolution v5.4 (J2SE 1.6+)

javolution.xml
Class XMLObjectReader

java.lang.Object
  extended by 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
XMLObjectReader()
          Default constructor.
 
Method Summary
 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.
 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

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

J avolution v5.4 (J2SE 1.6+)

Copyright © 2005 - 2009 Javolution.