All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface uhr.core.tron.Flexitron

public interface Flexitron
extends ConvenientStringMap
This interface defines a flexible datatron that can meet a vast variety of needs. It's designed to be configured by a wrapper interface so that clients can merely use new Wrapper(). It's intended use is for receiving a parsed XML document, and for general all purpose use. We hope it will be used for many inter-part data structure needs, giving us all consistency and reuse.

By nesting Flexitrons one can build a tree datastructure.

The main features are:

Keyed and Elements, or just Elements. If keyed then the usual collection of key values is maintained. If Elements then a collection of Elements is maintained. Each Element has a key and value.

Add, remove key values or Elements.

Get key values or enumerate Elements. It makes no sense to get an Element by key due to duplicate keys.

Automatic detection of duplicate keys. When a duplicate key is added, the Flexitron automatically switches from key values and Elements to just Elements. This simplifies parsing a document into a data structure.

Key paths may be used to get values if Keyed. The key separator is configurable.

Many convenience methods for dealing with primitives.

Configurable for a variety of uses.

Configuration is done in the implementation constructor. This prevents the client from fiddling with configuration, and makes the implementaiton easier because it can assume no further configuration is allowed once created. Wrappers extend Flexitron and the Wrapper constructor configures the Flexitron. The configurable properties are:
IsElementalOnly - Default is false. True to maintain elements only, false to maintain elements and keyed values.

IsAutoDetectDuplicateKeys - Default is false, which means they are not allowed.

IsNullValuesAllowed - Default if false.

KeySeparator - Default is null, no tree.

The default configuration is just like a Hashtable except that we use add instead of put, and overwrites are not allowed. To do an overwrite, first remove the existing key.

Method Index

o add(String, Object)
Adds the value in the collection and associates it with the key for retrival.
o containsElement(Element)
Returns true if the collection contains the element, false if not.
o containsKey(String)
Returns true if the collection contains the key, false if not.
o get(String)
Returns the value to which the specified key is mapped in this collection.
o getElements()
Returns an enumeration of the elements in this collection.
o getKeys()
Returns an enumeration of the keys in this collection.
o getKeySeparator()
Returns the nested key separator or null if none in use.
o getSize()
Returns the number of key values or elements in the collection, which may be zero.
o isAutoDetectDuplicateKeys()
Determines whether the collection will automatically switch to isElemental() if a duplicate key is added.
o isElemental()
Determines whether the collection has Elements or key values.
o isElementalOnly()
Determines whether if only elements are maintained.
o isEmpty()
Returns true if the collection is empty or false if not.
o isNullValueAllowed()
Determines whether null values are allowed.
o removeAll()
Removes all keys and values from the collection.
o removeElement(Element)
Removes the first occurance of the element from the collection.
o removeKey(String)
Removes the key and its value.
o toString()
Returns a comma delimited string of key/values, for example: "[Name=Pantajeli, Age=11]".

Methods

o isElementalOnly 
 public abstract boolean isElementalOnly()
Determines whether if only elements are maintained. The default is false. True is the same as the collection behaving like a Vector. False allows maintaining keyed values and the elements.

Returns:
true if only elements are maintained, false if not.
o isAutoDetectDuplicateKeys 
 public abstract boolean isAutoDetectDuplicateKeys()
Determines whether the collection will automatically switch to isElemental() if a duplicate key is added. True allows this to happen, false prevents it and duplicate keys.

Returns:
true if the feature is on, false if off.
o isNullValueAllowed 
 public abstract boolean isNullValueAllowed()
Determines whether null values are allowed. A null can be a perfectly valid data value in some designs, so we support it.

Returns:
true if null values are allowed, false if not.
o getKeySeparator 
 public abstract String getKeySeparator()
Returns the nested key separator or null if none in use. The default is null.

The separator is used for reads with nested keys, such as get("State/County/Georgia.Fulton") where "/" is the separator. We recommend not using "." as the separator to allow the use of more meaningful keys. Naturally we recommend "/" for the separator.

o isElemental 
 public abstract boolean isElemental()
Determines whether the collection has Elements or key values.

Returns:
true if is using Elements, false if using key values.
o add 
 public abstract void add(String key,
                          Object value)
Adds the value in the collection and associates it with the key for retrival. If the key is a duplicate and IsAutoDetectDuplicateKeys is true, then the key and value are put into an Element, and the collection is said to be "elemental".

If the value is a Flexitron then its values can be retreived with a nested key such as "State/County/Georgia.Fulton".

Parameters:
key - the unique identifier for the value.
value - the Object to associate with the key.
Throws: IllegalStateException
if the key is a duplicate and IsAutoDetectDuplicateKeys is false.
Throws: IllegalArgumentException
if the key is null.
o removeKey 
 public abstract Object removeKey(String key)
Removes the key and its value. This is only for not is Elemental.

Parameters:
key - the key to remove.
Returns:
the value removed, or null if none or the value was null.
Throws: IllegalStateException
if the collection is Elemental.
o removeElement 
 public abstract boolean removeElement(Element element)
Removes the first occurance of the element from the collection. Since you may not have the actual element to remove, create a new one with the desired key and value. This is used to match the one to remove. This is only for is Elemental.

Parameters:
element - the element to remove.
Returns:
true if the element was removed, false if not.
Throws: IllegalStateException
if the collection is not Elemental.
o removeAll 
 public abstract void removeAll()
Removes all keys and values from the collection. Has no effect on the configuration.

o get 
 public abstract Object get(String key)
Returns the value to which the specified key is mapped in this collection. Do not use if isElemental().

If a key separator is in use and the separator is present in the key, then the nested key value is returned. Note this assumes that nested keys except the last are Flexitrons. For example the key "State/County/Georgia.Fulton" implies that a Flexitron was added to this collection with the key of "State" and it contained a key of "County" with a Flexitron value that had a key of "Georgia.Fulton" with an arbitrary value, which is what is returned.

Parameters:
key - the key of the value to retrieve.
Returns:
the value for the key, or null if not found or null if the value was null.
Throws: IllegalStateException
if isElemental() or if the nested key is incompatable with the actual contents.
o getKeys 
 public abstract Enumeration getKeys()
Returns an enumeration of the keys in this collection. Do not use if isElemental().

Returns:
an enumeration of all the keys, in order if ordered keys.
Throws: IllegalStateException
if isElemental();
o getElements 
 public abstract Enumeration getElements()
Returns an enumeration of the elements in this collection.

Returns:
an enumeration of all the elements in order.
o getSize 
 public abstract int getSize()
Returns the number of key values or elements in the collection, which may be zero. Note this doesn't include children if a tree.

Returns:
the size of the collection.
o isEmpty 
 public abstract boolean isEmpty()
Returns true if the collection is empty or false if not.

Returns:
true if empty or false if not.
o containsKey 
 public abstract boolean containsKey(String key)
Returns true if the collection contains the key, false if not. Do not use if isElemental().

Parameters:
key - the key to test.
Returns:
true if the collection contains the key, false if not.
Throws: IllegalStateException
if isElemental();
o containsElement 
 public abstract boolean containsElement(Element element)
Returns true if the collection contains the element, false if not.

Parameters:
element - the element to test.
Returns:
true if the collection contains the element, false if not.
o toString 
 public abstract String toString()
Returns a comma delimited string of key/values, for example: "[Name=Pantajeli, Age=11]". If a tree then a tree format is used. Both are designed to be easily readable.

Returns:
the String representation of the collection.
Overrides:
toString in class Object 
All Packages  Class Hierarchy  This Package  Previous  Next  Index