DateStructImpl (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.record.impl

## Class DateStructImpl

- java.lang.Object
- - tv.amwa.maj.record.impl.DateStructImpl

- All Implemented Interfaces:
    Serializable, Cloneable, DateStruct

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

  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

  See Also:
    `TimeStampImpl`, `TimeStructImpl`, `TypeDefinitions.DateStruct`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateStructImpl()` Create a new date structure for the current date.
    `DateStructImpl(byte day, byte month, short year)` Create a new date value using the given year, month and day of the month values.
    `DateStructImpl(Calendar dateItem)` Create a new date structure from a `Calendar` value.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DateStruct` | `clone()` Create a cloned copy of this date value.
    `boolean` | `equals(Object o)` Tests to see if this date structure has an equal value to the date structure passed in.
    `static void` | `generateEmbeddableORM(Node parent, String namespace, String prefix)`
    `static void` | `generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)`
    `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()`
    `static DateStructImpl` | `parseFactory(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` | `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

    - #### DateStructImpl

          public DateStructImpl(@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.

    - #### DateStructImpl

          public DateStructImpl(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`

    - #### DateStructImpl

          public DateStructImpl()

      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.

    - #### 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.

      Specified by:
        `getDateValue` in interface `DateStruct`
      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 `DateStruct`
      Overrides:
        `toString` in class `Object`
      Returns:
        Date value formatted as a UTC-style string without a timezone.
      See Also:
        `Forge.parseDate(String)`

    - #### parseFactory

          public static final DateStructImpl parseFactory(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.

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### clone

          public final DateStruct clone()

      Description copied from interface: `DateStruct`

      Create a cloned copy of this date value.

      Specified by:
        `clone` in interface `DateStruct`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of this date value.

    - #### generateEmbeddableORM

          public static final void generateEmbeddableORM(Node parent,
                                                         String namespace,
                                                         String prefix)

    - #### generateEmbeddedORM

          public static final void generateEmbeddedORM(Node parent,
                                                       String ownerName,
                                                       String namespace,
                                                       String prefix)

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.