oracle.javatools.data
Class HashStructure

java.lang.Object
  oracle.javatools.data.Structure
      oracle.javatools.data.HashStructure

All Implemented Interfaces:

Dirtyable

public abstract class HashStructure
extends Structure

This class implements a hash data structure intended to be used as the generic storage for project metadata that can be marshalled to and from a persistent form without depending on custom marshalling code. The types of data that can be stored in HashStructure are limited to the following:

• String
• boolean
• int
• long
• float
• double
• URL
• HashStructure
• ListStructure

Property Names - Slash Notation

Items are stored in HashStructure by name. No item may have a null name, but the empty string is a valid name. The '/' character is a reserved character for names and is used to delimit HashStructure sublevels. For example, if you invoke hashStructure.getString("a/b/c"), this is semantically equivalent to "first look in hashStructure for a sub-HashStructure named a, and if found look in a for a sub-HashStructure named b, and if found look in b for a String named c and return it; otherwise, return null."

HashStructure provides support for tracking a dirty flag, performing a deep equals comparison, and performing a deep copy operation.

Chained HashStructure

HashStructure supports layering multiple HashStructure instances into a single composite, "chained" HashStructure used for resolving a property that may be defined in any of the layers. The typical use case is two HashStructure instances where the first represents user-customized project properties and the second represents team-level project properties. If a user overrides a value in the user-customized properties, then a chained HashStructure configured to search user properties before the team properties will give precedence to property values defined at the user-customization level. All chained HashStructures will resolve lookups this way, where the first hit in the chain determines the returned value.

Modifying values in a chained HashStructure is more complicated, since it depends on whether an overridden value exists and whether the chain is biased toward overriding or toward preserving the status quo, by modifying the layer in which a lookup would currently resolve.

In general, callers should not have to distinguish whether the HashStructure is chained or not, or if chained, what kind of chain. In fact, the HashStructure API does not provide a mechanism for detecting this. Usually, the distinction is only important for UI that modifies the properties.

Placeholder Values

When a caller looks up a property in the HashStructure, the caller often needs to get a sensible default value back when the property doesn't exist in the HashStructure and for subsequent lookups to continue returning the same defaulted value until it is explicitly changed. At the same time however, specifying the default value and having the HashStructure hold it shouldn't cause the HashStructure to become dirty and adversely affect equals comparison.

To address these requirements, HashStructure supports the notion of 'placeholder' values. In this context, the opposite of 'placeholder' is 'persistent'. A placeholder is a default value specified by a caller through one of the following placeholder-enabled methods:

• getString(java.lang.String, java.lang.String)
• getBoolean(java.lang.String, boolean)
• getInt(java.lang.String, int)
• getLong(java.lang.String, long)
• getFloat(java.lang.String, float)
• getDouble(java.lang.String, double)
• getURL(java.lang.String, java.net.URL)
• putPlaceholderURL(java.lang.String, java.net.URL)
• getOrCreateHashStructure(java.lang.String)
• putPlaceholderHashStructure(java.lang.String, oracle.javatools.data.HashStructure)
• getOrCreateListStructure(java.lang.String)
• putPlaceholderListStructure(java.lang.String, oracle.javatools.data.ListStructure)

When these methods are called, if the value doesn't already exist at the specified name, a placeholder with the specified default value is stored in the HashStructure. If the value did already exist at the specified name, it isn't necessary to fallback on the default, so no placeholder is used, and the existing value is simply returned. Storing a placeholder doesn't cause the HashStructure to become dirty, and when the HashStructure is persisted, placeholder values are not written to the persistent storage.

To be consistent with how a HashStructure is persisted, the equals comparison of two HashStructure instances when placeholders are involved is somewhat more complicated. Suppose we have two HashStructure instances, H1 and H2, which may either have a single property named "a" or no property at all. When comparing H1 and H2:

• If H1/a and H2/a are both placeholders, H1 and H2 are equal if the values of H1/a and H2/a are equal.
• If H1/a is a placeholder and H2/a exists but is not a placeholder, H1 and H2 are not equal, even if the values of H1/a and H2/a are equal.
• If H1/a is a placeholder and H2/a does not exist, H1 and H2 are equal.

The copy operation implemented by copyTo(oracle.javatools.data.HashStructure) and copyTo(oracle.javatools.data.HashStructure, java.lang.String[]) will copy placeholder values from the origin to destination. The copy operation will convert a placeholder value to a persistent value and vice versa if necessary to make the destination a copy of the original.

Change Events

HashStructure supports a callback mechanism to notify listeners whenever a property has changed. A client can receive these events by registering a listener through Structure.addStructureChangeListener(oracle.javatools.data.StructureChangeListener). Normally, a change event is fired on every change made to the HashStructure. However, change events can be batched into groups if the caller uses the Structure.applyBatchChanges(java.lang.Runnable) method and applies changes to the HashStructure within the specified Runnable. When using applyBatchChanges, events are buffered until the Runnable finishes, at which time a single event is fired for all the changes that occurred. The single event contains details on each individual change that occurred.

Persistence

The persistence of HashStructure is handled by a separate class that iterates through HashStructure keys, skipping keys that are for placeholder values, and marshals the data into an appropriate format. In the Oracle IDE, persistence to XML is done by HashStructureIO.

See Also:

HashStructureIO

Field Summary

static int	NONEXISTENT Return value from keyStatus(java.lang.String) to indicate that the key is nonexistent.
static int	PERSISTENT Return value from keyStatus(java.lang.String) and parameter option to setKeyStatus(java.lang.String,int) to indicate that the key is for a persistent value.
static int	PLACEHOLDER Return value from keyStatus(java.lang.String) and parameter option to setKeyStatus(java.lang.String,int) to indicate that the key is for a placeholder value.

Method Summary

void	applyChange(ChangeInfo change) Applies the change described by the specified ChangeInfo to this HashStructure.
void	applyChanges(ChangeInfo[] changes) Applies the changes described by the specified ChangeInfo array to this HashStructure.
HashStructure	asReadOnly() Returns a HashStructure that provides read-only access to this HashStructure's properties.
void	clear() Removes all data from this HashStructure.
abstract boolean	containsKey(java.lang.String name)
HashStructure	copyTo(HashStructure target) Copies all properties recursively from this HashStructure to the specified target HashStructure.
HashStructure	copyTo(HashStructure target, java.lang.String[] names) Copies the properties specified by the names parameter from this HashStructure to the specified target HashStructure.
boolean	equals(java.lang.Object obj)
java.util.List	getAsList(java.lang.String name) Returns the property at the specified name as an unmodifiable List, whether or not the property name actually points to a ListStructure.
boolean	getBoolean(java.lang.String name) Returns the boolean equivalent value of the object bound at the specified name.
boolean	getBoolean(java.lang.String name, boolean defaultValue) Returns the boolean equivalent value of the object bound at the specified name.
double	getDouble(java.lang.String name) Returns the double equivalent value of the object bound at the specified name.
double	getDouble(java.lang.String name, double defaultValue) Returns the double equivalent value of the object bound at the specified name.
float	getFloat(java.lang.String name) Returns the float equivalent value of the object bound at the specified name.
float	getFloat(java.lang.String name, float defaultValue) Returns the float equivalent value of the object bound at the specified name.
HashStructure	getHashStructure(java.lang.String name)
int	getInt(java.lang.String name) Returns the int equivalent value of the object bound at the specified name.
int	getInt(java.lang.String name, int defaultValue) Returns the int equivalent value of the object bound at the specified name.
ListStructure	getListStructure(java.lang.String name) Returns the ListStructure bound at the specified name or null of no object is bound.
long	getLong(java.lang.String name) Returns the long equivalent value of the object bound at the specified name.
long	getLong(java.lang.String name, long defaultValue) Returns the long equivalent value of the object bound at the specified name.
abstract java.lang.Object	getObject(java.lang.String name) Returns the Object stored at the specified name.
HashStructure	getOrCreateHashStructure(java.lang.String name) Returns the HashStructure bound at the specified name or if no object is currently bound to that name creates a new, empty HashStructure object and binds it to the specified name as a placeholder.
ListStructure	getOrCreateListStructure(java.lang.String name) Returns the ListStructure bound at the specified name or if no object is currently bound to that name creates a new, empty ListStructure object and binds it to the specified name as a placeholder.
java.lang.String	getString(java.lang.String name) Returns the String value that is bound at the specified name.
java.lang.String	getString(java.lang.String name, java.lang.String defaultValue) Returns the String value that is bound at the specified name.
java.net.URL	getURL(java.lang.String name) Returns the URL bound at the specified name or null if no object is bound.
java.net.URL	getURL(java.lang.String name, java.net.URL defaultValue) Returns the URL bound at the specified name.
abstract void	hideValues(java.lang.String[] names) Moves all of the specified properties into a "dormant" state, which means the values are still saved, but they will not participate in any HashStructure operations (get, put, containsKey, etc) until recovered by recoverValues(..).
boolean	isAnyValueOverridden(java.lang.String[] names) For a chained HashStructure, this method will return true if any of the specified properties has its value defined anywhere other than the last HashStructure in the chain.
boolean	isReadOnly() Returns true if this HashStructure is in a read-only mode or false if this HashStructure is modifiable.
abstract java.util.Set<java.lang.String>	keySet() Returns the keys of this HashStructure as an unmodifiable Set.
abstract int	keyStatus(java.lang.String key) For the specified key, returns whether the key exists, is persistent, or is a placeholder.
static HashStructure	newChainForOverriding(HashStructure[] hashes) Returns a composite HashStructure that is backed by the specified array of HashStructures, treating the array as a lookup queue.
static HashStructure	newChainForStatusQuo(HashStructure[] hashes) Returns a composite HashStructure that is backed by the specified array of HashStructures, treating the array as a lookup queue.
static HashStructure	newInstance()
abstract java.util.Set<java.lang.String>	persistentKeySet() Returns the persistent keys of this HashStructure as an unmodifiable Set.
void	putBoolean(java.lang.String name, boolean value) Binds the specified name to the specified value.
void	putDouble(java.lang.String name, double value) Binds the specified name to the specified value.
void	putFloat(java.lang.String name, float value) Binds the specified name to the specified value.
void	putHashStructure(java.lang.String name, HashStructure hash) Binds the specified name to the specified HashStructure.
void	putInt(java.lang.String name, int value) Binds the specified name to the specified value.
void	putListStructure(java.lang.String name, ListStructure list) Binds the specified name to the specified ListStructure.
void	putLong(java.lang.String name, long value) Binds the specified name to the specified value.
void	putPlaceholderHashStructure(java.lang.String name, HashStructure hash) Binds the specified name to the specified HashStructure as a placeholder.
void	putPlaceholderListStructure(java.lang.String name, ListStructure list) Binds the specified name to the specified ListStructure as a placeholder.
void	putPlaceholderURL(java.lang.String name, java.net.URL placeholderValue) Puts the specified URL as a placeholder into this HashStructure.
void	putString(java.lang.String name, java.lang.String value) Binds the specified name to the specified value.
void	putString(java.lang.String name, java.lang.String value, boolean removeIfNullValue) Binds the specified name to the specified value.
void	putURL(java.lang.String name, java.net.URL value) Binds the specified name to the specified value.
void	putURL(java.lang.String name, java.net.URL value, boolean removeIfNullValue) Binds the specified name to the specified value.
abstract void	recoverValues(java.lang.String[] names) Recovers the specified properties from the "dormant" state, so that they again participate in all HashStructure operations.
abstract void	remove(java.lang.String name) Removes the object bound to the specified name from this Structure.
abstract void	setKeyStatus(java.lang.String key, int status) For the specified key, if it exists in any form in this HashStructure, the key status is changed to the specified state, which must be either PERSISTENT or PLACEHOLDER.
abstract void	setParentDirtyable(Dirtyable parentDirtyable) Sets the Dirtyable that will be used as the delegate for tracking the dirty flag.
abstract int	size() Returns the number of keys that are bound in this HashStructure.

Methods inherited from class oracle.javatools.data.Structure

addStructureChangeListener, applyBatchChanges, getFullName, getStructName, intern, intern, isDirty, markDirty, removeStructureChangeListener

Methods inherited from class java.lang.Object

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

Field Detail

NONEXISTENT

public static final int NONEXISTENT

Return value from keyStatus(java.lang.String) to indicate that the key is nonexistent.

See Also:

Constant Field Values

PERSISTENT

public static final int PERSISTENT

Return value from keyStatus(java.lang.String) and parameter option to setKeyStatus(java.lang.String,int) to indicate that the key is for a persistent value.

See Also:

Constant Field Values

PLACEHOLDER

public static final int PLACEHOLDER

Return value from keyStatus(java.lang.String) and parameter option to setKeyStatus(java.lang.String,int) to indicate that the key is for a placeholder value.

See Also:

Constant Field Values

Method Detail

newInstance

public static final HashStructure newInstance()

newChainForStatusQuo

public static final HashStructure newChainForStatusQuo(HashStructure[] hashes)

Returns a composite HashStructure that is backed by the specified array of HashStructures, treating the array as a lookup queue. The composite HashStructure is called "status quo" because a "put" operation will first scan the array looking for the first hash to define the property and assign the new value there. So effectively, a HashStructure in this type of chain will only be modified if it already contains the property in question or if it is the last HashStructure in the chain and no earlier HashStructure in the chain contains the property.

newChainForOverriding

public static final HashStructure newChainForOverriding(HashStructure[] hashes)

Returns a composite HashStructure that is backed by the specified array of HashStructures, treating the array as a lookup queue. The composite HashStructure is called "overriding" because a "put" operation will only be applied to the first HashStructure in the chain. So effectively, a HashStructure in this type of chain will only be modified if it is in position to override a value defined later in the chain.

getString

public final java.lang.String getString(java.lang.String name)

Returns the String value that is bound at the specified name. If the value is null, null is returned. If the value is non-null and is not a String, the result of calling toString() on the value is returned. If the name is not bound, null is returned.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String or if a leaf object is encountered when a substructure is expected.

getString

public final java.lang.String getString(java.lang.String name,
                                        java.lang.String defaultValue)

Returns the String value that is bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue string is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String or if a leaf object is encountered when a substructure is expected.

putString

public final void putString(java.lang.String name,
                            java.lang.String value)

Binds the specified name to the specified value. If the name is already bound to a value, the new value replaces the old value. If the value is null, then the name is bound to null. To remove the binding, use putString(String, String, boolean) or remove(String).

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putString("a/b","c") would throw ClassCastException.

putString

public final void putString(java.lang.String name,
                            java.lang.String value,
                            boolean removeIfNullValue)

Binds the specified name to the specified value. If the name is already bound to a value, the new value replaces the old value.

When the value is null, the behavior depends on the value of the removeIfNullValue parameter. If removeIfNullValue is true, the name is unbound from the HashStructure. If removeIfNullValue is false, then the name is bound to null.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putString("a/b","c") would throw ClassCastException.

getBoolean

public final boolean getBoolean(java.lang.String name)

Returns the boolean equivalent value of the object bound at the specified name. If null is bound or there is no value bound, this method returns false.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a boolean) or if a leaf object is encountered when a substructure is expected.

getBoolean

public final boolean getBoolean(java.lang.String name,
                                boolean defaultValue)

Returns the boolean equivalent value of the object bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue boolean is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a boolean) or if a leaf object is encountered when a substructure is expected.

putBoolean

public final void putBoolean(java.lang.String name,
                             boolean value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putBoolean("a/b",true) would throw ClassCastException.

getInt

public final int getInt(java.lang.String name)

Returns the int equivalent value of the object bound at the specified name. If null is bound or there is no bound value, this method returns 0.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to an int) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into an int.

getInt

public final int getInt(java.lang.String name,
                        int defaultValue)

Returns the int equivalent value of the object bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue int is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to an int) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into an int.

putInt

public final void putInt(java.lang.String name,
                         int value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putInt("a/b",17) would throw ClassCastException.

getLong

public final long getLong(java.lang.String name)

Returns the long equivalent value of the object bound at the specified name. If null is bound or there is no bound value, this method returns 0.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a long) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a long.

getLong

public final long getLong(java.lang.String name,
                          long defaultValue)

Returns the long equivalent value of the object bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue long is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a long) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a long.

putLong

public final void putLong(java.lang.String name,
                          long value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putLong("a/b",17L) would throw ClassCastException.

getFloat

public final float getFloat(java.lang.String name)

Returns the float equivalent value of the object bound at the specified name. If null is bound or there is no bound value, this method returns 0.0.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a float) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a float.

getFloat

public final float getFloat(java.lang.String name,
                            float defaultValue)

Returns the float equivalent value of the object bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue float is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a float) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a float.

putFloat

public final void putFloat(java.lang.String name,
                           float value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putFloat("a/b",3.14159f) would throw ClassCastException.

getDouble

public final double getDouble(java.lang.String name)

Returns the double equivalent value of the object bound at the specified name. If null is bound or there is no bound value, this method returns 0.0.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a double) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a double.

getDouble

public final double getDouble(java.lang.String name,
                              double defaultValue)

Returns the double equivalent value of the object bound at the specified name. If null is bound or there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue double is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to String (which is subsequently converted to a double) or if a leaf object is encountered when a substructure is expected.

java.lang.NumberFormatException - if the object bound at the name cannot be converted into a double.

putDouble

public final void putDouble(java.lang.String name,
                            double value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putDouble("a/b",2.718281828d) would throw ClassCastException.

getURL

public final java.net.URL getURL(java.lang.String name)

Returns the URL bound at the specified name or null if no object is bound.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to URL or if a leaf object is encountered when a substructure is expected.

getURL

public final java.net.URL getURL(java.lang.String name,
                                 java.net.URL defaultValue)

Returns the URL bound at the specified name. Null is a possible value. If there is no bound value, the value of the defaultValue parameter is returned, and the defaultValue URL is put into the HashStructure as a placeholder.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to URL or if a leaf object is encountered when a substructure is expected.

putPlaceholderURL

public final void putPlaceholderURL(java.lang.String name,
                                    java.net.URL placeholderValue)

Puts the specified URL as a placeholder into this HashStructure. However, if the HashStructure already contains a property at the specified name, this method behaves exactly like putURL(java.lang.String,java.net.URL), replacing the existing value with the specified value and making the HashStructure dirty.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putPlaceholderURL("a/b",url) would throw ClassCastException.

putURL

public final void putURL(java.lang.String name,
                         java.net.URL value)

Binds the specified name to the specified value. If a value is already bound at the name, the new value replaces the old value.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putURL("a/b",url) would throw ClassCastException.

putURL

public final void putURL(java.lang.String name,
                         java.net.URL value,
                         boolean removeIfNullValue)

Binds the specified name to the specified value. If the name is already bound to a value, the new value replaces the old value.

When the value is null, the behavior depends on the value of the removeIfNullValue parameter. If removeIfNullValue is true, the name is unbound from the HashStructure. If removeIfNullValue is false, then the name is bound to null.

Throws:

java.lang.ClassCastException - if the name specifies a substructure but a leaf object is encountered instead. For example, if hash.getObject("a") would return a String, then calling hash.putURL("a/b",url,true) would throw ClassCastException.

getObject

public abstract java.lang.Object getObject(java.lang.String name)

Returns the Object stored at the specified name. The possible types that are returned from this method are:

• java.lang.String (for String, boolean, int, long, double, float)
• java.net.URL
• HashStructure
• ListStructure

keySet

public abstract java.util.Set<java.lang.String> keySet()

Returns the keys of this HashStructure as an unmodifiable Set. The returned set includes both persistent and placeholder keys.

Throws:

java.lang.UnsupportedOperationException - if any attempt is made to modify the returned Set.

applyChange

public final void applyChange(ChangeInfo change)

Applies the change described by the specified ChangeInfo to this HashStructure. This method is most often used to apply deltas accumulated through a ChangeBuffer from a copy of the HashStructure back to the original.

applyChanges

public final void applyChanges(ChangeInfo[] changes)

Applies the changes described by the specified ChangeInfo array to this HashStructure. This method is most often used to apply deltas accumulated through a ChangeBuffer from a copy of the HashStructure back to the original.

persistentKeySet

public abstract java.util.Set<java.lang.String> persistentKeySet()

Returns the persistent keys of this HashStructure as an unmodifiable Set. Placeholder keys are not persistent, so they are omitteed.

keyStatus

public abstract int keyStatus(java.lang.String key)

For the specified key, returns whether the key exists, is persistent, or is a placeholder. The return value from this method will be one of NONEXISTENT, PERSISTENT, or PLACEHOLDER.

setKeyStatus

public abstract void setKeyStatus(java.lang.String key,
                                  int status)

For the specified key, if it exists in any form in this HashStructure, the key status is changed to the specified state, which must be either PERSISTENT or PLACEHOLDER.

getHashStructure

public final HashStructure getHashStructure(java.lang.String name)

Parameters:

name - The name of the HashStructure to retrieve.

Returns:

the HashStructure bound at the specified name or null of no object is bound. However, if this HashStructure is a chained HashStructure, this method will never return null; use containsKey(java.lang.String) to test for existence instead of checking if getHashStructure returns null.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to HashStructure.

getOrCreateHashStructure

public final HashStructure getOrCreateHashStructure(java.lang.String name)

Returns the HashStructure bound at the specified name or if no object is currently bound to that name creates a new, empty HashStructure object and binds it to the specified name as a placeholder.

Throws:

java.lang.ClassCastException - if there is already a non-null object bound at the name, and it cannot be cast to HashStructure.

putHashStructure

public final void putHashStructure(java.lang.String name,
                                   HashStructure hash)

Binds the specified name to the specified HashStructure. If a HashStructure is already bound at the name, the new one replaces the old.

Throws:

java.lang.IllegalArgumentException - if either the name or the structure parameter is null.

java.lang.IllegalStateException - if a cyclical reference is detected. Cycles are not allowed in a graph of HashStructure and ListStructure objects.

putPlaceholderHashStructure

public final void putPlaceholderHashStructure(java.lang.String name,
                                              HashStructure hash)

Binds the specified name to the specified HashStructure as a placeholder. If a HashStructure is already bound at the name, the new one replaces the old and is stored as a regular value rather than a placeholder.

Throws:

java.lang.IllegalArgumentException - if either the name or the structure parameter is null.

java.lang.IllegalStateException - if a cyclical reference is detected. Cycles are not allowed in a graph of HashStructure and ListStructure objects.

getAsList

public final java.util.List getAsList(java.lang.String name)

Returns the property at the specified name as an unmodifiable List, whether or not the property name actually points to a ListStructure. If the named property is defined but is not a List, it is returned wrapped in an unmodifiable List; that will happen even if the defined property has a null value. If the named property is already a ListStructure, it is simply wrapped by Collections.unmodifiableList(..) and then returned. If the named property is not defined (i.e. containsKey is false for the name), then this method returns null.

getListStructure

public final ListStructure getListStructure(java.lang.String name)

Returns the ListStructure bound at the specified name or null of no object is bound.

Throws:

java.lang.ClassCastException - if the object bound at the name cannot be cast to ListStructure.

getOrCreateListStructure

public final ListStructure getOrCreateListStructure(java.lang.String name)

Returns the ListStructure bound at the specified name or if no object is currently bound to that name creates a new, empty ListStructure object and binds it to the specified name as a placeholder.

Throws:

java.lang.ClassCastException - if there is already a non-null object bound at the name, and it cannot be cast to ListStructure.

putListStructure

public final void putListStructure(java.lang.String name,
                                   ListStructure list)

Binds the specified name to the specified ListStructure. If a ListStructure is already bound at the name, the new one replaces the old.

Throws:

java.lang.IllegalArgumentException - if either the name or the structure parameter is null.

java.lang.IllegalStateException - if a cyclical reference is detected. Cycles are not allowed in a graph of HashStructure and ListStructure objects.

putPlaceholderListStructure

public final void putPlaceholderListStructure(java.lang.String name,
                                              ListStructure list)

Binds the specified name to the specified ListStructure as a placeholder. If a ListStructure is already bound at the name, the new one replaces the old and is stored as a regular value rather than a placeholder.

Throws:

java.lang.IllegalArgumentException - if either the name or the structure parameter is null.

java.lang.IllegalStateException - if a cyclical reference is detected. Cycles are not allowed in a graph of HashStructure and ListStructure objects.

clear

public void clear()

Removes all data from this HashStructure.

Overrides:

clear in class Structure

containsKey

public abstract boolean containsKey(java.lang.String name)

Returns:

true if the specified name is bound in this Structure, whether persistent or placeholder; false otherwise. Use keyStatus(java.lang.String) if the distinction between persistent and placeholder is important.

remove

public abstract void remove(java.lang.String name)

Removes the object bound to the specified name from this Structure.

size

public abstract int size()

Returns the number of keys that are bound in this HashStructure. This includes both persistent and placeholder keys.

setParentDirtyable

public abstract void setParentDirtyable(Dirtyable parentDirtyable)

Sets the Dirtyable that will be used as the delegate for tracking the dirty flag. When no parent Dirtyable is set (or when null is explicitly set), this HashStructure will track the dirty state directly.

isAnyValueOverridden

public boolean isAnyValueOverridden(java.lang.String[] names)

For a chained HashStructure, this method will return true if any of the specified properties has its value defined anywhere other than the last HashStructure in the chain. For an unchained HashStructure, this method will always return false.

hideValues

public abstract void hideValues(java.lang.String[] names)

Moves all of the specified properties into a "dormant" state, which means the values are still saved, but they will not participate in any HashStructure operations (get, put, containsKey, etc) until recovered by recoverValues(..).

See Also:

recoverValues(java.lang.String[])

recoverValues

public abstract void recoverValues(java.lang.String[] names)

Recovers the specified properties from the "dormant" state, so that they again participate in all HashStructure operations.

See Also:

hideValues(java.lang.String[])

isReadOnly

public boolean isReadOnly()

Returns true if this HashStructure is in a read-only mode or false if this HashStructure is modifiable. See asReadOnly() for details.

asReadOnly

public HashStructure asReadOnly()

Returns a HashStructure that provides read-only access to this HashStructure's properties. Any changes to the original, modifiable HashStructure will continue to be seen by the read-only instance. Any attempt to modify the returned HashStructure, including adding or removing listeners, results in an UnsupportedOperationException being thrown.

copyTo

public HashStructure copyTo(HashStructure target,
                            java.lang.String[] names)

Copies the properties specified by the names parameter from this HashStructure to the specified target HashStructure. The names may use slash notation to indicate properties located in a substructure.

copyTo

public HashStructure copyTo(HashStructure target)

Copies all properties recursively from this HashStructure to the specified target HashStructure. The copy operation buffers change events so that only a single StructureChangeEvent is fired on the target HashStructure as a result of invoking copyTo.

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object