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

java.lang.Object
  extended by org.opensha.commons.data.ContainerSubset2D<T>
All Implemented Interfaces:
java.io.Serializable, java.lang.Iterable<T>, Container2D<T>, Named
Direct Known Subclasses:
GriddedSubsetSurface

public class ContainerSubset2D<T>
extends java.lang.Object
implements Container2D<T>, java.io.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 java.lang.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  java.lang.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.
 java.util.ListIterator<T> getAllByColumnsIterator()
          Iterate over all cells in the subset window.
 java.util.ListIterator<T> getAllByRowsIterator()
          Iterate over all cells in the subset window.
 java.util.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
 java.lang.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.
 java.util.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.
 java.util.Iterator<T> iterator()
           
 java.util.ListIterator<T> listIterator()
          iterate over all data points, no guarentee of order returned
static void main(java.lang.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(java.lang.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.
 java.lang.Object[][] toJava2D()
          Use Window2D to generate this.
 java.lang.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 java.lang.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 java.lang.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 java.lang.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:
java.lang.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 java.lang.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:
java.lang.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 java.lang.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:
java.lang.ArrayIndexOutOfBoundsException - Thown if any of the idices go beyond the range of the referencing container

setStartRow

public void setStartRow(int startRow)
                 throws java.lang.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:
java.lang.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 java.lang.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:
java.lang.ArrayIndexOutOfBoundsException - Thrown if any of the values are invalid, such as negative indices.

setStartCol

public void setStartCol(int startCol)
                 throws java.lang.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:
java.lang.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 java.lang.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:
java.lang.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 java.lang.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:
java.lang.ArrayIndexOutOfBoundsException - If the indices value are invalid for the container2D

getColumnIterator

public java.util.ListIterator<T> getColumnIterator(int row)
                                            throws java.lang.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:
java.lang.ArrayIndexOutOfBoundsException - If the x-coord index value are invalid for the container2D

getRowIterator

public java.util.ListIterator<T> getRowIterator(int column)
                                         throws java.lang.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:
java.lang.ArrayIndexOutOfBoundsException - If the y-coord index value are invalid for the container2D

getAllByColumnsIterator

public java.util.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 java.util.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 java.lang.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:
java.lang.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 java.lang.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:
java.lang.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 java.util.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 java.lang.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 java.lang.String toString()
Prints out each location and fault information for debugging

Specified by:
toString in interface Container2D<T>
Overrides:
toString in class java.lang.Object

main

public static void main(java.lang.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(java.lang.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 java.lang.String getName()
Description copied from interface: Named
Returns the name of this object

Specified by:
getName in interface Named

iterator

public java.util.Iterator<T> iterator()
Specified by:
iterator in interface java.lang.Iterable<T>