gov.sandia.cognition.io

Class XStreamSerializationHandler

java.lang.Object

gov.sandia.cognition.io.XStreamSerializationHandler

@CodeReview(reviewer="Kevin R. Dixon",date="2008-12-02",changesNeeded=false,comments={"Minor cosmetic changes.","Otherwise, this wrapper class is fine."}) @CodeReview(reviewer="Kevin R. Dixon",date="2008-02-08",changesNeeded=false,comments={"Changed the read() method to close the stream it creates after reading.","Minor formatting change, and fixed a few typos.","Added PublicationReference for the Object Streams Tutorial.","Otherwise, looks fine."})
 @PublicationReference(author="XStream Documentation",
                      title="Object Streams Tutorial",
                      type=WebPage,
                      year=2008,
                      url="http://xstream.codehaus.org/objectstream.html")
 @SoftwareReference(name="XStream",
                   version="1.2.1",
                   url="http://xstream.codehaus.org/",
                   license=BSD,
                   licenseURL="http://xstream.codehaus.org/")
public class XStreamSerializationHandler
extends java.lang.Object

Reads and writes Objects in XML format. Generally speaking, this requires no extra methods for an Object (it's automagic using Reflection). Based on XStream package.

KNOWN LIMITATION: The read() method will thrown an exception "java.io.IOException: com.thoughtworks.xstream.io.StreamException: : input contained no data" when trying to read the SECOND object from an XML InputStream/Reader. This is because XML files must have a single root node (which would be the FIRST object in the file), and anything after the close of the root node (the SECOND object) is considered invalid or nonexistent. To address the limitation, refer to http://xstream.codehaus.org/objectstream.html

Since:

1.0

Author:

Kevin R. Dixon

Constructor Summary

Constructors

Constructor and Description
XStreamSerializationHandler()

Method Summary

Modifier and Type	Method and Description
static java.lang.Object	convertFromString(java.lang.String string) Attempts to read an Object from the given string.
static java.lang.String	convertToString(java.io.Serializable object) Writes the given object to a String.
static java.lang.Object	read(java.io.InputStream stream) Reads an Object from the given InputStream.
static java.lang.Object	read(java.io.Reader reader) Reads an Object from the given Reader.
static java.lang.Object	readFromFile(java.io.File file) Reads an Object from the given file name.
static java.lang.Object	readFromFile(java.lang.String fileName) Reads an Object from the given file name.
static boolean	write(java.io.OutputStream stream, java.io.Serializable object) Writes the given object to the given OutputStream
static boolean	write(java.io.Writer writer, java.io.Serializable object) Writes the given object to the given Writer
static void	writeToFile(java.io.File file, java.io.Serializable object) Writes the given object to the given file using XStream serialization.
static void	writeToFile(java.lang.String fileName, java.io.Serializable object) Writes the given object to the given file using XStream serialization.

Methods inherited from class java.lang.Object

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

Constructor Detail

XStreamSerializationHandler

public XStreamSerializationHandler()

Method Detail

write

public static boolean write(java.io.OutputStream stream,
                            java.io.Serializable object)
                     throws java.io.IOException

Writes the given object to the given OutputStream

Parameters:

stream - OutputStream to write the object to

object - Object to write to the OutputStream

Returns:

true on success, false otherwise

Throws:

java.io.IOException - If there's a problem writing

write

public static boolean write(java.io.Writer writer,
                            java.io.Serializable object)
                     throws java.io.IOException

Writes the given object to the given Writer

Parameters:

writer - Writer to write the object to

object - Object to write to the Writer

Returns:

true on success, false otherwise

Throws:

java.io.IOException - If there's a problem writing

writeToFile

public static void writeToFile(java.lang.String fileName,
                               java.io.Serializable object)
                        throws java.io.IOException

Writes the given object to the given file using XStream serialization.

Parameters:

fileName - The file to write to.

object - The object to write.

Throws:

java.io.IOException - If there is an error in writing.

writeToFile

public static void writeToFile(java.io.File file,
                               java.io.Serializable object)
                        throws java.io.IOException

Writes the given object to the given file using XStream serialization.

Parameters:

file - The file to write to.

object - The object to write.

Throws:

java.io.IOException - If there is an error in writing.

readFromFile

public static java.lang.Object readFromFile(java.lang.String fileName)
                                     throws java.io.IOException

Reads an Object from the given file name.

KNOWN LIMITATION: This method will thrown an exception "java.io.IOException: com.thoughtworks.xstream.io.StreamException: : input contained no data" when trying to read the SECOND object from an XML InputStream/Reader. This is because XML files must have a single root node (which would be the FIRST object in the file), and anything after the close of the root node (the SECOND object) is considered invalid or inexistent. To address the limitation, refer to http://xstream.codehaus.org/objectstream.html

Parameters:

fileName - The name of the file to read from.

Returns:

Deserialized object (null on exception)

Throws:

java.io.IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

readFromFile

public static java.lang.Object readFromFile(java.io.File file)
                                     throws java.io.IOException

Reads an Object from the given file name.

KNOWN LIMITATION: This method will thrown an exception "java.io.IOException: com.thoughtworks.xstream.io.StreamException: : input contained no data" when trying to read the SECOND object from an XML InputStream/Reader. This is because XML files must have a single root node (which would be the FIRST object in the file), and anything after the close of the root node (the SECOND object) is considered invalid or inexistent. To address the limitation, refer to http://xstream.codehaus.org/objectstream.html

Parameters:

file - The file to read from.

Returns:

Deserialized object (null on exception)

Throws:

java.io.IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

read

public static java.lang.Object read(java.io.InputStream stream)
                             throws java.io.IOException

Reads an Object from the given InputStream.

KNOWN LIMITATION: This method will thrown an exception "java.io.IOException: com.thoughtworks.xstream.io.StreamException: : input contained no data" when trying to read the SECOND object from an XML InputStream/Reader. This is because XML files must have a single root node (which would be the FIRST object in the file), and anything after the close of the root node (the SECOND object) is considered invalid or inexistent. To address the limitation, refer to http://xstream.codehaus.org/objectstream.html

Parameters:

stream - InputStream from which to read

Returns:

Deserialized object (null on exception)

Throws:

java.io.IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

read

public static java.lang.Object read(java.io.Reader reader)
                             throws java.io.IOException

Reads an Object from the given Reader. KNOWN LIMITATION: This method will thrown an exception "java.io.IOException: com.thoughtworks.xstream.io.StreamException: : input contained no data" when trying to read the SECOND object from an XML InputStream/Reader. This is because XML files must have a single root node (which would be the FIRST object in the file), and anything after the close of the root node (the SECOND object) is considered invalid or inexistent. To address the limitation, refer to http://xstream.codehaus.org/objectstream.html

Parameters:

reader - Reader from which to read

Returns:

Deserialized object (null on exception)

Throws:

java.io.IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

convertToString

public static java.lang.String convertToString(java.io.Serializable object)
                                        throws java.io.IOException

Writes the given object to a String.

Parameters:

object - Object to write to the String.

Returns:

The string containing the XML version of the object.

Throws:

java.io.IOException - If there's a problem writing.

convertFromString

public static java.lang.Object convertFromString(java.lang.String string)
                                          throws java.io.IOException

Attempts to read an Object from the given string.

Parameters:

string - The String containing the XStream version of the object.

Returns:

The Object read from the given string.

Throws:

java.io.IOException - If there is a problem reading.