org.sakaiproject.component.gradebook
Class VersionedExternalizable

java.lang.Object
  extended by org.sakaiproject.component.gradebook.VersionedExternalizable
All Implemented Interfaces:
Externalizable, Serializable
Direct Known Subclasses:
GradebookDefinition

public abstract class VersionedExternalizable
extends Object
implements Externalizable

Generic helper class for serializing Java objects to and from simply-formatted XML for archival and reconstitution across data definition versions.

XStream is used to handle the marshalling and unmarshalling work. The main addition is an "externalizableVersion" attribute on the POJO's top-level element. That attribute can then be checked for incompatibilities before reconstitution, and used to convert old data into its new form. (Currently, if there's a version mismatch and nothing is done about it, this class throws a ConversionException.)

Translation to and from XML can be handled either with the static "toXML" and "fromXML" methods, or through the Externalizable interface. The chief benefit of the static methods is that they (theoretically) give subclasses the ability to translate across versions using XSLT, and possibly even return an object of a different class than the original.

TODO For the functionality being checked in (site-to-site migration), this class is not strictly necessary. It's here on a speculative basis for upcoming import/archive/merge development.

See Also:
Serialized Form

Nested Class Summary
static class VersionedExternalizable.Converter
          This XStream converter stores the externalizable version of the class as a Document-level attribute for easy access by translators.
 
Field Summary
static String VERSION_ATTRIBUTE
           
 
Constructor Summary
VersionedExternalizable()
           
 
Method Summary
static Object fromXml(String xmlString)
           
abstract  String getExternalizableVersion()
           
protected static com.thoughtworks.xstream.XStream getXStream()
           
 void readExternal(ObjectInput inputStream)
           
static String toXml(Object obj)
           
 void writeExternal(ObjectOutput outputStream)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION_ATTRIBUTE

public static String VERSION_ATTRIBUTE
Constructor Detail

VersionedExternalizable

public VersionedExternalizable()
Method Detail

getExternalizableVersion

public abstract String getExternalizableVersion()
Returns:
non-null archivable version identifier for the object definition

getXStream

protected static com.thoughtworks.xstream.XStream getXStream()

readExternal

public void readExternal(ObjectInput inputStream)
                  throws IOException,
                         ClassNotFoundException
Specified by:
readExternal in interface Externalizable
Throws:
IOException
ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput outputStream)
                   throws IOException
Specified by:
writeExternal in interface Externalizable
Throws:
IOException

toXml

public static String toXml(Object obj)
Parameters:
obj - the Java object (usually a subclass of VersionedExternalizable) to describe as XML
Returns:
XML describing the object

fromXml

public static Object fromXml(String xmlString)
Parameters:
xmlString - XML string (presumably created by this class) describing a Java object
Returns:
the Java object it describes


Copyright © 2011 Sakai Project. All Rights Reserved.