com.jstatcom.model
Class JSCSArray

java.lang.Object
  com.jstatcom.model.AbstractJSCData
      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:

• JSCDataEventTypes.VALUE_CHANGED if newCols is not empty
• JSCDataEventTypes.EMPTY_STATE if newCols is not empty and this was empty before

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:

• JSCDataEventTypes.VALUE_CHANGED if newRows is not empty
• JSCDataEventTypes.EMPTY_STATE if newRows is not empty and this was empty before

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:

• JSCDataEventTypes.EMPTY_STATE event
• JSCDataEventTypes.VALUE_CHANGED event

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:

• a.isEqual(a.copy())- compares values
• a.getName().equals(a.copy().getName())- compares name

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:

• JSCDataEventTypes.VALUE_CHANGED in any case
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

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:

• JSCDataEventTypes.VALUE_CHANGED if some column was deleted
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

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:

• JSCDataEventTypes.VALUE_CHANGED in any case
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

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:

• JSCDataEventTypes.VALUE_CHANGED if some row was deleted
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

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:

• value() == null
• rows() == 0
• cols() == 0

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:

• JSCDataEventTypes.VALUE_CHANGED if newValue is different from current value
• JSCDataEventTypes.EMPTY_STATE if newValue is not empty and this was empty before
• JSCDataEventTypes.EMPTY_STATE if newValue is empty and this was not empty before

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:

• oldValue- new Object[] { oldString, new Integer(i), new Integer(j) }
• newValue- new Object[] { newString, new Integer(i), new Integer(j) }

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