...
/* ================================================================
* Delft FEWS
* ================================================================
*
* Project Info: http://www.wldelft.nl/soft/fews/index.html
* Project Lead: Karel Heynert (karel.heynert@wldelft.nl)
*
* (C) Copyright 2003, by WL | Delft Hydraulics
* P.O. Box 177
* 2600 MH Delft
* The Netherlands
* http://www.wldelft.nl
*
* DELFT-FEWS is a sophisticated collection of modules designed
* for building a FEWS customised to the specific requirements
* of individual agencies. An open modelling approach allows users
* to add their own modules in an efficient way.
*
* ----------------------------------------------------------------
* TimeSeriesContentHandler.java
* ----------------------------------------------------------------
* (C) Copyright 2003, by WL | Delft Hydraulics
*
* Original Author: Onno van den Akker
*/
package nl.wldelft.util.timeseries;
import nl.wldelft.util.ExternalFloatsReference;
import nl.wldelft.util.Missings;
import nl.wldelft.util.Period;
import nl.wldelft.util.Properties;
import nl.wldelft.util.Season;
import nl.wldelft.util.coverage.Geometry;
import nl.wldelft.util.geodatum.GeoDatum;
import nl.wldelft.util.ratingcurve.RatingCurveEquation;
import nl.wldelft.util.ratingcurve.RatingCurveInterpolationMethod;
import java.text.SimpleDateFormat;
import java.util.TimeZone;
/**
* The interface <code>TimeSeriesContentHandler</code> represents the classes
* to handle the time series data that are supplied by the time series parsers.
*/
public interface TimeSeriesContentHandler {
/**
* Defines time zone which should be used while importing time series.
* If time zone is defined in the file format - this TimeZone should not be used.
* @return
*/
TimeZone getDefaultTimeZone();
void clearMissingValues();
/**
* Adds a value that should be recognized as missing when calling {@link #setValue(float)}, {@link #setValue(char, String)} or {@link #setCoverageValues(float[])}
* {@link Float#NaN} is always recognized as missing
*/
void addMissingValue(float missingValue);
/**
* Adds a alpha numeric tag that should be recognized as missing when calling {@link #setValue(char, String)}
* These alphanumeric missings are not recognized when using {@link #setValue(float)} or {@link #setCoverageValues(float[])}
* The missings added with {@link #addMissingValue(float)} and {@link #addMissingValueRange(float, float)} are also recognized
* {@link Float#NaN} is always recognized as missing
*
*/
void addMissingValue(String missingValue);
/**
* Adds a range of values that should be recognized as missing when calling {@link #setValue} or {@link #setCoverageValues(float[])}
* NaN, null and an empty string, string with only spaces are always recognized as missing
*/
void addMissingValueRange(float minMissingValue, float maxMissingValue);
/**
* Creating an alias allows high speed switching between different headers
* E.g. For files with multiple parameters per row, for every row multiple switches are required between different headers
* This will not work properly without defining an alias for every column
* The alias is ultimate fast in the range form 0 to 1000
*
* @param alias, integer for ultimate speed, good practice is to use the parameter column index.
* @param header
*/
void createTimeSeriesHeaderAlias(int alias, TimeSeriesHeader header);
/**
* Changes the header that will be used when calling {@link #applyCurrentFields()}
* A call to this method will not consume any significant time
* {@link #setTimeSeriesHeader(TimeSeriesHeader)} is relatively time consuming
* @see #createTimeSeriesHeaderAlias(int, TimeSeriesHeader)
* @param alias defined with {@link #createTimeSeriesHeaderAlias (int, TimeSeriesHeader)}
* @throws IllegalArgumentException when alias is not created before
*/
void setTimeSeriesHeader(int alias);
/**
* Same as {@link #setTimeSeriesHeader(int)} , but slightly SLOWER
* The second time this method is called for the SAME header,
* there is NO new time series created but the first one is re-selected
* This method is relatively time consuming.
* When parsing multiple parameters per row use {@link #setTimeSeriesHeader (int)}
*/
void setTimeSeriesHeader(TimeSeriesHeader header);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
* A NEW time series is created, with a new forecast time and new ensemble member index
* A warning is logged when this method is called twice for the same header (historical non ensemble time series)
*/
void setNewTimeSeriesHeader(TimeSeriesHeader header);
/**
* The parser should call this method when it starts parsing time/values and has any idea of the period of the values that will come.
* This information is only used by this content handler for OPTIMISATION and
* is never required and never results in an error when the real period is differs from the estimated period
* @param period
*/
void setEstimatedPeriod(Period period);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
*
* @param time Represents the number of milliseconds since January 1, 1970, 00:00:00 GMT
*/
void setTime(long time);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
*
* @param time Represents the number of milliseconds since January 1, 1970, 00:00:00 GMT
* @param minTime Represents the number of milliseconds since January 1, 1970, 00:00:00 GMT
* @param maxTime Represents the number of milliseconds since January 1, 1970, 00:00:00 GMT
*/
void setTimeAndRange(long time, long startTime, long endTime);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
*
* @param timeZone
* @param year eg 1996
* @param oneBasedMonth 1 .. 12 (1==January)
* @param dayOfMonth 1 .. 31
* @param hourInDay 0 .. 23
* @param minute 0 .. 59
* @param second 0 .. 59
* @param millis 0 .. 999
*/
void setTime(TimeZone timeZone, int year, int oneBasedMonth, int dayOfMonth, int hourInDay, int minute, int second, int millis);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
*
* In addition to simple date format 24h will be recognized as 0h the next day
*
* @param timeZone. When not known use {@link #getDefaultTimeZone()}
* @param pattern see {@link SimpleDateFormat}, in addition for HH 24 will be recognized as 0:00 the next day
* @param dateTime leading and trailing spaces are ignored
*/
void setTime(TimeZone timeZone, String pattern, String dateTime);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
* <p>
* In addition to simple date format 24h will be recognized as 0h the next day
*
* @param timeZone. When not known use {@link #getDefaultTimeZone()}
* @param pattern see {@link SimpleDateFormat}, in addition for HH 24 will be recognized as 0:00 the next day
* @param dateTime leading and trailing spaces are ignored
* @param startDateTime leading and trailing spaces are ignored
* @param endDateTime leading and trailing spaces are ignored
*/
void setTimeAndRange(TimeZone timeZone, String pattern, String dateTime, String startDateTime, String endDateTime);
/**
* Changes the time that will be used when calling {@link #applyCurrentFields()}
*
* In addition to simple date format 24h will be recognized as 0h the next day
*
* @param timeZone. When not known use {@link #getDefaultTimeZone()}
* @param datePattern see {@link SimpleDateFormat}
* @param date leading and trailing spaces are ignored
* @param timePattern see {@link SimpleDateFormat}, in addition for HH 24 will be recognized as 0:00 the next day
* @param time leading and trailing spaces are ignored
*/
void setTime(TimeZone timeZone, String datePattern, String date, String timePattern, String time);
/**
* Return false if any value for the selected time series with {@link #setTimeSeriesHeader} is wanted
* When true parsing of ALL values for this time series can be skipped
*/
boolean isCurrentTimeSeriesHeaderForAllTimesRejected();
/**
* Return false if the value selected time {@link #setTimeSeriesHeader} and selected time {@link #setTime(long)} is wanted
* When true parsing of the time and time series can be skipped
*/
boolean isCurrentTimeSeriesHeaderForCurrentTimeRejected();
/**
* Return tue if the selected time series {@link #setTimeSeriesHeader} is alphanumeric
*/
boolean isCurrentTimeSeriesAlphanumeric();
/**
* Return tue if the selected time series {@link #setTimeSeriesHeader} is of TimeSeriesType temporary
*/
boolean isCurrentTimeSeriesTemporary();
/**
* Changes the flag that will be used for when calling {@link #applyCurrentFields()}
*/
void setFlag(int flag);
/**
* Changes the flag that will be used for when calling {@link #applyCurrentFields()}
*/
void setFlag(String flag);
/**
* Changes the flag that will be used for when calling {@link #applyCurrentFields()}
*/
void setFlag(Flag flag);
/**
* Changes the flag source that will be used for when calling {@link #applyCurrentFields()}
* When a flag is marked as manual the flag will be fixed until the value is changed
* An automatic flag can be changed on automatic revalidation (rate of change)
*/
void setFlagSource(String flag);
/**
* Clear all flag source columns.
*/
void clearFlagSourceColumns();
/**
* Adds a new flag source column
* The returned index should be used for {@link #setColumnFlagSource(int, String)}
*/
int addFlagSourceColumn(String flagSourceColumnId);
/**
* Set the flag source for the specified flag source column
* Use {@link #addFlagSourceColumn(String)} for the columnIndex
*/
void setColumnFlagSource(int columnIndex, String flagSource);
/**
* Changes the sample id that will be used for when calling {@link #applyCurrentFields()}
*/
void setSampleId(String sampleId);
void setModifierName(String modifierName);
/**
* Changes the out of detection range that will be used when calling {@link #applyCurrentFields()}
*/
void setOutOfDetectionRangeFlag(OutOfDetectionRangeFlag flag);
/**
* Changes the {@link State} that will be used when calling {@link #applyCurrentFields()}
*/
void setState(State state);
/**
* Changes the comment that will be used when calling {@link #applyCurrentFields()}
*/
void setComment(String comment);
/**
* Changes the user that will be used when calling {@link #applyCurrentFields()}
*/
void setUser(String user);
/**
* Changes the
...
properties that will be used when calling {@link
...
#applyCurrentFields()}
...
*
...
The ...
properties ...
are ...
used ...
as ...
extra ...
tags, ...
like ...
comments, that is stored per value
*/
void setProperties(Properties properties);
/**
*
...
When ...
a ...
overruling ...
geometry is ...
defined ...
(in grids.xml) this geometry will overturn the geometry set with {@link #setGeometry(Geometry)}
...
*...
When there is a ...
overruling ...
geometry ...
the ...
content handler will log an error when the number of rows and cols is not the same a set with {@link #setGeometry(Geometry)}
*
...
@return
...
...
...
...
...
*/
...
...
...
...
Geometry getOverrulingGeometry();
/**
...
...
...
...
* ...
Used ...
by ...
the parser to create a ...
geometry ...
when ...
there ...
is ...
no ...
geometry ...
info ...
available ...
in ...
the file
*/
...
...
GeoDatum ...
getDefaultGeoDatum(
...
);
...
/**
...
* Changes the
...
geometry that will be used when calling {@link
...
#applyCurrentFields()}
...
*
...
...
...
...
...
* ...
When ...
only ...
the ...
number ...
of ...
rows and ...
cols ...
are ...
available ...
use {@link
...
NonGeoReferencedGridGeometry#create(int, int))))|
* @see #getDefaultGeoDatum()
*/
...
void
...
setGeometry(
...
Geometry ...
geometry);
...
/**
...
...
...
...
* ...
Changes ...
the ...
value resolution that will be ...
used ...
when ...
calling ...
{@link #applyCurrentFields()}
* Only be used when the file format don't uses IEEE floats to store the values
* e.g. When there are only integers parsed the value resolution is 1.0
* e.g. When there at maximum to decimals the value resolution is 0.01;
*
...
e.g. When file format store the values as integers and divides the integers by 5 afterwards the value resolution is 0.2
*
* @param valueResolution
*/
...
void
...
setValueResolution(
...
float ...
valueResolution);
...
/**
...
* Changes
...
the domain axes value resolutions that will be used when calling {@link
...
#applyCurrentFields()}
...
*
...
Only be used when the file format don't uses IEEE floats to store the values
* e.g. When there are only integers parsed the value resolution is 1.0
*
...
e.g. When there at maximum ...
to ...
decimals ...
the ...
value ...
resolution ...
is 0.01;
* e.g.
...
When ...
file ...
format ...
store ...
the values as integers and divides the integers by 5 afterwards the value resolution is 0.2
*
...
...
...
...
...
* ...
@param ...
valueResolutions
...
...
*/...
void
...
setDomainAxesValueResolutions(float... valueResolutions);
/**
...
* Changes the
...
value that will be used...
when calling {@link #applyCurrentFields()}
*/
void setValue(float value);
/**
*
...
Changes the value that will be used when calling {@link
...
#applyCurrentFields()}
...
*
...
When ...
the ...
value ...
is missing the minValue and maxValue should also be missing (and visa versa)
*/
void setValueAndRange(float value, float minValue, float maxValue);
/**
* Changes the value that will be used when calling {@link #applyCurrentFields()}
*
...
When the value ...
can ...
not be parsed an error will be logged, no exception is thrown
*
...
Add ...
missing ...
value...
...
tags ...
before ...
calling ...
this ...
function {@link
...
#addMissingValue(String)}
...
* e.g. addMissingValue('?')
*
...
...
...
...
...
* ...
@param ...
value ...
leading ...
and ...
trailing ...
spaces ...
are ...
ignored
*/
...
...
void ...
setValue(char decimalSeparator, String value);
...
/**
...
*
...
Changes the value ...
that ...
will ...
be ...
used ...
when ...
calling {@link
...
#applyCurrentFields(
...
)}
...
* When the value can not be parsed an error will be logged, no exception is thrown
* Add missing value tags before calling this function {@link #addMissingValue(String)}
* e.g. addMissingValue('?')
* When the value is missing the minValue and maxValue should also be missing (and visa versa)
*
* @param value leading and trailing spaces are ignored
*/
...
...
...
...
void ...
setValueAndRange(char decimalSeparator, String value, String minValue, String maxValue);
/**
*
...
Puts ...
the ...
domain ...
axes values. For a spectrum these are the frequencies. For directional spectrum the first domain axis is the frequency and the second domain axis is the direction.
* The domain axis index is zero based.
*
...
For ...
performance ...
reasons ...
do ...
not ...
parse ...
the ...
values ...
when ...
{@link
...
#isCurrentTimeSeriesHeaderForCurrentTimeRejected()}
...
returns true
*
...
For performance reasons do no recreate the values array for every time step again
...
* When all values (e.g. all time steps) share the ...
same ...
domain ...
axis ...
values ...
only ...
call ...
this ...
method once
*
...
...
* @see #setValues
*/
...
...
void setDomainAxesValues(float[]... domainAxesValues);
/**
* Puts the values for the specified domains. eg. For a spectrum these are the energy values for all the frequency bands
* The number of values should equal the domain0.length * domain1.length * domain2.length etc {@link #setDomainAxesValues(float[]...)}
*
...
The index of one value when having two domains is domain1Index + domain0Index * domain1.length.
* When having two domains the first domain axis represent the rows and the second domain axis represent the columns
*
...
The size of each domain axis may change every time step
* For
...
performance ...
reasons ...
do ...
not ...
parse ...
the ...
values when ...
{@link
...
#isCurrentTimeSeriesHeaderForCurrentTimeRejected()}
...
returns true
*
...
For performance reasons do ...
not ...
call ...
when the...
domain axes values are not changes. Most of ...
the time ...
all ...
time ...
steps ...
share ...
the ...
same domain values
* @see
...
#setDomainAxesValues(float[]...)
*/
...
void
...
setValues(
...
float[]
...
values);
...
/**
...
*
...
Puts the string values for the specified domains. Equivalent of the function {@link #setValues(float[] values)}
* When one or more values can not be parsed an error will be logged, no exception is thrown
* Add missing value tags before calling this function {@link #addMissingValue(String)}
* e.g.
...
addMissingValue('?')
*
* @param values leading and trailing spaces are ignored
*/
void setValues(char decimalSeparator, String[] values);
/**
* Puts the coverage values for the last set time and and last set header with the last set flag and last set geometry
*
...
When {@link
...
#getOverrulingGeometry
...
(...
)} returns not null there is no need to to set the geometry
* When the active geometry does not have the same number of rows and cols an error message is logged.
*
...
For performance reasons do not parse the values when ...
{@link
...
#isCurrentTimeSeriesHeaderForCurrentTimeRejected()} returns true
*
...
...
For ...
performance ...
reasons ...
do ...
no ...
recreate ...
the ...
values ...
array ...
for ...
every ...
time ...
step ...
again
...
*/
...
...
...
...
void setCoverageValues(float[] values);
void setCoverageValues(ExternalFloatsReference externalFloatsReference, float minValue, float maxValue, Missings missings);
void setRatingCurveStageValues(float[] values);
void setRatingCurveDischargeValues(float[] values);
void setRatingCurveMinStageValue(float min);
void setRatingCurveMaxStageValue(float max);
void setRatingCurveInterpolationMethod(RatingCurveInterpolationMethod interpolationMethod);
void
...
setRatingCurveLogScaleStraightLineStageOffsets(
...
float[] values);
/**
...
* Sets
...
the rating ...
curve ...
table ...
flags for ...
each row, null is allowed
*/
void setRatingCurveFlags(int[] flags);
default void addRatingCurveEquation(RatingCurveEquation equation) {
}
void setRatingCurveSeason(Season season);
void setRatingCurvePeriod(Period period);
/**
* When value is marked manual it can not be overwritten with an value that is marked automatic
*/
void setValueSource(ValueSource flag);
/**
* Saves the current fields for the current time series header and current time.
* The current fields are not cleared so it is only required
* to update the changed fields for the next call to {@link #applyCurrentFields()}
*/
void applyCurrentFields();
default void setImportState(String importState) {
// noop.
}
default String getImportState() {
return null;
}
default void rejectSample() {}
}