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

tv.amwa.maj.record

## Interface TimeStamp

- All Known Implementing Classes:
    TimeStampImpl

      public interface TimeStamp

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

  For more information on UTC, see the entry on Coordinated Universal Time on Wikipedia.

  To make values of this type, use the following methods from the MAJ forge:

  - From its component parts: `Forge.makeTimeStamp(DateStruct, TimeStruct)` and `Forge.makeTimeStamp(short, byte, byte, byte, byte, byte, byte)`;
  - From a `Calendar` value: `Forge.makeTimeStamp(java.util.Calendar)`;
  - The date and time now: `Forge.now()`;
  - From a string representation as generated by `toString()`: `Forge.parseTimeStamp(String)`.
  See Also:
    `TimeStruct`, `DateStruct`, `TypeDefinitions.TimeStamp`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TimeStamp` | `clone()` Create a cloned copy of this time stamp.
    `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.
    `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.
    `String` | `toString()` Formats the time stamp as a string according ISO 8601 and as a UTC value.

- - ### Method Detail

    - #### setStamp

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

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

      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.

    - #### getDate

          DateStruct getDate()

      Returns the date component of the time stamp.

      Returns:
        Date component of the time stamp.

    - #### setDate

          void setDate(DateStruct date)
                throws NullPointerException,
                       IllegalArgumentException

      Sets the date component of the time stamp.

      Parameters:
        `date` - Date component of the time stamp.
      Throws:
        `NullPointerException` - The given data structure is `null`.
        `IllegalArgumentException` - The given date is not valid.

    - #### getTime

          TimeStruct getTime()

      Returns the time component of the time stamp.

      Returns:
        Time component of the time stamp.

    - #### setTime

          void setTime(TimeStruct time)
                throws NullPointerException,
                       IllegalArgumentException

      Sets the time component of the time stamp.

      Parameters:
        `time` - Time component of the time stamp.
      Throws:
        `NullPointerException` - The given time structure is `null`.
        `IllegalArgumentException` - The given time is not valid.

    - #### clone

          TimeStamp clone()

      Create a cloned copy of this time stamp.

      Returns:
        Cloned copy of this time stamp.

    - #### toString

          String toString()

      Formats the time stamp as a 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.

      The representation of a time stamp generated by this method can be converted back to a time stamp value using `Forge.parseTimeStamp(String)`.

      Overrides:
        `toString` in class `Object`
      See Also:
        `Forge.parseTimeStamp(String)`, `SimpleDateFormat`

    - #### getTimeStamp

          Calendar getTimeStamp()

      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.

      Returns:
        Calendar value representing this time stamp.
      See Also:
        `Forge.makeTimeStamp(Calendar)`

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