tauzaman.temporaldatatypes
Class Period

java.lang.Object
  |
  +--tauzaman.temporaldatatypes.Period

All Implemented Interfaces:

java.lang.Cloneable

public class Period

extends java.lang.Object

implements java.lang.Cloneable

The Period class provides a set of constructor and accessor operations on periods. (Arithmetic and comparison operations are implemented in a Semantics.) A period is the time between two Instants anchored to the time-line, for instance, "[July 4, 2002 - July 12, 2002]". All periods, when represented in a Period object, are assumed to be closed, that is the endpoints are included in the time of the period (note however, that periods may be constructed from strings that represent either open or closed periods, it is just that the constructed period will be assumed to be closed). Currently there is a constraint that the Instants in the period must have either be granularity-less values (e.g., MIN) or have the same granularity. Futhermore the starting Instant must come before the ending Instant. This is the standard package that supports operations on periods that have a known, fixed position as well as those that indeterminately known. To perform comparisons and arithmetic operations on Periods, it is first necessary to create a Semantics interface. A Semantics implements common comparison and arithmetic operations on temporal entities. For example a user would write code like the following.

     // Left operand semantics casts operands in binary operations 
     // to the granularity of the left operand, and then performs
     // the desired operation. 
     Ops = new LeftOperandSemantics();
     // Create two Periods, in this case, both are at the granularity of days
     Period i = new Period("[July 3, 2002 - July 10, 2002]");
     Period j = new Period("[July 4, 2002 - July 5, 2002]");
     // Is i earlier on the time-line than j?
     if (Ops.precedes(i,j)) ...
  

We employ this strategy so that all the period operations can be performed under varying Semantics.

See Also:

DeterminateSemantics, IndeterminateSemantics

Field Summary

(package private) TauZamanService	cachedTauZamanService TauZamanService that this Instant is created under
private Instant	endingInstant
private Instant	startingInstant

Constructor Summary

Period(Granularity g, Instant startingInstant, Instant endingInstant)
Construct a Period from a pair of Instants.

Period(Instant startingInstant, Instant endingInstant)
Construct a Period from a pair of Instants.

Period(java.lang.String literal)
Construct a Period object from a given String temporal constant.

Method Summary

Period	cast(Granularity g) Cast the bounding Instants to the specified granularity.
Granule	getEarliest() Selector - Returns the earliest Granule in the Period.
Instant	getEnding() Selector - Returns the ending Instant in the Period.
Granularity	getGranularity() Retrieve the granularity of the Period.
Granule	getLatest() Selector - Returns the latest Granule in the Period.
Instant	getStarting() Selector - Returns the starting Instant in the Period.
java.lang.String	image() Build a nice string image of an Period, for debugging mostly.
java.lang.String	output() Returns string representation of this Instant.
Period	scale(Granularity g) Scale the bounding Instants to the specified granularity.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

startingInstant

private Instant startingInstant

endingInstant

private Instant endingInstant

cachedTauZamanService

TauZamanService cachedTauZamanService

TauZamanService that this Instant is created under

Constructor Detail

Period

public Period(Granularity g,
              Instant startingInstant,
              Instant endingInstant)

Construct a Period from a pair of Instants. It will first convert each Instant to the desired granularity using the default conversion semantics. It will also ensure that the starting Instant is before the ending Instant.

Parameters:

g - - Granularity of desired period

startingInstant - - first Instant

endingInstant - - second Instant

Throws:

badPeriod - - possibly terminates before it starts, currently it will set the starting and terminating Instants as the same Instant.

Status:

NOT IMPLEMENTED

Period

public Period(Instant startingInstant,
              Instant endingInstant)

Construct a Period from a pair of Instants. It will check to ensure that both Instants are in the same granularity and that the starting Instant is before the ending Instant

Parameters:

startingInstant - - First instant

endingInstant - - Second instant

Throws:

badPeriod - - possibly terminates before it starts, if so it sets the terminatingInstant to be the same as the startingInstant

Status:

NOT IMPLEMENTED

Period

public Period(java.lang.String literal)
       throws TemporalDataTypeFormationException

Construct a Period object from a given String temporal constant.

Parameters:

literal - String represantion of Period

Throws:

TemporalDataTypeFormationException - if any abnormal condition occurs during parsing of string temporal constant to Instant timestamp

Method Detail

output

public java.lang.String output()
                        throws TemporalDataTypeFormationException

Returns string representation of this Instant.

Returns:

String temporal constant that corresponds to this Instant

Throws:

TemporalDataTypeFormationException - if any abnormal condition occurs when forming string temporal constant from timestamp

image

public java.lang.String image()

Build a nice string image of an Period, for debugging mostly. Provides an alternative to toString().

Returns:

String image of Period

getStarting

public Instant getStarting()

Selector - Returns the starting Instant in the Period.

Returns:

Instant - the Instant

getEnding

public Instant getEnding()

Selector - Returns the ending Instant in the Period.

Returns:

Instant - the Instant

getEarliest

public Granule getEarliest()

Selector - Returns the earliest Granule in the Period.

Returns:

Granule - the Granule of the Starting Instant

getLatest

public Granule getLatest()

Selector - Returns the latest Granule in the Period.

Returns:

the ending instant's granule

getGranularity

public Granularity getGranularity()

Retrieve the granularity of the Period.

Returns:

Granularity

scale

public Period scale(Granularity g)

Scale the bounding Instants to the specified granularity. Constructs a new Period.

Parameters:

g - - target Granularity

cast

public Period cast(Granularity g)

Cast the bounding Instants to the specified granularity. Constructs a new Period.

Parameters:

g - - target Granularity