org.opensha.commons.data
Class ContainerSubset2D<T>

java.lang.Object
  org.opensha.commons.data.ContainerSubset2D<T>

All Implemented Interfaces:

Serializable, Iterable<T>, Container2D<T>, Named

Direct Known Subclasses:

GriddedSubsetSurface

public class ContainerSubset2D<T>
extends Object
implements Container2D<T>, Serializable

Title: ContainerSubset2D

Description: Small read only window into larger Container2d. This class takes a Container2D as a variable, then becomes a "window" into the larger grid. Since this class implements Container2DAPI it "looks" like a Container2D.

All this class does is provide convinience methods to zoom into a smaller section of the referenced Container2D. It translates the window x and y coordinate indices into the real indices of the referenced container.

The key to understanding this class is the Window2D that contains a minX, maxX, minY and maxY values. These are the translation indices to go between this subset coordinate system to the referencing container's coordinate system. For example the 0th index along x axis in this subset container maps to minX index in the main container.

Another trick used in this class is useful to understand. Basically the API allows translation, modifications of the Window2D around the larger referenced container. Because there are four variables to the Window2D, this could take four method calls to change the data. Because there is more than one step involved, and any one step can potentially fail, I needed to provide a rollback mechanism to the last know good state. This is the purpose of the oldWindow variable and the commit and rollback functions.

This class was designed with the purpose of examining rupture locals in a fault gridded surface, but has been generalized to work with any Container2DAPI.

Version:

1.0

Author:

Steven W. Rock

See Also:

Serialized Form

Field Summary

protected static String	C Class name used for debbuging
protected static boolean	D if true print out debugging statements
protected Container2D<T>	data Internal reference to real data container.
protected String	name Every container has a name associated with it to distinguish it from other container instances.
protected Window2D	oldWindow The API allows translation, modifications of the Window2D around the larger referenced container.
protected static char	TAB
protected Window2D	window Data containing indexing information into larger dataset.

Constructor Summary

ContainerSubset2D(int numRows, int numCols, int startRow, int startCol)
Constructor for the ContainerSubset2D object.

ContainerSubset2D(int numRows, int numCols, int startRow, int startCol, Container2D<T> data)
Constructor for the ContainerSubset2D object.

Method Summary

void	clear() Sublcass not allowed to modify data, i.e.
protected void	commit() Completes a transaction.
boolean	exist(int row, int column) Returns true if a non-null java object resides at the specified cell, i.e.
T	get(int row, int column) Returns the object stored in the Container2D at the subset's window coordinates.
ListIterator<T>	getAllByColumnsIterator() Iterate over all cells in the subset window.
ListIterator<T>	getAllByRowsIterator() Iterate over all cells in the subset window.
ListIterator<T>	getColumnIterator(int row) Iterate over all columns values in one row of the surface.
Container2D<T>	getContainer2D() Returns the container2D pointer contained in the subset window.
int	getEndCol() Returns the last col index on the Window2D
int	getEndRow() Returns the last row index on the Window2D
String	getName() Returns the name of this object
int	getNumCols() Returns number of cols in the Window2D.
int	getNumRows() Returns number of rows in the Window2D.
ListIterator<T>	getRowIterator(int column) Iterate over all row values in one column of the surface.
int	getStartCol() Gets the startColindex of the Window2D object
int	getStartRow() Gets the startRow index of the Window2D object
protected void	initTransaction() Start of a transaction - simply clones the Window2D into the old Window.
Iterator<T>	iterator()
ListIterator<T>	listIterator() iterate over all data points, no guarentee of order returned
static void	main(String[] args) The main program for the Container2D class.
protected void	rollback() Copies the oldWindow back into the Window2D, restoring the window to it's previous size.
void	set(int row, int column, T obj) This method is required of the Contianer2dAPI.
void	setContainer2D(Container2D<T> data) Allows setting the reference to a new Container2D.
void	setName(String name) Every container has a name associated with it to distinguish it from other container instances.
void	setStartCol(int startCol) Used to update the starting cal index in the Window2D.
void	setStartRow(int startRow) Used to update the starting row index in the Window2D.
void	shiftCols(int delta) Shifts the Window2D "window" into the main Container2D by the specified number of index points.
void	shiftRows(int delta) Shifts the Window2D "window" into the main Container2D by the specified number of index points.
long	size() Returns the size of the subset window, numRows * numCols.
Object[][]	toJava2D() Use Window2D to generate this.
String	toString() Prints out each location and fault information for debugging
protected void	validate() Internal helper function that performs various validation checks between the Window2D values and the referenced container domain and range values.

Methods inherited from class java.lang.Object

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

Field Detail

C

protected static final String C

Class name used for debbuging

See Also:

Constant Field Values

D

protected static final boolean D

if true print out debugging statements

See Also:

Constant Field Values

name

protected String name

Every container has a name associated with it to distinguish it from other container instances. SUbsets can also have names different from the referenced container. Also useful for displaying in a GUI.

window

protected Window2D window

Data containing indexing information into larger dataset. Contains xMin, xMax, yMin, and yMax indexes. This allows translation from this subset container coordinate system into the lerger referenced container. For example the 0th index along the x axis in this subset container maps to minX index in the main container.

oldWindow

protected Window2D oldWindow

The API allows translation, modifications of the Window2D around the larger referenced container. Because there are four variables to the Window2D, this could take four method calls to change the data. Because there is more than one step involved, and any one step can potentially fail, I needed to provide a rollback mechanism to the last know good state. This is the purpose of the oldWindow variable and the commit and rollback functions. .

data

protected Container2D<T> data

Internal reference to real data container.

TAB

protected static final char TAB

See Also:

Constant Field Values

Constructor Detail

ContainerSubset2D

public ContainerSubset2D(int numRows,
                         int numCols,
                         int startRow,
                         int startCol)
                  throws ArrayIndexOutOfBoundsException

Constructor for the ContainerSubset2D object. Provides specifications that allows the Window2D to be fully specified

Parameters:

numRows - number of index points along the x-axis

numCols - number of index points along the y-axis

startRow - Staring row of this subset, put in Window2D

startCol - Staring col of this subset, put in Window2D

Throws:

ArrayIndexOutOfBoundsException - Thown if any of the idices go beyond the range of the referencing container

ContainerSubset2D

public ContainerSubset2D(int numRows,
                         int numCols,
                         int startRow,
                         int startCol,
                         Container2D<T> data)
                  throws ArrayIndexOutOfBoundsException

Constructor for the ContainerSubset2D object. Provides specifications that allows the Window2D to be fully specified. Also sets the reference to the real data in the main Container2D

Parameters:

numRows - number of index points along the x-axis

numCols - number of index points along the y-axis

startRow - Staring row of this subset, put in Window2D

startCol - Staring col of this subset, put in Window2D

Throws:

ArrayIndexOutOfBoundsException - Thown if any of the idices go beyond the range of the referencing container

Method Detail

setContainer2D

public void setContainer2D(Container2D<T> data)
                    throws ArrayIndexOutOfBoundsException

Allows setting the reference to a new Container2D. All indexes must have been set already i the Window2D before calling this function. If invalid data, the window is rolled back to the old one.

Parameters:

data - The new container2D value

Throws:

ArrayIndexOutOfBoundsException - Thown if any of the idices go beyond the range of the referencing container

setStartRow

public void setStartRow(int startRow)
                 throws ArrayIndexOutOfBoundsException

Used to update the starting row index in the Window2D. If invalid data, the window is rolled back to the old one.

Parameters:

startRow - The new startRow value

Throws:

ArrayIndexOutOfBoundsException - Thrown if this start row is an invalid index in the main container, i.e. too large or negative.

validate

protected void validate()
                 throws ArrayIndexOutOfBoundsException

Internal helper function that performs various validation checks between the Window2D values and the referenced container domain and range values. Validates that all the subset indeces are within the main Container2D space.

Throws:

ArrayIndexOutOfBoundsException - Thrown if any of the values are invalid, such as negative indices.

setStartCol

public void setStartCol(int startCol)
                 throws ArrayIndexOutOfBoundsException

Used to update the starting cal index in the Window2D. If invalid data, the window is rolled back to the old one.

Parameters:

startRow - The new startCal value in Window2D

Throws:

ArrayIndexOutOfBoundsException - Thrown if this start cal is an invalid index in the main container, i.e. too large or negative.

set

public void set(int row,
                int column,
                T obj)
         throws ArrayIndexOutOfBoundsException

This method is required of the Contianer2dAPI. This subclass was designed as read-only so throws an exception if you try to use this.

Specified by:

set in interface Container2D<T>

Parameters:

row - x-coord

column - y-coord

obj - new object to place in the container cell

Throws:

ArrayIndexOutOfBoundsException - Never thrown, function disabled.

getContainer2D

public Container2D<T> getContainer2D()

Returns the container2D pointer contained in the subset window.

Returns:

The container2D pointer

getStartRow

public int getStartRow()

Gets the startRow index of the Window2D object

Returns:

The startRow value

getStartCol

public int getStartCol()

Gets the startColindex of the Window2D object

Returns:

The startCol value

getNumRows

public int getNumRows()

Returns number of rows in the Window2D.

Specified by:

getNumRows in interface Container2D<T>

Returns:

The num rows

getNumCols

public int getNumCols()

Returns number of cols in the Window2D.

Specified by:

getNumCols in interface Container2D<T>

Returns:

The num cols

getEndRow

public int getEndRow()

Returns the last row index on the Window2D

Returns:

The numRows value

getEndCol

public int getEndCol()

Returns the last col index on the Window2D

Returns:

The numCols value

get

public T get(int row,
             int column)
      throws ArrayIndexOutOfBoundsException

Returns the object stored in the Container2D at the subset's window coordinates. These are translated to the real coordinates using the Window2D

Specified by:

get in interface Container2D<T>

Parameters:

row - x-coord

column - y-coord

Returns:

The java objectg stored in the container.

Throws:

ArrayIndexOutOfBoundsException - If the indices value are invalid for the container2D

getColumnIterator

public ListIterator<T> getColumnIterator(int row)
                                  throws ArrayIndexOutOfBoundsException

Iterate over all columns values in one row of the surface. Note this only returns the column values in this subset window, not the full container.

Specified by:

getColumnIterator in interface Container2D<T>

Parameters:

row - Row to get all column points from

Returns:

The columnIterator value

Throws:

ArrayIndexOutOfBoundsException - If the x-coord index value are invalid for the container2D

getRowIterator

public ListIterator<T> getRowIterator(int column)
                               throws ArrayIndexOutOfBoundsException

Iterate over all row values in one column of the surface. Note this only returns the row values in this subset window, not the full container.

Specified by:

getRowIterator in interface Container2D<T>

Parameters:

row - Column to get all row points from

Returns:

The rowIterator value

Throws:

ArrayIndexOutOfBoundsException - If the y-coord index value are invalid for the container2D

getAllByColumnsIterator

public ListIterator<T> getAllByColumnsIterator()

Iterate over all cells in the subset window. This iterator starts with the first column and returns all row elements, then moves to the next column, and so on.

Note: This iterates only over the subset indices, not over the full container. The iterator implementation is contained as an inner class in this clas file.

Specified by:

getAllByColumnsIterator in interface Container2D<T>

Returns:

The allByColumnsIterator value

getAllByRowsIterator

public ListIterator<T> getAllByRowsIterator()

Iterate over all cells in the subset window. This iterator starts with the first row and returns all column elements, then moves to the next row, and so on.

Note: This iterates only over the subset indices, not over the full container. The iterator implementation is contained as an inner class in this clas file.

Specified by:

getAllByRowsIterator in interface Container2D<T>

Returns:

The allByRowsIterator value

shiftRows

public void shiftRows(int delta)
               throws ArrayIndexOutOfBoundsException

Shifts the Window2D "window" into the main Container2D by the specified number of index points. This allows the window to be moved over various points of interest without construction of a brand new object.

Parameters:

delta - Number of points to shift the Window2D along the x-axis

Throws:

ArrayIndexOutOfBoundsException - Thrown if the shift moves the window outside the main container boundaries.

initTransaction

protected void initTransaction()

Start of a transaction - simply clones the Window2D into the old Window. This is needed because resizing the window is a multistep process, i.e. more than onw function call required to shift in the x, then the y directions. Any of these functions can throw errors. So if one fails, we have to "undo" all the previous successful function calls. They all must succede or the resizing is considered a failure and all operations must be undone, resetting to the original state. That is the purpose of the rollback() function.

rollback

protected void rollback()

Copies the oldWindow back into the Window2D, restoring the window to it's previous size.

commit

protected void commit()

Completes a transaction. All required actions completed successfully so the old window variable is deleted and the changes kept in the primary Window2D.

shiftCols

public void shiftCols(int delta)
               throws ArrayIndexOutOfBoundsException

Shifts the Window2D "window" into the main Container2D by the specified number of index points. This allows the window to be moved over various points of interest without construction of a brand new object.

Parameters:

delta - Number of points to shift the Window2D along the y-axis

Throws:

ArrayIndexOutOfBoundsException - Thrown if the shift moves the window outside the main container boundaries.

size

public long size()

Returns the size of the subset window, numRows * numCols.

Specified by:

size in interface Container2D<T>

Returns:

Description of the Return Value

exist

public boolean exist(int row,
                     int column)

Returns true if a non-null java object resides at the specified cell, i.e. row and column index.

Specified by:

exist in interface Container2D<T>

Parameters:

row - x-coord

column - y-coord

Returns:

true or false if the object exits.

clear

public void clear()

Sublcass not allowed to modify data, i.e. read only. Therefore this function is not supported, but required by the API.

Specified by:

clear in interface Container2D<T>

listIterator

public ListIterator<T> listIterator()

iterate over all data points, no guarentee of order returned

Specified by:

listIterator in interface Container2D<T>

Returns:

Description of the Return Value

toJava2D

public Object[][] toJava2D()

Use Window2D to generate this. Translates the internal data structure of this 2D window into a Java2D array. This is needed fo specific JFreeChart functionaliry.

Returns:

Description of the Return Value

toString

public String toString()

Prints out each location and fault information for debugging

Specified by:

toString in interface Container2D<T>

Overrides:

toString in class Object

main

public static void main(String[] args)

The main program for the Container2D class. Used to test and demonstrate usage of this class.

Parameters:

args - The command line arguments

setName

public void setName(String name)

Description copied from interface: Container2D

Every container has a name associated with it to distinguish it from other container instances.

Specified by:

setName in interface Container2D<T>

getName

public String getName()

Description copied from interface: Named

Returns the name of this object

Specified by:

getName in interface Named

iterator

public Iterator<T> iterator()

Specified by:

iterator in interface Iterable<T>