Media Authoring
with Java API

tv.amwa.maj.embeddable
Class DateStruct

java.lang.Object
  extended by 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()

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.