org.rapidcontext.core.data

Class Dict

java.lang.Object

org.rapidcontext.core.data.Dict

public class Dict
extends java.lang.Object

A general data dictionary. Compared to the standard Map interface, this class provides a number of improvements;

• Access Methods -- Methods to provide easy access to integer, boolean and string values without casting.
• Sealing -- Simple creation of read-only objects.
• Deep Copies -- Provides a meaningful way to clone or copy data.
• Serialization -- Utility classes are available for serializing to JSON, XML, etc.
• Debug Info -- The toString() method provides a more usable default implementation.

A dictionary is more or less a hash table with name and value pairs. The names are non-empty strings and values may have any type, but recommended types are String, Integer, Boolean, Dict and Array. Circular or self-referencing structures should not be used, since most data serialization cannot handle them.

Version:

1.0

Author:

Per Cederberg

Constructor Summary

Constructors

Constructor and Description
Dict() Creates a new empty dictionary.
Dict(int initialCapacity) Creates a new empty dictionary.

Method Summary

Modifier and Type	Method and Description
java.lang.String	add(java.lang.String key, java.lang.Object value) Adds a dictionary value using the specified key if possible.
void	addAll(Dict dict) Adds all key-value pairs from another dictionary to this one.
java.lang.String	addBoolean(java.lang.String key, boolean value) Adds a boolean property value using the specified key if possible.
java.lang.String	addInt(java.lang.String key, int value) Adds an integer property value using the specified key if possible.
boolean	containsKey(java.lang.String key) Checks if the specified key is defined in this dictionary.
boolean	containsValue(java.lang.Object value) Checks if the specified value is contained in this dictionary.
Dict	copy() Creates a copy of this dictionary.
java.lang.Object	get(java.lang.String key) Returns the dictionary value for the specified key.
java.lang.Object	get(java.lang.String key, java.lang.Object defaultValue) Returns the dictionary value for the specified key.
Array	getArray(java.lang.String key) Returns the dictionary array value for the specified key.
boolean	getBoolean(java.lang.String key, boolean defaultValue) Returns the dictionary boolean value for the specified key.
java.util.Date	getDate(java.lang.String key, java.util.Date defaultValue) Returns the dictionary date value for the specified key.
Dict	getDict(java.lang.String key) Returns the dictionary dictionary value for the specified key.
int	getInt(java.lang.String key, int defaultValue) Returns the dictionary integer value for the specified key.
java.lang.String	getString(java.lang.String key, java.lang.String defaultValue) Returns the dictionary string value for the specified key.
java.lang.String	keyOf(java.lang.Object value) Returns the first dictionary key having the specified value.
java.lang.String[]	keys() Returns an array with all the defined dictionary key names.
void	remove(java.lang.String key) Deletes the specified dictionary key and its value.
void	seal(boolean recursive) Seals this dictionary and prohibits further modifications.
void	set(java.lang.String key, java.lang.Object value) Modifies or defines the dictionary value for the specified key.
void	setAll(Dict dict) Modifies or defines all keys from another dictionary.
void	setBoolean(java.lang.String key, boolean value) Modifies or defines the boolean dictionary value for the specified key.
void	setInt(java.lang.String key, int value) Modifies or defines the integer dictionary value for the specified key.
int	size() Returns the size of the dictionary, i.e.
java.lang.String	toString() Returns a string representation of this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dict

public Dict()

Creates a new empty dictionary.

Dict

public Dict(int initialCapacity)

Creates a new empty dictionary. By default a dictionary is created with a null key map, but if this constructor is used the map will be initialized with the specified capacity.

Parameters:

initialCapacity - the initial dictionary capacity

Method Detail

toString

public java.lang.String toString()

Returns a string representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this object

copy

public Dict copy()

Creates a copy of this dictionary. The copy is a "deep copy", as all dictionary and array values will be recursively copied.

Returns:

a deep copy of this object

seal

public void seal(boolean recursive)

Seals this dictionary and prohibits further modifications. If the seal is applied recursively, any dictionary or array values in this object will also be sealed. Once sealed, this instance is an immutable read-only object.

Parameters:

recursive - the recursive flag

size

public int size()

Returns the size of the dictionary, i.e. the number of keys in it.

Returns:

the size of the dictionary, or zero (0) if empty

containsKey

public boolean containsKey(java.lang.String key)

Checks if the specified key is defined in this dictionary. Note that a key name may be defined but still contain a null value.

Parameters:

key - the key name

Returns:

true if the key is defined, or false otherwise

containsValue

public boolean containsValue(java.lang.Object value)

Checks if the specified value is contained in this dictionary. Note that equals() comparison is used, so only simple values may be checked.

Parameters:

value - the value to check for

Returns:

true if the value exists, or false otherwise

keyOf

public java.lang.String keyOf(java.lang.Object value)

Returns the first dictionary key having the specified value. Note that equals() comparison is used, so only simple values may be checked.

Parameters:

value - the value to check for

Returns:

the dictionary key name, or null if the value wasn't found

keys

public java.lang.String[] keys()

Returns an array with all the defined dictionary key names. The keys are ordered as originally added to this object.

Returns:

an array with all dictionary key names

get

public java.lang.Object get(java.lang.String key)

Returns the dictionary value for the specified key.

Parameters:

key - the dictionary key name

Returns:

the dictionary key value, or null if the key is not defined

get

public java.lang.Object get(java.lang.String key,
                            java.lang.Object defaultValue)

Returns the dictionary value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead.

Parameters:

key - the dictionary key name

defaultValue - the default value

Returns:

the dictionary key value value, or the default value if the key is not defined

getString

public java.lang.String getString(java.lang.String key,
                                  java.lang.String defaultValue)

Returns the dictionary string value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a string, the toString() method will be called.

Parameters:

key - the dictionary key name

defaultValue - the default value

Returns:

the dictionary key value, or the default value if the key is not defined

getBoolean

public boolean getBoolean(java.lang.String key,
                          boolean defaultValue)

Returns the dictionary boolean value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a boolean, any object that does not equal FALSE, "", "false" or 0 will be converted to true.

Parameters:

key - the dictionary key name

defaultValue - the default value

Returns:

the dictionary key value, or the default value if the key is not defined

getInt

public int getInt(java.lang.String key,
                  int defaultValue)
           throws java.lang.NumberFormatException

Returns the dictionary integer value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a number, a conversion of the toString() value of the object will be attempted.

Parameters:

key - the dictionary key name

defaultValue - the default value

Returns:

the dictionary key value, or the default value if the key is not defined

Throws:

java.lang.NumberFormatException - if the value didn't contain a valid integer

getDate

public java.util.Date getDate(java.lang.String key,
                              java.util.Date defaultValue)
                       throws java.lang.NumberFormatException

Returns the dictionary date value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a date, a numeric conversion of the string value (excluding any '@' prefix) will be attempted.

Parameters:

key - the dictionary key name

defaultValue - the default value

Returns:

the dictionary key value, or the default value if the key is not defined

Throws:

java.lang.NumberFormatException - if the value didn't contain a valid date, number or numeric string

getDict

public Dict getDict(java.lang.String key)
             throws java.lang.ClassCastException

Returns the dictionary dictionary value for the specified key. If the value is not a dictionary, an exception will be thrown.

Parameters:

key - the dictionary key name

Returns:

the dictionary key value, or null if the key is not defined

Throws:

java.lang.ClassCastException - if the value is not a dictionary

getArray

public Array getArray(java.lang.String key)
               throws java.lang.ClassCastException

Returns the dictionary array value for the specified key. If the value is not an array, an exception will be thrown.

Parameters:

key - the dictionary key name

Returns:

the dictionary key value, or null if the key is not defined

Throws:

java.lang.ClassCastException - if the value is not an array

set

public void set(java.lang.String key,
                java.lang.Object value)
         throws java.lang.NullPointerException,
                java.lang.UnsupportedOperationException

Modifies or defines the dictionary value for the specified key.

Parameters:

key - the dictionary key name

value - the value to set

Throws:

java.lang.NullPointerException - if the key is null or an empty string

java.lang.UnsupportedOperationException - if this object has been sealed

setBoolean

public void setBoolean(java.lang.String key,
                       boolean value)
                throws java.lang.NullPointerException,
                       java.lang.UnsupportedOperationException

Modifies or defines the boolean dictionary value for the specified key.

Parameters:

key - the dictionary key name

value - the value to set

Throws:

java.lang.NullPointerException - if the key is null or an empty string

java.lang.UnsupportedOperationException - if this object has been sealed

setInt

public void setInt(java.lang.String key,
                   int value)
            throws java.lang.NullPointerException,
                   java.lang.UnsupportedOperationException

Modifies or defines the integer dictionary value for the specified key.

Parameters:

key - the dictionary key name

value - the value to set

Throws:

java.lang.NullPointerException - if the key is null or an empty string

java.lang.UnsupportedOperationException - if this object has been sealed

setAll

public void setAll(Dict dict)

Modifies or defines all keys from another dictionary. If one of the keys already exists, it will be overwritten with the value from the specified dictionary.

Parameters:

dict - the dictionary to copy from

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed

add

public java.lang.String add(java.lang.String key,
                            java.lang.Object value)
                     throws java.lang.UnsupportedOperationException

Adds a dictionary value using the specified key if possible. If the key is already in use, a new unique key will be generated instead. This will ensure that an existing value will not be overwritten.

Parameters:

key - the suggested dictionary key name

value - the value to set

Returns:

the dictionary key name used

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed

addBoolean

public java.lang.String addBoolean(java.lang.String key,
                                   boolean value)
                            throws java.lang.UnsupportedOperationException

Adds a boolean property value using the specified key if possible. If the key is already in use, a new unique key will be generated instead. This will ensure that an existing value will not be overwritten.

Parameters:

key - the suggested dictionary key name

value - the value to set

Returns:

the dictionary key name used

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed

addInt

public java.lang.String addInt(java.lang.String key,
                               int value)
                        throws java.lang.UnsupportedOperationException

Adds an integer property value using the specified key if possible. If the key is already in use, a new unique key will be generated instead. This will ensure that an existing value will not be overwritten.

Parameters:

key - the suggested dictionary key name

value - the value to set

Returns:

the dictionary key name used

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed

addAll

public void addAll(Dict dict)

Adds all key-value pairs from another dictionary to this one. If one of the keys are already in use, a new unique key will be generated instead. This will ensure that existing values will not be overwritten.

Parameters:

dict - the dictionary to add from

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed

remove

public void remove(java.lang.String key)
            throws java.lang.UnsupportedOperationException

Deletes the specified dictionary key and its value.

Parameters:

key - the dictionary key name

Throws:

java.lang.UnsupportedOperationException - if this object has been sealed