saaps.dbt
Class Database

java.lang.Object
  |
  +--saaps.dbt.Database
Direct Known Subclasses:
ACEmagDB, ACEmagHourlyDB, ACEsweDB, ACEsweHourlyDB, AEDB, DstDB, GOES08partDB, GOES08xrayDB, GOES10partDB, GOES10xrayDB, KpDB, LANL1990_095DB, OMNIDB

public abstract class Database
extends java.lang.Object

Database is the abstract base class for all saaps data classes. It provides storing and retrieving of the data defined by the classes that extend Database.

Information about the data is stored in the class MetaData which is initialized from the *.meta file when an instance of Database is created.

The static method getInstance(String) can be used to get an instance of Database, it will open the data file in read-write mode. The other static method getInstance(String, boolean) should be used when you want to open the data file in read only mode.

Version:
$Revision: 1.8 $
Author:
Leif Kalla (leif@irf.se)

Field Summary
protected static java.lang.String baseDir
          Absolute path to the database.
static java.lang.String dataDirVar
          An environment property name that defines the path to database.
protected  double dataGapValue
           
protected  boolean isSet
          Indicates if this instance of Database has valid MetaData.
 MetaData meta
           
protected  java.io.RandomAccessFile raf
          Reading and writeing of data is done through a RandomAccessFile class.
 
Constructor Summary
Database()
           
 
Method Summary
private  DatabaseObject average(java.util.Vector vec)
          Averages this data.
private  DatabaseObject[] average(java.util.Vector vec, int ave)
          Averages this data.
 void close()
          Close the database.
protected  double getDataGapValue()
          Gets the dataGapValue.
abstract  java.util.Date getDate(java.lang.Object obj)
          Gets the date from this object.
protected abstract  MetaData getEmptyMetaData(java.util.Date sd, java.util.Date ed)
          Gets a MetaData object with the dates set to the supplied dates.
 DatabaseObject getFirst()
          Gets the first database object in the database.
static Database getInstance(java.lang.String myDB)
          Runs method getInstance with the default action to open database for read/write.
static Database getInstance(java.lang.String myDB, boolean readOnlyAccess)
          Gets a Database object.
 DatabaseObject getLast()
          Gets the last database object in the database
abstract  java.util.Vector getLatestDatabaseObjects()
           Do not use this method it will be removed !
 TimeSeries getResampledTimeSeries(java.util.Date sd, java.util.Date ed, long sampleInterval)
          Gets a TimeSeries object.
 TimeSeries getTimeSeries(java.util.Date sd, java.util.Date ed, long limit)
          Gets a TimeSeries object.
protected  void importAscii(java.lang.String inputfile)
          Imports ASCII data to our database.
 boolean isSet()
          Indicates if the MetaData is set and the data file is open.
protected  long position(boolean start)
          Positions in start or end of file.
private  long position(java.util.Date d, boolean fromStart)
          Runs position with default action to position before the search date.
private  long position(java.util.Date d, boolean fromStart, boolean before)
          Positions the RandomAccessFile at the location closest to the supplied date and returns the location of the object after this.
abstract  java.lang.Object read()
          Gets the object at the current point in file.
 java.util.Vector retrieve()
          Gets all objects in the database (returned in a Vector).
 java.lang.Object retrieve(java.util.Date sd)
          Gets the object before this date.
 java.util.Vector retrieve(java.util.Date sd, java.util.Date ed)
          Gets the objects between the two dates.
 java.util.Vector retrieve(java.util.Date sd, java.util.Date ed, boolean before)
          Gets the DatabaseObjects between the dates.
 TimeSeries retrieveAVE(int fieldIndex, java.util.Date[] events, long start, long end)
          Retrieves a TimeSeries object containing the averaged data for the input event list.
 TimeSeries retrieveAVE(int fieldIndex, java.util.Date[] events, long start, long end, boolean withAdditionalInfo)
          Retrieves a TimeSeries object containing the averaged data for the input event list.
 ObjectTimeSeries retrieveOTS(java.util.Date sd, java.util.Date ed, boolean before)
          Gets an ObjectTimeSeries containing data between the dates.
 TimeSeries retrieveSEA(int fieldIndex, java.util.Date[] events, long start, long end, boolean withAdditionalInfo)
          Retrieves a TimeSeries object containing the averaged data for the input event list.
 TimeSeries retrieveTS(java.util.Date sd, java.util.Date ed, boolean before)
          Gets a TimeSeries containing data between the dates.
 TimeSeries retrieveTS(java.util.Date sd, java.util.Date ed, boolean before, long sampleInterval)
          Gets a TimeSeries containing data between the dates, the data is resampled if needed to the sampleinterval stated.
protected abstract  MetaData setDefaultMeta(java.util.Date sd, java.util.Date ed)
          Sets the MetaData for the specific database and stores it to file.
 void store(ObjectTimeSeries ts)
          Stores DatabaseObjects to file.
 void store(java.util.Vector vec)
          Stores DatabaseObjects to file without checking the input data.
abstract  void write(java.lang.Object dbo)
          Writes data at the current point in file.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

baseDir

protected static java.lang.String baseDir
Absolute path to the database. The dataDirVar contains the name of the property that will reset the path if it's defined.

dataDirVar

public static java.lang.String dataDirVar
An environment property name that defines the path to database.

meta

public MetaData meta

dataGapValue

protected double dataGapValue

isSet

protected boolean isSet
Indicates if this instance of Database has valid MetaData.

raf

protected java.io.RandomAccessFile raf
Reading and writeing of data is done through a RandomAccessFile class.
Constructor Detail

Database

public Database()
Method Detail

getInstance

public static Database getInstance(java.lang.String myDB)
Runs method getInstance with the default action to open database for read/write.
Parameters:
myDB - the database to be loaded
Returns:
a Database object

getInstance

public static Database getInstance(java.lang.String myDB,
                                   boolean readOnlyAccess)
Gets a Database object. Also retrieves the MetaData information from file and opens the randomaccessfile (data file).

If loading of MetaData fails, the default MetaData is set using getEmptyMetaData(Date, Date). In this case the isSet variable is set to false.

Parameters:
myDB - the database to be loaded
readOnlyAccess - the access mode
Returns:
a Database object

close

public void close()
           throws java.io.IOException
Close the database.

Note: we don't have any open method yet so you will have to get a new instance of this database to get an open file.


isSet

public boolean isSet()
Indicates if the MetaData is set and the data file is open. If MetaData is set by getEmptyMetaData(Date , Date ) the parameter isSet is false.
Returns:
true if the MetaData is set

position

protected final long position(boolean start)
                       throws java.io.IOException
Positions in start or end of file.
Parameters:
start - if true position in beginning of file
Returns:
the position

position

private final long position(java.util.Date d,
                            boolean fromStart)
                     throws java.io.IOException
Runs position with default action to position before the search date. See also position(Date , boolean , boolean ).
Parameters:
d - the search date
fromStart - if true then serach file from beginning else proceed from current file position.
Returns:
the position for the data item that follows this one

position

private final long position(java.util.Date d,
                            boolean fromStart,
                            boolean before)
                     throws java.io.IOException
Positions the RandomAccessFile at the location closest to the supplied date and returns the location of the object after this. Position will try to use MetaData to do a faster search.

If the date is after last date in file the fileposition is left at EOF and an IOException is thrown.

Parameters:
d - the date to be found.
fromStart - if true then serach file from beginning, not using MetaData, else proceed from current file position.
before - if true position before date else at or after date
Returns:
the position for the data item that follows this one

getFirst

public DatabaseObject getFirst()
                        throws java.io.IOException
Gets the first database object in the database.
Returns:
the first DatabaseObject from the database

getLast

public DatabaseObject getLast()
                       throws java.io.IOException
Gets the last database object in the database
Returns:
the last DatabaseObject from the database

retrieve

public final java.util.Vector retrieve()
                                throws java.io.IOException
Gets all objects in the database (returned in a Vector). Note: We should take care when using this so that we don't exhaust memory. You should use one of the other retrieve methods when you want to load data.
Returns:
a Vector containing all DatabaseObjects.

retrieve

public final java.lang.Object retrieve(java.util.Date sd)
                                throws java.io.IOException
Gets the object before this date.
Parameters:
sd - the search date
Returns:
object before the search date.

retrieve

public final java.util.Vector retrieve(java.util.Date sd,
                                       java.util.Date ed)
                                throws java.io.IOException
Gets the objects between the two dates. If the first date is after the second date, only the object at the first date will be returned.
Parameters:
sd - start date for search
ed - end date for search
Returns:
a Vector containing the DatabaseObjects between the dates.

retrieve

public final java.util.Vector retrieve(java.util.Date sd,
                                       java.util.Date ed,
                                       boolean before)
                                throws java.io.IOException
Gets the DatabaseObjects between the dates. If the first date is after the second date, only the object at the first date will be returned.
Parameters:
sd - start date for search
ed - end date for search
before - if true then the first object returned is before the start search date.
Returns:
a Vector containing the DatabaseObjects between the dates.

retrieveOTS

public final ObjectTimeSeries retrieveOTS(java.util.Date sd,
                                          java.util.Date ed,
                                          boolean before)
                                   throws java.io.IOException,
                                          IllegalTimeSeriesException
Gets an ObjectTimeSeries containing data between the dates. See also retrieve(Date, Date, boolean)
Parameters:
sd - start date for search
ed - end date for search
before - if true then the first object returned is before the start search date.
Returns:
the ObjectTimeSeries

retrieveTS

public final TimeSeries retrieveTS(java.util.Date sd,
                                   java.util.Date ed,
                                   boolean before)
                            throws java.io.IOException
Gets a TimeSeries containing data between the dates. See also retrieve(Date, Date, boolean) and retrieveOTS(Date, Date, boolean).
Parameters:
sd - start date for search
ed - end date for search
before - if true then the first object returned is before the start search date.
Returns:
the TimeSeries

retrieveTS

public final TimeSeries retrieveTS(java.util.Date sd,
                                   java.util.Date ed,
                                   boolean before,
                                   long sampleInterval)
                            throws java.io.IOException,
                                   TimeSeriesException
Gets a TimeSeries containing data between the dates, the data is resampled if needed to the sampleinterval stated. See also retrieve(Date, Date, boolean) and retrieveOTS(Date, Date, boolean).
Parameters:
sd - start date for search
ed - end date for search
before - if true then the first object returned is before the start search date.
sampleInterval - timestep that the data should have [ms]
Returns:
the TimeSeries

retrieveAVE

public TimeSeries retrieveAVE(int fieldIndex,
                              java.util.Date[] events,
                              long start,
                              long end)
                       throws java.io.IOException,
                              TimeSeriesIndexException,
                              IllegalTimeSeriesException
Retrieves a TimeSeries object containing the averaged data for the input event list.

Every date/time in the events list is used as time reference for data retrieval, the start and end parameters define the time window for which data is retrieved. If data for any of these time windows is missing an IOException is thrown. The data loaded for every event is averaged, time is set from the middle of the event data. A TimeSeries object containing the data field indicated is created from the averaged data.

Parameters:
fieldIndex - index of the data field
events - array of event times
start - event window starts here (normally negative [milliseconds])
end - event window ends here (normally positiv [milliseconds])
Returns:
TimeSeries object with averaged fieldName data for start to end time for every event
Throws:
TimeSeriesIndexException - when fieldIndex is out of bounds
java.io.IOException - when data for any of the event times are missing

retrieveAVE

public TimeSeries retrieveAVE(int fieldIndex,
                              java.util.Date[] events,
                              long start,
                              long end,
                              boolean withAdditionalInfo)
                       throws java.io.IOException,
                              TimeSeriesIndexException,
                              IllegalTimeSeriesException
Retrieves a TimeSeries object containing the averaged data for the input event list.

Every date/time in the events list is used as time reference for data retrieval, the start and end parameters define the time window for which data is retrieved. If data for any of these time windows is missing an IOException is thrown. The data loaded for every event is averaged, time is set from the middle of the event data. A TimeSeries object containing the data field indicated, the number of datapoints used in the average and the standard deviation is created from the averaged data.

Parameters:
fieldIndex - index of the data field
events - array of event times
start - event window starts here (normally negative [milliseconds])
end - event window ends here (normally positiv [milliseconds])
withAdditionalInfo - if false run the other method retrieveAVE(int, Date[], long, long).
Returns:
TimeSeries object with averaged fieldName data for start to end time for every event
Throws:
TimeSeriesIndexException - when fieldIndex is out of bounds
java.io.IOException - when data for any of the event times are missing

retrieveSEA

public TimeSeries retrieveSEA(int fieldIndex,
                              java.util.Date[] events,
                              long start,
                              long end,
                              boolean withAdditionalInfo)
                       throws java.io.IOException,
                              TimeSeriesIndexException,
                              IllegalTimeSeriesException
Retrieves a TimeSeries object containing the averaged data for the input event list.

Every date/time in the events list is used as time reference for data retrieval, the start and end parameters define the time window for which data is retrieved. If data for any of these time windows is missing an IOException is thrown. The data field indicated is averaged over the events. A TimeSeries object containing the data field indicated, the number of datapoints used in the average and the standard deviation is created from the averaged data.

Parameters:
fieldIndex - index of the data field
events - array of event times
start - event window starts here (normally negative [milliseconds])
end - event window ends here (normally positiv [milliseconds])
withAdditionalInfo - Not used yet
Returns:
TimeSeries object with averaged fieldName data for every event.
Throws:
TimeSeriesIndexException - when fieldIndex is out of bounds
java.io.IOException - when data for any of the event times are missing

getTimeSeries

public TimeSeries getTimeSeries(java.util.Date sd,
                                java.util.Date ed,
                                long limit)
                         throws java.io.IOException,
                                MetaNotSetException,
                                TimestepException,
                                DatabaseException
Gets a TimeSeries object. The limit parameter will be the maximum memory consumption of the resultimg TimeSeries object, in other words the data will be resampled to fit into that memory.

Note: This method only handles data with constant timestep.

Parameters:
sd - start date for search
ed - end date for search
limit - limits the size of the TimeSeries object
Returns:
TimeSeries contains data between the dates, possibly reduced

getResampledTimeSeries

public TimeSeries getResampledTimeSeries(java.util.Date sd,
                                         java.util.Date ed,
                                         long sampleInterval)
                                  throws java.io.IOException,
                                         MetaNotSetException,
                                         TimestepException,
                                         DatabaseException
Gets a TimeSeries object. If needed, the data is resampled to match the required sample interval. Note: This method only handles data with constant timestep.
Parameters:
sd - start date for search
ed - end date for search
sampleInterval - data is resampled to this interval if needed [ms]
Returns:
TimeSeries contains data between the dates, possibly reduced

average

private DatabaseObject average(java.util.Vector vec)
Averages this data. Note: This method only handles data with constant timestep.
Parameters:
vec - a Vector containing the data to be averaged
Returns:
the averaged DatabaseObject with time set to the middle of the input data

average

private DatabaseObject[] average(java.util.Vector vec,
                                 int ave)
                          throws DatabaseException
Averages this data. Note: This method only handles data with constant timestep.
Parameters:
vec - a Vector containing the data to be averaged
ave - defines the number of objects that will be averaged
Returns:
a Vector containing DatabaseObjects averaged according the ave parameter
Throws:
DatabaseException - even number of elements

getDataGapValue

protected double getDataGapValue()
Gets the dataGapValue.
Returns:
the dataGapValue.

store

public final void store(java.util.Vector vec)
Stores DatabaseObjects to file without checking the input data.

Note:You should not use this version of the store method ! See store(ObjectTimeSeries)

Parameters:
vec - data to be stored

store

public final void store(ObjectTimeSeries ts)
Stores DatabaseObjects to file. This version of store will do the necessary checks on the ObjectTimeSeries so that it is safe to write it to our database. Currently it will only allow writing if the TimeSeries follows the rules for the specific database. Data will not be written if it's not inside the start and end time in the MetaData (end time can be endtime + timestep).
Parameters:
ts - ObjectTimeSeries containing the data thats about to be stored

importAscii

protected void importAscii(java.lang.String inputfile)
Imports ASCII data to our database. The format of the data is as output from ExportAscii application. It will fill a buffer of DatabaseObjects and then try to store it, read again and store until it is finished or an exception occures.

Note: Currently the buffering doesn't work ! vectors below 200Mb in size is imported correctly.

Parameters:
inputfile - the file containing the data to be imported

read

public abstract java.lang.Object read()
                               throws java.io.IOException
Gets the object at the current point in file.
Returns:
an object from the database
Throws:
java.io.IOException - when reading fails

write

public abstract void write(java.lang.Object dbo)
                    throws java.io.IOException
Writes data at the current point in file.
Parameters:
dbo - an object containg data to be written.
Throws:
java.io.IOException - when writeing fails

getDate

public abstract java.util.Date getDate(java.lang.Object obj)
Gets the date from this object. See also DatabaseObject.getDate().
Parameters:
obj - a database object
Returns:
the Date for the input object

getLatestDatabaseObjects

public abstract java.util.Vector getLatestDatabaseObjects()
Do not use this method it will be removed !

setDefaultMeta

protected abstract MetaData setDefaultMeta(java.util.Date sd,
                                           java.util.Date ed)
                                    throws java.io.IOException
Sets the MetaData for the specific database and stores it to file.
Parameters:
sd - start time of data in datafile
ed - end time of data in datafile
Returns:
the new MetaData object
Throws:
java.io.IOException - when save of MetaData fails

getEmptyMetaData

protected abstract MetaData getEmptyMetaData(java.util.Date sd,
                                             java.util.Date ed)
Gets a MetaData object with the dates set to the supplied dates.
Parameters:
sd - fake start date
ed - fake end date
Returns:
the fake MetaData object