NASA World Wind

gov.nasa.worldwind.util
Class RestorableSupport

java.lang.Object
  extended by gov.nasa.worldwind.util.RestorableSupport

public class RestorableSupport
extends 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
static class RestorableSupport.StateObject
          An interface to the stateObject elements in an XML state document, as defined by RestorableSupport.
 
Method Summary
 RestorableSupport.StateObject addStateObject(RestorableSupport.StateObject context, String name)
          Adds a new StateObject with the specified name.
 RestorableSupport.StateObject addStateObject(String name)
          Adds a new StateObject with the specified name.
 void addStateValueAsBoolean(RestorableSupport.StateObject context, String name, boolean booleanValue)
          Adds a new StateObject with the specified name and Boolean value.
 void addStateValueAsBoolean(String name, boolean booleanValue)
          Adds a new StateObject with the specified name and Boolean value.
 void addStateValueAsDouble(RestorableSupport.StateObject context, String name, double doubleValue)
          Adds a new StateObject with the specified name and Double value.
 void addStateValueAsDouble(String name, double doubleValue)
          Adds a new StateObject with the specified name and Double value.
 void addStateValueAsInteger(RestorableSupport.StateObject context, String name, int intValue)
          Adds a new StateObject with the specified name and Integer value.
 void addStateValueAsInteger(String name, int intValue)
          Adds a new StateObject with the specified name and Integer value.
 void addStateValueAsString(RestorableSupport.StateObject context, String name, String value)
          Adds a new StateObject with the specified name and String value.
 void addStateValueAsString(RestorableSupport.StateObject context, String name, String value, boolean escapeValue)
          Adds a new StateObject with the specified name and String value.
 void addStateValueAsString(String name, String value)
          Adds a new StateObject with the specified name and String value.
 void addStateValueAsString(String name, String value, boolean escapeValue)
          Adds a new StateObject with the specified name and String value.
static Color decodeColor(String encodedString)
          Returns the Color described by the String encodedString.
static String encodeColor(Color color)
          Returns a String encoding of the specified color.
 RestorableSupport.StateObject[] getAllStateObjects(RestorableSupport.StateObject context)
          Returns all StateObjects directly beneath the a context StateObject.
 RestorableSupport.StateObject[] getAllStateObjects(RestorableSupport.StateObject context, String name)
          Returns all StateObjects with the specified name.
 RestorableSupport.StateObject[] getAllStateObjects(String name)
          Returns any StateObjects directly beneath the document root that have the specified name.
 String getStateAsXml()
          Returns an XML document string describing this RestorableSupport's current set of state objects.
 RestorableSupport.StateObject getStateObject(RestorableSupport.StateObject context, String name)
          Returns the StateObject with the specified name.
 RestorableSupport.StateObject getStateObject(String name)
          Returns the StateObject with the specified name.
 String getStateObjectTagName()
          Returns the String to be used for each state object's tag name.
 Boolean getStateValueAsBoolean(RestorableSupport.StateObject context, String name)
          Returns the value of the StateObject with the specified name as a Boolean.
 Boolean getStateValueAsBoolean(String name)
          Returns the value of the StateObject with the specified name as a Boolean.
 Double getStateValueAsDouble(RestorableSupport.StateObject context, String name)
          Returns the value of the StateObject with the specified name as a Double.
 Double getStateValueAsDouble(String name)
          Returns the value of the StateObject with the specified name as a Double.
 Integer getStateValueAsInteger(RestorableSupport.StateObject context, String name)
          Returns the value of the StateObject with the specified name as an Integer.
 Integer getStateValueAsInteger(String name)
          Returns the value of the StateObject with the specified name as an Integer.
 String getStateValueAsString(RestorableSupport.StateObject context, String name)
          Returns the value of the StateObject with the specified name as a String.
 String getStateValueAsString(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 parse(String stateInXml)
          Creates a new RestorableSupport with the contents of the specified state document.
 void setStateObjectTagName(String stateObjectTagName)
          Sets the String to be used for each state object's tag name.
 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
 

Method Detail

addStateObject

public RestorableSupport.StateObject addStateObject(RestorableSupport.StateObject context,
                                                    String name)
Adds a new StateObject with the specified name. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be created, or null to place it under the document root.
name - the new StateObject's name.
Returns:
the new StateObject instance.
Throws:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateObject

public RestorableSupport.StateObject addStateObject(String name)
Adds a new StateObject with the specified name. The new StateObject will be 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:
IllegalArgumentException - If name is null.

addStateValueAsBoolean

public void addStateValueAsBoolean(RestorableSupport.StateObject context,
                                   String name,
                                   boolean booleanValue)
Adds a new StateObject with the specified name and Boolean value. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be created, or null to place it under the document root.
name - the new StateObject's name.
booleanValue - the new StateObject's Boolean value.
Throws:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsBoolean

public void addStateValueAsBoolean(String name,
                                   boolean booleanValue)
Adds a new StateObject with the specified name and Boolean value. The new StateObject will be 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:
IllegalArgumentException - If name is null.

addStateValueAsDouble

public void addStateValueAsDouble(RestorableSupport.StateObject context,
                                  String name,
                                  double doubleValue)
Adds a new StateObject with the specified name and Double value. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be created, or null to place it under the document root.
name - the new StateObject's name.
doubleValue - the new StateObject's Double value.
Throws:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsDouble

public void addStateValueAsDouble(String name,
                                  double doubleValue)
Adds a new StateObject with the specified name and Double value. The new StateObject will be 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:
IllegalArgumentException - If name is null.

addStateValueAsInteger

public void addStateValueAsInteger(RestorableSupport.StateObject context,
                                   String name,
                                   int intValue)
Adds a new StateObject with the specified name and Integer value. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be created, or null to place it under the document root.
name - the new StateObject's name.
intValue - the new StateObject's Integer value.
Throws:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

addStateValueAsInteger

public void addStateValueAsInteger(String name,
                                   int intValue)
Adds a new StateObject with the specified name and Integer value. The new StateObject will be 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:
IllegalArgumentException - If name is null.

addStateValueAsString

public void addStateValueAsString(RestorableSupport.StateObject context,
                                  String name,
                                  String value)
Adds a new StateObject with the specified name and String value. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be created, or null to place it under the document root.
name - the new StateObject's name.
value - the new StateObject's String value.
Throws:
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,
                                  String name,
                                  String value,
                                  boolean escapeValue)
Adds a new StateObject with the specified name and String value. If context is not null, the new StateObject will be nested directly beneath the specified context. Otherwise, the new StateObject will be 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 will be 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 will be 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:
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(String name,
                                  String value)
Adds a new StateObject with the specified name and String value. The new StateObject will be 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:
IllegalArgumentException - If either name or value is null.

addStateValueAsString

public void addStateValueAsString(String name,
                                  String value,
                                  boolean escapeValue)
Adds a new StateObject with the specified name and String value. The new StateObject will be 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 will be 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:
IllegalArgumentException - If either name or value is null.

decodeColor

public static Color decodeColor(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 will return null.

Parameters:
encodedString - String to decode.
Returns:
Color decoded from the specified encodedString, or null if the String cannot be decoded.
Throws:
IllegalArgumentException - If encodedString is null.

encodeColor

public static String encodeColor(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:
IllegalArgumentException - If color is null.

getAllStateObjects

public RestorableSupport.StateObject[] getAllStateObjects(RestorableSupport.StateObject context)
Returns all StateObjects directly beneath the a context StateObject. If context is not null, this will return all the StateObjects directly below the specified context. Otherwise, this will return 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 will have zero length if none exist.
Throws:
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,
                                                          String name)
Returns all StateObjects with the specified name. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search the StateObjects directly beneath the document root. If no StateObjects with that name exist, this will return 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 will have zero length if none exist.
Throws:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getAllStateObjects

public RestorableSupport.StateObject[] getAllStateObjects(String name)
Returns any StateObjects directly beneath the document root that have the specified name. If no StateObjects with that name exist, this will return a valid StateObject array with zero length.

Parameters:
name - the StateObject name to search for.
Returns:
an array of the StateObject instances, which will have zero length if none exist.
Throws:
IllegalArgumentException - If name is null.

getStateAsXml

public String getStateAsXml()
Returns an XML document string describing this RestorableSupport's current set of state objects. If this RestorableSupport cannot be converted, this will return null.

Returns:
an XML state document string.

getStateObject

public RestorableSupport.StateObject getStateObject(RestorableSupport.StateObject context,
                                                    String name)
Returns the StateObject with the specified name. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search the StateObjects directly beneath the document root. If no StateObject with that name exists, this will return 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:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateObject

public RestorableSupport.StateObject getStateObject(String name)
Returns the StateObject with the specified name. This will search the StateObjects directly beneath the document root. If no StateObject with that name exists, this will return null.

Parameters:
name - the StateObject name to search for.
Returns:
the StateObject instance, or null if none exists.
Throws:
IllegalArgumentException - If name is null.

getStateObjectTagName

public String getStateObjectTagName()
Returns the String to be used for each state object's tag name. This tag name will be used as a search parameter to find a state object, and will be 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 Boolean getStateValueAsBoolean(RestorableSupport.StateObject context,
                                      String name)
Returns the value of the StateObject with the specified name as a Boolean. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search the StateObjects directly beneath the document root. If no StateObject with that name exists, this will return null. Otherwise, the Boolean value returned is equivalent to passing the StateObject's 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:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsBoolean

public Boolean getStateValueAsBoolean(String name)
Returns the value of the StateObject with the specified name as a Boolean. This will search the StateObjects directly beneath the document root. If no StateObject with that name exists, this will return null. Otherwise, the Boolean value returned is equivalent to passing the StateObject's 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:
IllegalArgumentException - If name is null.

getStateValueAsDouble

public Double getStateValueAsDouble(RestorableSupport.StateObject context,
                                    String name)
Returns the value of the StateObject with the specified name as a Double. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search 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 will return 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:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsDouble

public Double getStateValueAsDouble(String name)
Returns the value of the StateObject with the specified name as a Double. This will search 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 will return null.

Parameters:
name - the StateObject name to search for.
Returns:
the value of the StateObject as a Double, or null if none exists.
Throws:
IllegalArgumentException - If name is null.

getStateValueAsInteger

public Integer getStateValueAsInteger(RestorableSupport.StateObject context,
                                      String name)
Returns the value of the StateObject with the specified name as an Integer. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search 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 will return 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:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsInteger

public Integer getStateValueAsInteger(String name)
Returns the value of the StateObject with the specified name as an Integer. This will search 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 will return null.

Parameters:
name - the StateObject name to search for.
Returns:
the value of the StateObject as an Integer, or null if none exists.
Throws:
IllegalArgumentException - If name is null.

getStateValueAsString

public String getStateValueAsString(RestorableSupport.StateObject context,
                                    String name)
Returns the value of the StateObject with the specified name as a String. If context is not null, this will search the StateObjects directly below the specified context. Otherwise, this will search 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 will return 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:
IllegalArgumentException - If name is null, or if context is not null and does not belong to this RestorableSupport.

getStateValueAsString

public String getStateValueAsString(String name)
Returns the value of the StateObject with the specified name as a String. This will search 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 will return null.

Parameters:
name - the StateObject name to search for.
Returns:
the value of the StateObject as a String, or null if none exists.
Throws:
IllegalArgumentException - If name is null.

newRestorableSupport

public static RestorableSupport newRestorableSupport()
Creates a new RestorableSupport with no contents.

Returns:
a new, empty RestorableSupport instance.

parse

public static RestorableSupport parse(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:
IllegalArgumentException - If stateInXml is null, or the its contents are not a well formed XML document.

setStateObjectTagName

public void setStateObjectTagName(String stateObjectTagName)
Sets the String to be used for each state object's tag name. This tag name will be used as a search parameter to find a state object, and will be used as the tag name when a new state object is created. Setting this value will 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:
IllegalArgumentException - If stateObjectTagName is null.

toString

public 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 Object
Returns:
an XML state document string.

NASA World Wind