All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface uhr.core.tron.Flexitron

public interface Flexitron
extends ConvenientStringMap, Replicatable, Cloneable
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.

A Flexitron contains 2 collections - A Hashtable and a Vector. The Vector has Entrys. An Entry has a key and value. The keys and values in the Hashtable are the sameas those in the Vector.

If a duplicate key is detected and isAutoDetectDuplicateKeys() = true, the Flexitron stops maintaining the Hashtable, and the Flexitron is now said to be "entrymental", a term similar to "elemental".

The main features are:

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

Add, remove key values or Entrys.

Get key values or enumerate Entrys. It makes no sense to get an Entry 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 Entrys to just Entrys. 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:
IsEntrysOnly - Default is false. True to maintain Entrys only, false to maintain Entrys 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.

We use the improper spelling of "Entrys", instead of the proper "Entries", for easier mind mapping.

NOTE - Currently we only have add and remove. In the future we may have a replace.

Method Index

o add(String, Object)
Adds the value in the collection and associates it with the key for retrival.
o containsEntry(Entry)
Returns true if the collection contains the Entry, false if not.
o containsKey(String)
Returns true if the collection contains the key, false if not.
o enumerateEntrys()
Returns an enumeration of the Entrys in this collection.
o enumerateKeys()
Returns an enumeration of the keys in this collection.
o get(String)
Returns the value to which the specified key is mapped in this collection.
o getEntryAt(int)
Returns the Entry at the specified index.
o getFlexitron(String)
Returns the value for the key, cast to a Flexitron.
o getKeySeparator()
Returns the nested key separator or null if none in use.
o getSize()
Returns the number of key values or Entrys in the collection, which may be zero.
o getValueAt(int)
Returns the value at the specified index in the Entrys.
o insertBefore(String, Object, String)
Inserts the key and value before the first keyBefore.
o isAutoDetectDuplicateKeys()
Determines whether the collection will automatically switch to isEntrymental() equals true if a duplicate key is added.
o isEmpty()
Returns true if the collection is empty or false if not.
o isEntrymental()
Determines whether the collection has only Entrys (true) or has Entrys and key values.
o isEntrysOnly()
Determines whether only Entrys are maintained.
o isNullValueAllowed()
Determines whether null values are allowed.
o removeAll()
Removes all keys and values from the collection.
o removeEntry(Entry)
Removes the first occurance of the Entry from the collection.
o removeKey(String)
Removes the key and its value.
o setContents(Flexitron)
Sets the entire contents of this Flexitron with the keys and values of the contents, including the configuration of the contents.
o toString()
Returns a comma delimited string of key/values, for example: "[Name=Pantajeli, Age=11]".

Methods

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

Returns:
true if only Entrys are maintained, false if not.
o isAutoDetectDuplicateKeys 
 public abstract boolean isAutoDetectDuplicateKeys()
Determines whether the collection will automatically switch to isEntrymental() equals true 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 isEntrymental 
 public abstract boolean isEntrymental()
Determines whether the collection has only Entrys (true) or has Entrys and key values. A collection that is using only Entrys is said to be "entrymental".

Returns:
true if using only Entrys, false if not.
o setContents 
 public abstract void setContents(Flexitron contents)
Sets the entire contents of this Flexitron with the keys and values of the contents, including the configuration of the contents. This is very handy for popping Flexitron data into a Message.

Parameters:
contents - the entire new contents of this Flexitron.
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 Entry, and the collection is said to be "entrymental".

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 insertBefore 
 public abstract void insertBefore(String key,
                                   Object value,
                                   String keyBefore)
Inserts the key and value before the first keyBefore. The keyBefore must already be in the collection and the key must not already be in the collection.

Parameters:
key - the unique identifier for the value.
value - the Object to associate with the key.
keyBefore - the key to insert the key/value before.
o removeKey 
 public abstract Object removeKey(String key)
Removes the key and its value. This is only for not isEntrymental().

Parameters:
key - the key to remove.
Returns:
the value removed, or null if none or the value was null.
Throws: IllegalStateException
if the collection isEntrymental().
o removeEntry 
 public abstract boolean removeEntry(Entry entry)
Removes the first occurance of the Entry from the collection. Since you may not have the actual Entry 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 isEntrymental().

Parameters:
entry - the Entry to remove.
Returns:
true if the Entry was removed, false if not.
Throws: IllegalStateException
if the collection is not Entrymental.
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 isEntrymental().

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 isEntrymental() or if the nested key is incompatable with the actual contents.
o getFlexitron 
 public abstract Flexitron getFlexitron(String key)
Returns the value for the key, cast to a Flexitron. This is extremely useful in nexted key data structures. It yields more concise code.

Parameters:
key - the key of the value to return.
Returns:
the value for the key or null if none.
Throws: ClassCastException
if the value is not null and not a Flexitron.
o getEntryAt 
 public abstract Entry getEntryAt(int index)
Returns the Entry at the specified index.

Parameters:
index - the index of interest.
Returns:
the Entry at the index.
Throws: ArrayIndexOutOfBoundsException
if invalid index.
o getValueAt 
 public abstract Object getValueAt(int index)
Returns the value at the specified index in the Entrys.

Parameters:
index - the Entry index of interest.
Returns:
the value in the Entry at the index.
Throws: ArrayIndexOutOfBoundsException
if invalid index.
o enumerateKeys 
 public abstract Enumeration enumerateKeys()
Returns an enumeration of the keys in this collection. Do not use if isEntrymental().

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

Returns:
an enumeration of all the Entrys in order.
o getSize 
 public abstract int getSize()
Returns the number of key values or Entrys 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 isEntrymental().

Parameters:
key - the key to test.
Returns:
true if the collection contains the key, false if not.
Throws: IllegalStateException
if isEntrymental();
o containsEntry 
 public abstract boolean containsEntry(Entry entry)
Returns true if the collection contains the Entry, false if not.

Parameters:
entry - the Entry to test.
Returns:
true if the collection contains the entry, 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