org.mulgara.util
Class LexicalDateTime

java.lang.Object
  org.mulgara.util.LexicalDateTime

public class LexicalDateTime
extends Object

This class represents a dateTime value, preserving its lexical representation exactly. It stores the value of the dateTime in the canonical form, but also contains values which allow the preservation of the non-canonical format.

Author:

Paul Gearon © 2008 Fedora Commons

Constructor Summary

LexicalDateTime(long millis)
Convenience constructor which allows easy construction of a LexicalDateTime using the milliseconds since the epoch.

LexicalDateTime(long millis, int tzHours, int tzMinutes, boolean isMidnight, byte milliPlaces, boolean isLocalTz, boolean isZulu)
This constructor is used to set each field explicitly, when all such information is available.

Method Summary

static LexicalDateTime	decode(ByteBuffer bb) Decodes a ByteBuffer into a LexicalDateTime.
static LexicalDateTime	decode(long millis, byte timezoneState, byte places) Decodes a millisecond value and an encoded byte into a timezone and flags.
ByteBuffer	encode(ByteBuffer bb) Fills in a ByteBuffer with the data required to encode this object.
byte	encodeTimezoneState() Creates a byte code for the timezone and flags of this dateTime.
boolean	equals(Object o)
byte	getDecimalPlaces() Gets the number of decimal places to represent the fraction of a second.
long	getMillis() Gets the number of milliseconds since the epoch.
int	getTZHour() The the hour part of the offset for the timezone.
long	getTZMinute() The the minute part of the offset for the timezone.
int	hashCode()
boolean	isLocal() Gets the flag that indicates no timezone is present, and the local default should be used.
boolean	isMidnight() Gets the flag that indicates that this time is a non-canonical form of midnight.
boolean	isZulu() Gets the flag that indicates the Zulu timezone (UTC) and representation.
static LexicalDateTime	parseDateTime(String dt) Parse a dateTime string.
static int	requiredBufferSize() Get the size of buffer in bytes required to store this object
String	toString() Return a lexical representation of this dateTime.

Methods inherited from class java.lang.Object

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

Constructor Detail

LexicalDateTime

public LexicalDateTime(long millis,
                       int tzHours,
                       int tzMinutes,
                       boolean isMidnight,
                       byte milliPlaces,
                       boolean isLocalTz,
                       boolean isZulu)

This constructor is used to set each field explicitly, when all such information is available. No checking is performed on the consistency of the millisecond value, though some minimal testing is done on flags. Whether tested or not, the following should hold:

• if isMidnight is set, then millis must be a multiple of 24 hours.
• if isLocalTz is set, then tzHours and tzMinutes should be 0, and isZulu must be false.
• if isZulu is set, then tzHours and tzMinutes must be 0.
• millis % 10^(6 - milliPlaces) == 0

Parameters:

millis - The milliseconds since the epoch.

tzHours - The hour offset for the timezone.

tzMinutes - The minute offset for the timezone.

isMidnight - If the non-canonical form for midnight is used. "24:00:00"

milliPlaces - The number of decimal places used for representing millisecds as fractions of a second.

isLocalTz - Indicates no timezone information, so use the local default.

isZulu - Indicates that the timezone is "Zulu". This is equivalent to 00:00 and is represented as "Z".

Throws:

IllegalArgumentException - if the isZulu flag conflicts with the timezone values or the offsets.

LexicalDateTime

public LexicalDateTime(long millis)

Convenience constructor which allows easy construction of a LexicalDateTime using the milliseconds since the epoch.

Parameters:

millis - Milliseconds since the epoch.

Method Detail

getMillis

public long getMillis()

Gets the number of milliseconds since the epoch.

getTZHour

public int getTZHour()

The the hour part of the offset for the timezone.

getTZMinute

public long getTZMinute()

The the minute part of the offset for the timezone.

isMidnight

public boolean isMidnight()

Gets the flag that indicates that this time is a non-canonical form of midnight.

isLocal

public boolean isLocal()

Gets the flag that indicates no timezone is present, and the local default should be used.

isZulu

public boolean isZulu()

Gets the flag that indicates the Zulu timezone (UTC) and representation.

getDecimalPlaces

public byte getDecimalPlaces()

Gets the number of decimal places to represent the fraction of a second.

requiredBufferSize

public static int requiredBufferSize()

Get the size of buffer in bytes required to store this object

encode

public ByteBuffer encode(ByteBuffer bb)

Fills in a ByteBuffer with the data required to encode this object.

Parameters:

bb - The ByteBuffer to populate.

Returns:

The populated ByteBuffer.

encodeTimezoneState

public byte encodeTimezoneState()

Creates a byte code for the timezone and flags of this dateTime.

bits 7-2	timezone code
bit 1	local flag
bit 0	midnight flag

Returns:

a byte containing the timezone data.

decode

public static LexicalDateTime decode(ByteBuffer bb)

Decodes a ByteBuffer into a LexicalDateTime.

Parameters:

bb - The ByteBuffer to decode.

Returns:

a new LexicalDateTime structure.

decode

public static LexicalDateTime decode(long millis,
                                     byte timezoneState,
                                     byte places)

Decodes a millisecond value and an encoded byte into a timezone and flags.

Parameters:

millis - The milliseconds since the epoch.

timezoneState - The encoded data representing the timezone.

places - The number of decimal places for the seconds representation.

Returns:

a new LexicalDateTime structure.

toString

public String toString()

Return a lexical representation of this dateTime.

Overrides:

toString in class Object

parseDateTime

public static LexicalDateTime parseDateTime(String dt)
                                     throws ParseException

Parse a dateTime string. It must be of the form: ('-')? yyyy '-' MM '-' dd 'T' hh ':' mm ':' ss ( '.' s+ )? ( ( ('+'|'-')? hh ':' mm ) | 'Z' )?

Parameters:

dt - The dateTime string to parse.

Returns:

a new LexcalDateTime value.

Throws:

ParseException - If a character that doesn't match the above pattern is discovered.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object