com.jstatcom.model
Class JSCSArray

java.lang.Object
  extended by com.jstatcom.model.AbstractJSCData
      extended by com.jstatcom.model.JSCSArray
All Implemented Interfaces:
JSCData

public final class JSCSArray
extends AbstractJSCData

A wrapper for string arrays that conforms to the JSCData interface.

A JSCSArray is empty, if the stored array is null or has either zero rows or columns. All rows of array values must have the same length.

All array arguments are copied before they are set as values. The original arrays are untouched. In a similar way all get methods return either a copy of a mutable object (like String[][]) or a reference to an immutable object.

Whenever the value of this data object changes, registered JSCDataListeners are notified via a JSCDataEvent. If not otherwise stated, the event objects always contain the values before the change and after the change.

This class is thread-safe. All access to mutable data is synchronized. All events are fired outside the synchronized blocks.

Author:
Markus Kraetzig

Nested Class Summary
static class JSCSArray.Row
          Inner class for storing rows of this array as XML elements.
 
Field Summary
static javolution.xml.XmlFormat<JSCSArray> JSCSArray_XML
          XML format field for (de)serialization.
 
Constructor Summary
JSCSArray(JSCSArray sarray)
          Copy-Constructor.
JSCSArray(java.lang.String name)
          Creates an empty JSCSArray.
JSCSArray(java.lang.String name, java.lang.String... value)
          Creates a JSCSArray from value.
JSCSArray(java.lang.String name, java.lang.String[][] value)
          Creates a JSCSArray from value.
 
Method Summary
 void appendCols(JSCSArray newCols)
          Appends newCols to the right end of the value array.
 void appendRows(JSCSArray newRows)
          Appends newRows to the bottom the value array.
 void clear()
          Clears this data object.
 int cols()
          Gets the number of columns in the stored array.
 JSCSArray copy()
          Gets a copy of the current object.
 void delCol(int i)
          Deletes column i from the value array.
 void delColsIf(int[] index)
          Deletes all columns of this that have a corresponding nonzero element in index.
 void delRow(int i)
          Deletes row i from the value array.
 void delRowsIf(int[] index)
          Deletes all rows of this that have a corresponding nonzero element in index.
 java.lang.String display()
          Gets a string representing the String[][] stored.
 java.lang.String[] getCol(int colIndex)
          Gets the column of the underlying string array specified with colIndex.
 boolean isEmpty()
          Gets whether this is empty.
 boolean isEqual(JSCData o)
          Gets whether the values of this data object and other are logically equal.
 java.lang.String name()
          Gets the name of the data object.
 int rows()
          Gets the number of rows in the stored array.
 java.lang.String[][] selRowsIf(int[] rowIndex)
          Gets all rows of the underlying string array that have a nonzero corresponding element in rowIndex.
 void setFormatString(java.lang.String newFormatString)
          Sets a new format string.
 void setVal(JSCSArray val)
          Sets the values stored in val to this JSCSArray.
 void setVal(java.lang.String... newValue)
          Sets the value of this to newValue, see setVal(String[][] newValue).
 void setVal(java.lang.String[][] newValue)
          Sets the value of this to newValue.
 void setValAt(java.lang.String val, int i, int j)
          Sets the String element stored at index i, j.
 java.lang.String[][] stringArray()
          Gets a copy of the underlying value as a String[][].
 java.lang.String stringAt(int i, int j)
          Gets the String element stored at index i, j.
 java.lang.String toString()
          Gets a string representation of this JSCSArray instance.
 void transpose()
          Transposes the underlying array.
 JSCTypes type()
          Gets the type of this JSCData object.
 java.lang.Object value()
          Gets a copy of the underlying value, which is stored as a String[][].
 java.lang.String[] vec()
          Gets the columns of this object stacked into a String[].
 
Methods inherited from class com.jstatcom.model.AbstractJSCData
addJSCDataListener, getJSCProperty, removeJSCDataListener, removeJSCProperty, setJSCProperty
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

JSCSArray_XML

public static final javolution.xml.XmlFormat<JSCSArray> JSCSArray_XML
XML format field for (de)serialization.

Constructor Detail

JSCSArray

public JSCSArray(java.lang.String name)
Creates an empty JSCSArray.

Parameters:
name - the identifier of that object
Throws:
java.lang.IllegalArgumentException - if name is not valid or if (name == null)
See Also:
JSCConstants.isValidName(java.lang.String)

JSCSArray

public JSCSArray(java.lang.String name,
                 java.lang.String[][] value)
Creates a JSCSArray from value. The elements of value are copied before.

Parameters:
name - the identifier of that object
value - the String[][] to be copied and used as value
Throws:
java.lang.IllegalArgumentException - if name is not valid
or if rows of value have different lengths or if (name == null)
See Also:
JSCConstants.isValidName(java.lang.String)

JSCSArray

public JSCSArray(JSCSArray sarray)
Copy-Constructor.

Parameters:
sarray - the string array to copy
Throws:
java.lang.IllegalArgumentException - if (sarray == null)
See Also:
JSCConstants.isValidName(java.lang.String)

JSCSArray

public JSCSArray(java.lang.String name,
                 java.lang.String... value)
Creates a JSCSArray from value. The elements of value are copied before.

Parameters:
name - the identifier of that object
value - the String[] to be copied and used as value
Throws:
java.lang.IllegalArgumentException - if name is not valid
or if (name == null)
See Also:
JSCConstants.isValidName(java.lang.String)
Method Detail

appendCols

public void appendCols(JSCSArray newCols)
Appends newCols to the right end of the value array. Fires a JSCDataEvent of type: It is possible to append columns to an empty data object. This would be similar to setting new values. If newCols is empty, nothing happens.

Parameters:
newCols - the JSCSArray to be appended
Throws:
java.lang.IllegalArgumentException - if (newCols == null) or if (rows() > 0 && newCols.rows() > 0 && rows() != newCols.rows())

appendRows

public void appendRows(JSCSArray newRows)
Appends newRows to the bottom the value array. Fires a JSCDataEvent of type: It is possible to append rows to an empty data object. This would be similar to setting new values. If newRows is empty, nothing happens.

Parameters:
newRows - the JSCSArray to be appended
Throws:
java.lang.IllegalArgumentException - if (newRows == null) or if (cols() > 0 && newRows.cols() > 0 && cols() != newRows.cols())

clear

public void clear()
Clears this data object. Fires: if it was not empty before. After calling this method isEmpty returns true.


cols

public int cols()
Gets the number of columns in the stored array.

Returns:
the number of columns or 0 if (isEmpty())

copy

public JSCSArray copy()
Description copied from interface: JSCData
Gets a copy of the current object. Implementations of this method must fulfil the two conditions: JSCDataListeners attached to the original object should not be copied.

Returns:
a clonelike copy of the original object
See Also:
JSCData

delCol

public void delCol(int i)
Deletes column i from the value array. Fires a JSCDataEvent of type:

Parameters:
i - the index of the column to remove
Throws:
java.lang.IllegalStateException - if this is empty
java.lang.IllegalArgumentException - if column index is invalid

delColsIf

public void delColsIf(int[] index)
Deletes all columns of this that have a corresponding nonzero element in index. If index contains only zeros, nothing happens. If index selects all columns, this is cleared.

This method fires a JSCDataEvent of type:

Parameters:
index - the cols() x 1 int array, nonzero entries select columns
Throws:
java.lang.IllegalStateException - if this is empty
java.lang.IllegalArgumentException - if (index.length != cols()) or if (index == null)

delRow

public void delRow(int i)
Deletes row i from the value array. Fires a JSCDataEvent of type:

Parameters:
i - the index of the row to remove
Throws:
java.lang.IllegalStateException - if this is empty
java.lang.IllegalArgumentException - if row index is invalid

delRowsIf

public void delRowsIf(int[] index)
Deletes all rows of this that have a corresponding nonzero element in index. If index contains only zeros, nothing happens. If index selects all rows, this is cleared.

This method fires a JSCDataEvent of type:

Parameters:
index - the rows() x 1 int array, nonzero entries select rows
Throws:
java.lang.IllegalStateException - if this is empty
java.lang.IllegalArgumentException - if (index.length != rows()) or if (index == null)

display

public java.lang.String display()
Gets a string representing the String[][] stored.

Specified by:
display in interface JSCData
Overrides:
display in class AbstractJSCData
Returns:
"{}" if isEmpty == true, otherwise a formatted string with all elements in table form, the format parameters can be changed via setFormatString

isEmpty

public boolean isEmpty()
Gets whether this is empty. This method returns true if one of the following conditions is met:

Returns:
true if empty

isEqual

public boolean isEqual(JSCData o)
Description copied from interface: JSCData
Gets whether the values of this data object and other are logically equal.

Returns:
true if considered equal according to the logic of the representation
See Also:
JSCData

name

public java.lang.String name()
Description copied from interface: JSCData
Gets the name of the data object. It must fulfil the requirements for variable names defined in JSCConstants.

Returns:
the name
See Also:
JSCData

rows

public int rows()
Gets the number of rows in the stored array.

Returns:
the number of rows or 0 if (isEmpty())

setFormatString

public void setFormatString(java.lang.String newFormatString)
Sets a new format string. This string is used by the display method to format the string array. The default format string is

"%-12s ".

For a complete description of all legal arguments, see the PrintfFormat documentation. The string must contain exactly one conversion character.

Parameters:
newFormatString - the format string to be used for display
Throws:
java.lang.IllegalArgumentException - if newFormatString is not valid
See Also:
PrintfFormat

setVal

public void setVal(java.lang.String[][] newValue)
Sets the value of this to newValue. Fires a JSCDataEvent of type: A value is empty if it is either null or at least one dimension is zero. The newValue is only compared to the existing value if a listener to JSCDataEventTypes.VALUE_CHANGED is registered.

Parameters:
newValue - the new value
Throws:
java.lang.IllegalArgumentException - if rows of newValue have different lengths

setVal

public void setVal(java.lang.String... newValue)
Sets the value of this to newValue, see setVal(String[][] newValue).

Parameters:
newValue - the new value

setVal

public void setVal(JSCSArray val)
Sets the values stored in val to this JSCSArray. Future changes in val have no effect on this.

Parameters:
val - instance of JSCSArray
Throws:
java.lang.IllegalArgumentException - if (val == null)

setValAt

public void setValAt(java.lang.String val,
                     int i,
                     int j)
Sets the String element stored at index i, j. Fires a JSCDataEvent of type JSCDataEventTypes.VALUE_CHANGED if the new value is different from the one currently stored at that position. The event object contains the following values: Thus listeners can exactly pin down, where the change in the array happened.

Parameters:
val - the String to store at the given position
i - the row index, zero based
j - the column index, zero based
Throws:
java.lang.IllegalArgumentException - if indices out of range

stringArray

public java.lang.String[][] stringArray()
Gets a copy of the underlying value as a String[][].

Returns:
the string array
if this is empty new String[0][0] is returned

vec

public java.lang.String[] vec()
Gets the columns of this object stacked into a String[].

Returns:
vectorized version of this
if this is empty new String[0] is returned

stringAt

public java.lang.String stringAt(int i,
                                 int j)
Gets the String element stored at index i, j.

Parameters:
i - the row index, zero based
j - the column index, zero based
Returns:
the String stored at this array position
Throws:
java.lang.IllegalArgumentException - if indices out of range

toString

public java.lang.String toString()
Gets a string representation of this JSCSArray instance. The value is only represented with a summary string, because the underlying array might be large. To print the complete value, use display instead.

Overrides:
toString in class AbstractJSCData
Returns:
string with name, type and value information

type

public JSCTypes type()
Gets the type of this JSCData object.

Returns:
JSCTypes.SARRAY
See Also:
JSCTypes

value

public java.lang.Object value()
Gets a copy of the underlying value, which is stored as a String[][].

Returns:
the value object
if this is empty new String[0][0] is returned

transpose

public void transpose()
Transposes the underlying array. Nothing happens if this is empty. Fires a JSCDataEvent of type JSCDataEventTypes.VALUE_CHANGED if the stored array is not symmetric.


selRowsIf

public java.lang.String[][] selRowsIf(int[] rowIndex)
Gets all rows of the underlying string array that have a nonzero corresponding element in rowIndex.

Parameters:
rowIndex - this.rows() x 1 vector selecting rows
Returns:
new array with the extracted rows, new string[0][0] if index contains only 0's, a copy of the underlying values if rowIndex contains only nonzero elements
Throws:
java.lang.IllegalArgumentException - if (rowIndex == null) or if (this.isEmpty() && rowIndex > 0) or if (this.rows() != rowIndex)

getCol

public java.lang.String[] getCol(int colIndex)
Gets the column of the underlying string array specified with colIndex. The index starts with 0 as usual.

Parameters:
colIndex - the index of the column to extract (starting from 0)
Returns:
a one dimensional string array with the column data
Throws:
java.lang.IllegalStateException - if this is empty
java.lang.IllegalArgumentException - colIndex is outside of valid array bounds