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

tv.amwa.maj.record.impl

## Class TimeStampImpl

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

- All Implemented Interfaces:
    Serializable, Cloneable, XMLSerializable, TimeStamp

      public final class TimeStampImpl
      extends Object
      implements TimeStamp, Serializable, XMLSerializable, Cloneable

  Implementation of a date and time in UTC (Coordinated Universal Time). The value is made up of a date and time structure.

  The internal representation of this value is a `Calendar` value.

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

           `Date` date

  See Also:
    `TimeStamp`, `DateStructImpl`, `TimeStructImpl`, `TypeDefinitions.TimeStamp`, `Calendar`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `MYSQL_COLUMN_DEFINITION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeStampImpl()` Create a new time stamp value to represent the time now.
    `TimeStampImpl(Calendar calendarItem)` Create a new time stamp from the given calendar value.
    `TimeStampImpl(DateStruct date, TimeStruct time)` Create a new time stamp from the given date and time structures.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendXMLChildren(Node parent)` Append extra child elements to the given parent node to serialize the value of an object to an XML fragment.
    `TimeStamp` | `clone()` Create a cloned copy of this time stamp.
    `boolean` | `equals(Object o)` Checks for the equality of UTC values only and not the exact equality of the underlying calendar value representation.
    `static TimeStamp` | `fromPersistentForm(String timeStamp)`
    `static void` | `generateEmbeddableORM(Node parent, String namespace, String prefix)`
    `static void` | `generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)`
    `String` | `getComment()` Include a comment when serializing a value to XML.
    `DateStruct` | `getDate()` Returns the date component of the time stamp.
    `TimeStruct` | `getTime()` Returns the time component of the time stamp.
    `Calendar` | `getTimeStamp()` Returns a calendar value representing this time stamp.
    `int` | `hashCode()`
    `static TimeStampImpl` | `parseFactory(String stamp)` Create a time stamp from a string that is formatted according to the UTC standards.
    `void` | `setDate(DateStruct date)` Sets the date component of the time stamp.
    `void` | `setStamp(DateStruct date, TimeStruct time)` Simultaneously sets the date and time components of the time stamp.
    `void` | `setTime(TimeStruct time)` Sets the time component of the time stamp.
    `void` | `setTimeStamp(Calendar timestampItem)` Set the value of this time stamp using a `Calendar` value.
    `static String` | `toPersistentForm(TimeStamp timeStamp)`
    `String` | `toString()` Formats the string according ISO 8601 and as a UTC value.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MYSQL_COLUMN_DEFINITION

          public static final String MYSQL_COLUMN_DEFINITION

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TimeStampImpl

          public TimeStampImpl()

      Create a new time stamp value to represent the time now.

    - #### TimeStampImpl

          public TimeStampImpl(Calendar calendarItem)
                        throws IllegalArgumentException,
                               NullPointerException

      Create a new time stamp from the given calendar value.

      Parameters:
        `calendarItem` - Calendar value to use to create a new time stamp.
      Throws:
        `IllegalArgumentException` - The resulting time stamp value would not be valid.
        `NullPointerException` - Argument is `null`.

    - #### TimeStampImpl

          public TimeStampImpl(DateStruct date,
                               TimeStruct time)
                        throws NullPointerException,
                               IllegalArgumentException

      Create a new time stamp from the given date and time structures.

      Parameters:
        `date` - Date to set for the new time stamp.
        `time` - Time to set for the new time stamp.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`.
        `IllegalArgumentException` - The resulting time stamp value would not be valid.

  - ### Method Detail

    - #### getDate

          public final DateStruct getDate()

      Description copied from interface: `TimeStamp`

      Returns the date component of the time stamp.

      Specified by:
        `getDate` in interface `TimeStamp`
      Returns:
        Date component of the time stamp.

    - #### setDate

          public final void setDate(DateStruct date)
                             throws NullPointerException,
                                    IllegalArgumentException

      Description copied from interface: `TimeStamp`

      Sets the date component of the time stamp.

      Specified by:
        `setDate` in interface `TimeStamp`
      Parameters:
        `date` - Date component of the time stamp.
      Throws:
        `NullPointerException` - The given data structure is `null`.
        `IllegalArgumentException` - The given date is not valid.

    - #### getTime

          public final TimeStruct getTime()

      Description copied from interface: `TimeStamp`

      Returns the time component of the time stamp.

      Specified by:
        `getTime` in interface `TimeStamp`
      Returns:
        Time component of the time stamp.

    - #### setTime

          public final void setTime(TimeStruct time)
                             throws NullPointerException,
                                    IllegalArgumentException

      Description copied from interface: `TimeStamp`

      Sets the time component of the time stamp.

      Specified by:
        `setTime` in interface `TimeStamp`
      Parameters:
        `time` - Time component of the time stamp.
      Throws:
        `NullPointerException` - The given time structure is `null`.
        `IllegalArgumentException` - The given time is not valid.

    - #### setStamp

          public final void setStamp(DateStruct date,
                                     TimeStruct time)
                              throws NullPointerException,
                                     IllegalArgumentException

      Description copied from interface: `TimeStamp`

      Simultaneously sets the date and time components of the time stamp.

      Specified by:
        `setStamp` in interface `TimeStamp`
      Parameters:
        `date` - Date component of the time stamp.
        `time` - Time component of the time stamp.
      Throws:
        `NullPointerException` - One or both of the given data or time structures are `null`.
        `IllegalArgumentException` - One or both of the given date or time values are not valid.

    - #### getTimeStamp

          public final Calendar getTimeStamp()

      Description copied from interface: `TimeStamp`

      Returns a calendar value representing this time stamp. The method returns a copy of internal calendar value to preserve the internal state of this value.

      Specified by:
        `getTimeStamp` in interface `TimeStamp`
      Returns:
        Calendar value representing this time stamp.
      See Also:
        `Forge.makeTimeStamp(Calendar)`

    - #### setTimeStamp

          public final void setTimeStamp(Calendar timestampItem)
                                  throws NullPointerException,
                                         IllegalArgumentException

      Set the value of this time stamp using a `Calendar` value. This method is strict in its interpretation of date and time values.

      Note that all fields of the value will be preserved within the time stamp value and available on a call to `getTimeStamp()`.

      Parameters:
        `timestampItem` - Calendar value to use to set the value of this time stamp.
      Throws:
        `NullPointerException` - Argument is `null`.
        `IllegalArgumentException` - The given calendar value is not a valid date or time.

    - #### toString

          public final String toString()

      Formats the string according ISO 8601 and as a UTC value.

      The format of the string is "`yyyy-MM-dd'T'HH:mm:ss.SSZ`", where:

      - yyyy - Year part of the time stamp value.
      - MM - Month part of the time stamp value, in the range 1 to 12.
      - dd - Day of the month part of the time stamp value, in the range 1 to 31.
      - HH - Hour of the day of the time stamp value, specified in 24-hour clock in the range 0 to 23.
      - mm - Minute part of the time stamp value, in the range 0 to 59.
      - ss - Second part of the time stamp value, normally in the range 0 to 59.
      - SS - hundreths of a second part of the time stamp value, in the range .00 to .99.
      - Z - The letter "Z" to indicate that this value is shown in UTC.
      Specified by:
        `toString` in interface `TimeStamp`
      Overrides:
        `toString` in class `Object`
      See Also:
        `Object.toString()`, `SimpleDateFormat`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### parseFactory

          public static final TimeStampImpl parseFactory(String stamp)
                                                  throws ParseException,
                                                         NullPointerException

      Create a time stamp from a string that is formatted according to the UTC standards. If the value is given with a timezone part, the internal representation will be converted to UTC "`+0000`", otherwise kwown as "`Z`".

      One acceptable format of the string is "`yyyy-MM-dd'T'HH:mm:ss.SSSZ`", where:

      - yyyy - Year part of the time stamp value.
      - MM - Month part of the time stamp value, in the range 1 to 12.
      - dd - Day of the month part of the time stamp value, in the range 1 to 31.
      - HH - Hour of the day of the time stamp value, specified in 24-hour clock in the range 0 to 23.
      - mm - Minute part of the time stamp value, in the range 0 to 59.
      - ss - Second part of the time stamp value, normally in the range 0 to 59.
      - SSS - millisecond part of the time stamp value, in the range .000 to .999.
      - Z - Timezone part of the time stamp value, measured as a positive or negative hours and minutes offset from UTC, e.g. "-0800" for Pacific Standard Time.

      Alternatively, a "`Z`" may be used in place of "`+0000`". The number of milliseconds can be expressed by 1/250ths of a second.

      Parameters:
        `stamp` - String representation of a time stamp value.
      Returns:
        Newly created MAJ time stamp value from given string value.
      Throws:
        `ParseException` - A problem with the given string prevents it from being converted to a time stamp value, or the resulting value in unacceptable.
        `NullPointerException` - Argument is `null`.

    - #### equals

          public final boolean equals(Object o)

      Checks for the equality of UTC values only and not the exact equality of the underlying calendar value representation.

      Overrides:
        `equals` in class `Object`
      See Also:
        `Object.equals(java.lang.Object)`

    - #### clone

          public final TimeStamp clone()

      Description copied from interface: `TimeStamp`

      Create a cloned copy of this time stamp.

      Specified by:
        `clone` in interface `TimeStamp`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of this time stamp.

    - #### appendXMLChildren

          public final void appendXMLChildren(Node parent)

      Description copied from interface: `XMLSerializable`

      Append extra child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the `XMLBuilder` class are provided to help with this process.

      Specified by:
        `appendXMLChildren` in interface `XMLSerializable`
      Parameters:
        `parent` - XML parent element to append child nodes to.

    - #### getComment

          public String getComment()

      Description copied from interface: `XMLSerializable`

      Include a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.

      Specified by:
        `getComment` in interface `XMLSerializable`
      Returns:
        Comment to add as the first child node of the element representing this class.

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

    - #### toPersistentForm

          public static final String toPersistentForm(TimeStamp timeStamp)

    - #### fromPersistentForm

          public static final TimeStamp fromPersistentForm(String timeStamp)

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