xbn.array
Class AOSLookup

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.array.AOSLookup

public class AOSLookup

extends XBNObject

Holds metadata about an array of strings. For easy creation of an AOSLookup, see AOSLCreator.

Source code: AOSLookup.java

Note that the original array of strings is not held in this object. You need to hold it externally.

The objects in an AOSLookup

Take this array of strings: ["aaa", "ccc", "bbb", "bbb", "aaa", "ddd", "ccc", "bbb"]

Unique array of UniqueStrings

The central piece of information in this AOSLookup is the unique array of UniqueStrings (wrapped by a UniqueStringAP):

getString()	getUnqArrIdx()	getInstanceCount()
aaa	0	2
ccc	1	2
bbb	2	3
ddd	3	1

This array contains metadata about each unique string existing in the string array, in the same order as the first instance found. The getUnqArrIdx value is simply the array index of itself (useless here, but read on...).

Absolute array of UniqueStrings

The second object is the absolute array of UniqueStrings (wrapped by a UniqueStringAP), in the same order as the string array, and with the same duplication:

getString()	getUnqArrIdx()	getInstanceCount()
aaa	0	2
ccc	1	2
bbb	2	3
bbb	2	3
aaa	0	2
ddd	3	1
ccc	1	2
bbb	2	3

These UniqueString objects are are not new instances. They are references to the original object, as exists in the unique array of UniqueStrings. It is in this array in which the getUnqArrIdx value becomes useful.

The getInstanceCount value is extra information. It's not critical to AOSLookup.

AOSLHashtable

The final object is an AOSLHashtable. An AOSLHashtable wraps around a Hashtable, where the key is a unique string, and the value is the UniqueString object representing it:

Key (unique string)	Value (UniqueString)
aaa	[aaa, 0, 2]
bbb	[bbb, 2, 3]
ccc	[ccc, 1, 2]
ddd	[ddd, 3, 1]

Again, these UniqueString value objects are references to the original objects, as exist in the unique array of UniqueStrings. Note that the ordering presented here is made up. A Hashtable keeps its ordering behind the scenes.

The benefits of these objects

With these three objects, you can quickly access any piece of information from any other.

From the string value, you can retrieve the unique array index with:

getAOSLHashtable().getUniqueString(__THE_STRING__).getUnqArrIdx()

From the unique array index, you can retrieve the string value:

getUSAPUnique().getUniqueString(__THE_UNQ_ARR_IDX__).getString()

From the absolute array index, you can retrieve the string value...

getUSAPAbsolute().getUniqueString(__THE_ABS_ARR_IDX__).getString()

...or the unique array index:

getUSAPAbsolute().getUniqueString(__THE_ABS_ARR_IDX__).getUnqArrIdx()

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute)
Create an AOSLookup.unique UniqueStringAP, and absolute UniqueStringAP.

AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute, boolean b_listUnqStrs)
Create an AOSLookup.unique UniqueStringAP, absolute UniqueStringAP, and list-unique-string setting.

AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute, boolean b_listUnqStrs, boolean b_validateParams)
Create an AOSLookup.unique UniqueStringAP, absolute UniqueStringAP, and list-unique-string and validate-parameters settings.

Method Summary

void	appendUSLToSB(StringBuffer str_buffer) Append the list of strings to the provided StringBuffer.
void	appendUSLToSB(StringBuffer str_buffer, String s_prefix) Append the list of strings to the provided StringBuffer.
void	appendUSLToSB(StringBuffer str_buffer, String s_prefix, String s_whenNoList) Append the list of strings to the provided StringBuffer.
protected Object	clone() Get a full (deep) copy of this AOSLookup as an Object.
void	crashIfBadInternalObjs() Verifies that all internal objects are correctly formatted, and crashes if they are not.
void	crashIfBadInternalObjs(String s_callingClsFnc) Verifies that all internal objects are correctly formatted, and crashes if they are not.
boolean	doListUnqStrs() Should getUnqStrList and appendUSLToSB print out the list of strings?
AOSLookup	getAOSLClone() Get a full (deep) copy of this AOSLookup.
AOSLHashtable	getAOSLHashtable() Get the AOSLHashtable for direct manipulation.
String	getUnqStrList() Get the list of strings in the original array as a list.
String	getUnqStrList(String s_prefix) Get the list of strings in the original array as a list.
String	getUnqStrList(String s_prefix, String s_whenNoList) Get the list of strings in the original array as a list.
UniqueStringAP	getUSAPAbsolute() Get the absolute UniqueStringAP for direct manipulation.
UniqueStringAP	getUSAPUnique() Get the unique UniqueStringAP for direct manipulation.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

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

Constructor Detail

AOSLookup

public AOSLookup(AOSLHashtable aosl_hashtable,
                 UniqueStringAP usap_unique,
                 UniqueStringAP usap_absolute)

Create an AOSLookup.unique UniqueStringAP, and absolute UniqueStringAP.

Equal to AOSLookup(aosl_hashtable, usap_unique, usap_absolute, b_listUnqStrs, true)

AOSLookup

public AOSLookup(AOSLHashtable aosl_hashtable,
                 UniqueStringAP usap_unique,
                 UniqueStringAP usap_absolute,
                 boolean b_listUnqStrs)

Create an AOSLookup.unique UniqueStringAP, absolute UniqueStringAP, and list-unique-string setting.

Equal to AOSLookup(aosl_hashtable, usap_unique, usap_absolute, b_listUnqStrs, b_validateParams, true)

AOSLookup

public AOSLookup(AOSLHashtable aosl_hashtable,
                 UniqueStringAP usap_unique,
                 UniqueStringAP usap_absolute,
                 boolean b_listUnqStrs,
                 boolean b_validateParams)

Create an AOSLookup.unique UniqueStringAP, absolute UniqueStringAP, and list-unique-string and validate-parameters settings.

Parameters:

aosl_hashtable - The AOSLHashtable. May not be null.

usap_unique - The UniqueStringAP representing the unique strings in the string array. May not be null, each element must be non-null.

usap_absolute - The UniqueStringAP representing the absolute strings in the string array. May not be null, and no element may be null.

b_listUnqStrs - Should getUnqStrList and appendUSLToSB actually list the strings (absolutely), or should you get a "strings not listed" message?

b_validateParams - .................

Method Detail

getAOSLHashtable

public final AOSLHashtable getAOSLHashtable()

Get the AOSLHashtable for direct manipulation.

Returns:

aosl_hashtable Exactly as provided to the constructor

getUSAPUnique

public final UniqueStringAP getUSAPUnique()

Get the unique UniqueStringAP for direct manipulation.

See the section regarding this object in the overall documentation.

Returns:

usap_unique Exactly as provided to the constructor

getUSAPAbsolute

public final UniqueStringAP getUSAPAbsolute()

Get the absolute UniqueStringAP for direct manipulation.

See the section regarding this object in the overall documentation.

Returns:

usap_absolute Exactly as provided to the constructor

doListUnqStrs

public final boolean doListUnqStrs()

Should getUnqStrList and appendUSLToSB print out the list of strings?

Returns:

b_listUnqStrs Exactly as provided to the constructor

getUnqStrList

public final String getUnqStrList()

Get the list of strings in the original array as a list.

Returns:

getUnqStrList("")

getUnqStrList

public final String getUnqStrList(String s_prefix)

Get the list of strings in the original array as a list.

Returns:

getUnqStrList(s_prefix, "")

getUnqStrList

public final String getUnqStrList(String s_prefix,
                                  String s_whenNoList)

Get the list of strings in the original array as a list.

Returns:

The resulting value contained in the StringBuffer, after calling appendUSLToSB((new StringBuffer("")), s_prefix, "")

appendUSLToSB

public final void appendUSLToSB(StringBuffer str_buffer)

Append the list of strings to the provided StringBuffer.

Equal to appendUSLToSB(str_buffer, "")

appendUSLToSB

public final void appendUSLToSB(StringBuffer str_buffer,
                                String s_prefix)

Append the list of strings to the provided StringBuffer.

Equal to appendUSLToSB(str_buffer, s_prefix, "")

appendUSLToSB

public final void appendUSLToSB(StringBuffer str_buffer,
                                String s_prefix,
                                String s_whenNoList)

Append the list of strings to the provided StringBuffer.

Parameters:

s_prefix - What should be first appended to str_buffer, regardless of the doListUnqStrs setting. If null, no prefix is desired.

s_whenNoList - If doListUnqStrs equals false, then this is the string appended to str_buffer (after s_prefix).

crashIfBadInternalObjs

public final void crashIfBadInternalObjs()

Verifies that all internal objects are correctly formatted, and crashes if they are not.

Equal to crashIfBadInternalObjs("crashIfBadInternalObjs")

crashIfBadInternalObjs

public final void crashIfBadInternalObjs(String s_callingClsFnc)

Verifies that all internal objects are correctly formatted, and crashes if they are not.

This class verifies that ..............

Parameters:

s_callingClsFnc - The class-plus-function name from which potential error messages should appear like they're coming from.

getAOSLClone

public final AOSLookup getAOSLClone()

Get a full (deep) copy of this AOSLookup.

Returns:

(AOSLookup)clone()

clone

protected Object clone()
                throws CloneNotSupportedException

Get a full (deep) copy of this AOSLookup as an Object.

Overrides:

clone in class Object