gov.nasa.worldwind.util

Class RestorableSupport

java.lang.Object

gov.nasa.worldwind.util.RestorableSupport

public class RestorableSupport
extends java.lang.Object

RestorableSupport provides convenient read and write access to restorable state located in a simple XML document format. This document is rooted by the restorableState element. State is stored in stateObject elements. Each stateObject element is identified by its name attribute. The value of a stateObject can either be simple text content, or nested stateObject elements.

For example, this document stores four states: the string "Hello World!", the largest value an unsigned byte can hold, the value of PI to six digits, and a boolean "true".

  <?xml version="1.0" encoding="UTF-8"?>
  <restorableState>
    <stateObject name="helloWorldString">Hello World!</stateObject>
    <stateObject name="maxUnsignedByteValue">255</stateObject>
    <stateObject name="pi">3.141592</stateObject>
    <stateObject name="booleanTrue">true</stateObject>
  </restorableState>
 

Callers can create a new RestorableSupport with no state content, or create a RestorableSupport from an existing XML document string. Callers can then add state by name and value, and query state by name. RestorableSupport provides convenience methods for addding and querying state values as Strings, Integers, Doubles, and Booleans.

See Also:

Restorable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RestorableSupport.StateObject An interface to the stateObject elements in an XML state document, as defined by RestorableSupport.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	DEFAULT_DOCUMENT_ELEMENT_TAG_NAME
protected static java.lang.String	DEFAULT_STATE_OBJECT_TAG_NAME
protected org.w3c.dom.Document	doc
protected java.lang.String	stateObjectTagName
protected javax.xml.xpath.XPath	xpath

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RestorableSupport(org.w3c.dom.Document doc) Creates a new RestorableSupport with no contents and using a specified Document.

Method Summary

Modifier and Type	Method and Description
RestorableSupport.StateObject	addStateObject(RestorableSupport.StateObject context, java.lang.String name) Adds a new StateObject with the specified name.
RestorableSupport.StateObject	addStateObject(java.lang.String name) Adds a new StateObject with the specified name.
void	addStateValueAsBoolean(RestorableSupport.StateObject context, java.lang.String name, boolean booleanValue) Adds a new StateObject with the specified name and Boolean value.
void	addStateValueAsBoolean(java.lang.String name, boolean booleanValue) Adds a new StateObject with the specified name and Boolean value.
void	addStateValueAsColor(RestorableSupport.StateObject context, java.lang.String name, java.awt.Color color)
void	addStateValueAsColor(java.lang.String name, java.awt.Color color)
void	addStateValueAsDouble(RestorableSupport.StateObject context, java.lang.String name, double doubleValue) Adds a new StateObject with the specified name and Double value.
void	addStateValueAsDouble(java.lang.String name, double doubleValue) Adds a new StateObject with the specified name and Double value.
void	addStateValueAsImageSourceList(RestorableSupport.StateObject context, java.lang.String name, java.util.Map<java.lang.Integer,java.lang.Object> imageSources, int faceCount)
void	addStateValueAsImageSourceList(java.lang.String name, java.util.Map<java.lang.Integer,java.lang.Object> imageSources, int faceCount)
void	addStateValueAsInteger(RestorableSupport.StateObject context, java.lang.String name, int intValue) Adds a new StateObject with the specified name and Integer value.
void	addStateValueAsInteger(java.lang.String name, int intValue) Adds a new StateObject with the specified name and Integer value.
void	addStateValueAsLatLon(RestorableSupport.StateObject context, java.lang.String name, LatLon location)
void	addStateValueAsLatLon(java.lang.String name, LatLon location)
void	addStateValueAsLatLonList(RestorableSupport.StateObject context, java.lang.String name, java.lang.Iterable<? extends LatLon> locations)
void	addStateValueAsOffsetPair(RestorableSupport.StateObject context, java.lang.String name, float[] offsetPair)
void	addStateValueAsOffsets(RestorableSupport.StateObject context, java.lang.String name, OffsetsList offsets)
void	addStateValueAsOffsets(java.lang.String name, OffsetsList offsets)
void	addStateValueAsOffsetsList(RestorableSupport.StateObject context, java.lang.String name, java.util.Map<java.lang.Integer,OffsetsList> offsets)
void	addStateValueAsPosition(RestorableSupport.StateObject context, java.lang.String name, Position position)
void	addStateValueAsPosition(java.lang.String name, Position position)
void	addStateValueAsSector(RestorableSupport.StateObject context, java.lang.String name, Sector sector)
void	addStateValueAsSector(java.lang.String name, Sector sector)
void	addStateValueAsString(RestorableSupport.StateObject context, java.lang.String name, java.lang.String value) Adds a new StateObject with the specified name and String value.
void	addStateValueAsString(RestorableSupport.StateObject context, java.lang.String name, java.lang.String value, boolean escapeValue) Adds a new StateObject with the specified name and String value.
void	addStateValueAsString(java.lang.String name, java.lang.String value) Adds a new StateObject with the specified name and String value.
void	addStateValueAsString(java.lang.String name, java.lang.String value, boolean escapeValue) Adds a new StateObject with the specified name and String value.
static void	adjustTitleAndDisplayName(AVList params)
protected boolean	containsElement(org.w3c.dom.Element elem)
protected static void	createDocumentElement(org.w3c.dom.Document doc, java.lang.String tagName)
protected RestorableSupport.StateObject	createStateObject(org.w3c.dom.Element context, java.lang.String name, java.lang.String value)
protected RestorableSupport.StateObject	createStateObject(org.w3c.dom.Element context, java.lang.String name, java.lang.String value, boolean escapeValue)
static java.awt.Color	decodeColor(java.lang.String encodedString) Returns the Color described by the String encodedString.
static java.lang.String	encodeColor(java.awt.Color color) Returns a String encoding of the specified color.
protected RestorableSupport.StateObject[]	extractStateObjects(org.w3c.dom.Element context)
protected RestorableSupport.StateObject[]	findAllStateObjects(org.w3c.dom.Node context, java.lang.String name)
protected RestorableSupport.StateObject	findStateObject(org.w3c.dom.Node context, java.lang.String name)
RestorableSupport.StateObject[]	getAllStateObjects(RestorableSupport.StateObject context) Returns all StateObjects directly beneath the a context StateObject.
RestorableSupport.StateObject[]	getAllStateObjects(RestorableSupport.StateObject context, java.lang.String name) Returns all StateObjects with the specified name.
RestorableSupport.StateObject[]	getAllStateObjects(java.lang.String name) Returns any StateObjects directly beneath the document root that have the specified name.
protected org.w3c.dom.Element	getDocumentElement()
java.lang.String	getDocumentElementTagName() Returns the String that represents the document element name.
java.lang.String	getStateAsXml() Returns an XML document string describing this RestorableSupport's current set of state objects.
RestorableSupport.StateObject	getStateObject(RestorableSupport.StateObject context, java.lang.String name) Returns the StateObject with the specified name.
RestorableSupport.StateObject	getStateObject(java.lang.String name) Returns the StateObject with the specified name.
java.lang.Boolean	getStateObjectAsBoolean(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Boolean.
java.awt.Color	getStateObjectAsColor(RestorableSupport.StateObject stateObject)
java.lang.Double	getStateObjectAsDouble(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Double.
java.lang.Float	getStateObjectAsFloat(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Float.
java.util.HashMap<java.lang.Integer,java.lang.Object>	getStateObjectAsImageSourceList(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a HashMap of pairs, representing the shape's imageSources.
java.lang.Integer	getStateObjectAsInteger(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as an Integer.
LatLon	getStateObjectAsLatLon(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a LatLon.
java.util.List<LatLon>	getStateObjectAsLatLonList(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a List of LatLons.
java.lang.Long	getStateObjectAsLong(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Long.
float[]	getStateObjectAsOffsetPair(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a float[].
OffsetsList	getStateObjectAsOffsets(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a OffsetsList.
java.util.HashMap<java.lang.Integer,OffsetsList>	getStateObjectAsOffsetsList(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a HashMap of pairs.
Position	getStateObjectAsPosition(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Position.
Sector	getStateObjectAsSector(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a Sector.
java.lang.String	getStateObjectAsString(RestorableSupport.StateObject stateObject) Returns the value of the StateObject as a String.
java.lang.String	getStateObjectTagName() Returns the String to be used for each state object's tag name.
java.lang.Boolean	getStateValueAsBoolean(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as a Boolean.
java.lang.Boolean	getStateValueAsBoolean(java.lang.String name) Returns the value of the StateObject with the specified name as a Boolean.
java.awt.Color	getStateValueAsColor(RestorableSupport.StateObject context, java.lang.String name)
java.lang.Double	getStateValueAsDouble(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as a Double.
java.lang.Double	getStateValueAsDouble(java.lang.String name) Returns the value of the StateObject with the specified name as a Double.
java.lang.Float	getStateValueAsFloat(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as a Float.
java.lang.Float	getStateValueAsFloat(java.lang.String name) Returns the value of the StateObject with the specified name as a Float.
java.util.HashMap<java.lang.Integer,java.lang.Object>	getStateValueAsImageSourceList(RestorableSupport.StateObject context, java.lang.String name)
java.util.HashMap<java.lang.Integer,java.lang.Object>	getStateValueAsImageSourceList(java.lang.String name)
java.lang.Integer	getStateValueAsInteger(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as an Integer.
java.lang.Integer	getStateValueAsInteger(java.lang.String name) Returns the value of the StateObject with the specified name as an Integer.
LatLon	getStateValueAsLatLon(RestorableSupport.StateObject context, java.lang.String name)
LatLon	getStateValueAsLatLon(java.lang.String name)
java.util.List<LatLon>	getStateValueAsLatLonList(RestorableSupport.StateObject context, java.lang.String name)
java.util.List<LatLon>	getStateValueAsLatLonList(java.lang.String name)
java.lang.Long	getStateValueAsLong(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as a Long.
java.lang.Long	getStateValueAsLong(java.lang.String name) Returns the value of the StateObject with the specified name as a Long.
float[]	getStateValueAsOffsetPair(RestorableSupport.StateObject context, java.lang.String name)
float[]	getStateValueAsOffsetPair(java.lang.String name)
OffsetsList	getStateValueAsOffsets(RestorableSupport.StateObject context, java.lang.String name)
OffsetsList	getStateValueAsOffsets(java.lang.String name)
java.util.HashMap<java.lang.Integer,OffsetsList>	getStateValueAsOffsetsList(RestorableSupport.StateObject context, java.lang.String name)
java.util.HashMap<java.lang.Integer,OffsetsList>	getStateValueAsOffsetsList(java.lang.String name)
Position	getStateValueAsPosition(RestorableSupport.StateObject context, java.lang.String name)
Position	getStateValueAsPosition(java.lang.String name)
Sector	getStateValueAsSector(RestorableSupport.StateObject context, java.lang.String name)
Sector	getStateValueAsSector(java.lang.String name)
java.lang.String	getStateValueAsString(RestorableSupport.StateObject context, java.lang.String name) Returns the value of the StateObject with the specified name as a String.
java.lang.String	getStateValueAsString(java.lang.String name) Returns the value of the StateObject with the specified name as a String.
static RestorableSupport	newRestorableSupport() Creates a new RestorableSupport with no contents.
static RestorableSupport	newRestorableSupport(java.lang.String documentElementName) Creates a new RestorableSupport with no contents.
static RestorableSupport	parse(java.lang.String stateInXml) Creates a new RestorableSupport with the contents of the specified state document.
void	setStateObjectTagName(java.lang.String stateObjectTagName) Sets the String to be used for each state object's tag name.
java.lang.String	toString() Returns an XML document string describing this RestorableSupport's current set of state objects.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_DOCUMENT_ELEMENT_TAG_NAME

protected static final java.lang.String DEFAULT_DOCUMENT_ELEMENT_TAG_NAME

See Also:

Constant Field Values

DEFAULT_STATE_OBJECT_TAG_NAME

protected static final java.lang.String DEFAULT_STATE_OBJECT_TAG_NAME

See Also:

Constant Field Values

doc

protected org.w3c.dom.Document doc

stateObjectTagName

protected java.lang.String stateObjectTagName

xpath

protected javax.xml.xpath.XPath xpath

Constructor Detail

RestorableSupport

protected RestorableSupport(org.w3c.dom.Document doc)

Creates a new RestorableSupport with no contents and using a specified Document.

Parameters:

doc - the document to hold the restorable state.

Throws:

java.lang.IllegalArgumentException - if the document reference is null.

Method Detail

addStateObject

public RestorableSupport.StateObject addStateObject(RestorableSupport.StateObject context,
                                                    java.lang.String name)

Adds a new StateObject with the specified name. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

context - the StateObject under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

Returns:

the new StateObject instance.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateObject

public RestorableSupport.StateObject addStateObject(java.lang.String name)

Adds a new StateObject with the specified name. The new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

name - the new StateObject's name.

Returns:

the new StateObject instance.

Throws:

java.lang.IllegalArgumentException - If name is null.

addStateValueAsBoolean

public void addStateValueAsBoolean(RestorableSupport.StateObject context,
                                   java.lang.String name,
                                   boolean booleanValue)

Adds a new StateObject with the specified name and Boolean value. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

context - the StateObject context under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

booleanValue - the new StateObject's Boolean value.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsBoolean

public void addStateValueAsBoolean(java.lang.String name,
                                   boolean booleanValue)

Adds a new StateObject with the specified name and Boolean value. The new StateObject is placed beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

name - the new StateObject's name.

booleanValue - the new StateObject's Boolean value.

Throws:

java.lang.IllegalArgumentException - If name is null.

addStateValueAsColor

public void addStateValueAsColor(RestorableSupport.StateObject context,
                                 java.lang.String name,
                                 java.awt.Color color)

addStateValueAsColor

public void addStateValueAsColor(java.lang.String name,
                                 java.awt.Color color)

addStateValueAsDouble

public void addStateValueAsDouble(RestorableSupport.StateObject context,
                                  java.lang.String name,
                                  double doubleValue)

Adds a new StateObject with the specified name and Double value. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

context - the StateObject context under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

doubleValue - the new StateObject's Double value.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsDouble

public void addStateValueAsDouble(java.lang.String name,
                                  double doubleValue)

Adds a new StateObject with the specified name and Double value. The new StateObject is placed beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

name - the new StateObject's name.

doubleValue - the new StateObject's Double value.

Throws:

java.lang.IllegalArgumentException - If name is null.

addStateValueAsImageSourceList

public void addStateValueAsImageSourceList(RestorableSupport.StateObject context,
                                           java.lang.String name,
                                           java.util.Map<java.lang.Integer,java.lang.Object> imageSources,
                                           int faceCount)

addStateValueAsImageSourceList

public void addStateValueAsImageSourceList(java.lang.String name,
                                           java.util.Map<java.lang.Integer,java.lang.Object> imageSources,
                                           int faceCount)

addStateValueAsInteger

public void addStateValueAsInteger(RestorableSupport.StateObject context,
                                   java.lang.String name,
                                   int intValue)

Adds a new StateObject with the specified name and Integer value. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

context - the StateObject context under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

intValue - the new StateObject's Integer value.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsInteger

public void addStateValueAsInteger(java.lang.String name,
                                   int intValue)

Adds a new StateObject with the specified name and Integer value. The new StateObject is placed beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

name - the new StateObject's name.

intValue - the new StateObject's Integer value.

Throws:

java.lang.IllegalArgumentException - If name is null.

addStateValueAsLatLon

public void addStateValueAsLatLon(RestorableSupport.StateObject context,
                                  java.lang.String name,
                                  LatLon location)

addStateValueAsLatLon

public void addStateValueAsLatLon(java.lang.String name,
                                  LatLon location)

addStateValueAsLatLonList

public void addStateValueAsLatLonList(RestorableSupport.StateObject context,
                                      java.lang.String name,
                                      java.lang.Iterable<? extends LatLon> locations)

addStateValueAsOffsetPair

public void addStateValueAsOffsetPair(RestorableSupport.StateObject context,
                                      java.lang.String name,
                                      float[] offsetPair)

addStateValueAsOffsets

public void addStateValueAsOffsets(RestorableSupport.StateObject context,
                                   java.lang.String name,
                                   OffsetsList offsets)

addStateValueAsOffsets

public void addStateValueAsOffsets(java.lang.String name,
                                   OffsetsList offsets)

addStateValueAsOffsetsList

public void addStateValueAsOffsetsList(RestorableSupport.StateObject context,
                                       java.lang.String name,
                                       java.util.Map<java.lang.Integer,OffsetsList> offsets)

addStateValueAsPosition

public void addStateValueAsPosition(RestorableSupport.StateObject context,
                                    java.lang.String name,
                                    Position position)

addStateValueAsPosition

public void addStateValueAsPosition(java.lang.String name,
                                    Position position)

addStateValueAsSector

public void addStateValueAsSector(RestorableSupport.StateObject context,
                                  java.lang.String name,
                                  Sector sector)

addStateValueAsSector

public void addStateValueAsSector(java.lang.String name,
                                  Sector sector)

addStateValueAsString

public void addStateValueAsString(RestorableSupport.StateObject context,
                                  java.lang.String name,
                                  java.lang.String value)

Adds a new StateObject with the specified name and String value. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

context - the StateObject context under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

value - the new StateObject's String value.

Throws:

java.lang.IllegalArgumentException - If either name or value is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsString

public void addStateValueAsString(RestorableSupport.StateObject context,
                                  java.lang.String name,
                                  java.lang.String value,
                                  boolean escapeValue)

Adds a new StateObject with the specified name and String value. If context is not null, the new StateObject is nested directly beneath the specified context. Otherwise, the new StateObject is placed directly beneath the document root. If a StateObject with this name already exists, a new one is still created. If escapeValue is true, the text in value is escaped in a CDATA section. Otherwise, no special processing is performed on value. Once value has been escaped and added, it can be extracted exactly like any other String value.

Parameters:

context - the StateObject context under which the new StateObject is created, or null to place it under the document root.

name - the new StateObject's name.

value - the new StateObject's String value.

escapeValue - whether to escape the String value or not.

Throws:

java.lang.IllegalArgumentException - If either name or value is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsString

public void addStateValueAsString(java.lang.String name,
                                  java.lang.String value)

Adds a new StateObject with the specified name and String value. The new StateObject is placed beneath the document root. If a StateObject with this name already exists, a new one is still created.

Parameters:

name - the new StateObject's name.

value - the new StateObject's String value.

Throws:

java.lang.IllegalArgumentException - If either name or value is null.

addStateValueAsString

public void addStateValueAsString(java.lang.String name,
                                  java.lang.String value,
                                  boolean escapeValue)

Adds a new StateObject with the specified name and String value. The new StateObject is placed beneath the document root. If a StateObject with this name already exists, a new one is still created. If escapeValue is true, the text in value is escaped in a CDATA section. Otherwise, no special processing is performed on value. Once value has been escaped and added, it can be extracted exactly like any other String value.

Parameters:

name - the new StateObject's name.

value - the new StateObject's String value.

escapeValue - whether to escape the String value or not.

Throws:

java.lang.IllegalArgumentException - If either name or value is null.

adjustTitleAndDisplayName

public static void adjustTitleAndDisplayName(AVList params)

containsElement

protected boolean containsElement(org.w3c.dom.Element elem)

createDocumentElement

protected static void createDocumentElement(org.w3c.dom.Document doc,
                                            java.lang.String tagName)

createStateObject

protected RestorableSupport.StateObject createStateObject(org.w3c.dom.Element context,
                                                          java.lang.String name,
                                                          java.lang.String value)

createStateObject

protected RestorableSupport.StateObject createStateObject(org.w3c.dom.Element context,
                                                          java.lang.String name,
                                                          java.lang.String value,
                                                          boolean escapeValue)

decodeColor

public static java.awt.Color decodeColor(java.lang.String encodedString)

Returns the Color described by the String encodedString. This understands Colors encoded with a call to encodeColor(java.awt.Color). If encodedString cannot be decoded, this method returns null.

Parameters:

encodedString - String to decode.

Returns:

Color decoded from the specified encodedString, or null if the String cannot be decoded.

Throws:

java.lang.IllegalArgumentException - If encodedString is null.

encodeColor

public static java.lang.String encodeColor(java.awt.Color color)

Returns a String encoding of the specified color. The Color can be restored with a call to decodeColor(String).

Parameters:

color - Color to encode.

Returns:

String encoding of the specified color.

Throws:

java.lang.IllegalArgumentException - If color is null.

extractStateObjects

protected RestorableSupport.StateObject[] extractStateObjects(org.w3c.dom.Element context)

findAllStateObjects

protected RestorableSupport.StateObject[] findAllStateObjects(org.w3c.dom.Node context,
                                                              java.lang.String name)

findStateObject

protected RestorableSupport.StateObject findStateObject(org.w3c.dom.Node context,
                                                        java.lang.String name)

getAllStateObjects

public RestorableSupport.StateObject[] getAllStateObjects(RestorableSupport.StateObject context)

Returns all StateObjects directly beneath the a context StateObject. If context is not null, this method returns all the StateObjects directly below the specified context. Otherwise, this method returns all the StateObjects directly beneath the document root.

Parameters:

context - StateObject context to search, or null to search the document root.

Returns:

an array of the StateObject instances, which has zero length if none exist.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getAllStateObjects

public RestorableSupport.StateObject[] getAllStateObjects(RestorableSupport.StateObject context,
                                                          java.lang.String name)

Returns all StateObjects with the specified name. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObjects with that name exist, this method returns a valid StateObject array with zero length.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

an array of the StateObject instances, which has zero length if none exist.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getAllStateObjects

public RestorableSupport.StateObject[] getAllStateObjects(java.lang.String name)

Returns any StateObjects directly beneath the document root that have the specified name. If no StateObjects with that name exist, this method returns a valid StateObject array with zero length.

Parameters:

name - the StateObject name to search for.

Returns:

an array of the StateObject instances, which has zero length if none exist.

Throws:

java.lang.IllegalArgumentException - If name is null.

getDocumentElement

protected org.w3c.dom.Element getDocumentElement()

getDocumentElementTagName

public java.lang.String getDocumentElementTagName()

Returns the String that represents the document element name.

Returns:

String for the document element name.

getStateAsXml

public java.lang.String getStateAsXml()

Returns an XML document string describing this RestorableSupport's current set of state objects. If this RestorableSupport cannot be converted, this method returns null.

Returns:

an XML state document string.

getStateObject

public RestorableSupport.StateObject getStateObject(RestorableSupport.StateObject context,
                                                    java.lang.String name)

Returns the StateObject with the specified name. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the StateObject instance, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateObject

public RestorableSupport.StateObject getStateObject(java.lang.String name)

Returns the StateObject with the specified name. This searches the StateObjects directly beneath the document root. If no StateObject with that name exists, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the StateObject instance, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateObjectAsBoolean

public java.lang.Boolean getStateObjectAsBoolean(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Boolean. The Boolean value returned is equivalent to passing the StateObject's String value to Boolean.valueOf.

Parameters:

stateObject - the StateObject that is converted to a Boolean.

Returns:

the value of the StateObject as a Boolean.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsColor

public java.awt.Color getStateObjectAsColor(RestorableSupport.StateObject stateObject)

getStateObjectAsDouble

public java.lang.Double getStateObjectAsDouble(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Double.

Parameters:

stateObject - the StateObject that is converted to a Double.

Returns:

the value of the StateObject as a Double.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsFloat

public java.lang.Float getStateObjectAsFloat(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Float.

Parameters:

stateObject - the StateObject that is converted to a Float.

Returns:

the value of the StateObject as a Float.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsImageSourceList

public java.util.HashMap<java.lang.Integer,java.lang.Object> getStateObjectAsImageSourceList(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a HashMap of pairs, representing the shape's imageSources.

Parameters:

stateObject - the StateObject that is converted to a HashMap of imageSources.

Returns:

the value of the StateObject as a HashMap of pairs.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsInteger

public java.lang.Integer getStateObjectAsInteger(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as an Integer.

Parameters:

stateObject - the StateObject that is converted to an Integer.

Returns:

the value of the StateObject as an Integer.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsLatLon

public LatLon getStateObjectAsLatLon(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a LatLon.

Parameters:

stateObject - the StateObject that is converted to a LatLon.

Returns:

the value of the StateObject as a LatLon.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsLatLonList

public java.util.List<LatLon> getStateObjectAsLatLonList(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a List of LatLons.

Parameters:

stateObject - the StateObject that is converted to a List of LatLons.

Returns:

the value of the StateObject as a List of LatLons.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsLong

public java.lang.Long getStateObjectAsLong(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Long.

Parameters:

stateObject - the StateObject that is converted to a Long.

Returns:

the value of the StateObject as a Long.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsOffsetPair

public float[] getStateObjectAsOffsetPair(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a float[].

Parameters:

stateObject - the StateObject that is converted to a float[].

Returns:

the value of the StateObject as a float[].

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsOffsets

public OffsetsList getStateObjectAsOffsets(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a OffsetsList.

Parameters:

stateObject - the StateObject that is converted to a OffsetsList.

Returns:

the value of the StateObject as a OffsetsList.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsOffsetsList

public java.util.HashMap<java.lang.Integer,OffsetsList> getStateObjectAsOffsetsList(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a HashMap of pairs.

Parameters:

stateObject - the StateObject that is converted to a HashMap of OffsetsLists.

Returns:

the value of the StateObject as a HashMap of pairs.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsPosition

public Position getStateObjectAsPosition(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Position.

Parameters:

stateObject - the StateObject that is converted to a Position.

Returns:

the value of the StateObject as a Position.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsSector

public Sector getStateObjectAsSector(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a Sector.

Parameters:

stateObject - the StateObject that is converted to a Sector.

Returns:

the value of the StateObject as a Sector.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectAsString

public java.lang.String getStateObjectAsString(RestorableSupport.StateObject stateObject)

Returns the value of the StateObject as a String.

Parameters:

stateObject - the StateObject that is converted to a String.

Returns:

the value of the StateObject as a String.

Throws:

java.lang.IllegalArgumentException - If stateObject is null, or does not belong to this RestorableSupport.

getStateObjectTagName

public java.lang.String getStateObjectTagName()

Returns the String to be used for each state object's tag name. This tag name is used as a search parameter to find a state object, and is used as the tag name when a new state object is created. The default tag name is "stateObject".

Returns:

String to be used for each state object's tag name

getStateValueAsBoolean

public java.lang.Boolean getStateValueAsBoolean(RestorableSupport.StateObject context,
                                                java.lang.String name)

Returns the value of the StateObject with the specified name as a Boolean. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, this method returns null. Otherwise, the Boolean value returned is equivalent to passing the StateObject's String value to Boolean.valueOf.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Boolean, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsBoolean

public java.lang.Boolean getStateValueAsBoolean(java.lang.String name)

Returns the value of the StateObject with the specified name as a Boolean. This method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, this method returns null. Otherwise, the Boolean value returned is equivalent to passing the StateObject's String value to Boolean.valueOf.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Boolean, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateValueAsColor

public java.awt.Color getStateValueAsColor(RestorableSupport.StateObject context,
                                           java.lang.String name)

getStateValueAsDouble

public java.lang.Double getStateValueAsDouble(RestorableSupport.StateObject context,
                                              java.lang.String name)

Returns the value of the StateObject with the specified name as a Double. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Double, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Double, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsDouble

public java.lang.Double getStateValueAsDouble(java.lang.String name)

Returns the value of the StateObject with the specified name as a Double. This method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Double, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Double, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateValueAsFloat

public java.lang.Float getStateValueAsFloat(RestorableSupport.StateObject context,
                                            java.lang.String name)

Returns the value of the StateObject with the specified name as a Float. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Float, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Float, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsFloat

public java.lang.Float getStateValueAsFloat(java.lang.String name)

Returns the value of the StateObject with the specified name as a Float. This method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Float, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Float, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateValueAsImageSourceList

public java.util.HashMap<java.lang.Integer,java.lang.Object> getStateValueAsImageSourceList(RestorableSupport.StateObject context,
                                                                                            java.lang.String name)

getStateValueAsImageSourceList

public java.util.HashMap<java.lang.Integer,java.lang.Object> getStateValueAsImageSourceList(java.lang.String name)

getStateValueAsInteger

public java.lang.Integer getStateValueAsInteger(RestorableSupport.StateObject context,
                                                java.lang.String name)

Returns the value of the StateObject with the specified name as an Integer. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not an Integer, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as an Integer, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsInteger

public java.lang.Integer getStateValueAsInteger(java.lang.String name)

Returns the value of the StateObject with the specified name as an Integer. This method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not an Integer, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as an Integer, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateValueAsLatLon

public LatLon getStateValueAsLatLon(RestorableSupport.StateObject context,
                                    java.lang.String name)

getStateValueAsLatLon

public LatLon getStateValueAsLatLon(java.lang.String name)

getStateValueAsLatLonList

public java.util.List<LatLon> getStateValueAsLatLonList(RestorableSupport.StateObject context,
                                                        java.lang.String name)

getStateValueAsLatLonList

public java.util.List<LatLon> getStateValueAsLatLonList(java.lang.String name)

getStateValueAsLong

public java.lang.Long getStateValueAsLong(RestorableSupport.StateObject context,
                                          java.lang.String name)

Returns the value of the StateObject with the specified name as a Long. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Double, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Long, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsLong

public java.lang.Long getStateValueAsLong(java.lang.String name)

Returns the value of the StateObject with the specified name as a Long. This searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a Long, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as a Long, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

getStateValueAsOffsetPair

public float[] getStateValueAsOffsetPair(RestorableSupport.StateObject context,
                                         java.lang.String name)

getStateValueAsOffsetPair

public float[] getStateValueAsOffsetPair(java.lang.String name)

getStateValueAsOffsets

public OffsetsList getStateValueAsOffsets(RestorableSupport.StateObject context,
                                          java.lang.String name)

getStateValueAsOffsets

public OffsetsList getStateValueAsOffsets(java.lang.String name)

getStateValueAsOffsetsList

public java.util.HashMap<java.lang.Integer,OffsetsList> getStateValueAsOffsetsList(RestorableSupport.StateObject context,
                                                                                   java.lang.String name)

getStateValueAsOffsetsList

public java.util.HashMap<java.lang.Integer,OffsetsList> getStateValueAsOffsetsList(java.lang.String name)

getStateValueAsPosition

public Position getStateValueAsPosition(RestorableSupport.StateObject context,
                                        java.lang.String name)

getStateValueAsPosition

public Position getStateValueAsPosition(java.lang.String name)

getStateValueAsSector

public Sector getStateValueAsSector(RestorableSupport.StateObject context,
                                    java.lang.String name)

getStateValueAsSector

public Sector getStateValueAsSector(java.lang.String name)

getStateValueAsString

public java.lang.String getStateValueAsString(RestorableSupport.StateObject context,
                                              java.lang.String name)

Returns the value of the StateObject with the specified name as a String. If context is not null, this method searches the StateObjects directly below the specified context. Otherwise, this method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a String, this method returns null.

Parameters:

context - StateObject context to search, or null to search the document root.

name - the StateObject name to search for.

Returns:

the value of the StateObject as a String, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsString

public java.lang.String getStateValueAsString(java.lang.String name)

Returns the value of the StateObject with the specified name as a String. This method searches the StateObjects directly beneath the document root. If no StateObject with that name exists, or if the value of that StateObject is not a String, this method returns null.

Parameters:

name - the StateObject name to search for.

Returns:

the value of the StateObject as a String, or null if none exists.

Throws:

java.lang.IllegalArgumentException - If name is null.

newRestorableSupport

public static RestorableSupport newRestorableSupport()

Creates a new RestorableSupport with no contents.

Returns:

a new, empty RestorableSupport instance.

newRestorableSupport

public static RestorableSupport newRestorableSupport(java.lang.String documentElementName)

Creates a new RestorableSupport with no contents.

Parameters:

documentElementName - the name of the restorable state document element.

Returns:

a new, empty RestorableSupport instance.

Throws:

java.lang.IllegalArgumentException - if the specified element name is null or empty.

parse

public static RestorableSupport parse(java.lang.String stateInXml)

Creates a new RestorableSupport with the contents of the specified state document.

Parameters:

stateInXml - the XML document to parse for state.

Returns:

a new RestorableSupport instance with the specified state.

Throws:

java.lang.IllegalArgumentException - If stateInXml is null, or the its contents are not a well formed XML document.

setStateObjectTagName

public void setStateObjectTagName(java.lang.String stateObjectTagName)

Sets the String to be used for each state object's tag name. This tag name is used as a search parameter to find a state object, and is used as the tag name when a new state object is created. Setting this value does not retroactively set tag names for existing state objects. The default tag name is "stateObject".

Parameters:

stateObjectTagName - String to be used for each state object's tag name.

Throws:

java.lang.IllegalArgumentException - If stateObjectTagName is null.

toString

public java.lang.String toString()

Returns an XML document string describing this RestorableSupport's current set of state objects. Calling toString is equivalent to calling getStateAsXml.

Overrides:

toString in class java.lang.Object

Returns:

an XML state document string.