com.yahoo.bard.webservice.data.time

Interface TimeGrain

All Superinterfaces:

Granularity

All Known Subinterfaces:

ZonelessTimeGrain

All Known Implementing Classes:

DefaultTimeGrain, ZonedTimeGrain

public interface TimeGrain
extends Granularity

TimeGrain represents a strategy for Granularities to map time into monotonic increasing time buckets. Time Grains have a single field joda period. They use estimated duration to create a natural comparison ordering. Time grains support the concept of satisfiability, where a satisfies b if b can always be constructed from one or more a's exactly. Time grains can test an instant to determine whether it 'aligns', i.e. maps to a boundary between mapped time buckets under the grain. Time grains must also implement an error message describing legal alignments when expected alignment fails.

Method Summary

Modifier and Type	Method and Description
default boolean	accepts(Collection<org.joda.time.Interval> intervals) Determine if all intervals align with a granularity.
boolean	aligns(org.joda.time.DateTime dateTime) Determines if this dateTime falls on a time grain boundary.
default boolean	aligns(org.joda.time.Interval interval) Determines if this interval corresponds with time grain boundaries.
String	getAlignmentDescription() Get description of correct alignment of a granularity, e.g.
org.joda.time.Duration	getEstimatedDuration() Estimated duration gives a rough millisecond length of the TimeGrain usable for comparison.
String	getName() Get the name of the granularity.
org.joda.time.ReadablePeriod	getPeriod() Get the Period of the TimeGrain.
String	getPeriodString() Period string to use when serializing.
String	getType() Type of Granularity to use when serializing.
default Iterator<org.joda.time.Interval>	intervalsIterator(SimplifiedIntervalList intervals) Build an iterator from a pre-simplified list of intervals.
default org.joda.time.DateTime	roundCeiling(org.joda.time.DateTime dateTime) Round the DateTime to the "front edge" (ie.
org.joda.time.DateTime	roundFloor(org.joda.time.DateTime dateTime) Given a date time find the first instant at or before that date time which starts a time grain.
default boolean	satisfiedBy(Granularity that) Determine if this granularity can be fulfilled by an aggregate of another granularity.
boolean	satisfiedBy(TimeGrain grain) True if the argument grain can be used to build this grain.
String	toString()

Methods inherited from interface com.yahoo.bard.webservice.data.time.Granularity

intervalsIterable, intervalsIterator, satisfies

Method Detail

getType

String getType()

Type of Granularity to use when serializing.

Returns:

the type of the TimeGrain

getPeriodString

String getPeriodString()

Period string to use when serializing.

Returns:

the period string

roundFloor

org.joda.time.DateTime roundFloor(org.joda.time.DateTime dateTime)

Given a date time find the first instant at or before that date time which starts a time grain.

Parameters:

dateTime - The time being rounded

Returns:

The first date time instant of the bucket this date time maps into

roundCeiling

default org.joda.time.DateTime roundCeiling(org.joda.time.DateTime dateTime)

Round the DateTime to the "front edge" (ie. the most recent time) of the time bucket the DateTime falls in.

Parameters:

dateTime - DateTime to round

Returns:

the rounded DateTime

toString

String toString()

Overrides:

toString in class Object

getPeriod

org.joda.time.ReadablePeriod getPeriod()

Get the Period of the TimeGrain.

Returns:

the TimeGrain Period

getName

String getName()

Description copied from interface: Granularity

Get the name of the granularity.

Specified by:

getName in interface Granularity

Returns:

the granularity name

getAlignmentDescription

String getAlignmentDescription()

Description copied from interface: Granularity

Get description of correct alignment of a granularity, e.g. week

Specified by:

getAlignmentDescription in interface Granularity

Returns:

the correct alignment description

satisfiedBy

boolean satisfiedBy(TimeGrain grain)

True if the argument grain can be used to build this grain. This grain doesn't need to be a regular multiple of the reference grain. (e.g. months are an irregular number of days long) In the basic case this will support compositions such as days into months or weeks. If additional narrowing concerns are applied, less specified grains can satisfy more specified grains, but not vice versa. For example, a day with a time zone can be satisfied by one without a time zone, but zoneless time cannot be satisfied by timezoned time.

Parameters:

grain - The grain being tested

Returns:

true if this grain can be built out of the parameter grain

satisfiedBy

default boolean satisfiedBy(Granularity that)

Description copied from interface: Granularity

Determine if this granularity can be fulfilled by an aggregate of another granularity.

Specified by:

satisfiedBy in interface Granularity

Parameters:

that - The granularity to be compared against

Returns:

true if this granularity can be expressed in terms of elements of that granularity

getEstimatedDuration

org.joda.time.Duration getEstimatedDuration()

Estimated duration gives a rough millisecond length of the TimeGrain usable for comparison.

Returns:

a millisecond based estimate of the length of this time grain

aligns

boolean aligns(org.joda.time.DateTime dateTime)

Determines if this dateTime falls on a time grain boundary.

Parameters:

dateTime - A date time to test against the time grain boundary

Returns:

true if the date time is at the beginning of a time grain bucket.

aligns

default boolean aligns(org.joda.time.Interval interval)

Determines if this interval corresponds with time grain boundaries.

Parameters:

interval - An interval to test against the time grain boundary

Returns:

true if the interval starts and stop on a time grain boundaries.

accepts

default boolean accepts(Collection<org.joda.time.Interval> intervals)

Description copied from interface: Granularity

Determine if all intervals align with a granularity.

Specified by:

accepts in interface Granularity

Parameters:

intervals - The collection of intervals that should be checked

Returns:

true if all of the intervals start and end on instants which this granularity bounds

intervalsIterator

default Iterator<org.joda.time.Interval> intervalsIterator(SimplifiedIntervalList intervals)

Description copied from interface: Granularity

Build an iterator from a pre-simplified list of intervals.

Specified by:

intervalsIterator in interface Granularity

Parameters:

intervals - The intervals as a simplified interval list

Returns:

A grain delimited iterator returning all the intervals in the interval set

See Also:

Granularity.intervalsIterator(Collection)