gov.sandia.cognition.io
Class XStreamSerializationHandler

java.lang.Object
  extended by gov.sandia.cognition.io.XStreamSerializationHandler

@CodeReviews(reviews={@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 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
XStreamSerializationHandler()
           
 
Method Summary
static Object convertFromString(String string)
          Attempts to read an Object from the given string.
static String convertToString(Serializable object)
          Writes the given object to a String.
static Object read(InputStream stream)
          Reads an Object from the given InputStream.
static Object read(Reader reader)
          Reads an Object from the given Reader.
static Object readFromFile(File file)
          Reads an Object from the given file name.
static Object readFromFile(String fileName)
          Reads an Object from the given file name.
static boolean write(OutputStream stream, Serializable object)
          Writes the given object to the given OutputStream
static boolean write(Writer writer, Serializable object)
          Writes the given object to the given Writer
static void writeToFile(File file, Serializable object)
          Writes the given object to the given file using XStream serialization.
static void writeToFile(String fileName, 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(OutputStream stream,
                            Serializable object)
                     throws 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:
IOException - If there's a problem writing

write

public static boolean write(Writer writer,
                            Serializable object)
                     throws 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:
IOException - If there's a problem writing

writeToFile

public static void writeToFile(String fileName,
                               Serializable object)
                        throws 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:
IOException - If there is an error in writing.

writeToFile

public static void writeToFile(File file,
                               Serializable object)
                        throws 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:
IOException - If there is an error in writing.

readFromFile

public static Object readFromFile(String fileName)
                           throws 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:
IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

readFromFile

public static Object readFromFile(File file)
                           throws 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:
IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

read

public static Object read(InputStream stream)
                   throws 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:
IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

read

public static Object read(Reader reader)
                   throws 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:
IOException - if an Object can't be deserialized from the reader (See LIMITATION above)

convertToString

public static String convertToString(Serializable object)
                              throws 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:
IOException - If there's a problem writing.

convertFromString

public static Object convertFromString(String string)
                                throws 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:
IOException - If there is a problem reading.