tv.amwa.maj.embeddable
Class DateStruct

java.lang.Object
  tv.amwa.maj.embeddable.DateStruct

All Implemented Interfaces:

Serializable, Cloneable, MAJCommon, DateStruct

public final class DateStruct
extends Object
implements DateStruct, Serializable, Cloneable, MAJCommon

Implementation of the date component of timestamp values that are specified according to Coordinated Universal Time (UTC). AAF dates represent dates with year, month and day of the month components.

As specified, AAF dates do not represent the timezone associated with a date and in this sense are not fully compatible with UTC dates. Internally, this class uses the Calendar class with its support for internationalization so timezone is represented when provided through methods such as getDateValue(). Also, this class restricts the acceptable range of values to acceptable values, which includes checking for leap years and unacceptable dates such as 31st February.

A date structure is represented in the database by a column of type date:

     `Date` date
 

Author:

Richard Cartwright

See Also:

TimeStamp, TimeStruct, TypeDefinitionRecord.DateStruct, Serialized Form

Constructor Summary

DateStruct()
Create a new date structure for the current date.

DateStruct(byte day, byte month, short year)
Create a new date value using the given year, month and day of the month values.

DateStruct(Calendar dateItem)
Create a new date structure from a Calendar value.

Method Summary

static DateStruct	castFromInterface(DateStruct alien) Create an instance of this date structure implementation using a possibly alien implementation that at least implements tv.amwa.maj.record.DateStruct.
DateStruct	clone() Creates a cloned deep copy of this embeddable value.
boolean	equals(Object o) Tests to see if this date structure has an equal value to the date structure passed in.
Calendar	getDateValue() Returns a copy of the Calendar value representing the day given by this date.
byte	getDay() Returns the day of the month component of the date.
byte	getMonth() Returns the month component of the date, which is in the range 1 to 12.
short	getYear() Returns the year component of the date.
int	hashCode() Returns a hash code value for this embeddable object.
static DateStruct	parseDateStruct(String date) Create a new date structure value from a string representation of a date.
void	setDate(byte day, byte month, short year) Simultaneously set the components of date structure value with the given day, month and year.
void	setDateValue(Calendar dateItem) Set the Calendar value used internally to represent this date value.
void	setDay(byte day) Set the day of the month component of the date, in the range 1 to 31.
void	setMonth(byte month) Set the month component of the date, which is in the range 1 to 12.
void	setPropertiesFromInterface(DateStruct castFrom) Set the properties of this value from those available in the given value, which is specified by the date structure interface.
void	setYear(short year) Sets the year component of the date, in the range -9999 to 9999.
String	toString() Formats the date value as a UTC date-only value.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DateStruct

public DateStruct(@UInt8
                  byte day,
                  @UInt8
                  byte month,
                  @Int16
                  short year)
           throws IllegalArgumentException

Create a new date value using the given year, month and day of the month values.

Parameters:

day - Day component of the date.

month - Month component of the date.

year - Year component of the date.

Throws:

IllegalArgumentException - One or more of the arguments has a value outside of an acceptable range.

DateStruct

public DateStruct(Calendar dateItem)
           throws NullPointerException,
                  IllegalArgumentException

Create a new date structure from a Calendar value.

Note that the newly created date structure may not store the timezone and other locale information encoded in the original calendar value.

Parameters:

dateItem - Calendar value to use to extract a day, month and year from.

Throws:

NullPointerException - Argument is null.

IllegalArgumentException

DateStruct

public DateStruct()

Create a new date structure for the current date.

Method Detail

setDate

public void setDate(@UInt8
                    byte day,
                    @UInt8
                    byte month,
                    @Int16
                    short year)
             throws IllegalArgumentException

Description copied from interface: DateStruct

Simultaneously set the components of date structure value with the given day, month and year.

Specified by:

setDate in interface DateStruct

Parameters:

day - Day of the month component of the date.

month - Month component of the date.

year - Year component of the date.

Throws:

IllegalArgumentException - One or more of the component values is outside the acceptable range for their values, or the specified date does not exist.

castFromInterface

public static final DateStruct castFromInterface(DateStruct alien)
                                          throws NullPointerException

Create an instance of this date structure implementation using a possibly alien implementation that at least implements tv.amwa.maj.record.DateStruct. If the given value is an instance of this class, the value is returned directly, otherwise a new date structure is constructed with an equivalent value to the given value.

Parameters:

alien - Object implementing DateStruct to use to create an instance of this implementation from.

Returns:

Instance of this date structure implementation with a value equivalent to that of the given object.

Throws:

NullPointerException - The alien value argument is null.

See Also:

setPropertiesFromInterface(tv.amwa.maj.record.DateStruct)

setPropertiesFromInterface

public final void setPropertiesFromInterface(DateStruct castFrom)
                                      throws NullPointerException

Set the properties of this value from those available in the given value, which is specified by the date structure interface.

Parameters:

castFrom - Value to extract properties from.

Throws:

NullPointerException - The given value to use to set this value is null.

See Also:

castFromInterface(tv.amwa.maj.record.DateStruct)

getDay

@UInt8
public final byte getDay()

Description copied from interface: DateStruct

Returns the day of the month component of the date.

Specified by:

getDay in interface DateStruct

Returns:

Day of the month component of the date.

setDay

public final void setDay(@UInt8
                         byte day)
                  throws IllegalArgumentException

Description copied from interface: DateStruct

Set the day of the month component of the date, in the range 1 to 31.

Specified by:

setDay in interface DateStruct

Parameters:

day - Day of the month component of the date.

Throws:

IllegalArgumentException - Provided day value is outside the acceptable range.

getMonth

@UInt8
public final byte getMonth()

Description copied from interface: DateStruct

Returns the month component of the date, which is in the range 1 to 12.

Specified by:

getMonth in interface DateStruct

Returns:

Month component of the date.

setMonth

public final void setMonth(@UInt8
                           byte month)
                    throws IllegalArgumentException

Description copied from interface: DateStruct

Set the month component of the date, which is in the range 1 to 12.

Specified by:

setMonth in interface DateStruct

Parameters:

month - Month component of the date.

Throws:

IllegalArgumentException - Provided month value is outside the acceptable range.

getYear

@Int16
public final short getYear()

Description copied from interface: DateStruct

Returns the year component of the date.

Specified by:

getYear in interface DateStruct

Returns:

Year part of the date.

setYear

public final void setYear(@Int16
                          short year)
                   throws IllegalArgumentException

Description copied from interface: DateStruct

Sets the year component of the date, in the range -9999 to 9999.

Specified by:

setYear in interface DateStruct

Parameters:

year - Year component of the date.

Throws:

IllegalArgumentException - Year is outside the acceptable range.

getDateValue

public final Calendar getDateValue()

Returns a copy of the Calendar value representing the day given by this date.

Returns:

Java Calendar representation of this date structure, to the current default timezone and locale settings.

setDateValue

public final void setDateValue(Calendar dateItem)
                        throws NullPointerException,
                               IllegalArgumentException

Set the Calendar value used internally to represent this date value.

Parameters:

dateItem - Calendar value to use to set the date.

Throws:

NullPointerException - The given calendar value is null.

IllegalArgumentException

toString

public final String toString()

Formats the date value as a UTC date-only value. The format is "yyyy-mm-dd", the year followed by the month followed by the day of the month. Note that locale and timezone are not available in a date structure.

Specified by:

toString in interface MAJCommon

Overrides:

toString in class Object

Returns:

Date value formatted as a UTC-style string without a timezone.

See Also:

Object.toString()

parseDateStruct

public static final DateStruct parseDateStruct(String date)
                                        throws ParseException,
                                               NullPointerException,
                                               IllegalArgumentException

Create a new date structure value from a string representation of a date. The date should be represented as the UTC portion of a date in the format "yyyy-mm-dd".

Note that this method does not support the specification of timezone or dates earlier than 1AD.

Parameters:

date - Date value represented as a string.

Returns:

Newly created date structure taken from the given string.

Throws:

ParseException - Given string value cannot be parsed into a date structure as it is in the wrong format.

NullPointerException - The given string representation of a date is null.

IllegalArgumentException - After successful parsing, the given date is not an acceptable value.

equals

public final boolean equals(Object o)

Tests to see if this date structure has an equal value to the date structure passed in. Comparison is done based on year, month and day of month values only to remain compatible with the fields actually represented by AAF.

Specified by:

equals in interface MAJCommon

Overrides:

equals in class Object

Parameters:

o - Object to test for equality with.

Returns:

Is the given object equals to this value?

See Also:

Object.equals(Object)

hashCode

public final int hashCode()

Description copied from interface: MAJCommon

Returns a hash code value for this embeddable object.

Specified by:

hashCode in interface MAJCommon

Overrides:

hashCode in class Object

Returns:

Hash code value for this embeddable object.

See Also:

Object.hashCode()

clone

public final DateStruct clone()

Description copied from interface: MAJCommon

Creates a cloned deep copy of this embeddable value. The clone will be initialized to have the same value as this value but exists independently from then on. Changes to this value will not effect the clone and changes to the clone will not effect this. MAJ API clones are true deep clones with no shared references to areas of memory within the original.

This method does not throw a CloneNotSupportedException as all embeddable values must implement the Cloneable interface.

Specified by:

clone in interface MAJCommon

Overrides:

clone in class Object

Returns:

Independent clone of this value, which is a deep copy.

See Also:

Object.clone()