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

tv.amwa.maj.record.impl

## Class TimeStructImpl

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

- All Implemented Interfaces:
    Serializable, Cloneable, TimeStruct

      public final class TimeStructImpl
      extends Object
      implements TimeStruct, Serializable, Cloneable

  Implementation of the time component of date and time values specified according to Coordinated Universal Time (UTC), including hour, minute, second and 1/250th of a second. The time structure is itself a component of a timestamp.

  This implementation is backed by a `Calendar`.

  See Also:
    `DateStructImpl`, `TimeStamp`, `TypeDefinitions.TimeStruct`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeStructImpl()` Create a new time structure set to the current time.
    `TimeStructImpl(byte hour, byte minute, byte second)` Create a time value from its hour, minute and second component parts.
    `TimeStructImpl(byte hour, byte minute, byte second, byte fraction)` Create a time value from all of its component parts.
    `TimeStructImpl(Calendar timeItem)` Create a new time structure from the given calendar value.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TimeStruct` | `clone()` Create a cloned copy of this time value.
    `boolean` | `equals(Object o)` Tests to see if the value of two time structures are equal.
    `static void` | `generateEmbeddableORM(Node parent, String namespace, String prefix)`
    `static void` | `generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)`
    `byte` | `getFraction()` Returns the fractions of a second component of the time value, measured in 1/250ths of a second..
    `byte` | `getHour()` Returns the hours component of the time value.
    `byte` | `getMinute()` Returns the minutes component of the time value.
    `byte` | `getSecond()` Returns the seconds component of the time value.
    `Calendar` | `getTimeValue()` Returns a copy of the calendar value used to represent the time value.
    `int` | `hashCode()`
    `static TimeStructImpl` | `parseFactory(String time)` Creates a new time value from a UTC-style string.
    `void` | `setFraction(byte fraction)` Sets the fractions of a second component of the time value, meansured in 1/250ths of a second and so in the range 0 to 249.
    `void` | `setHour(byte hour)` Sets the hours component of the time value, in the range 0 to 23.
    `void` | `setMinute(byte minute)` Sets the minutes component of the time value, in the range 0 to 59.
    `void` | `setSecond(byte second)` Sets the second component of the time value, normally in the range 0 to 59.
    `void` | `setTime(byte hour, byte minute, byte second)` Set the values of the time structure using an hour, minute and second values provided.
    `void` | `setTime(byte hour, byte minute, byte second, byte fraction)` Sets all the values of the time structure using the hour, minute, second and fraction of a second values provided.
    `void` | `setTimeValue(Calendar timeItem)` Sets the value of the time structure from the given calendar value.
    `String` | `toString()` Formats a UTC-style string representation of the time structure's value, including the timezone offset.

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

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

- - ### Constructor Detail

    - #### TimeStructImpl

          public TimeStructImpl(byte hour,
                                byte minute,
                                byte second,
                                byte fraction)
                         throws IllegalArgumentException

      Create a time value from all of its component parts.

      Parameters:
        `hour` - Hour component of the time value, in the inclusive range 0 to 23.
        `minute` - Minute component of the time value, in the inclusive range 0 to 59.
        `second` - Second component of the time value, normally in the inclusive range 0 to 59.
        `fraction` - 1/250th of a second component of the time value, in the inclusive range 0 to 249.
      Throws:
        `IllegalArgumentException` - One or more of the parameters is out of range.

    - #### TimeStructImpl

          public TimeStructImpl(byte hour,
                                byte minute,
                                byte second)
                         throws IllegalArgumentException

      Create a time value from its hour, minute and second component parts. The fraction of a second is set to 0.

      Parameters:
        `hour` - Hour component of the time value, in the inclusive range 0 to 23.
        `minute` - Minute component of the time value, in the inclusive range 0 to 59.
        `second` - Second component of the time value, normally in the inclusive range 0 to 59.
      Throws:
        `IllegalArgumentException` - One or more of the parameters is out of range.

    - #### TimeStructImpl

          public TimeStructImpl(Calendar timeItem)
                         throws NullPointerException,
                                IllegalArgumentException

      Create a new time structure from the given calendar value.

      Parameters:
        `timeItem` - Calendar item to use to create a new time structure.
      Throws:
        `NullPointerException` - Argument is null.
        `IllegalArgumentException` - The given calendar value contains out-of-range values.

    - #### TimeStructImpl

          public TimeStructImpl()

      Create a new time structure set to the current time.

  - ### Method Detail

    - #### getFraction

          public final byte getFraction()

      Description copied from interface: `TimeStruct`

      Returns the fractions of a second component of the time value, measured in 1/250ths of a second..

      Specified by:
        `getFraction` in interface `TimeStruct`
      Returns:
        Fractions of a second component of the time value.

    - #### setFraction

          public final void setFraction(byte fraction)
                                 throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Sets the fractions of a second component of the time value, meansured in 1/250ths of a second and so in the range 0 to 249.

      Specified by:
        `setFraction` in interface `TimeStruct`
      Parameters:
        `fraction` - Fractions of a second component of the time value.
      Throws:
        `IllegalArgumentException` - The fractions of a second value is outside the acceptable range.

    - #### getHour

          public final byte getHour()

      Description copied from interface: `TimeStruct`

      Returns the hours component of the time value.

      Specified by:
        `getHour` in interface `TimeStruct`
      Returns:
        Hours component of the time value.

    - #### setHour

          public final void setHour(byte hour)
                             throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Sets the hours component of the time value, in the range 0 to 23.

      Specified by:
        `setHour` in interface `TimeStruct`
      Parameters:
        `hour` - Hours component of the time value.
      Throws:
        `IllegalArgumentException` - The hours value is outside the acceptable range.

    - #### getMinute

          public final byte getMinute()

      Description copied from interface: `TimeStruct`

      Returns the minutes component of the time value.

      Specified by:
        `getMinute` in interface `TimeStruct`
      Returns:
        Minutes component of the time value.

    - #### setMinute

          public final void setMinute(byte minute)
                               throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Sets the minutes component of the time value, in the range 0 to 59.

      Specified by:
        `setMinute` in interface `TimeStruct`
      Parameters:
        `minute` - Minutes component of the time value.
      Throws:
        `IllegalArgumentException` - The minute value is outside the acceptable range.

    - #### getSecond

          public final byte getSecond()

      Description copied from interface: `TimeStruct`

      Returns the seconds component of the time value. Note that advanced implementations may allow for very occasional leap second values of 60 or 61.

      Specified by:
        `getSecond` in interface `TimeStruct`
      Returns:
        Seconds component of the time value.

    - #### setSecond

          public final void setSecond(byte second)
                               throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Sets the second component of the time value, normally in the range 0 to 59. Note that advanced implementations may allow for very occasional leap second values of 60 or 61.

      Specified by:
        `setSecond` in interface `TimeStruct`
      Parameters:
        `second` - Seconds component of the time value.
      Throws:
        `IllegalArgumentException` - The second value is outside the acceptable range.

    - #### setTime

          public final void setTime(byte hour,
                                    byte minute,
                                    byte second)
                             throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Set the values of the time structure using an hour, minute and second values provided. The fraction of the second represented is set to be 0.

      Specified by:
        `setTime` in interface `TimeStruct`
      Parameters:
        `hour` - Hours component of the time value, represented in 24-hour clock format.
        `minute` - Minutes component of the time value.
        `second` - Seconds component of the time value.
      Throws:
        `IllegalArgumentException` - One or more of the values is outside the acceptable range for a time value.

    - #### setTime

          public final void setTime(byte hour,
                                    byte minute,
                                    byte second,
                                    byte fraction)
                             throws IllegalArgumentException

      Description copied from interface: `TimeStruct`

      Sets all the values of the time structure using the hour, minute, second and fraction of a second values provided.

      Specified by:
        `setTime` in interface `TimeStruct`
      Parameters:
        `hour` - Hours component of the time value, represented in 24-hour clock format.
        `minute` - Minutes component of the time value.
        `second` - Seconds component of the time value.
        `fraction` - Fractions of a second component of the time value, measured in 1/250ths of a second.
      Throws:
        `IllegalArgumentException` - One or more of the values is outside the acceptable range for a time value.

    - #### setTimeValue

          public final void setTimeValue(Calendar timeItem)
                                  throws NullPointerException,
                                         IllegalArgumentException

      Sets the value of the time structure from the given calendar value.

      Parameters:
        `timeItem` - Calendar value to set for this time structure.
      Throws:
        `NullPointerException` - Argument is null.
        `IllegalArgumentException` - The given calendar value contains one or more fields that are out of range.

    - #### getTimeValue

          public final Calendar getTimeValue()

      Returns a copy of the calendar value used to represent the time value.

      Returns:
        Copy of the calendar value used to represent this time structure.

    - #### toString

          public final String toString()

      Formats a UTC-style string representation of the time structure's value, including the timezone offset. The format used is "`HH:mm:ss.SSSZ`", where:

      - "HH" is the two digit hour of the day in 24-hour clock;
      - "mm" is the two digit minute;
      - "ss" is the two digit second;
      - "SSS" is the three digital millisecond value;
      - "Z" is the timezone offset from UTC, measure in positive or negative hours and minutes, e.g. "+0000" for GMT and "-0800" for PST.
      Specified by:
        `toString` in interface `TimeStruct`
      Overrides:
        `toString` in class `Object`
      Returns:
        String representation of the time value according to the local time zone.
      See Also:
        `Object.toString()`, `SimpleDateFormat`

    - #### equals

          public final boolean equals(Object o)

      Tests to see if the value of two time structures are equal. Two time values are equal if and only each of their hour, minute, second and fraction of a second values are equal respectively.

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

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### clone

          public final TimeStruct clone()

      Description copied from interface: `TimeStruct`

      Create a cloned copy of this time value.

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

    - #### parseFactory

          public static final TimeStructImpl parseFactory(String time)
                                                   throws ParseException,
                                                          NullPointerException

      Creates a new time value from a UTC-style string. The expected format of the string is "`HH:mm:ss.SSSZ`", where:

      - "HH" is the two digit hour of the day in 24-hour clock;
      - "mm" is the two digit minute;
      - "ss" is the two digit second;
      - "SSS" is the three digital millisecond value;
      - "Z" is the timezone offset from UTC, measure in positive or negative hours and minutes, e.g. "+0000" for GMT and "-0800" for PST.

      Note that if a timezone value different from UTC ("+0000"), the time value will be converted to its UTC equivalent.

      Parameters:
        `time` - UTC-style string time value.
      Returns:
        Time structure representing the given string time value.
      Throws:
        `ParseException` - The given value could not be converted into a time structure value.
        `NullPointerException` - Argument is null.

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