com.ozdevworx.dtype.impl
Class KeyedList

java.lang.Object
  extended by com.ozdevworx.dtype.impl.KeyedList
All Implemented Interfaces:
DataHandler

public class KeyedList
extends java.lang.Object
implements DataHandler

A List based array. Access DataHandlers Data via a String label or a numeric index.
A DataHandler is an Object itself so support for multidimensional DataHandler Objects is generic to this implementation.

This DataHandler implementation uses synchronisation as specified by the DataHandler interface.

The core abstract implementation for this DataHandler implementation is ArrayList.
We are using dual synchronised ArrayList's that work in strict unison to maintain data integrity and maximise the flexibility and dynamics in this Data Type.
ArrayList is one of the better performing List implementations. The synchronisation abilities of the ArrayList is handled by this class as ArrayList is not a synchronised Object by default.

Version:
1.0.0.7
Author:
Tim Gall (Oz-DevWorX)

Field Summary
static java.lang.String VERSION
          static version number of this class
 
Constructor Summary
KeyedList()
          Create a case sensitive DataHandler of initial capacity 10.
Initial capacity is 10 with an expansion rate of 10 when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
length() returns the actual size and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.
KeyedList(boolean lowerCaseKeys)
          Create a case insensitive DataHandler of initial capacity incSize.
Initial capacity is 10 with an expansion rate of 10 when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.
KeyedList(int incSize)
          Create a case sensitive DataHandler of initial capacity incSize.
Initial capacity is incSize with an expansion rate of incSize when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.
KeyedList(int incSize, boolean lowerCaseKeys)
          Create a case insensitive DataHandler of initial capacity incSize.
Initial capacity is incSize with an expansion rate of incSize when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.
 
Method Summary
 void addData(java.lang.String n, java.lang.Object d)
          Adds Elements to this DataHandler Object.
If the key is null or the equivalent of, the Element will not be added to this DataHandler.

NOTE:
Use setData(String n, Object d) to modify existing data by key
or setData(int i, Object d) to modify existing data by index.
 void clearData()
          Resets this DataHandler.
 int countMatches(java.lang.String n)
          Counts the Elements with key names matching name n in this DataHandler.
protected  java.lang.String fixCase(java.lang.String n)
          Correct the CaSe for DataHandler keys.
NOTE: we use Locale.ENGLISH as recommended by the java.util.Locale documentation to preserve the programatic sense of the keys name.
 java.lang.Object getData(int i)
          Alias function for getObject(int i)
 java.lang.Object getData(java.lang.String n)
          Alias function for getObject(String n)
 double getDouble(int i)
          Get the value at index i as a Double or throw an error if the data is not valid for this java Type.
 double getDouble(java.lang.String n)
          Get the value at name n as a Double or throw an error if the data is not valid for this java Type.
 float getFloat(int i)
          Get the value at index i as a Float or throw an error if the data is not valid for this java Type.
 float getFloat(java.lang.String n)
          Get the value at name n as a Float or throw an error if the data is not valid for this java Type.
 int getIndex(java.lang.String n)
          Get a keys index in this set from its name String
 int getIndexByElement(java.lang.String key, java.lang.String data)
           
 int[] getIndexes(java.lang.String n)
          Get all key indexes in this set from a key name String.
 int getInt(int i)
          Get the value at index i as an Integer or throw an error if the data is not valid for this java Type.
 int getInt(java.lang.String n)
          Get the value at name n as an Integer or throw an error if the data is not valid for this java Type.
protected  java.lang.Object getItem(int i, boolean notNull)
          Gets Elements from any List implementation based on the Elements index i.
Allows missing keys and missing indexes to be handled gracefully and discreetly.
 java.lang.String getKey(int i)
          Get the keys name at index i.
 long getLong(int i)
          Get the value at index i as a Long or throw an error if the data is not valid for this java Type.
 long getLong(java.lang.String n)
          Get the value at name n as a Long or throw an error if the data is not valid for this java Type.
 java.lang.Object getObject(int i)
          Get the Object at column index i.
 java.lang.Object getObject(java.lang.String n)
          Get the Object at column name n.
 java.lang.Object getObjectByElement(java.lang.String key, java.lang.String data)
           
 java.lang.Short getShort(int i)
          Get the value at index i as a Short or throw an error if the data is not valid for this java Type.
 java.lang.Short getShort(java.lang.String n)
          Get the value at name n as a Short or throw an error if the data is not valid for this java Type.
 java.lang.String getString(int i)
          Get the Object at column index i as a String.
 java.lang.String getString(java.lang.String n)
          Get the Object at column name n as a String.
 boolean hasData(java.lang.String value)
          Does this data exist in the set?
The usefulness of this function is questionable.
 boolean hasElement(java.lang.String key, java.lang.String data)
          Does this DataHandler Element exist in the set?
 boolean hasKey(int index)
          Does this key exist in the set?
 boolean hasKey(java.lang.String value)
          Does this key exist in the set?
 boolean isEmpty()
          Determines if this DataHandler contains Elements.
 int length()
          Count all Elements in this DataHandler.
 void removeByIndex(int i)
          Removes the Element at index and shrinks this DataHandler so that Element index+1 will be positioned at index after the original Element at index is removed.
 void removeByKey(java.lang.String n)
          Removes the Element at name n and shrinks this DataHandler by one Element.
 void setData(int i, java.lang.Object d)
          Update the Element at index i with data d.
No action is taken if index i is greater than this DataHandlers size.
 void setData(int index, java.lang.String newKey, java.lang.Object newObj)
          Update the Element at index with a new key and new data.
No action is taken if index is greater than this DataHandlers size.
 void setData(java.lang.String n, java.lang.Object d)
          Update the Element at name n with data d or add a new Element if key name n doesnt exist.

USE:
addData(String n, Object d) to add new data or data with duplicate keys to this DataHandler.
 void setData(java.lang.String key, java.lang.String newKey, java.lang.Object newObj)
          Update the Element at name key with a new key and new data or add a new Element if name key doesnt exist.

NOTE:
Use addData(String n, Object d) to add new data or data with duplicate keys to this DataHandler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final java.lang.String VERSION
static version number of this class

See Also:
Constant Field Values
Constructor Detail

KeyedList

public KeyedList()
Create a case sensitive DataHandler of initial capacity 10.
Initial capacity is 10 with an expansion rate of 10 when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
length() returns the actual size and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.


KeyedList

public KeyedList(boolean lowerCaseKeys)
Create a case insensitive DataHandler of initial capacity incSize.
Initial capacity is 10 with an expansion rate of 10 when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.

Parameters:
lowerCaseKeys - boolean. If true, keys all use lower case, if false keys all use upper case.

KeyedList

public KeyedList(int incSize)
Create a case sensitive DataHandler of initial capacity incSize.
Initial capacity is incSize with an expansion rate of incSize when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.

Parameters:
incSize - int. This value affects the initial size and the expansion rate when the DataHandler is growing.

KeyedList

public KeyedList(int incSize,
                 boolean lowerCaseKeys)
Create a case insensitive DataHandler of initial capacity incSize.
Initial capacity is incSize with an expansion rate of incSize when the DataHandler is growing.
Empty place holders are ignored when manipulating and querying data.

EG:
getSize() returns the actual Element count and does not include placeholders related to this DataHandlers growth rate.
isEmpty() does not count placeholders, only actual Elements that were added to the DataHandler.
etc.

Parameters:
incSize - int. This value affects the initial size and the expansion rate when the DataHandler is growing.
lowerCaseKeys - boolean. If true, keys all use lower case, if false keys all use upper case.
Method Detail

addData

public void addData(java.lang.String n,
                    java.lang.Object d)
Description copied from interface: DataHandler
Adds Elements to this DataHandler Object.
If the key is null or the equivalent of, the Element will not be added to this DataHandler.

NOTE:
Use setData(String n, Object d) to modify existing data by key
or setData(int i, Object d) to modify existing data by index.

Specified by:
addData in interface DataHandler
Parameters:
n - String - key name
d - Object - data to add to this DataHandler.
See Also:
DataHandler.addData(java.lang.String, java.lang.Object)

clearData

public void clearData()
Description copied from interface: DataHandler
Resets this DataHandler.

Specified by:
clearData in interface DataHandler
See Also:
DataHandler.clearData()

countMatches

public int countMatches(java.lang.String n)
Description copied from interface: DataHandler
Counts the Elements with key names matching name n in this DataHandler.

Specified by:
countMatches in interface DataHandler
Parameters:
n - The keys name to seek
Returns:
the number of matching keys in this DataHandler
See Also:
DataHandler.countMatches(java.lang.String)

getData

public java.lang.Object getData(int i)
Description copied from interface: DataHandler
Alias function for getObject(int i)

Specified by:
getData in interface DataHandler
Parameters:
i - int - keys index
Returns:
a data Object based on its key index i
See Also:
DataHandler.getData(int)

getData

public java.lang.Object getData(java.lang.String n)
Description copied from interface: DataHandler
Alias function for getObject(String n)

Specified by:
getData in interface DataHandler
Parameters:
n - String - key name
Returns:
a data Object based on its keys name n
See Also:
DataHandler.getData(java.lang.String)

getDouble

public double getDouble(int i)
                 throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at index i as a Double or throw an error if the data is not valid for this java Type.

Specified by:
getDouble in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Double value located at column index i.
Throws:
IlegalNumberTypeException - if value at i is not a Double.
See Also:
DataHandler.getDouble(int)

getDouble

public double getDouble(java.lang.String n)
                 throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at name n as a Double or throw an error if the data is not valid for this java Type.

Specified by:
getDouble in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Double value located at column name n.
Throws:
IlegalNumberTypeException - if value at n is not a Double.
See Also:
DataHandler.getDouble(java.lang.String)

getFloat

public float getFloat(int i)
               throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at index i as a Float or throw an error if the data is not valid for this java Type.

Specified by:
getFloat in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Float value located at column i.
Throws:
IlegalNumberTypeException - if value at i is not a Float.
See Also:
DataHandler.getFloat(int)

getFloat

public float getFloat(java.lang.String n)
               throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at name n as a Float or throw an error if the data is not valid for this java Type.

Specified by:
getFloat in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Float value located at column name n.
Throws:
IlegalNumberTypeException - if value at n is not a Float.
See Also:
DataHandler.getFloat(java.lang.String)

getIndex

public int getIndex(java.lang.String n)
Description copied from interface: DataHandler
Get a keys index in this set from its name String

Specified by:
getIndex in interface DataHandler
Parameters:
n - String - keys name
Returns:
The keys index.
See Also:
DataHandler.getIndex(java.lang.String)

getIndexByElement

public int getIndexByElement(java.lang.String key,
                             java.lang.String data)
Specified by:
getIndexByElement in interface DataHandler
Parameters:
key - The keys name to locate
data - The data to find a match for
Returns:
The Objects index at key location (or -1 if none found)
See Also:
DataHandler.getIndexByElement(java.lang.String, java.lang.String)

getIndexes

public int[] getIndexes(java.lang.String n)
Description copied from interface: DataHandler
Get all key indexes in this set from a key name String.

Specified by:
getIndexes in interface DataHandler
Parameters:
n - String - key name
Returns:
int[] with the matching key-indexes in this DataHandler matching n (keyName)
See Also:
DataHandler.getIndexes(java.lang.String)

getInt

public int getInt(int i)
           throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at index i as an Integer or throw an error if the data is not valid for this java Type.

Specified by:
getInt in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Integer value located at column index i.
Throws:
IlegalNumberTypeException - if value at i is not an Integer.
See Also:
DataHandler.getInt(int)

getInt

public int getInt(java.lang.String n)
           throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at name n as an Integer or throw an error if the data is not valid for this java Type.

Specified by:
getInt in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Integer value located at column name n.
Throws:
IlegalNumberTypeException - if value at n is not an Integer.
See Also:
DataHandler.getInt(java.lang.String)

getKey

public java.lang.String getKey(int i)
Description copied from interface: DataHandler
Get the keys name at index i.

Specified by:
getKey in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
the keys name
See Also:
DataHandler.getKey(int)

getLong

public long getLong(int i)
             throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at index i as a Long or throw an error if the data is not valid for this java Type.

Specified by:
getLong in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Long value located at column i.
Throws:
IlegalNumberTypeException - if value at i is not a Long.
See Also:
DataHandler.getLong(int)

getLong

public long getLong(java.lang.String n)
             throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at name n as a Long or throw an error if the data is not valid for this java Type.

Specified by:
getLong in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Long value located at column name n.
Throws:
IlegalNumberTypeException - if value at i is not a Long.
See Also:
DataHandler.getLong(java.lang.String)

getObject

public java.lang.Object getObject(int i)
Description copied from interface: DataHandler
Get the Object at column index i.

Specified by:
getObject in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Object located at column i.
See Also:
DataHandler.getObject(int)

getObject

public java.lang.Object getObject(java.lang.String n)
Description copied from interface: DataHandler
Get the Object at column name n.

Specified by:
getObject in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Object located at column name n.
See Also:
DataHandler.getObject(java.lang.String)

getObjectByElement

public java.lang.Object getObjectByElement(java.lang.String key,
                                           java.lang.String data)
Specified by:
getObjectByElement in interface DataHandler
Parameters:
key - The keys name to locate
data - The data to find a match for
Returns:
The data Object at key location (or null if none found)
See Also:
DataHandler.getObjectByElement(java.lang.String, java.lang.String)

getShort

public java.lang.Short getShort(int i)
                         throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at index i as a Short or throw an error if the data is not valid for this java Type.

Specified by:
getShort in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
Short value located at column i.
Throws:
IlegalNumberTypeException - if value at i is not a Short.
See Also:
DataHandler.getShort(int)

getShort

public java.lang.Short getShort(java.lang.String n)
                         throws IlegalNumberTypeException
Description copied from interface: DataHandler
Get the value at name n as a Short or throw an error if the data is not valid for this java Type.

Specified by:
getShort in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
Short value located at column name n.
Throws:
IlegalNumberTypeException - if value at n is not a Short.
See Also:
DataHandler.getShort(java.lang.String)

getString

public java.lang.String getString(int i)
Description copied from interface: DataHandler
Get the Object at column index i as a String.

Specified by:
getString in interface DataHandler
Parameters:
i - The columns index to seek.
Returns:
a data String based on its keys index
See Also:
DataHandler.getString(int)

getString

public java.lang.String getString(java.lang.String n)
Description copied from interface: DataHandler
Get the Object at column name n as a String.

Specified by:
getString in interface DataHandler
Parameters:
n - The columns name to seek.
Returns:
a data String based on its keys name
See Also:
DataHandler.getString(java.lang.String)

hasData

public boolean hasData(java.lang.String value)
Description copied from interface: DataHandler
Does this data exist in the set?
The usefulness of this function is questionable.

Specified by:
hasData in interface DataHandler
Parameters:
value - data to search the set for.
Returns:
true if the data is found, else false.
See Also:
DataHandler.hasData(java.lang.String)

hasElement

public boolean hasElement(java.lang.String key,
                          java.lang.String data)
Description copied from interface: DataHandler
Does this DataHandler Element exist in the set?

Specified by:
hasElement in interface DataHandler
Parameters:
key - The Elements key String
data - The Elements data Object as a String
Returns:
true if this Element is found, else false.
See Also:
DataHandler.hasElement(java.lang.String, java.lang.String)

hasKey

public boolean hasKey(int index)
Description copied from interface: DataHandler
Does this key exist in the set?

Specified by:
hasKey in interface DataHandler
Parameters:
index - key index to search the set for.
Returns:
true if the key is found, else false.
See Also:
DataHandler.hasKey(int)

hasKey

public boolean hasKey(java.lang.String value)
Description copied from interface: DataHandler
Does this key exist in the set?

Specified by:
hasKey in interface DataHandler
Parameters:
value - key to search the set for.
Returns:
true if the key is found, else false.
See Also:
DataHandler.hasKey(java.lang.String)

isEmpty

public boolean isEmpty()
Description copied from interface: DataHandler
Determines if this DataHandler contains Elements.

Specified by:
isEmpty in interface DataHandler
Returns:
true if this DataHandler does not contain Elements else returns false
See Also:
DataHandler.isEmpty()

length

public int length()
Description copied from interface: DataHandler
Count all Elements in this DataHandler.

Specified by:
length in interface DataHandler
Returns:
the size of this DataHandler
See Also:
DataHandler.length()

removeByIndex

public void removeByIndex(int i)
Description copied from interface: DataHandler
Removes the Element at index and shrinks this DataHandler so that Element index+1 will be positioned at index after the original Element at index is removed.

Specified by:
removeByIndex in interface DataHandler
Parameters:
i - Element index to remove from this DataHandler.
See Also:
DataHandler.removeByIndex(int)

removeByKey

public void removeByKey(java.lang.String n)
Description copied from interface: DataHandler
Removes the Element at name n and shrinks this DataHandler by one Element.

Specified by:
removeByKey in interface DataHandler
Parameters:
n - Elements name to remove from this DataHandler.
See Also:
DataHandler.removeByKey(java.lang.String)

setData

public void setData(int i,
                    java.lang.Object d)
Description copied from interface: DataHandler
Update the Element at index i with data d.
No action is taken if index i is greater than this DataHandlers size.

Specified by:
setData in interface DataHandler
Parameters:
i - The Elements index.
d - the Data to update index i with.
See Also:
DataHandler.setData(int, java.lang.Object)

setData

public void setData(int index,
                    java.lang.String newKey,
                    java.lang.Object newObj)
Description copied from interface: DataHandler
Update the Element at index with a new key and new data.
No action is taken if index is greater than this DataHandlers size.

Specified by:
setData in interface DataHandler
Parameters:
index - The Element at index we want to update.
newKey - the new key for the Element.
newObj - the Data to update the Element with.
See Also:
DataHandler.setData(int, java.lang.String, java.lang.Object)

setData

public void setData(java.lang.String n,
                    java.lang.Object d)
Description copied from interface: DataHandler
Update the Element at name n with data d or add a new Element if key name n doesnt exist.

USE:
addData(String n, Object d) to add new data or data with duplicate keys to this DataHandler.

Specified by:
setData in interface DataHandler
Parameters:
n - The Elements name.
d - the Data to update/add to this DataHandler.
See Also:
DataHandler.setData(java.lang.String, java.lang.Object)

setData

public void setData(java.lang.String key,
                    java.lang.String newKey,
                    java.lang.Object newObj)
Description copied from interface: DataHandler
Update the Element at name key with a new key and new data or add a new Element if name key doesnt exist.

NOTE:
Use addData(String n, Object d) to add new data or data with duplicate keys to this DataHandler.

Specified by:
setData in interface DataHandler
Parameters:
key - The first Element with name matching key.
newKey - the new key for the Element.
newObj - the Data to update the Element with.
See Also:
DataHandler.setData(java.lang.String, java.lang.String, java.lang.Object)

fixCase

protected java.lang.String fixCase(java.lang.String n)
Correct the CaSe for DataHandler keys.
NOTE: we use Locale.ENGLISH as recommended by the java.util.Locale documentation to preserve the programatic sense of the keys name. Particularly String wrappers and special characters.

Parameters:
n - A DataHandler key of unknown character CaSe.
Returns:
A key matching our Database case restrictions (if any).

getItem

protected java.lang.Object getItem(int i,
                                   boolean notNull)
Gets Elements from any List implementation based on the Elements index i.
Allows missing keys and missing indexes to be handled gracefully and discreetly.

Parameters:
i - int - List-index
notNull - - boolean
Returns:
Object or empty-string if no index in list