ch.agent.t2.time

Class TimeFactory

java.lang.Object

ch.agent.t2.time.TimeFactory

All Implemented Interfaces:

TimeDomain, TimeFormatter, TimePacker, TimeScanner

public class TimeFactory
extends Object
implements TimeDomain, TimePacker, TimeFormatter, TimeScanner

A TimeFactory makes TimeIndex objects and acts as an immutable TimeDomain. A time domain is defined by the following 4 properties:

1. the resolution, which is never null,
2. the origin, which is long offset from the base time of January 1 year zero,
3. a base period pattern, which can be null,
4. a sub period pattern, which can be null.

Author:

Jean-Paul Vetterli

See Also:

Resolution, BasePeriodPattern, SubPeriodPattern

Field Summary

Fields inherited from interface ch.agent.t2.time.TimeDomain

BASE_YEAR_FOR_NANO, DAYS_TO_19700101, DAYS_TO_20000101

Constructor Summary

Constructors

Constructor and Description
TimeFactory(TimeDomainDefinition def) Constructor providing a default time formatter and time scanner.
TimeFactory(TimeDomainDefinition def, TimeFormatter formatter) Constructor providing a default time scanner.
TimeFactory(TimeDomainDefinition def, TimeFormatter formatter, TimeScanner scanner) Construct a TimeFactory for the given time domain.

Method Summary

Modifier and Type	Method and Description
int	compareResolutionTo(Resolution unit) Return a negative, zero, positive number if the resolution is higher, the same, or lower than the argument.
boolean	equals(Object obj)
String	format(TimeParts timeParts) Generate a string representing the time in the time parts object.
BasePeriodPattern	getBasePeriodPattern() Return the base period pattern.
int	getBasePeriodSize() Return the number of time points within a base period.
TimeIndex	getBasePeriodStart(TimeIndex t) Return the time index of the first time point in the base period containing the time specified.
DayOfWeek	getDayOfWeek(TimeIndex time) Return the day of week for the given time.
TimeFormatter	getFormatter() Return the time formatter to use when formatting times in this domain.
String	getLabel() Return the label of the time domain, uniquely identifying the domain when using a TimeDomainCatalog.
long	getOrigin() Return the origin of the time domain.
TimePacker	getPacker() Return the time packer to use for processing times in this domain.
Resolution	getResolution() Return the resolution of the time domain.
TimeScanner	getScanner() Return the time scanner to use when scanning strings as times in this domain.
SubPeriodPattern	getSubPeriodPattern() Return the sub period pattern.
int	hashCode()
TimeIndex	maxTime() Return a new TimeIndex giving the maximum time in this domain.
TimeIndex	maxTime(boolean offsetCompatible) Return a new TimeIndex giving the maximum time in this domain.
TimeIndex	minTime() Return a new TimeIndex giving the minimum time in this domain.
TimeIndex	minTime(boolean offsetCompatible) Return a new TimeIndex giving the minimum time in this domain.
long	pack(TimeParts tp, Adjustment adjust) Pack the component elements of the time into a numeric time index.
void	requireEquality(TimeDomain domain) Throw an exception if the domain is not equal to this domain.
TimeParts	scan(Resolution unit, String time) Scan the date string into a time parts object.
boolean	similar(TimeDomain domain) Compare to another time domain, ignoring label.
TimeIndex	time(long index) Return a new TimeIndex corresponding to the given index.
TimeIndex	time(long year, int month, int day, int hour, int min, int sec, int usec, Adjustment adjust) Return a new TimeIndex corresponding to the list of parameters.
TimeIndex	time(String date) Return a new TimeIndex corresponding to the given date string.
TimeIndex	time(String date, Adjustment adjust) Return a new TimeIndex corresponding to the given date string.
TimeIndex	timeFromOffset(long offset) Return a new TimeIndex corresponding to the given offset.
String	toString()
TimeParts	unpack(long time) Unpack the numeric representation of time into its component elements.
boolean	valid(long t, boolean testOnly) Return true if the numeric time index is valid for the domain.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TimeFactory

public TimeFactory(TimeDomainDefinition def,
                   TimeFormatter formatter,
                   TimeScanner scanner)

Construct a TimeFactory for the given time domain.

Parameters:

def - a non-null time domain definition

formatter - a non-null time formatter

scanner - a non-null time scanner

TimeFactory

public TimeFactory(TimeDomainDefinition def)

Constructor providing a default time formatter and time scanner.

Parameters:

def - a non-null time domain definition

TimeFactory

public TimeFactory(TimeDomainDefinition def,
                   TimeFormatter formatter)

Constructor providing a default time scanner.

Parameters:

def - a non-null time domain definition

formatter - a non-null time formatter

Method Detail

getPacker

public TimePacker getPacker()

Description copied from interface: TimeDomain

Return the time packer to use for processing times in this domain.

Specified by:

getPacker in interface TimeDomain

Returns:

a time packer, never null

getFormatter

public TimeFormatter getFormatter()

Description copied from interface: TimeDomain

Return the time formatter to use when formatting times in this domain.

Specified by:

getFormatter in interface TimeDomain

Returns:

a time formatter, never null

getScanner

public TimeScanner getScanner()

Description copied from interface: TimeDomain

Return the time scanner to use when scanning strings as times in this domain.

Specified by:

getScanner in interface TimeDomain

Returns:

a time scanner, never null

getLabel

public String getLabel()

Description copied from interface: TimeDomain

Return the label of the time domain, uniquely identifying the domain when using a TimeDomainCatalog.

Specified by:

getLabel in interface TimeDomain

Returns:

the label of the time domain

getOrigin

public long getOrigin()

Description copied from interface: TimeDomain

Return the origin of the time domain. By default it is 0L.

Specified by:

getOrigin in interface TimeDomain

Returns:

a positive or negative number

getResolution

public Resolution getResolution()

Description copied from interface: TimeDomain

Return the resolution of the time domain.

Specified by:

getResolution in interface TimeDomain

Returns:

a time unit

compareResolutionTo

public int compareResolutionTo(Resolution unit)

Description copied from interface: TimeDomain

Return a negative, zero, positive number if the resolution is higher, the same, or lower than the argument. To make things completely clear, second resolution is higher than year resolution.

Specified by:

compareResolutionTo in interface TimeDomain

Parameters:

unit - a non-null resolution

Returns:

a negative (zero, positive) number if the resolution is higher (same, lower) than the argument

requireEquality

public void requireEquality(TimeDomain domain)
                     throws T2Exception

Description copied from interface: TimeDomain

Throw an exception if the domain is not equal to this domain.

Specified by:

requireEquality in interface TimeDomain

Parameters:

domain - a time domain

Throws:

T2Exception

similar

public boolean similar(TimeDomain domain)

Description copied from interface: TimeDomain

Compare to another time domain, ignoring label. Two time domains are similar if they have the same implementation and all their members other than the label are equal.

Specified by:

similar in interface TimeDomain

Parameters:

domain - a time domain

Returns:

true if the time domains are similar

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

time

public TimeIndex time(long year,
                      int month,
                      int day,
                      int hour,
                      int min,
                      int sec,
                      int usec,
                      Adjustment adjust)
               throws T2Exception

Description copied from interface: TimeDomain

Return a new TimeIndex corresponding to the list of parameters. If necessary, adjustments are made as specified. An exception is thrown if an adjustment is required but not allowed.

See the comment in TimeDomain.time(String) for important details about discarding unnecessary time components.

Specified by:

time in interface TimeDomain

Parameters:

year - the year

month - the month

day - the day

hour - the hour

min - the minute

sec - the second

usec - the microsecond

adjust - a non-null adjustment mode

Returns:

a TimeIndex in the domain

Throws:

T2Exception

time

public TimeIndex time(String date)
               throws T2Exception

Description copied from interface: TimeDomain

Return a new TimeIndex corresponding to the given date string. Adjustments are not allowed. The date syntax is the one implemented by DefaultTimeScanner.

Date and time components too precise for the resolution of the time domain are discarded. As an example, all time components are discarded when the resolution is daily or less. There are cases where the time components have an effect on a date component. In such cases it is necessary to use first a higher resolution time domain then to convert to the wanted domain. An example of such a case is when the time component includes a time zone offset which changes the day (and possibly the month and year, as on January first or December 31).

Specified by:

time in interface TimeDomain

Parameters:

date - a non-null date string

Returns:

a TimeIndex in the domain

Throws:

T2Exception

time

public TimeIndex time(String date,
                      Adjustment adjust)
               throws T2Exception

Description copied from interface: TimeDomain

Return a new TimeIndex corresponding to the given date string. If necessary, adjustments are made as specified. An exception is thrown if an adjustment is required but not allowed. The date syntax is the one implemented by DefaultTimeScanner.

See the comment in TimeDomain.time(String) for important details about discarding unnecessary time components.

Specified by:

time in interface TimeDomain

Parameters:

date - a non-null date string

adjust - a non-null adjustment mode

Returns:

a TimeIndex in the domain

Throws:

T2Exception

minTime

public TimeIndex minTime()

Description copied from interface: TimeDomain

Return a new TimeIndex giving the minimum time in this domain. The result is equivalent to that of minTime(false).

Specified by:

minTime in interface TimeDomain

Returns:

a TimeIndex in the domain

maxTime

public TimeIndex maxTime()

Description copied from interface: TimeDomain

Return a new TimeIndex giving the maximum time in this domain. The result is equivalent to that of maxTime(false).

Specified by:

maxTime in interface TimeDomain

Returns:

a TimeIndex in the domain

minTime

public TimeIndex minTime(boolean offsetCompatible)

Description copied from interface: TimeDomain

Return a new TimeIndex giving the minimum time in this domain.

Specified by:

minTime in interface TimeDomain

Parameters:

offsetCompatible - if true, return a TimeIndex representable as an offset

Returns:

a TimeIndex in the domain

See Also:

TimeIndex.asOffset()

maxTime

public TimeIndex maxTime(boolean offsetCompatible)

Description copied from interface: TimeDomain

Return a new TimeIndex giving the maximum time in this domain.

Specified by:

maxTime in interface TimeDomain

Parameters:

offsetCompatible - if true, return a TimeIndex representable as an offset

Returns:

a TimeIndex in the domain

See Also:

TimeIndex.asOffset()

time

public TimeIndex time(long index)

Description copied from interface: TimeDomain

Return a new TimeIndex corresponding to the given index.

Specified by:

time in interface TimeDomain

Parameters:

index - a number

Returns:

a TimeIndex in the domain

timeFromOffset

public TimeIndex timeFromOffset(long offset)

Description copied from interface: TimeDomain

Return a new TimeIndex corresponding to the given offset.

Specified by:

timeFromOffset in interface TimeDomain

Parameters:

offset - a number to be added to the domain's origin

Returns:

a TimeIndex in the domain

valid

public boolean valid(long t,
                     boolean testOnly)
              throws T2Exception

Description copied from interface: TimePacker

Return true if the numeric time index is valid for the domain. Depending on the testOnly argument, the method throws an exception when the time is not valid.

Specified by:

valid in interface TimePacker

Parameters:

t - numeric time to validate

testOnly - if true do not throw an exception when time is not valid

Returns:

true if valid

Throws:

T2Exception

getBasePeriodPattern

public BasePeriodPattern getBasePeriodPattern()

Description copied from interface: TimePacker

Return the base period pattern. This pattern is used to compress or decompress the raw numeric time index to or from a denser one. The result is null when no such pattern is defined.

Specified by:

getBasePeriodPattern in interface TimePacker

Returns:

the base period pattern or null

getSubPeriodPattern

public SubPeriodPattern getSubPeriodPattern()

Description copied from interface: TimePacker

Return the sub period pattern. This pattern is used to add sub periods to a base period. The result is null when no such pattern is defined.

Specified by:

getSubPeriodPattern in interface TimePacker

Returns:

the sub period pattern or null

scan

public TimeParts scan(Resolution unit,
                      String time)
               throws T2Exception

Description copied from interface: TimeScanner

Scan the date string into a time parts object. The scanner extracts fields from the input and assigns them to time parts without checking their validity. From the point of view of the scanner day 42 of month 99 is okay. The time resolution is used for interpreting fractional seconds if present, because in a decimal fraction, leading zeros are significant but trailing zeros can be omitted (for example 1 corresponds to 100 milliseconds but 100000 microseconds).

Specified by:

scan in interface TimeScanner

Parameters:

unit - the time resolution

time - a non-null string containing a date and time specification

Returns:

a TimeParts

Throws:

T2Exception

format

public String format(TimeParts timeParts)

Description copied from interface: TimeFormatter

Generate a string representing the time in the time parts object.

Specified by:

format in interface TimeFormatter

Parameters:

timeParts - a non-null time parts object

Returns:

a string with the external representation of the time

pack

public long pack(TimeParts tp,
                 Adjustment adjust)
          throws T2Exception

Description copied from interface: TimePacker

Pack the component elements of the time into a numeric time index. Depending on the domain, not all times exist. In such cases, the time is adjusted upwards or downwards if permitted. When a base period and a sub period pattern are both active, the adjustment applies only to the sub period.

Specified by:

pack in interface TimePacker

Parameters:

tp - a time parts object

adjust - a non-null adjustment mode

Returns:

a numerical time index

Throws:

T2Exception

unpack

public TimeParts unpack(long time)

Description copied from interface: TimePacker

Unpack the numeric representation of time into its component elements.

Specified by:

unpack in interface TimePacker

Parameters:

time - a numeric time index

Returns:

a TimeParts

getDayOfWeek

public DayOfWeek getDayOfWeek(TimeIndex time)
                       throws T2Exception

Description copied from interface: TimePacker

Return the day of week for the given time.

Specified by:

getDayOfWeek in interface TimePacker

Parameters:

time - a time index

Returns:

the day of the week

Throws:

T2Exception

getBasePeriodSize

public int getBasePeriodSize()

Description copied from interface: TimePacker

Return the number of time points within a base period. When there is sub period pattern, the result is its size, else it is 1.

Specified by:

getBasePeriodSize in interface TimePacker

Returns:

the number of time points within a base period

getBasePeriodStart

public TimeIndex getBasePeriodStart(TimeIndex t)

Description copied from interface: TimePacker

Return the time index of the first time point in the base period containing the time specified. When there is no period pattern, this is the same as the time specified.

Specified by:

getBasePeriodStart in interface TimePacker

Parameters:

t - a non-null time index, which must be from this time domain

Returns:

a time index