org.opensha.commons.eq.cat
Class DefaultCatalog

java.lang.Object
  extended by org.opensha.commons.eq.cat.DefaultCatalog
All Implemented Interfaces:
Catalog
Direct Known Subclasses:
MutableCatalog

public class DefaultCatalog
extends java.lang.Object
implements Catalog

Default catalog implementation. This class validates all data added to this catalog and provides accessors for basic extents values (min and max lat, lon, depth, mag, and date). The extents values are calculated automatically as these data types are added to the catalog.

Note that implementation assumes that input data is sorted ascending by date.

A DefaultCatalog only allows access to copies of source data via getData(); internal arrays are unmodifiable. To avoid performance loss, especially with larger catalogs, users should use a MutableCatalog instead.

This class provides a static method to read catalog bounds data from an XML metadata element created when saving as a binary file. The bounds data is provided so that a catalog does not have to be loaded to retrieve min/max data. However, this data is not used to reset internal min/max fields; they are set each time a catalog is initialized/loaded.

Version:
$Id: DefaultCatalog.java 8980 2012-05-22 17:23:51Z pmpowers $
Author:
Peter Powers

Field Summary
 
Fields inherited from interface org.opensha.commons.eq.cat.Catalog
MAX_SIZE
 
Constructor Summary
DefaultCatalog()
          Constructs a new empty catalog.
DefaultCatalog(java.io.File file, CatalogReader reader)
          Constructs a new catalog from the given file using the specified reader.
 
Method Summary
 void addData(DataType type, java.lang.Object data)
          Adds an array of data of the specified type to this catalog.
 java.lang.Object clone()
          Returns a deep copy of this catalog.
 boolean contains(DataType type)
          Returns whether this catalog contains a particular DataType.
 java.lang.Object copyData(DataType type)
          Returns a deep copy of the requested data type or null if the type does not esist in this catalog.
 Catalog deriveCatalog(int[] indices, Catalog catalog)
          Derives a new catalog from this one using the events at the given indices.
 java.lang.Object deriveData(DataType type, int[] indices)
          Returns an indices.length sized array of the requested data type from the indices specified or null if the data type does not exist in this catalog.
static java.util.Map<java.lang.String,java.lang.String> getBoundsData(Element data)
          Deprecated. 
 java.lang.Object getData(DataType type)
          Returns a copy of the requested data type or null if the DataType is not present in this catalog.
 java.util.Set<DataType> getDataTypes()
          Returns an immutable set of the data types in this catalog.
 java.util.Date getDate(int index)
          Returns the Date of the event at index.
 int getEventID(int index)
          Returns the eventID of the event at index.
 java.lang.String getEventString(int index)
          Returns a string representation of the event at a given index.
 java.lang.String getEventStringWithID(int index)
          Returns a string representation of the event at a given index.
 long getTime(int index)
          Returns the time of the event at index (in milliseconds).
 double getValue(DataType type, int index)
          Returns the value of a the requested DataType for the event at the specified index.
 java.util.Date maxDate()
          Returns end date of this catalog or null if it is not set.
 double maxForType(DataType type)
          Returns the maximum value of the requested DataType.
 java.util.Date minDate()
          Returns start date of this catalog or null if it is not set.
 double minForType(DataType type)
          Returns the minimum value of the requested DataType.
 boolean readable()
          Returns whether copies of or references to internal data are provided by getData().
 void readCatalog(java.io.File file, Element meta)
          Reads this catalog from serialized data arrays.
protected  void setReadable(boolean readable)
          Sets whether getData() returns references to internal data arrays or copies.
 int size()
          Returns the number of events in this catalog or -1 if the catalog is empty.
 Element writeCatalog(java.io.File file)
          Writes this catalog as a binary file and returns XML metadata that can be referenced for data type order when deserializing.
 void writeCatalog(java.io.File file, CatalogWriter writer)
          Writes this catalog to a given file using a specified CatalogWriter.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DefaultCatalog

public DefaultCatalog()
Constructs a new empty catalog. Catalog size (event count) is set using the first data array added; all subsequent data arrays must be the same size as the first


DefaultCatalog

public DefaultCatalog(java.io.File file,
                      CatalogReader reader)
               throws java.io.IOException
Constructs a new catalog from the given file using the specified reader.

Parameters:
file - to read
reader - to process file
Throws:
java.io.IOException - if unable to initialize catalog using supplied File and CatalogReader
Method Detail

size

public int size()
Description copied from interface: Catalog
Returns the number of events in this catalog or -1 if the catalog is empty.

Specified by:
size in interface Catalog
Returns:
the catalog size

contains

public boolean contains(DataType type)
Description copied from interface: Catalog
Returns whether this catalog contains a particular DataType.

Specified by:
contains in interface Catalog
Parameters:
type - to look for
Returns:
whether data of the specified type exists in this catalog

clone

public java.lang.Object clone()
Returns a deep copy of this catalog.

Overrides:
clone in class java.lang.Object
Returns:
a duplicate Catalog
See Also:
Object.clone()

setReadable

protected void setReadable(boolean readable)
Sets whether getData() returns references to internal data arrays or copies. Open access can significantly reduce memory overhead but increases risks of catalog data manipulation if the catalog is re- written to disk.

Parameters:
readable - whether references to (true) or copies of (false) data are returned

readable

public boolean readable()
Description copied from interface: Catalog
Returns whether copies of or references to internal data are provided by getData().

Specified by:
readable in interface Catalog
Returns:
read access status

addData

public void addData(DataType type,
                    java.lang.Object data)
Description copied from interface: Catalog
Adds an array of data of the specified type to this catalog. The first call to this method sets the catalog size based on the supplied array. Method sets the size of the catalog if it has not yet been set. When event times are added to the catalog, they must be sorted ascending.

Specified by:
addData in interface Catalog
Parameters:
type - of data to be added
data - array to be added

getData

public java.lang.Object getData(DataType type)
Description copied from interface: Catalog
Returns a copy of the requested data type or null if the DataType is not present in this catalog. Implementations may return a reference or a deep copy of the requested data array.

Specified by:
getData in interface Catalog
Parameters:
type - requested
Returns:
the data array

copyData

public java.lang.Object copyData(DataType type)
Returns a deep copy of the requested data type or null if the type does not esist in this catalog.

Parameters:
type - requested
Returns:
a deep copy of the requested type

getDataTypes

public java.util.Set<DataType> getDataTypes()
Returns an immutable set of the data types in this catalog.

Returns:
the data type array

deriveData

public java.lang.Object deriveData(DataType type,
                                   int[] indices)
Returns an indices.length sized array of the requested data type from the indices specified or null if the data type does not exist in this catalog. This is a deep copy.

Parameters:
type - requested
indices - to return for type
Returns:
the data array
Throws:
java.lang.NullPointerException - if index array is null
java.lang.IndexOutOfBoundsException - if any indices are out of range TODO better argument checking

deriveCatalog

public Catalog deriveCatalog(int[] indices,
                             Catalog catalog)
Derives a new catalog from this one using the events at the given indices.

Parameters:
indices - of events to extract
catalog - the output catalog
Returns:
a reference to the output catalog provided
Throws:
java.lang.NullPointerException - if index array is null
java.lang.IndexOutOfBoundsException - if any indices are out of range TODO better argument checking

writeCatalog

public void writeCatalog(java.io.File file,
                         CatalogWriter writer)
                  throws java.io.IOException
Writes this catalog to a given file using a specified CatalogWriter.

Parameters:
file - to write to
writer - file formatter to use
Throws:
java.io.IOException - if unable to write catalog to file

writeCatalog

public Element writeCatalog(java.io.File file)
                     throws java.io.IOException
Writes this catalog as a binary file and returns XML metadata that can be referenced for data type order when deserializing. Metadata also contains catalog bounds (min/max) data (so that catalog does not have to be loaded to get summary info).

Parameters:
file - to write to
Returns:
an XML snippet of the write order and bounds metadata
Throws:
java.lang.NullPointerException - if supplied file is null
java.io.IOException - if there is a problem writing the file

readCatalog

public void readCatalog(java.io.File file,
                        Element meta)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Reads this catalog from serialized data arrays. The data types listed in 'fields' must be valid for catalog class or an exception will be thrown when an invalid data type is added to internal arrays.

Parameters:
file - to read
meta - data to read; XML format list of data types to load
Throws:
java.lang.NullPointerException - if supplied file or XML metadata is null
java.lang.IllegalArgumentException - if a DataType read from metadata is not a valid type
java.io.IOException - if there is an IO problem reading the file
java.lang.ClassNotFoundException - if there is a problem reading objects from the file

getEventString

public java.lang.String getEventString(int index)
Description copied from interface: Catalog
Returns a string representation of the event at a given index. Method will throw an exception if index is out of range or catalog does not contain time and magnitude data.

Specified by:
getEventString in interface Catalog
Parameters:
index - of event
Returns:
a string describing an earthquake event

getEventStringWithID

public java.lang.String getEventStringWithID(int index)
Description copied from interface: Catalog
Returns a string representation of the event at a given index.

Specified by:
getEventStringWithID in interface Catalog
Parameters:
index - of event
Returns:
a string describing an earthquake event

getEventID

public int getEventID(int index)
Description copied from interface: Catalog
Returns the eventID of the event at index.

Specified by:
getEventID in interface Catalog
Parameters:
index - of event
Returns:
the eventID value

getTime

public long getTime(int index)
Description copied from interface: Catalog
Returns the time of the event at index (in milliseconds).

Specified by:
getTime in interface Catalog
Parameters:
index - of event
Returns:
the time of the event

getDate

public java.util.Date getDate(int index)
Description copied from interface: Catalog
Returns the Date of the event at index.

Specified by:
getDate in interface Catalog
Parameters:
index - of event
Returns:
the Date of the event

minDate

public java.util.Date minDate()
Description copied from interface: Catalog
Returns start date of this catalog or null if it is not set.

Specified by:
minDate in interface Catalog
Returns:
the catalog start Date

maxDate

public java.util.Date maxDate()
Description copied from interface: Catalog
Returns end date of this catalog or null if it is not set.

Specified by:
maxDate in interface Catalog
Returns:
the catalog end Date

getValue

public double getValue(DataType type,
                       int index)
Description copied from interface: Catalog
Returns the value of a the requested DataType for the event at the specified index. Method is only valid for the following double-valued DataTypes: [LONGITUDE, LATITUDE, DEPTH, MAGNITUDE]

Specified by:
getValue in interface Catalog
Parameters:
type - requested
index - of event
Returns:
the type value at event index

minForType

public double minForType(DataType type)
Description copied from interface: Catalog
Returns the minimum value of the requested DataType. Method is only valid for the following double-valued DataTypes: [LONGITUDE, LATITUDE, DEPTH, MAGNITUDE]

Specified by:
minForType in interface Catalog
Parameters:
type - requested
Returns:
the minimum value for the DatType

maxForType

public double maxForType(DataType type)
Description copied from interface: Catalog
Returns the maximum value of the requested DataType. Method is only valid for the following double-valued DataTypes: [LONGITUDE, LATITUDE, DEPTH, MAGNITUDE]

Specified by:
maxForType in interface Catalog
Parameters:
type - requested
Returns:
the maximum value for the DatType

getBoundsData

@Deprecated
public static java.util.Map<java.lang.String,java.lang.String> getBoundsData(Element data)
Deprecated. 

Places catalog bounds data in a Map for easy access. Input metadata should have been created when saving catalog in binary format. If inappropriate XML is encountered, method returns null. TODO delete?

Parameters:
data - element to parse
Returns:
hastable of catalog bounds information