xbn.array.primitive
Class PrimitiveArray

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.util.XBNLocked
              |
              +--xbn.array.primitive.PrimitiveArray

Direct Known Subclasses:

PrimitiveArrayChar, PrimitiveArrayInt, PrimitiveArrayString

public abstract class PrimitiveArray

extends XBNLocked

Wraps around anything to make it appear like an array of primitives (including Strings).

Source code: PrimitiveArray.java.

Note that this class extends XBNLocked, and not XBNObject. This is in anticipation of many extending classes needing to optionally protect/un-protect access to the thing that is being wrapped.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

protected

PrimitiveArray(String s_fqClassName, PrimitiveArrayRule pa_rule) Create a PrimitiveArray.

Method Summary

boolean	areLmntsEqual(int i_idx1, int i_idx2) Are the two elements equal?
abstract boolean	areLmntsEqual(int i_idxThis, PrimitiveArray pa_other, int i_idxOther) Are the two elements equal?
void	crashIfBad() If the char array is not legal, then an AssertException should be thrown with a descriptive error message.
void	crashIfBad(String s_callingClsFnc, String s_varName) If the char array is not legal, then an AssertException should be thrown with a descriptive error message.
protected void	declareNoViolation() Declare that this PrimitiveArray and its contents are truly valid.
String	getFQClassName() What is the fully qualified class name of this PrimitiveArray?
abstract int	getLength() How many items exist in this PrimitiveArray?
String	getList() Get a listing of every item in this Primitive array.
String	getList(String s_divider) Get a listing of every item in this Primitive array.
String	getList(String s_prefix, String s_postfix) Get a listing of every item in this Primitive array.
String	getList(String s_prefix, String s_divider, String s_postfix) Get a listing of every item in this Primitive array.
SOBString[]	getNewAOSOBString() Get a new array of SOBStrings.
SOBStringBuffer[]	getNewAOSOBStringBuffer() Get a new array of SOBStringBuffers.
String[]	getNewAOString() Get a new array of strings, based upon all strings existing (via getString) in this PrimitiveArrayString.
PAViolation	getPAViolation()
PrimitiveArrayRule	getPrimitiveArrayRule() Get the PrimitiveArrayRule for direct manipulation.
SOBString	getSOBString(int i_dx) Get the element at the requested array index, as an SOBString.
SOBStringBuffer	getSOBStringBuffer(int i_dx) Get the element at the requested array index, as an SOBStringBuffer.
abstract String	getString(int i_dx) Get the element at the requested array index, as a string.
abstract boolean	isNull() Is the [thing being wrapped by this PrimitiveArray] null?
abstract boolean	isNull(int i_dx) Is the [thing] at the requested array index null?
boolean	isValid() Is the array legal, according to the PrimitiveArrayRule?
abstract boolean	isValid(String s_callingClsFnc, String s_varName) Is the array legal, according to the PrimitiveArrayRule?
protected void	setPAViolation(PAViolation pa_violation)
protected void	throwAXIllegal(String s_callingClsFnc, String s_varName, String s_currently) To be used by implementations of isValid.
protected void	throwLmntsEqualAioobx(int i_idxThis, String s_paOtherName, PrimitiveArray pa_other, int i_idxOther) To be used by implementations of areLmntsEqual.
boolean	wasValidated() Was the array deemed valid?

Methods inherited from class xbn.util.XBNLocked

throwLX, throwLX, throwLXIfLocked, throwLXIfLocked, throwLXIfLocked, throwLXIfUnlocked

Methods inherited from class xbn.XBNObject

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

Methods inherited from class java.lang.Object

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

Constructor Detail

PrimitiveArray

protected PrimitiveArray(String s_fqClassName,
                         PrimitiveArrayRule pa_rule)

Create a PrimitiveArray.

Parameters:

s_fqClassName - The fully qualified name of the class extending this one. This is used when the default crashIfBad function is used.

pa_rule - The definition of the rule that the array-wrapped-by-this-PrimitiveArray must follow. May not be null.

Method Detail

getPrimitiveArrayRule

public final PrimitiveArrayRule getPrimitiveArrayRule()

Get the PrimitiveArrayRule for direct manipulation.

Returns:

pa_rule Exactly as provided to constructor.

getString

public abstract String getString(int i_dx)

Get the element at the requested array index, as a string.

Parameters:

i_dx - The array index. Must range 0..[getLength() - 1], inclusive.

AssertException - If isNull equals true.

getSOBString

public SOBString getSOBString(int i_dx)

Get the element at the requested array index, as an SOBString.

Returns:

(new SOBString(getString(i_dx)))

getSOBStringBuffer

public SOBStringBuffer getSOBStringBuffer(int i_dx)

Get the element at the requested array index, as an SOBStringBuffer.

Returns:

(new SOBStringBuffer(getString(i_dx)))

getLength

public abstract int getLength()

How many items exist in this PrimitiveArray?

Throws:

AssertException - If isNull equals true.

getFQClassName

public final String getFQClassName()

What is the fully qualified class name of this PrimitiveArray?

Returns:

s_fqClassName Exactly as provided to the constructor.

isNull

public abstract boolean isNull()

Is the [thing being wrapped by this PrimitiveArray] null?

isNull

public abstract boolean isNull(int i_dx)

Is the [thing] at the requested array index null?

Parameters:

i_dx - The array index. Must range 0..[getLength() - 1], inclusive

AssertException - If isNull equals true.

areLmntsEqual

public final boolean areLmntsEqual(int i_idx1,
                                   int i_idx2)

Are the two elements equal?

Returns:

areLmntsEqual(i_idx1, this, i_idx2)

areLmntsEqual

public abstract boolean areLmntsEqual(int i_idxThis,
                                      PrimitiveArray pa_other,
                                      int i_idxOther)

Are the two elements equal?

Parameters:

i_idxThis - The array index. Must range 0..[getLength() - 1], inclusive

pa_other - The PrimitiveArray to retrieve element i_idxOther from. May not be null.

i_idxOther - The array index of the desired element in pa_other. Must be valid for pa_other.

isValid

public final boolean isValid()

Is the array legal, according to the PrimitiveArrayRule?

Returns:

isValid(null, null)

isValid

public abstract boolean isValid(String s_callingClsFnc,
                                String s_varName)

Is the array legal, according to the PrimitiveArrayRule?

Parameters:

s_callingClsFnc - The name of the class-plus-function, only for use in the potential error message. When either this and/or s_varName are non-null, an AssertException is thrown when the array is deemed invalid. When both parameters are null, false is returned when the array is invalid.

s_varName - The name of the array variable, only for use in the potential error message.

Returns:

true When the array is completely valid. Note: The moment this function returns true, wasValidated equals true.
false When the array is invalid, and both s_callingClsFnc and s_varName are null.

declareNoViolation

protected final void declareNoViolation()

Declare that this PrimitiveArray and its contents are truly valid.

Right before your version of isValid returns true, be sure to also call this function. See isValid.

This causes wasValidated to return true. There is no way to undo this without recreating the object.

Be careful when calling this function directly. You can call this function manually, but if the [thing being wrapped to look like an array] is not valid, you will get unpredictable results when using this class or its functions. Moral: Don't call this function unless you know what you're doing.

Equal to setPAViolation(new PAViolation())

setPAViolation

protected final void setPAViolation(PAViolation pa_violation)

getPAViolation

public final PAViolation getPAViolation()

wasValidated

public final boolean wasValidated()

Was the array deemed valid?

Returns:

(getPAViolation() != null && getPAViolation().hasNoViolation())

crashIfBad

public final void crashIfBad()

If the char array is not legal, then an AssertException should be thrown with a descriptive error message. Otherwise, do nothing.

Equal to crashIfBad(getFQClassName() + ".crashIfBad", "[the object wrapped by this PrimitiveArray]")

crashIfBad

public final void crashIfBad(String s_callingClsFnc,
                             String s_varName)

If the char array is not legal, then an AssertException should be thrown with a descriptive error message. Otherwise, do nothing.

Equal to isValid(s_callingClsFnc, s_varName)

Before isValid is called, it is verified that both parameters are non-null, and at least one character in length.

getNewAOString

public final String[] getNewAOString()

Get a new array of strings, based upon all strings existing (via getString) in this PrimitiveArrayString. See getString

Returns:

null If isNull is true.
An array of strings where each element is equal to getString([ARRAY_INDEX])

getNewAOSOBString

public final SOBString[] getNewAOSOBString()

Get a new array of SOBStrings. See getSOBString

Returns:

null If isNull is true.
An array of SOBStrings where each element is equal to getSOBString([ARRAY_INDEX])

getNewAOSOBStringBuffer

public final SOBStringBuffer[] getNewAOSOBStringBuffer()

Get a new array of SOBStringBuffers. See getSOBStringBuffer

Returns:

null If isNull is true.
An array of SOBStringBuffers where each element is equal to getSOBStringBuffer([ARRAY_INDEX])

getList

public String getList()

Get a listing of every item in this Primitive array.

Returns:

(new ListPA()).get(this)

getList

public String getList(String s_divider)

Get a listing of every item in this Primitive array.

Returns:

(new ListPA(s_divider)).get(this)

getList

public String getList(String s_prefix,
                      String s_postfix)

Get a listing of every item in this Primitive array.

Returns:

(new ListPA(s_prefix, s_postfix)).get(this)

getList

public String getList(String s_prefix,
                      String s_divider,
                      String s_postfix)

Get a listing of every item in this Primitive array.

Returns:

(new ListPA(s_prefix, s_divider, s_postfix)).get(this)

throwAXIllegal

protected final void throwAXIllegal(String s_callingClsFnc,
                                    String s_varName,
                                    String s_currently)

To be used by implementations of isValid. See isValid.

throwLmntsEqualAioobx

protected final void throwLmntsEqualAioobx(int i_idxThis,
                                           String s_paOtherName,
                                           PrimitiveArray pa_other,
                                           int i_idxOther)

To be used by implementations of areLmntsEqual. See areLmntsEqual.