vmm.core
Class SaveAndRestore

java.lang.Object
  vmm.core.SaveAndRestore

public class SaveAndRestore
extends java.lang.Object

Provides static methods for saving Exhibits and their associated Views to an XML file and for restoring an Exhbit and Views from such a file. (Methods in this class can also be used for encoding/decoding exhibits to XML Docment objects without ever writing them to a file.) There are also a few stating utility routines that can help programmers write Exhbit, View, and Decoration classes in a way that will work with this Save/Restore facility.

When Views and Exhibits are stored in XML format by this class their parameters are saved automatically. Decorations whose classes are marked with a VMMSave are saved automatically. Property variables in Views, Exhibits, and Decorations that are marked with a VMMSave annotation are saved automatically. Saving other data of a View, Exhibit, or Decoration class is the responsibility of that class. Parameters, properties, and decorations are restored automatically when the file is read. The Exhibit, View, and Decoration classes include an addExtraXML method that can be overridden to write any necessary extra data that is not saved automatically and a readExtraXML method for restoring the data when the file is read.

Note that for property variables, only properties of certain types are supported by these methods. For data other than supported properties, the programmer should write an XML representation of the data in writeExtraXML and should read this data in the readExtraXML method in the same class.

This class is meant to work with well-formed XML, but does not require valid XML (that is, there is no DTD or XML schema to specify the syntax).

Constructor Summary

SaveAndRestore()

Method Summary

static void	addDecorationElement(org.w3c.dom.Document doc, org.w3c.dom.Element parentElement, Decoration dec) Adds an XML element representing a Decoration to a specified parent element.
static void	addElement(org.w3c.dom.Document containingDocument, org.w3c.dom.Element parentElement, java.lang.String name, java.lang.Object value) Adds a child element to a given parent containing a "value" attribute with a specified value.
static void	addProperties(java.lang.Object propertyOwner, java.lang.String[] propertyNames, org.w3c.dom.Document document, org.w3c.dom.Element element) This is a convenience method that just calls addProperty(Object, String, Document, Element) for each name in the propertyNames array.
static void	addProperty(java.lang.Object propertyOwner, java.lang.String propertyName, org.w3c.dom.Document document, org.w3c.dom.Element element) Adds an XML Element represent a property of an object to an XML element that represents that object.
static Transform	buildTransformFromElement(org.w3c.dom.Element transformElement) Create a Transform object form a <transform> element that describes the transform.
static Exhibit	convertXMLToExhibit(org.w3c.dom.Document exhibitDocument) Constructs an Exhibit from its XML representation.
static org.w3c.dom.Document	exhibitToXML(Exhibit exhibit) Constructs an XML representaion of an Exhibit and any views of that exhibit, as returned by the Exhibit.getViews() method.
static org.w3c.dom.Document	exhibitToXML(Exhibit exhibit, View view) Constructs an XML representaion of an Exhibit and a single view of that Exhibit.
static org.w3c.dom.Document	exhibitToXML(Exhibit exhibit, View[] views) Constructs an XML representaion of an Exhibit and possibly some Views of that Exhibit.
static org.w3c.dom.Element	getChildElement(org.w3c.dom.Element parent, java.lang.String tagName) Returns a child element of an element, based on the name of the child element.
static java.lang.Object	getChildElementValue(org.w3c.dom.Element parentElement, java.lang.String name, java.lang.Class valueType) Retrieves a value from a child element that was created with addElement(Document, Element, String, Object)
static org.w3c.dom.Element	makeTransformElement(java.lang.String nodeName, org.w3c.dom.Document doc, Transform transform) Creates a transform element from a transform.
static Exhibit	readExhibitFromXML(java.io.File in) Read an XML file containing a representation of an Exhibit and possibly some associated Views.
static Exhibit	readExhibitFromXML(java.io.InputStream in, java.lang.String inputName) Read the XML representation of an exhibit and possibly some associated views from an InputStream.
static void	readProperties(java.lang.Object owner, org.w3c.dom.Element containingElement) Reads all the <propety> elements inside a given element and restores the values of those properties into a specified object.
static org.w3c.dom.Document	readXMLDocument(java.io.File file) Reads an XML file and produces a DOM Document tree from it.
static org.w3c.dom.Document	readXMLDocument(java.io.InputStream in, java.lang.String inputName) Reads XML from an input source and produces a DOM Document tree from it.
static void	writeXMLDocument(java.io.PrintWriter out, org.w3c.dom.Document doc) Writes a simple XML document to an output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

SaveAndRestore

public SaveAndRestore()

Method Detail

readExhibitFromXML

public static Exhibit readExhibitFromXML(java.io.File in)
                                  throws java.io.IOException

Read an XML file containing a representation of an Exhibit and possibly some associated Views. If any Views are found, the Exhibit is installed into each View, and the list of Views can be obtained by calling the Exhibit.getViews() method if the exhibit.

Parameters:

in - the XML file from which the data is to be read

Returns:

An exhibit read from the file. Any views that were read from the file can be retrieved by calling exhibit.getViews().

Throws:

java.io.IOException - throws IOException an error occurs while reading the file. This can include errors in XML syntax.

convertXMLToExhibit

public static Exhibit convertXMLToExhibit(org.w3c.dom.Document exhibitDocument)

Constructs an Exhibit from its XML representation. The representation is in the form of the Documents produced by the exhibitToXML(Exhibit) method and similar mehtods in this class. If the Document contains any Views, then the Exhibit is installed in each View. The list of views can be obtained by calling the exhibit's Exhibit.getViews() method.

Throws:

java.lang.IllegalArgumentException - if the Document is not a legal XML representation of an Exhibit

readExhibitFromXML

public static Exhibit readExhibitFromXML(java.io.InputStream in,
                                         java.lang.String inputName)
                                  throws java.io.IOException

Read the XML representation of an exhibit and possibly some associated views from an InputStream. If any Views are found, the Exhibit is installed into each View, and the list of Views can be obtained by calling the Exhibit.getViews() method if the exhibit.

Parameters:

in - the input stream from which the XML data is to be read

inputName - the file (or other) name of the input stream, which is used only in error messages

Returns:

An exhibit read from the file. Any views that were read from the file can be retrieved by calling exhibit.getViews().

Throws:

java.io.IOException - throws IOException an error occurs while reading the file. This can include errors in XML syntax.

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(java.io.File file)
                                            throws java.io.IOException

Reads an XML file and produces a DOM Document tree from it. This is meant for reading the XML form of an exhibit, but in fact it can read any XML document.

Throws:

java.io.IOException

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(java.io.InputStream in,
                                                   java.lang.String inputName)
                                            throws java.io.IOException

Reads XML from an input source and produces a DOM Document tree from it. This is meant for reading the XML form of an exhibit, but in fact it can read any XML document.

Throws:

java.io.IOException

exhibitToXML

public static org.w3c.dom.Document exhibitToXML(Exhibit exhibit,
                                                View view)

Constructs an XML representaion of an Exhibit and a single view of that Exhibit. This is a convenience method that just calls exhibitToXML(Exhibit, View[]).

exhibitToXML

public static org.w3c.dom.Document exhibitToXML(Exhibit exhibit)

Constructs an XML representaion of an Exhibit and any views of that exhibit, as returned by the Exhibit.getViews() method. This is a convenience method that just calls exhibitToXML(Exhibit, View[]).

exhibitToXML

public static org.w3c.dom.Document exhibitToXML(Exhibit exhibit,
                                                View[] views)

Constructs an XML representaion of an Exhibit and possibly some Views of that Exhibit. The XML document that is constructed is supposed to represent the complete state of the Exhbit and Views, allowing them to be reconstructed by the readExhibitFromXML(File) or convertXMLToExhibit(Document) method in this class.

Parameters:

exhibit - The exhibit whose state is to be encoded.

views - View of the exhibit that should be encoded into the XML document. If this is null, no views are encoded. Any view in this array must be capable of displaying the exhibit.

writeXMLDocument

public static void writeXMLDocument(java.io.PrintWriter out,
                                    org.w3c.dom.Document doc)

Writes a simple XML document to an output stream. This method is meant for use with the type of XML document manipulated with this class, with no namespaces, DTD, etc.

Parameters:

out - The non-null output stream to which the document is to be written.

doc - The non-null XML documnent that is to be written.

addProperties

public static void addProperties(java.lang.Object propertyOwner,
                                 java.lang.String[] propertyNames,
                                 org.w3c.dom.Document document,
                                 org.w3c.dom.Element element)

This is a convenience method that just calls addProperty(Object, String, Document, Element) for each name in the propertyNames array.

addProperty

public static void addProperty(java.lang.Object propertyOwner,
                               java.lang.String propertyName,
                               org.w3c.dom.Document document,
                               org.w3c.dom.Element element)

Adds an XML Element represent a property of an object to an XML element that represents that object. Note that this method does not have to be used with properties that are marked with the VMMSave annotation, since such properites are saved automatically.

The term "property" here refers to a JavaBean-style property with a "getXxxx()" and a "setXxxx(value)" method, where xxxx is the name of the property. This method can be called, for example, by an Exhibit, Decoration, or View to add properties to its XML representation. (This would be done in Exhibit.addExtraXML(Document, Element) and similar methods in decoration and view classes.) This method can only handle properties of certain types: any of the primitive types, String, Color, Point2D, Vector3D, double[], and any class that has a one-parameter constructor with arguemnt of type String that can reconstruct an object from the string returned by the toString() method of the object. (The conversion of value to string is actually done by Util.toExternalString(Object).)

Parameters:

propertyOwner - The non-null object whose property is to be encoded.

propertyName - The name of the property that is to be encoded.

document - The XML Document that contains the Element that is being created. This is provided as a parameter because it is needed to create any child elements that are to be added to the element.

element - The element that is being constructed to represent the propertyOwner.

Throws:

java.lang.IllegalArgumentException - if no such property is found in the propertyOwner object, or if any other Exception occurs.

See Also:

readProperties(Object, Element)

readProperties

public static void readProperties(java.lang.Object owner,
                                  org.w3c.dom.Element containingElement)
                           throws java.io.IOException

Reads all the <propety> elements inside a given element and restores the values of those properties into a specified object. The properties that are handled by this method are presumably properites that were added to the XML using the addProperty(Object, String, Document, Element) or addProperties(Object, String[], Document, Element) method. (In any case, the format of the property elements must be the same as those produced by these methods.)

Parameters:

owner - The object whose properties are being restored.

containingElement - The element that contains the <property> elements. The childer of this element are examined. Fore each child element whose tag name is "propety", an attempt is made to call setter method in the owner object to set the value of the property. If no setter method for the property exists, it is not considered to be an error. (This allows new properties to be added in future releases while still allowing old releases to read the settings files that contain the newly added properties.)

Throws:

java.io.IOException - if a <property> element does not have a name and a value attribute or if the value attribute cannot be converted to a value of the type required by the setter method for the property.

addDecorationElement

public static void addDecorationElement(org.w3c.dom.Document doc,
                                        org.w3c.dom.Element parentElement,
                                        Decoration dec)

Adds an XML element representing a Decoration to a specified parent element. Note that is is not necessary to use this method for Decorations whose classes are marked with the VMMSave annotation, since such decorations are saved automatically, along with the View or Exhibit to which they have been added.

When the parent element represents a View or Exhibit, the decoration will automatically be recreated and added to the recreated view or exhibit when the XML file is read. There is no need for the Exhibit or View class itself to take any action restore the decoration. This method would ordinarily be used in the addExtraXML method of an Exhibit or View class. Note however, that another possibility is to save other information (such as a boolean property) that indicates the presense of the decoration.

Parameters:

doc - The non-null overall XML document that is being constructed.

parentElement - The non-null element to which the decoration element is to be added as a child.

dec - The non-null decoration that is to be encoded into XML and added to the parent element in the XML document.

addElement

public static void addElement(org.w3c.dom.Document containingDocument,
                              org.w3c.dom.Element parentElement,
                              java.lang.String name,
                              java.lang.Object value)

Adds a child element to a given parent containing a "value" attribute with a specified value. The value is meant to be retrieved using getChildElementValue(Element, String, Class).

Parameters:

containingDocument - The document containing the parent element.

parentElement - The element to which the child is to be added.

name - The name of the child element.

value - The value of the "value" element. Major types such as Double, Float, Integer, String, Color, Vector3D, double[] are supported. The conversion of value-to-string is done using Util.toExternalString(Object).

getChildElementValue

public static java.lang.Object getChildElementValue(org.w3c.dom.Element parentElement,
                                                    java.lang.String name,
                                                    java.lang.Class valueType)

Retrieves a value from a child element that was created with addElement(Document, Element, String, Object)

Parameters:

parentElement - The element to which the child element was added.

name - The name of the child element.

valueType - The type of value expected.

Returns:

The value from the element, conveted from the "value" attribute string, or null if the value is not successfully retrieved.

makeTransformElement

public static org.w3c.dom.Element makeTransformElement(java.lang.String nodeName,
                                                       org.w3c.dom.Document doc,
                                                       Transform transform)

Creates a transform element from a transform.

Parameters:

nodeName - the name of the element that will be created

doc - the Document that will contain the transform element.

transform - the non-null transform

Returns:

A <transform> element that describes the transform.

buildTransformFromElement

public static Transform buildTransformFromElement(org.w3c.dom.Element transformElement)
                                           throws java.io.IOException

Create a Transform object form a <transform> element that describes the transform.

Throws:

java.io.IOException

getChildElement

public static org.w3c.dom.Element getChildElement(org.w3c.dom.Element parent,
                                                  java.lang.String tagName)

Returns a child element of an element, based on the name of the child element.

Parameters:

parent - the element that might contain the child element

tagName - the name of the desired child element

Returns:

the child element, or null if no child element with the given name exists. (If more than one exists, the first is returned.)