org.opensha.commons.eq.cat
Class DefaultCatalog

java.lang.Object
  org.opensha.commons.eq.cat.DefaultCatalog

All Implemented Interfaces:

Catalog

Direct Known Subclasses:

MutableCatalog

public class DefaultCatalog
extends 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(File file, CatalogReader reader)
Constructs a new catalog from the given file using the specified reader.

Method Summary

void	addData(DataType type, Object data) Adds an array of data of the specified type to this catalog.
Object	clone() Returns a deep copy of this catalog.
boolean	contains(DataType type) Returns whether this catalog contains a particular DataType.
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.
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 Map<String,String>	getBoundsData(Element data) Deprecated.
Object	getData(DataType type) Returns a copy of the requested data type or null if the DataType is not present in this catalog.
Set<DataType>	getDataTypes() Returns an immutable set of the data types in this catalog.
Date	getDate(int index) Returns the Date of the event at index.
int	getEventID(int index) Returns the eventID of the event at index.
String	getEventString(int index) Returns a string representation of the event at a given index.
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.
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.
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(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(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(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(File file,
                      CatalogReader reader)
               throws IOException

Constructs a new catalog from the given file using the specified reader.

Parameters:

file - to read

reader - to process file

Throws:

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 Object clone()

Returns a deep copy of this catalog.

Overrides:

clone in class 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,
                    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 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 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 Set<DataType> getDataTypes()

Returns an immutable set of the data types in this catalog.

Returns:

the data type array

deriveData

public 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:

NullPointerException - if index array is null

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:

NullPointerException - if index array is null

IndexOutOfBoundsException - if any indices are out of range TODO better argument checking

writeCatalog

public void writeCatalog(File file,
                         CatalogWriter writer)
                  throws IOException

Writes this catalog to a given file using a specified CatalogWriter.

Parameters:

file - to write to

writer - file formatter to use

Throws:

IOException - if unable to write catalog to file

writeCatalog

public Element writeCatalog(File file)
                     throws 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:

NullPointerException - if supplied file is null

IOException - if there is a problem writing the file

readCatalog

public void readCatalog(File file,
                        Element meta)
                 throws IOException,
                        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:

NullPointerException - if supplied file or XML metadata is null

IllegalArgumentException - if a DataType read from metadata is not a valid type

IOException - if there is an IO problem reading the file

ClassNotFoundException - if there is a problem reading objects from the file

getEventString

public 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 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 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 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 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 Map<String,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