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

tv.amwa.maj.industry

## Class Forge

- java.lang.Object
- - tv.amwa.maj.industry.Forge

-     public final class Forge
      extends Object

  Stamps out values of the model, record and union types, acting as a factory for these values and objects. All methods are static and reference underlying methods, produce value to the MAJ interface using static methods in the underlying implementation.

  To create new instances of media classes, whether AAF classes or extensions classes, use one of the following make methods:

  - `make(Class, Object...)` - Make an object that implements the given interface using the provided list of parameters.
  - `make(Class, boolean, Object...)` - Similar to the previous method, except you can define how strict you want MAJ to be in checking whether all the required parameters are provided.
  - `makeAAF(String, Object...)` - Make an instance of a defined AAF baseline class using its name, initialized using the list of paramters provided.
  - `makeByName(String, String, Object...)` - Make an instance of a class from a given namespace of the specified class name, initialized using the list of parameters provided.
  - `makeByName(String, String, boolean, Object...)` - As above, specifying how strict you want MAJ to be in checking whether all the required parameters are provided.

    All of the above methods take lists of name and value pairs and are very open to how the values are provided. For example, a data definition can be provided as an instance of a class implementing the data definition interface, an AUID identifying the definition or simply by its name, e.g. Picture.

    The record types supported by this factory class are: `AUID`, `DateStruct`, `EdgeCodeValue`, `PackageID`, `ProductVersion`, `Rational`, `RGBAComponent`, `TimecodeValue`, `TimeStamp`, `TimeStruct`, `VersionType`.

    The union types, compound-type values for passing or returning a single value to and from a MAJ method, are: `SourceReferenceValue`.

    Most types have a method that allows a string representation to be parsed and transformed into a value of the given type: `parseAUID(String)`, `parseDate(String)`, `parseEdgeCode(String)`, `parsePackageID(String)`, `parseProductVersion(String)`, `parseRational(String)`, `parseRGBAComponent(String)`, `parseTimecode(String)` / `parseTimecode(String, short, boolean)`, `parseTimeStamp(String)`, `parseTime(String)`, `parseVersion(String)`.

    Methods for creating values of a given type are listed below: `SourceReferenceValue`.

    - `AUID` - Make a value from the known component parts with `makeAUID(byte[])` and `makeAUID(int, short, short, byte[])`. Alternatively, use UUID-generation methods to make type 1, 3 and 4 UUIDs with `timebasedAUID()` / `timebasedAUID(byte[])`, `namebasedAUID(byte[])` / `namebasedAUID(String)` and `randomAUID()`. The nil AUID can be made using `nilAUID()`.
    - `DateStruct` - Make a date from its component parts with `makeDate(byte, byte, short)` or from an existing Java Calendar value with `makeDate(Calendar)`. For today's date, use `todaysDate()`.
    - `EdgeCodeValue` - Make an edge code value from its component parts with `makeEdgeCode(long, FilmType, EdgeType)` and with its optional header using `makeEdgeCode(long, FilmType, EdgeType, byte[])` or `makeEdgeCode(long, FilmType, EdgeType, String)`. For a default value, use `makeEdgeCode()`.
    - `PackageID` - Make a package identifier value from its component parts with `makePackageID(byte[])` and `makePackageID(byte[], byte, byte, byte, byte, AUID)`. Generate package identifiers according to specified generation strategies with `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)` and `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`. Create a D-Cinema UMID with `dCinemaUMID()`, a random UMID with `randomUMID()` or a zero UMID with `zeroPackageID()`.
    - `ProductVersion` - Make a product version value from its constituent parts with `makeProductVersion(short, short, short, short, ProductReleaseType)`. Alternatively, make a zero default value using `zeroProductVersion()`.
    - `Rational` - Make a rational value from its numerator and denominator with `makeRational(int, int)` or a zero valued rational with `zeroRational()`.
    - `RGBAComponent` - Make a RGBA component value from its size and code components with `makeRGBAComponent(RGBAComponentKind, byte)` or a zero default value with `zeroRGBAComponent()`.
    - `TimecodeValue` - Make a timecode value from its components with `makeTimecode(long, short, boolean)`. Alternatively, calculate a timecode value from a SMPTE-style set of values with `calculateTimecode(short, short, short, short, short, boolean)` or from other timecode values with `calculateDuration(TimecodeValue, TimecodeValue)` and `calculateEndTimecode(TimecodeValue, TimecodeValue)`.
    - `TimeStamp` - Make a time stamp value from its component parts with `makeTimeStamp(DateStruct, TimeStruct)` and `makeTimeStamp(short, byte, byte, byte, byte, byte, byte)`. Alternatively, make a time stamp from an existing `Calendar` value with `makeTimeStamp(Calendar)` or a time stamp for now with `now()`.
    - `TimeStruct` - Make a time value (with no date part) from its component parts with `makeTime(byte, byte, byte)` and `makeTime(byte, byte, byte, byte)`. Alternatively, make a time value from an existing `Calendar` value with `makeTime(Calendar)` or representing the current time with `timeNow()`.
    - `VersionType` - Make a version type value from its component parts with `makeVersion(byte, byte)` or a zero version type value with `zeroVersion()`.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TimecodeValue` | `calculateDuration(TimecodeValue startValue, TimecodeValue endValue)` Calculate the duration of a piece of media from its start timecode and end timecode.
    `static TimecodeValue` | `calculateEndTimecode(TimecodeValue startValue, TimecodeValue duration)` Calculate the end timecode for a segment of media from its start timecode and a timecode value representing its duration.
    `static TimecodeValue` | `calculateTimecode(short hours, short minutes, short seconds, short frames, short fps, boolean drop)` For lower frame rates (up to 30), calculate a new timecode value from the given hours, minutes, seconds and frames according to the given number of frames per second and whether the timecode value requires drop frame calculations.
    `static TimecodeValue` | `calculateTimecode(short hours, short minutes, short seconds, short frames, short framePair, short fps, boolean drop)` For higher frame rates (greater than 30), calculate a new timecode value from the given hours, minutes, seconds, frames and frame pair according to the given number of frames per second and whether the timecode value requires drop frame calculations.
    `static PackageID` | `dCinemaUMID()` Generates a package identifier appropriate for use in D-Cinema packaging, as defined in section 6.3.1 of SMPTE 429-3-2007.
    `static PackageID` | `generatePackageID(AUID materialNumber)` Generate a new package identifier appropriate for use in D-Cinema packaging using the given material number using the material number generation method.
    `static PackageID` | `generatePackageID(MaterialType materialType, InstanceNumberGeneration instanceNumberGeneration, MaterialNumberGeneration materialNumberGeneration)` Generate a new package identifier according to the given material type, instance number generation method and material number generation method.
    `static PackageID` | `generatePackageID(MaterialType materialType, InstanceNumberGeneration instanceNumberGeneration, MaterialNumberGeneration materialNumberGeneration, AUID materialNumber)` Generate a new package identifier according to the given material type, instance number generation method and material number generation method.
    `static PackageID` | `generatePackageID(MaterialType materialType, InstanceNumberGeneration instanceNumberGeneration, MaterialNumberGeneration materialNumberGeneration, byte[] extraData)` Generate a new package identifier according to the given material type, instance number generation method and material number generation method.
    `static SourceReferenceValue` | `inContextReference(int sourceTrackID)` Makes a new source reference to static material in a track within the same context as the package in which the reference is specified.
    `static SourceReferenceValue` | `inContextReference(int sourceTrackID, Long startPosition)` Makes a new source reference to timeline- or event-based material in a track within the same context as the package in which the reference is specified.
    `static <T extends MetadataObject> T` | `make(Class<T> type, boolean strict, Object... properties)` Create new instances of metadata objects using the definition of its primary interface and its initial property values.
    `static <T extends MetadataObject> T` | `make(Class<T> type, Object... properties)` Create new instances of metadata objects using the definition of its primary interface and its initial property values without being strict about required properties.
    `static <T extends MetadataObject> T` | `makeAAF(String typeName, Object... properties)` Create new instances of AAF baseline metadata objects using the name of the type and its initial property values, and also without being strict about required properties.
    `static AUID` | `makeAUID(byte[] bytes)` Make a new AUID value from a 16-byte array representing its internal value.
    `static AUID` | `makeAUID(int data1, short data2, short data3, byte[] data4)` Makes a new AUID value from its constituent parts.
    `static <T extends MetadataObject> T` | `makeByName(String namespace, String typeName, boolean strict, Object... properties)` Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values.
    `static <T extends MetadataObject> T` | `makeByName(String namespace, String typeName, Object... properties)` Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values, and also without being strict about required properties.
    `static DateStruct` | `makeDate(byte day, byte month, short year)` Create a new date value using the given year, 1-based month and day of the month values.
    `static DateStruct` | `makeDate(Calendar dateAsCalendar)` Make a new date structure from a `Calendar` value.
    `static EdgeCodeValue` | `makeEdgeCode()` Makes a default film edge code value, with start frame 0, a null film kind, null edge type and no header.
    `static EdgeCodeValue` | `makeEdgeCode(long startFrame, FilmType filmKind, EdgeType codeFormat)` Makes a new film edge code value from its component parts.
    `static EdgeCodeValue` | `makeEdgeCode(long startFrame, FilmType filmKind, EdgeType codeFormat, byte[] header)` Makes a new film edge code value from its component parts, including the optional header as a byte array.
    `static EdgeCodeValue` | `makeEdgeCode(long startFrame, FilmType filmKind, EdgeType codeFormat, String header)` Makes a new film edge code value from its component parts, including the optional header as a string.
    `static PackageID` | `makePackageID(byte[] bytes)` Make a new package identifier from the given byte array of elements.
    `static PackageID` | `makePackageID(byte[] univeralLabel, byte length, byte instanceHigh, byte instanceMid, byte instanceLow, AUID materialNumber)` Make a new package identifier from the specified parameters.
    `static ProductVersion` | `makeProductVersion(short major, short minor, short tertiary, short patchLevel, ProductReleaseType type)` Make a product version value that represents the version of an application.
    `static Rational` | `makeRational(int numerator, int denominator)` Make a rational value from its numerator and denominator.
    `static SourceReferenceValue` | `makeReference(PackageID sourcePackageID, int sourceTrackID, Long startPosition)` Make a new source reference value that contains a source package identifier, source track identifier and start position.
    `static RGBAComponent` | `makeRGBAComponent(RGBAComponentKind code, byte size)` Make an element of an RGBA layout array.
    `static TimeStruct` | `makeTime(byte hour, byte minute, byte second)` Make a time value from its hour, minute and second component parts.
    `static TimeStruct` | `makeTime(byte hour, byte minute, byte second, byte fraction)` Make a time value from all of its component parts.
    `static TimeStruct` | `makeTime(Calendar timeAsCalendar)` Make a new time structure from the given calendar value.
    `static TimecodeValue` | `makeTimecode(long startFrame, short fps, boolean drop)` Make a timecode value from its actual component parts.
    `static TimeStamp` | `makeTimeStamp(Calendar timeStampAsCalendar)` Make a time stamp using a `Calendar` value.
    `static TimeStamp` | `makeTimeStamp(DateStruct date, TimeStruct time)` Make a time stamp using the components of the given date and time values.
    `static TimeStamp` | `makeTimeStamp(short year, byte month, byte day, byte hour, byte minute, byte second, byte fraction)` Make a time stampe using all of the components of the date and time parts.
    `static VersionType` | `makeVersion(byte major, byte minor)` Make a version type value from its component major and minor values.
    `static AUID` | `namebasedAUID(byte[] nameData)` Generates a new UUID as an AUID generated with the name-based method, type 3.
    `static AUID` | `namebasedAUID(String nameData)` Generates a new UUID as an AUID generated with the name-based method, type 3, from a Java string value.
    `static AUID` | `nilAUID()` Makes the nil AUID that represents the nil UUID, a special value where every byte element is set to zero.
    `static TimeStamp` | `now()` Make a timestamp representing the date and time now.
    `static SourceReferenceValue` | `originalSource()` Makes a new source reference that indicates the reference is to essence that is the original source.
    `static AUID` | `parseAUID(String auidAsString)` Make a new AUID from a URN representation, as specified in section 3 of rfc 4122 or the commonly used URN representation of Universal Labels (starting with "`urn:x-ul:`" or "`urn:smpte:ul:`").
    `static DateStruct` | `parseDate(String dateAsString)` Make a new date structure value from a string representation of a date.
    `static EdgeCodeValue` | `parseEdgeCode(String edgeCodeAsString)` Creates an edge code value from a pseudo-XML representation, including all those generated by `EdgeCodeValue.toString()`.
    `static PackageID` | `parsePackageID(String packageIDAsString)` Parse a package identifier formatted as a URN-style UMID string and convert it into a newly instantiated package id with an equivalent value.
    `static ProductVersion` | `parseProductVersion(String versionAsAString)` Makes an instance of this product version class by parsing the given pseudo-XML version.
    `static Rational` | `parseRational(String rationalAsString)` Make a rational value by parsing a string representation.
    `static RGBAComponent` | `parseRGBAComponent(String rgbaComponentAsString)` Make a new element of an RGBA layout array by parsing the given pseudo-XML representation.
    `static TimeStruct` | `parseTime(String timeAsAString)` Makes a new time value from a UTC-style string.
    `static TimecodeValue` | `parseTimecode(String timecodeAsAString)` Makes a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, implying default values for the frames per second and drop frame parameters from the timecode text.
    `static TimecodeValue` | `parseTimecode(String timecodeAsAString, short explicitFramesPerSecond, boolean explicitDropFrameIndicator)` Makes a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, with all parameters specified.
    `static TimeStamp` | `parseTimeStamp(String timeStampAsAString)` Make a time stamp value from a string that is formatted according to the UTC standards.
    `static VersionType` | `parseVersion(String versionAsAString)` Make a version type value by parsing the given string representation.
    `static AUID` | `randomAUID()` Generates a new AUID using pseudo-random number generation, type 4.
    `static PackageID` | `randomUMID()` Generates a UMID with a random material number.
    `static void` | `setLocalNodeID(byte[] localNodeID)` Set the local node ID to use in the generation of time-based UUIDs as AUIDs.
    `static AUID` | `timebasedAUID()` Generates a new UUID as AUID generated according to the time and location based method, type 1.
    `static AUID` | `timebasedAUID(byte[] nodeID)` Generates a new UUID as an AUID from the current time and a location provided by the given node identifier.
    `static TimeStruct` | `timeNow()` Makes a time only value representing the time now.
    `static DateStruct` | `todaysDate()` Make a date structure representing the current date.
    `static PackageID` | `zeroPackageID()` Makes the zero package identifier that consists of every bit set to zero.
    `static ProductVersion` | `zeroProductVersion()` Make a zero product version value, with all numerical values set to zero and the release type set to unknown.
    `static Rational` | `zeroRational()` Make a rational value of zero, with numerator of 0 and denominator of 1.
    `static RGBAComponent` | `zeroRGBAComponent()` Make an element of an RGBA layout array with a `RGBAComponentKind.Null` code and a size of `0`.
    `static TimecodeValue` | `zeroTimecode()` Make a zero timecode value, with a zero start frame, zero frames per second and a zero drop frame.
    `static VersionType` | `zeroVersion()` Make a zero version number, where both major and minor parts are zero.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### parseAUID

          public static final AUID parseAUID(String auidAsString)
                                      throws NullPointerException,
                                             ParseException

      Make a new AUID from a URN representation, as specified in section 3 of rfc 4122 or the commonly used URN representation of Universal Labels (starting with "`urn:x-ul:`" or "`urn:smpte:ul:`"). The method accepts hexadecimal digits in upper or lower case.

      Example values are:

      `urn:uuid:B302CABE-7AAB-41C4-A072-F0E96C160D7D`
      `urn:uuid:00000000-0000-0000-0000-000000000000`
      `urn:smpte:ul:0602b34.010101ff.42464141.000d4d4f`
      Parameters:
        `auidAsString` - String value to use to create a new AUID.
      Returns:
        Newly created AUID value corresponding to the given string value.
      Throws:
        `NullPointerException` - AUID string value argument is `null`.
        `NumberFormatException` - The given string is not recognised as an AUID value, either because it is of the wrong length, has its separators in the wrong place, uses the wrong separators or contains non-hexadecimal values.
        `ParseException`
      See Also:
        `AUID.toString()`, `makeAUID(byte[])`

    - #### timebasedAUID

          public static final AUID timebasedAUID()

      Generates a new UUID as AUID generated according to the time and location based method, type 1. The node identifier used for this method can be set by calling `setLocalNodeID(byte[])`.

      It is possible to call this method repeatedly, even though Java's time resolution is to the nearest millisecond. An extra counter is implemented by MAJ in this method to provide an additional sequence of values to simulate the generation of time values measured in 100-nano second chunks as required by the UUID specification. The clock sequence part of the value is generated using a secure random number generator.

      Returns:
        Time and location based UUID as an AUID.
      See Also:
        `setLocalNodeID(byte[])`, `randomAUID()`, `namebasedAUID(byte[])`

    - #### setLocalNodeID

          public static final void setLocalNodeID(byte[] localNodeID)
                                           throws NullPointerException

      Set the local node ID to use in the generation of time-based UUIDs as AUIDs. This method is provided to allow the default host id generated in the instantiation of this class to be overridden. As the actual host identifier (Ethernet address) of a system is not available through the Java 1.5 APIs, the default value is generated from the IP address and domain name of this system. Using this method, the actual host identifier of the system can be set, or any other 6-byte unique identifier for the host.

      If you are using Java 1.6, the `Utilities.getLocalHostID()` method is available to return an Ethernet address for one of the local interfaces. Note that the value returned may change as interfaces are brought up and down, so this method should be good enough for the repeated generation of time-based UUIDs but not as a general and reliable system identifier.

      Parameters:
        `localNodeID` - A guaranteed to be unique identifier for the node on which this class is loaded. The value will be padded or truncated to 6-bytes.
      Throws:
        `NullPointerException` - The given byte array is `null`.
      See Also:
        `timebasedAUID()`, `Utilities.createLocalHostID(int)`, `Utilities.getLocalHostID()`

    - #### timebasedAUID

          public static final AUID timebasedAUID(byte[] nodeID)
                                          throws NullPointerException,
                                                 IllegalArgumentException

      Generates a new UUID as an AUID from the current time and a location provided by the given node identifier. The node identifier must be a byte array containing at least 6 elements.

      It is possible to call this method repeatedly, even though Java's time resolution is to the nearest millisecond. An extra counter is implemented by MAJ in this method to provide an additional sequence of values to simulate the generation of time values measured in 100-nano second chunks as required by the UUID specification. The clock sequence part of the value is generated using a secure random number generator.

      Parameters:
        `nodeID` - Unique identifier for this computational node, which must contain at least 6 bytes.
      Returns:
        Time and location based UUID as an AUID.
      Throws:
        `NullPointerException` - The node ID byte array argument is `null`.
        `IllegalArgumentException` - The node identifier must contain at least 6 bytes.
      See Also:
        `timebasedAUID()`, `namebasedAUID(byte[])`, `randomAUID()`

    - #### namebasedAUID

          public static final AUID namebasedAUID(byte[] nameData)
                                          throws NullPointerException

      Generates a new UUID as an AUID generated with the name-based method, type 3. This method is based on `UUID.nameUUIDFromBytes(byte[])` that uses an MD5 hashing algorithm.

      Parameters:
        `nameData` - Name data to use to create a name-based UUID.
      Returns:
        Name-based UUID as an AUID.
      Throws:
        `NullPointerException` - The name data provided is `null`.
      See Also:
        `UUID.nameUUIDFromBytes(byte[])`, `namebasedAUID(String)`, `timebasedAUID()`, `randomAUID()`

    - #### namebasedAUID

          public static final AUID namebasedAUID(String nameData)
                                          throws NullPointerException

      Generates a new UUID as an AUID generated with the name-based method, type 3, from a Java string value. This method is based on `UUID.nameUUIDFromBytes(byte[])` that uses an MD5 hashing algorithm.

      Parameters:
        `nameData` - Name data to use to create a name-based UUID as a string.
      Returns:
        Name-based UUID as an AUID.
      Throws:
        `NullPointerException` - The name data provided is `null`.
      See Also:
        `UUID.nameUUIDFromBytes(byte[])`, `String.getBytes()`, `namebasedAUID(byte[])`, `timebasedAUID()`, `randomAUID()`

    - #### randomAUID

          public static final AUID randomAUID()

      Generates a new AUID using pseudo-random number generation, type 4. This method uses the `java.security.SecureRandom` number generator, seeded from values in the local environment obscured with a mixing function.

      Returns:
        Random generation of a new UUID as an AUID.
      See Also:
        `Utilities.seedRandomMaker()`, `timebasedAUID()`, `namebasedAUID(byte[])`

    - #### makeAUID

          public static final AUID makeAUID(byte[] bytes)
                                     throws NullPointerException

      Make a new AUID value from a 16-byte array representing its internal value. The given array is copied to make the internal representation used here safe from subsequent changes to the passed array. If the array length is less than or greater than 16, the array is padded with 0's or truncated to contain exactly 16 bytes.

      If a SMPTE Universal Label is detected, starting with bytes `0x06`, `0x0e`, `0x2b` and `0x34`, then the first eight and last eight bytes are swapped over to make a valid AUID.

      Parameters:
        `bytes` - Byte array to use to set the value of the new AUID.
      Throws:
        `NullPointerException` - The given array of bytes is `null`.
      See Also:
        `makeAUID(int, short, short, byte[])`, `parseAUID(String)`

    - #### makeAUID

          public static final AUID makeAUID(int data1,
                                            short data2,
                                            short data3,
                                            byte[] data4)
                                     throws NullPointerException

      Makes a new AUID value from its constituent parts.

      Parameters:
        `data1` - Integer value ... the first 4 bytes, also known as the "`time_low`" part.
        `data2` - Short value ... the next 2 bytes, also known as the "`time_mid`" part.
        `data3` - Short value ... the next 2 bytes, also known as the "`time_mid_and_version`" part.
        `data4` - Array of 8 bytes ... the final 8 bytes, containing the variant, clock sequence and node parts. The value will be truncated or padded if more or less than 8 bytes are provided respectively.
      Throws:
        `NullPointerException` - The given data4 value byte array is `null`.
      See Also:
        `makeAUID(byte[])`, `parseAUID(String)`

    - #### nilAUID

          public static final AUID nilAUID()

      Makes the nil AUID that represents the nil UUID, a special value where every byte element is set to zero.

      Returns:
        The nil AUID.

    - #### parseDate

          public static final DateStruct parseDate(String dateAsString)
                                            throws NullPointerException,
                                                   ParseException,
                                                   IllegalArgumentException

      Make 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`". This method always parses values generated by the date structure's `DateStruct.toString()` method.

      Note that this method does not support the specification of timezone or dates earlier than 1AD.

      For example, Tuesday 4th January 2011 is represented as "`2011-01-04`".

      Parameters:
        `dateAsString` - Date value represented as a string.
      Returns:
        Newly created date structure taken from the given string.
      Throws:
        `NullPointerException` - The given string representation of a date is `null`.
        `ParseException` - Given string value cannot be parsed into a date structure as it is in the wrong format or is not a valid date.
        `IllegalArgumentException` - After successful parsing, the given date is not an acceptable value due to the year value being out of range.
      See Also:
        `DateStruct.toString()`, `parseTime(String)`, `parseTimeStamp(String)`

    - #### todaysDate

          public static final DateStruct todaysDate()

      Make a date structure representing the current date.

      Returns:
        Date structure representing the current date.
      See Also:
        `now()`, `timeNow()`

    - #### makeDate

          public static final DateStruct makeDate(@UInt8
                                                  byte day,
                                                  @UInt8
                                                  byte month,
                                                  @Int16
                                                  short year)
                                           throws IllegalArgumentException

      Create a new date value using the given year, 1-based month and day of the month values.

      Parameters:
        `day` - Day component of the date.
        `month` - Month component of the date, with 1 for January, 2 for February etc..
        `year` - Year component of the date.
      Throws:
        `IllegalArgumentException` - One or more of the arguments has a value outside of an acceptable range.
      See Also:
        `DateStruct.getDay()`, `DateStruct.getMonth()`, `DateStruct.getYear()`, `DateStruct.setDate(byte, byte, short)`

    - #### makeDate

          public static final DateStruct makeDate(Calendar dateAsCalendar)
                                           throws NullPointerException

      Make 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:
        `dateAsCalendar` - Calendar value to use to extract a day, month and year from.
      Throws:
        `NullPointerException` - The given calendar value is `null`.
      See Also:
        `DateStruct.getDateValue()`

    - #### parseEdgeCode

          public static final EdgeCodeValue parseEdgeCode(String edgeCodeAsString)
                                                   throws NullPointerException,
                                                          ParseException

      Creates an edge code value from a pseudo-XML representation, including all those generated by `EdgeCodeValue.toString()`. Edge code values are intended to match those generated for the AAF XML schema.

      An example edge code representation that would be parsed by this method is:

               <EdgecodeValue>
                 <EdgeCodeStart>321</EdgeCodeStart>
                 <FilmKind>Ft35MM</FilmKind>
                 <CodeFormat>EtKeycode</CodeFormat>
                 <!--Header as text: 'abcdefgh'-->
                 <EdgeCodeHeader>6162636465666768</EdgeCodeHeader>
               </EdgecodeValue>

      Note that any unrecognised values will result in the setting of a default value rather than an error. Parse exceptions are only thrown when the validity of a value can only be determined beyond matching a simple regular expression.

      Parameters:
        `edgeCodeAsString` - Pseudo-XML representation of an edge code value.
      Returns:
        Edge code value with values with component values parsed from the given string.
      Throws:
        `NullPointerException` - The given string value is `null`.
        `ParseException` - A problem occurred when trying to decode the given string.
      See Also:
        `EdgeCodeValue.toString()`

    - #### makeEdgeCode

          public static final EdgeCodeValue makeEdgeCode()

      Makes a default film edge code value, with start frame 0, a null film kind, null edge type and no header.

      Returns:
        Default film edge code value.

    - #### makeEdgeCode

          public static final EdgeCodeValue makeEdgeCode(@PositionType
                                                         long startFrame,
                                                         FilmType filmKind,
                                                         EdgeType codeFormat)
                                                  throws NullPointerException

      Makes a new film edge code value from its component parts.

      Parameters:
        `startFrame` - Specifies the edge code at the beginning of the corresponding segment.
        `filmKind` - Specifies the type of film.
        `codeFormat` - Specifies the edge code format.
      Throws:
        `NullPointerException` - One or more of the arguments is/are `null`.

    - #### makeEdgeCode

          public static final EdgeCodeValue makeEdgeCode(@PositionType
                                                         long startFrame,
                                                         FilmType filmKind,
                                                         EdgeType codeFormat,
                                                         byte[] header)
                                                  throws NullPointerException

      Makes a new film edge code value from its component parts, including the optional header as a byte array.

      Parameters:
        `startFrame` - Specifies the edge code at the beginning of the corresponding segment.
        `filmKind` - Specifies the type of film.
        `codeFormat` - Specifies the edge code format.
        `header` - Text prefix that identifies the film.
      Throws:
        `NullPointerException` - One or more of the arguments is/are `null`.

    - #### makeEdgeCode

          public static final EdgeCodeValue makeEdgeCode(@PositionType
                                                         long startFrame,
                                                         FilmType filmKind,
                                                         EdgeType codeFormat,
                                                         String header)
                                                  throws NullPointerException

      Makes a new film edge code value from its component parts, including the optional header as a string.

      Parameters:
        `startFrame` - Specifies the edge code at the beginning of the corresponding segment.
        `filmKind` - Specifies the type of film.
        `codeFormat` - Specifies the edge code format.
        `header` - Text prefix that identifies the film.
      Throws:
        `NullPointerException` - One or more of the arguments is/are `null`.

    - #### parsePackageID

          public static final PackageID parsePackageID(String packageIDAsString)
                                                throws NullPointerException,
                                                       ParseException

      Parse a package identifier formatted as a URN-style UMID string and convert it into a newly instantiated package id with an equivalent value. The format of the expected value is the same as that generated by the `PackageID.toString()` method.

      For example:

      `urn:smpte:umid:060a2b34.01010101.01010f13.1300b347.53b933d9.18245095.ca82322e.c0a801ba`

      Hexadecimal digits used to express the UMID value may be a mixture of upper or lower case letters.

      Note that this method also works with the old style of package ID URN, for example:

      `urn:x-umid:060a2b340101010101010f13-13-00b347-53b933d918245095ca82322ec0a801ba`
      Parameters:
        `packageIDAsString` - Package identifier value formatted as a URN-style UMID string.
      Returns:
        Package identifier value created from the given URN-style UMID value.
      Throws:
        `NullPointerException` - The package identifier string value is `null`.
        `ParseException` - The given URN value is the wrong length, a different kind or URN, has path separators in the wrong place or contains digits other than hexadecimal digits where hexadecimal digits are expected.
      See Also:
        `PackageID.toString()`

    - #### zeroPackageID

          public static final PackageID zeroPackageID()

      Makes the zero package identifier that consists of every bit set to zero. This value has special significance for original source references where it is used to indicate the original source, the end of this source reference chain.

      Returns:
        The zero package ID with all values set to zero.
      See Also:
        `makePackageID(byte[])`, `makePackageID(byte[], byte, byte, byte, byte, AUID)`

    - #### makePackageID

          public static final PackageID makePackageID(byte[] univeralLabel,
                                                      @UInt8
                                                      byte length,
                                                      @UInt8
                                                      byte instanceHigh,
                                                      @UInt8
                                                      byte instanceMid,
                                                      @UInt8
                                                      byte instanceLow,
                                                      AUID materialNumber)
                                               throws NullPointerException

      Make a new package identifier from the specified parameters. The label and material values are copied to ensure that subsequent external changes do not effect the newly created package identifier.

      A default universal label to set the package identifier to be a SMPTE UMID is available as constant `PackageID.BaseUniversalLabel`.

      Parameters:
        `univeralLabel` - Universal label component of the package identifier.
        `length` - Length of the following data.
        `instanceHigh` - Most significant part of the instance number component of the package identifier.
        `instanceMid` - Second most significant part the instance number component of the package identifier.
        `instanceLow` - Least significant part of the instance number component of the package identifier.
        `materialNumber` - Unique identifier for the identified material, the material number component of the package identifier.
      Throws:
        `NullPointerException` - One or both of the universal label or material number numbers are `null`.
      See Also:
        `zeroPackageID()`, `makePackageID(byte[])`, `PackageID.BaseUniversalLabel`

    - #### makePackageID

          public static final PackageID makePackageID(byte[] bytes)
                                               throws NullPointerException

      Make a new package identifier from the given byte array of elements. The array should be 32 bytes in length and in the form of a UMID. If the array is too short or too long, it will be padded with zeros or truncated to make it 32 bytes. The passed array value is cloned to avoid external changes to the array affecting this value.

      If the bytes of the material number part appear to be an unswapped universal label value, these will be swapped to an AUID-appropriate internal representation.

      Parameters:
        `bytes` - Byte array representing the elements of a package identifier.
      Returns:
        Package identifier created from the given array of bytes.
      Throws:
        `NullPointerException` - The given array of byte elements is `null`.
      See Also:
        `zeroPackageID()`, `makePackageID(byte[], byte, byte, byte, byte, AUID)`

    - #### generatePackageID

          public static final PackageID generatePackageID(AUID materialNumber)
                                                   throws NullPointerException

      Generate a new package identifier appropriate for use in D-Cinema packaging using the given material number using the material number generation method. As for completely random D-Cinema UMIDs, the material type is not identified and the instance number generation is not defined.

      Parameters:
        `materialNumber` - Material number part of the new package identifier.
      Returns:
        Package identifier appropriate for use in D-Cinema packaging.
      Throws:
        `NullPointerException` - Cannot use a `null` material number to generate a package identifier.
      See Also:
        `dCinemaUMID()`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`

    - #### generatePackageID

          public static final PackageID generatePackageID(MaterialType materialType,
                                                          InstanceNumberGeneration instanceNumberGeneration,
                                                          MaterialNumberGeneration materialNumberGeneration)
                                                   throws NullPointerException,
                                                          GenerationMethodNotSupportedException

      Generate a new package identifier according to the given material type, instance number generation method and material number generation method. The material type and generation methods are as described in SMPTE 330M.

      The supported material number generation methods are as follows:

      - `MaterialNumberGeneration.SMPTE` - Creates a material number from the system clock, current date, a two byte random number and a 6 byte system identifier. This approach is documented in section A.1 of SMPTE 330M and should ensure a high degree of identifier uniqueness. The system identifier must be provided as the first 6 bytes of the extra data parameter. Java 1.5 does not provide a means to extract the ethernet address of the system on which a virtual machine is running but a locally administered value that is a combination of bytes taken from the system's IP address and domain name should be sufficient. Just such a value is provided by calling `Utilities.createLocalHostID(6)`.
      - `MaterialNumberGeneration.UUID_UL` - Generates a material number from the UUID or universal label provided as the 16 bytes passed as the extra data parameter. The method assumes that the byte reordering documented in section A.2 of SMPTE 330M has already taken place. No validation of the UUID or universal label is carried out. In fact, this method is implemented here as a dumb pass through of the given value directly to the 16-bytes of the material number of the new package identifier.
      - `MaterialNumberGeneration.Masked` - Generates a material number according to the SMPTE method and then uses an MD5 function on the value to mask the details, as described in section A.3 of SMPTE 330M. This masking is normally done for security reasons so as to hide details of creation times and systems identification. Once masked, the time and host id values cannot be easily recovered and the masking function ensures the same degree of uniqueness as the SMPTE method.
      - `MaterialNumberGeneration.IEEE1394` - Generates a material number according to the IEEE 1394 network method, as described in section A.4 of SMPTE 330M. The first 8 bytes are generated from the system clock, current date and a random number. The last 8 bytes are the device node identifier that must be provided as the extra bytes parameter. The device node of the system on which the virtual machine is running is not available in the core Java API version 1.5. A locally derived host identifier created from the system's IP address and domain name can be generated by calling `Utilities.createLocalHostID(8)`.
      - `MaterialNumberGeneration.NotDefined` - A pseudo random number is generated for the 128-bits of data representing the material number, using the `SecureRandom` class.

      The supported instance generation methods are documented in more detail in `PackageID.nextInstance()`, with the instance number initialized as follows:

      - `InstanceNumberGeneration.LocalRegistration` - All three instance bytes are set to zero.
      - `InstanceNumberGeneration.CopyAndPseudoRandom16Bit` - The instance high byte is set to 0 and the other two bytes are set to random values.
      - `InstanceNumberGeneration.PseudoRandom24Bit` - The instance high, middle and low values are set using 24 randomly generated bits.
      - `InstanceNumberGeneration.LiveStream` - Not supported and throws a `GenerationMethodNotSupportedException`.
      - `InstanceNumberGeneration.NotDefined` - Same as PseudoRandom24Bit.

      The chosen type of instance number generated will define the behaviour of subsequent calls to `PackageID.nextInstance()` for the new package identifier.

      Parameters:
        `materialType` - Type of material represented by the new package identifier.
        `materialNumberGeneration` - Method to use to generate the material number of the package identifier.
        `instanceNumberGeneration` - Method to use to generate the first and next instance numbers for the package identifier.
      Returns:
        Newly manufactured package identifier, which is a SMPTE UMID according to the given specification.
      Throws:
        `NullPointerException` - One or more of the arguments is `null` and all are required.
        `GenerationMethodNotSupportedException` - The given material or instance number generation method is not supported.
      See Also:
        `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`, `generatePackageID(AUID)`, `dCinemaUMID()`

    - #### generatePackageID

          public static final PackageID generatePackageID(MaterialType materialType,
                                                          InstanceNumberGeneration instanceNumberGeneration,
                                                          MaterialNumberGeneration materialNumberGeneration,
                                                          byte[] extraData)
                                                   throws NullPointerException,
                                                          GenerationMethodNotSupportedException

      Generate a new package identifier according to the given material type, instance number generation method and material number generation method. The material type and generation methods are as described in SMPTE 330M.

      The supported material number generation methods are as follows:

      - `MaterialNumberGeneration.SMPTE` - Creates a material number from the system clock, current date, a two byte random number and a 6 byte system identifier. This approach is documented in section A.1 of SMPTE 330M and should ensure a high degree of identifier uniqueness. The system identifier must be provided as the first 6 bytes of the extra data parameter. Java 1.5 does not provide a means to extract the ethernet address of the system on which a virtual machine is running but a locally administered value that is a combination of bytes taken from the system's IP address and domain name should be sufficient. Just such a value is provided by calling `Utilities.createLocalHostID(6)`.
      - `MaterialNumberGeneration.UUID_UL` - Generates a material number from the UUID or universal label provided as the 16 bytes passed as the extra data parameter. The method assumes that the byte reordering documented in section A.2 of SMPTE 330M has already taken place. No validation of the UUID or universal label is carried out. In fact, this method is implemented here as a dumb pass through of the given value directly to the 16-bytes of the material number of the new package identifier.
      - `MaterialNumberGeneration.Masked` - Generates a material number according to the SMPTE method and then uses an MD5 function on the value to mask the details, as described in section A.3 of SMPTE 330M. This masking is normally done for security reasons so as to hide details of creation times and systems identification. Once masked, the time and host id values cannot be easily recovered and the masking function ensures the same degree of uniqueness as the SMPTE method.
      - `MaterialNumberGeneration.IEEE1394` - Generates a material number according to the IEEE 1394 network method, as described in section A.4 of SMPTE 330M. The first 8 bytes are generated from the system clock, current date and a random number. The last 8 bytes are the device node identifier that must be provided as the extra bytes parameter. The device node of the system on which the virtual machine is running is not available in the core Java API version 1.5. A locally derived host identifier created from the system's IP address and domain name can be generated by calling `Utilities.createLocalHostID(8)`.
      - `MaterialNumberGeneration.NotDefined` - A pseudo random number is generated for the 128-bits of data representing the material number, using the `SecureRandom` class.

      The supported instance generation methods are documented in more detail in `PackageID.nextInstance()`, with the instance number initialized as follows:

      - `InstanceNumberGeneration.LocalRegistration` - All three instance bytes are set to zero.
      - `InstanceNumberGeneration.CopyAndPseudoRandom16Bit` - The instance high byte is set to 0 and the other two bytes are set to random values.
      - `InstanceNumberGeneration.PseudoRandom24Bit` - The instance high, middle and low values are set using 24 randomly generated bits.
      - `InstanceNumberGeneration.LiveStream` - Not supported and throws a `GenerationMethodNotSupportedException`.
      - `InstanceNumberGeneration.NotDefined` - Same as PseudoRandom24Bit.

      The chosen type of instance number generated will define the behaviour of subsequent calls to `PackageID.nextInstance()` for the new package identifier.

      Parameters:
        `materialType` - Type of material represented by the new package identifier.
        `materialNumberGeneration` - Method to use to generate the material number of the package identifier.
        `instanceNumberGeneration` - Method to use to generate the first and next instance numbers for the package identifier.
        `extraData` - Additional data required by the material number generation method.
      Returns:
        Newly manufactured package identifier, which is a SMPTE UMID according to the given specification.
      Throws:
        `NullPointerException` - One or more of the arguments is `null` and all are required.
        `GenerationMethodNotSupportedException` - The given material or instance number generation method is not supported.
      See Also:
        `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `generatePackageID(AUID)`, `dCinemaUMID()`

    - #### generatePackageID

          public static final PackageID generatePackageID(MaterialType materialType,
                                                          InstanceNumberGeneration instanceNumberGeneration,
                                                          MaterialNumberGeneration materialNumberGeneration,
                                                          AUID materialNumber)
                                                   throws NullPointerException,
                                                          GenerationMethodNotSupportedException

      Generate a new package identifier according to the given material type, instance number generation method and material number generation method. The material type and generation methods are as described in SMPTE 330M.

      The supported material number generation methods are as follows:

      - `MaterialNumberGeneration.SMPTE` - Creates a material number from the system clock, current date, a two byte random number and a 6 byte system identifier. This approach is documented in section A.1 of SMPTE 330M and should ensure a high degree of identifier uniqueness. The system identifier must be provided as the first 6 bytes of the extra data parameter. Java 1.5 does not provide a means to extract the ethernet address of the system on which a virtual machine is running but a locally administered value that is a combination of bytes taken from the system's IP address and domain name should be sufficient. Just such a value is provided by calling `Utilities.createLocalHostID(6)`.
      - `MaterialNumberGeneration.UUID_UL` - Generates a material number from the UUID or universal label provided as the 16 bytes passed as the extra data parameter. The method assumes that the byte reordering documented in section A.2 of SMPTE 330M has already taken place. No validation of the UUID or universal label is carried out. In fact, this method is implemented here as a dumb pass through of the given value directly to the 16-bytes of the material number of the new package identifier.
      - `MaterialNumberGeneration.Masked` - Generates a material number according to the SMPTE method and then uses an MD5 function on the value to mask the details, as described in section A.3 of SMPTE 330M. This masking is normally done for security reasons so as to hide details of creation times and systems identification. Once masked, the time and host id values cannot be easily recovered and the masking function ensures the same degree of uniqueness as the SMPTE method.
      - `MaterialNumberGeneration.IEEE1394` - Generates a material number according to the IEEE 1394 network method, as described in section A.4 of SMPTE 330M. The first 8 bytes are generated from the system clock, current date and a random number. The last 8 bytes are the device node identifier that must be provided as the extra bytes parameter. The device node of the system on which the virtual machine is running is not available in the core Java API version 1.5. A locally derived host identifier created from the system's IP address and domain name can be generated by calling `Utilities.createLocalHostID(8)`.
      - `MaterialNumberGeneration.NotDefined` - A pseudo random number is generated for the 128-bits of data representing the material number, using the `SecureRandom` class.

      The supported instance generation methods are documented in more detail in `PackageID.nextInstance()`, with the instance number initialized as follows:

      - `InstanceNumberGeneration.LocalRegistration` - All three instance bytes are set to zero.
      - `InstanceNumberGeneration.CopyAndPseudoRandom16Bit` - The instance high byte is set to 0 and the other two bytes are set to random values.
      - `InstanceNumberGeneration.PseudoRandom24Bit` - The instance high, middle and low values are set using 24 randomly generated bits.
      - `InstanceNumberGeneration.LiveStream` - Not supported and throws a `GenerationMethodNotSupportedException`.
      - `InstanceNumberGeneration.NotDefined` - Same as PseudoRandom24Bit.

      The chosen type of instance number generated will define the behaviour of subsequent calls to `PackageID.nextInstance()` for the new package identifier.

      Parameters:
        `materialType` - Type of material represented by the new package identifier.
        `materialNumberGeneration` - Method to use to generate the material number of the package identifier.
        `instanceNumberGeneration` - Method to use to generate the first and next instance numbers for the package identifier.
        `materialNumber` - Material number to pass through to the last 16 bytes of the package identifier where appropriate.
      Returns:
        Newly manufactured package identifier, which is a SMPTE UMID according to the given specification.
      Throws:
        `NullPointerException` - One or more of the arguments is `null` and all are required.
        `GenerationMethodNotSupportedException` - The given material or instance number generation method is not supported.
      See Also:
        `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`, `generatePackageID(AUID)`, `dCinemaUMID()`

    - #### dCinemaUMID

          public static final PackageID dCinemaUMID()

      Generates a package identifier appropriate for use in D-Cinema packaging, as defined in section 6.3.1 of SMPTE 429-3-2007. This is a value with no material type defined, no instance number and a random UUID used for the material number.

      For example:

      `urn:smpte:umid:0602b34.01010105.01010f20.13000000.9ADB7935.22904D96.86656A99.78529D78`
      Returns:
        Package identifier appropriate for use in D-Cinema packaging.
      See Also:
        `generatePackageID(AUID)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`, `randomUMID()`

    - #### randomUMID

          public static final PackageID randomUMID()

      Generates a UMID with a random material number. A random UMID generated by this forge is actually the same as a D-Cinema UMID.

      Returns:
        Package identifier with a random material number.
      See Also:
        `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`, `dCinemaUMID()`

    - #### parseProductVersion

          public static final ProductVersion parseProductVersion(String versionAsAString)
                                                          throws NullPointerException,
                                                                 ParseException

      Makes an instance of this product version class by parsing the given pseudo-XML version. This method will create an instance from the result of calling the `ProductVersion.toString()` method. The pseudo-XML format is illustrated below:

               <ProductVersion>
                 <Major>0</Major>
                 <Minor>3</Minor>
                 <Tertiary>1</Tertiary>
                 <PatchLevel>2</PatchLevel>
                 <BuildType>VersionDebug</BuildType>
               </ProductVersion>

      If any tags are missing, default values are used and the method returns successfully. This method ignores any namespace prefix found in an element name.

      Parameters:
        `versionAsAString` - Pseudo-XML string to convert into a product version instance.
      Returns:
        Product version created from the given string.
      Throws:
        `NullPointerException` - The given version string is `null`.
        `ParseException` - Parse error creating a numerical value (major, minor, tertiary, patch level) or the given build type does not match the tokens of the product release type enumeration.

    - #### makeProductVersion

          public static final ProductVersion makeProductVersion(@UInt16
                                                                short major,
                                                                @UInt16
                                                                short minor,
                                                                @UInt16
                                                                short tertiary,
                                                                @UInt16
                                                                short patchLevel,
                                                                ProductReleaseType type)
                                                         throws NullPointerException,
                                                                IllegalArgumentException

      Make a product version value that represents the version of an application.

      Parameters:
        `major` - Application's major version number.
        `minor` - Application's minor version number.
        `tertiary` - Application's tertiary version number.
        `patchLevel` - Application's patch level.
        `type` - Application's product release type.
      Throws:
        `NullPointerException` - The product release type argument is `null`.
        `IllegalArgumentException` - One of more of the major, minor, tertiary or patch level values is negative.
      See Also:
        `zeroProductVersion()`

    - #### zeroProductVersion

          public static final ProductVersion zeroProductVersion()

      Make a zero product version value, with all numerical values set to zero and the release type set to unknown.

      Returns:
        Zero product version value.
      See Also:
        `makeProductVersion(short, short, short, short, ProductReleaseType)`

    - #### parseRational

          public static final Rational parseRational(String rationalAsString)
                                              throws NullPointerException,
                                                     ParseException

      Make a rational value by parsing a string representation. The string representation is expected to take the form of the numerator, followed by a slash character ('`/`'), followed by the denominator, e.g. "`-123/4567`". This format is as created by `Rational.toString()`.

      Parameters:
        `rationalAsString` - String to use to create a rational value.
      Returns:
        Corresponding rational value.
      Throws:
        `NullPointerException` - The rational as string argument is `null`.
        `PraseException` - The string is not formatted as a rational number representation.
        `ParseException`
      See Also:
        `Rational.toString()`

    - #### makeRational

          public static final Rational makeRational(@Int32
                                                    int numerator,
                                                    @Int32
                                                    int denominator)

      Make a rational value from its numerator and denominator.

      Parameters:
        `numerator` -
        `denominator` -
      Returns:
        Rational value as specified by the arguments.
      See Also:
        `zeroRational()`

    - #### zeroRational

          public static final Rational zeroRational()

      Make a rational value of zero, with numerator of 0 and denominator of 1.

      Returns:
        Zero rational value.
      See Also:
        `makeRational(int, int)`

    - #### parseRGBAComponent

          public static final RGBAComponent parseRGBAComponent(String rgbaComponentAsString)
                                                        throws NullPointerException,
                                                               ParseException

      Make a new element of an RGBA layout array by parsing the given pseudo-XML representation. This method will create an instance from the result of calling the `RGBAComponent.toString()` method. The pseudo-XML format is illustrated below:

             <RGBAComponent>
               <Code>CompRed</Code>
               <ComponentSize>8</ComponentSize>
             </RGBAComponent>

      If any tags are missing, default values are used and the method returns successfully. This method ignores any namespace prefix found in an element name.

      Parameters:
        `rgbaComponentAsString` - Pseudo-XML string to convert into a RGBA component instance.
      Returns:
        Newly created RGBA component instance.
      Throws:
        `NullPointerException` - The given psuedo-XML representation is `null`.
        `ParseException` - The component size could not be parsed into a byte value or the given component code was not recognized as an element of the RGBA component kind enumeration.
      See Also:
        `RGBAComponent.toString()`, `TypeDefinitions.RGBAComponent`, `TypeDefinitions.RGBALayout`

    - #### makeRGBAComponent

          public static final RGBAComponent makeRGBAComponent(RGBAComponentKind code,
                                                              @UInt8
                                                              byte size)
                                                       throws NullPointerException,
                                                              IllegalArgumentException

      Make an element of an RGBA layout array.

      Parameters:
        `code` - Code for the component.
        `size` - Size of the component in bits.
      Throws:
        `NullPointerException` - The code argument is `null`.
        `IllegalArgumentException` - The size argument is negative.
      See Also:
        `zeroRGBAComponent()`, `TypeDefinitions.RGBALayout`

    - #### zeroRGBAComponent

          public static final RGBAComponent zeroRGBAComponent()

      Make an element of an RGBA layout array with a `RGBAComponentKind.Null` code and a size of `0`.

      See Also:
        `makeRGBAComponent(RGBAComponentKind, byte)`, `TypeDefinitions.RGBALayout`

    - #### parseTimecode

          public static final TimecodeValue parseTimecode(String timecodeAsAString)
                                                   throws NullPointerException,
                                                          ParseException

      Makes a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, implying default values for the frames per second and drop frame parameters from the timecode text. The method will try and parse both drop and non-drop values, working with both SMPTE-12M values and a broader definition of timecodes as required for high frame rate television. This method assumes any value with a "`;`" in it is a drop-frame value at 30 fps or 60 fps, otherwise the value is assumed to be a non-drop timecode at 25 fps or 50 fps. The higher frame rates of 60 fps; and 50 fps if the value ends with a frame pair value of `.0` or `.1`.

      String timecode representations are parsed as follows:

      - The format of a non-drop timecode specified by frame is:
        <hour>`:`<minute>`:`<second>`:`<frame>(`.`<framePair>)?
      - The format of a drop timecode specified by frame is:
        <hour>`:`<minute>`:`<second>`;`<frame>(`.`<framePair>)?

      The hour, minute, second and frame values should all be Java short values. The framePair value should be either 0 or 1. The number of digits is not significant, although values are limited to being `Int16`. For example, the values `"01:02:03:04"` is parsed the same as `"1:2:003:4".`

      Parameters:
        `timecodeAsAString` - String representation of a timecode value.
      Returns:
        A timecode value created by parsing the given textual representation.
      Throws:
        `NullPointerException` - The given string representation of a timecode is actually `null`.
        `ParseException` - It is not possible to parse the given value to a MAJ API timecode value.
      See Also:
        `TimecodeValue.toString()`, `parseTimecode(String, short, boolean)`

    - #### parseTimecode

          public static final TimecodeValue parseTimecode(String timecodeAsAString,
                                                          @UInt16
                                                          short explicitFramesPerSecond,
                                                          boolean explicitDropFrameIndicator)
                                                   throws NullPointerException,
                                                          ParseException,
                                                          IllegalArgumentException

      Makes a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, with all parameters specified. The method will try and parse both drop and non-drop values, working with both SMPTE-12M values and the additional frame pair value for higher frame rate television.

      The format of a timecode parsed by this method is:

      <hour>`:`<minute>`:`<second>`:`<frame>(`.`<framePair>)?

      The hour, minute, second and frame values should all be Java short values. The framePair value should be either 0 or 1. The number of digits is not significant, although values are limited to being `Int16`. For example, the values `"01:02:03:04"` is parsed the same as `"1:2:003:4".`

      Parameters:
        `timecodeAsAString` - String representation of a timecode value.
        `explicitFramesPerSecond` - Explicit value for the frames per second of this timecode value.
        `explicitDropFrameIndicator` - Explicit indicator as to whether this timecode value requires allowance for drop frames.
      Returns:
        A timecode value created by parsing the given textual representation and explicit values.
      Throws:
        `NullPointerException` - The given string representation of a timecode is actually `null`.
        `ParseException` - It is not possible to parse the given value to a MAJ API timecode value.
        `IllegalArgumentException` - The given frames per second value cannot be negative or zero.
      See Also:
        `TimecodeValue.toString()`, `parseTimecode(String)`

    - #### makeTimecode

          public static final TimecodeValue makeTimecode(@FrameOffset
                                                         long startFrame,
                                                         @UInt16
                                                         short fps,
                                                         boolean drop)
                                                  throws IllegalArgumentException

      Make a timecode value from its actual component parts.

      Parameters:
        `startFrame` - Specifies the timecode as the number of frames offset from the start of the video or audio.
        `fps` - Frames per second of the videotape or audio tape.
        `drop` - Indicates whether the timecode is drop (`true` value) or nondrop (`false` value).
      Throws:
        `IllegalArgumentException` - The frames per second value is not a positive value.
      See Also:
        `calculateTimecode(short, short, short, short, short, boolean)`, `zeroTimecode()`

    - #### calculateTimecode

          public static final TimecodeValue calculateTimecode(short hours,
                                                              short minutes,
                                                              short seconds,
                                                              short frames,
                                                              @UInt16
                                                              short fps,
                                                              boolean drop)
                                                       throws IllegalArgumentException

      For lower frame rates (up to 30), calculate a new timecode value from the given hours, minutes, seconds and frames according to the given number of frames per second and whether the timecode value requires drop frame calculations. Internally, these values are converted to a frame offset value.

      This method does not apply strict boundaries. Negative values and values greater than the acceptable bounds when displaying a timecode will be accepted and mapped to an appropriate offset. For example, the following three calls to this method create equivalent timecode values:

           Forge.calculateTimecode(0, 0, 63,   0, 25, false);
           Forge.calculateTimecode(0, 1, 03,   0, 25, false);
           Forge.calculateTimecode(0, 1, 04, -25, 25, false);

      Parameters:
        `hours` - Number of hours since the start of an item represented by this timecode.
        `minutes` - Number of minutes in the hour of an item represented by this timecode.
        `seconds` - Number of seconds in the minute of an item represented by this timecode.
        `frames` - Number of frames through the second of an item represented by this timecode.
        `fps` - Number of frames per second for this timecode value.
        `drop` - Does this timecode require drop frame calculation?
      Throws:
        `IllegalArgumentException` - The number of frames per second is not a positive (greater than zero) number.
      See Also:
        `makeTimecode(long, short, boolean)`, `calculateTimecode(short, short, short, short, short, short, boolean)`, `zeroTimecode()`

    - #### calculateTimecode

          public static final TimecodeValue calculateTimecode(short hours,
                                                              short minutes,
                                                              short seconds,
                                                              short frames,
                                                              short framePair,
                                                              @UInt16
                                                              short fps,
                                                              boolean drop)
                                                       throws IllegalArgumentException

      For higher frame rates (greater than 30), calculate a new timecode value from the given hours, minutes, seconds, frames and frame pair according to the given number of frames per second and whether the timecode value requires drop frame calculations. Internally, these values are converted to a frame offset value.

      This method does not apply strict boundaries. Negative values and values greater than the acceptable bounds when displaying a timecode will be accepted and mapped to an appropriate offset.

      Some examples:

           Forge.calculateTimecode(0, 0, 63,   0, 0, 50, false);
           Forge.calculateTimecode(0, 1, 03,   0, 1, 60, true);
           Forge.calculateTimecode(0, 1, 04, -25, 0, 60, true);

      Parameters:
        `hours` - Number of hours since the start of an item represented by this timecode.
        `minutes` - Number of minutes in the hour of an item represented by this timecode.
        `seconds` - Number of seconds in the minute of an item represented by this timecode.
        `frames` - Number of frames through the second of an item represented by this timecode.
        `framePair` - For frame rates higher than 30fps, which sub-frame is being referenced. This is normally 0 for the first and 1 for the second.
        `fps` - Number of frames per second for this timecode value.
        `drop` - Does this timecode require drop frame calculation?
      Throws:
        `IllegalArgumentException` - The number of frames per second is not a positive (greater than zero) number.
      See Also:
        `makeTimecode(long, short, boolean)`, `calculateTimecode(short, short, short, short, short, boolean)`, `zeroTimecode()`

    - #### zeroTimecode

          public static final TimecodeValue zeroTimecode()

      Make a zero timecode value, with a zero start frame, zero frames per second and a zero drop frame.

      Returns:
        Zero timecode value.
      See Also:
        `makeTimecode(long, short, boolean)`, `calculateTimecode(short, short, short, short, short, boolean)`

    - #### calculateDuration

          public static final TimecodeValue calculateDuration(TimecodeValue startValue,
                                                              TimecodeValue endValue)
                                                       throws NullPointerException,
                                                              IllegalArgumentException

      Calculate the duration of a piece of media from its start timecode and end timecode. The value returned is a timecode representing the duration. Both values must be specified with the same number of frames per second and matching drop timecode specifications. The end value must be the same or greater than the start value.

      To calculate the number of frames of an item of media, call `TimecodeValue.getStartTimecode()` on the value returned by this method.

      Parameters:
        `startValue` - Start timecode at the beginning of the segment of media, sometimes known as SOM (Start Of Message).
        `endValue` - End timecode at the end of the segment of media, sometimes known as EOM (End Of Message).
      Returns:
        Duration timecode value calculated as the difference between the end value and the start value.
      Throws:
        `NullPointerException` - One or both of the start and/or end timecodes is/are `null`.
        `IllegalArgumentException` - It was not possible to calculate the duration as the timecode values are incompatible or the start value is after the end value.
      See Also:
        `LengthType`, `calculateEndTimecode(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)`

    - #### calculateEndTimecode

          public static final TimecodeValue calculateEndTimecode(TimecodeValue startValue,
                                                                 TimecodeValue duration)
                                                          throws NullPointerException,
                                                                 IllegalArgumentException

      Calculate the end timecode for a segment of media from its start timecode and a timecode value representing its duration. Both values must be specified with the same number of frames per second and matching drop timecode specifications.

      Parameters:
        `startValue` - Start timecode at the beginning of a segment of media.
        `duration` - Duration of the media specified as a timecode value.
      Returns:
        End timecode value calculated by adding the duration timecode's length to the start timecode.
      Throws:
        `NullPointerException` - One or both of the start and/or duration values is/are `null`.
        `IllegalArgumentException` - It was not possible to calculate the end timecode as the timecode values are incompatible.
      See Also:
        `calculateDuration(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)`

    - #### parseTimeStamp

          public static final TimeStamp parseTimeStamp(String timeStampAsAString)
                                                throws NullPointerException,
                                                       ParseException

      Make a time stamp value 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 100ths of a second.

      Values in this format can be created using `TimeStamp.toString()`.

      Parameters:
        `timeStampAsAString` - 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` - The given time stamp as a string value is `null`.
      See Also:
        `TimeStamp.toString()`, `parseTime(String)`, `parseDate(String)`

    - #### makeTimeStamp

          public static final TimeStamp makeTimeStamp(DateStruct date,
                                                      TimeStruct time)
                                               throws NullPointerException,
                                                      IllegalArgumentException

      Make a time stamp using the components of the given date and time values. This method is strict in its interpretation of date and time values.

      Parameters:
        `date` - Date component of the time stamp to create.
        `time` - Time component of the time stamp to create.
      Returns:
        Timestamp created from the given date and time values.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`.
        `IllegalArgumentException` - The resulting time stamp value would not be valid.
      See Also:
        `makeTimeStamp(Calendar)`, `makeTimeStamp(short, byte, byte, byte, byte, byte, byte)`, `now()`

    - #### makeTimeStamp

          public static final TimeStamp makeTimeStamp(@Int16
                                                      short year,
                                                      @UInt8
                                                      byte month,
                                                      @UInt8
                                                      byte day,
                                                      @UInt8
                                                      byte hour,
                                                      @UInt8
                                                      byte minute,
                                                      @UInt8
                                                      byte second,
                                                      @UInt8
                                                      byte fraction)
                                               throws IllegalArgumentException

      Make a time stampe using all of the components of the date and time parts. This method is strict in its interpretation of date and time values.

      Parameters:
        `year` - Year component of the time stamp.
        `month` - Month component of the time stamp, 1-based, with 1 for January, 2 for Febrary etc..
        `day` - Day of the month component of the time stamp.
        `hour` - Hour component of the time stamp.
        `minute` - Minute component of the time stamp.
        `second` - Second component of the time stamp.
        `fraction` - Fraction of a second component of the time stamp, measured in 1/250ths of a second.
      Returns:
        Timestamp created from its component parts.
      Throws:
        `IllegalArgumentException` - The resulting time stamp value would not be valid.
      See Also:
        `makeTimeStamp(DateStruct, TimeStruct)`, `makeTimeStamp(Calendar)`, `now()`

    - #### makeTimeStamp

          public static final TimeStamp makeTimeStamp(Calendar timeStampAsCalendar)
                                               throws NullPointerException,
                                                      IllegalArgumentException

      Make a 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 `TimeStamp.getTimeStamp()`.

      Parameters:
        `timeStampAsCalendar` - Calendar value to use to set the value of this time stamp.
      Throws:
        `NullPointerException` - The given calendar value is `null`.
        `IllegalArgumentException` - The given calendar value is not a valid date or time.
      See Also:
        `makeTimeStamp(DateStruct, TimeStruct)`, `makeTimeStamp(short, byte, byte, byte, byte, byte, byte)`, `now()`

    - #### now

          public static final TimeStamp now()

      Make a timestamp representing the date and time now.

      Returns:
        Timestamp for the current date and time.
      See Also:
        `todaysDate()`, `timeNow()`

    - #### parseTime

          public static final TimeStruct parseTime(String timeAsAString)
                                            throws NullPointerException,
                                                   ParseException

      Makes 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:
        `timeAsAString` - UTC-style string time value.
      Returns:
        Time structure representing the given string time value.
      Throws:
        `NullPointerException` - Provided time as a string value is `null`.
        `ParseException` - The given value could not be converted into a time structure value.
      See Also:
        `TimeStruct.toString()`, `parseTimeStamp(String)`, `parseDate(String)`

    - #### makeTime

          public static final TimeStruct makeTime(byte hour,
                                                  byte minute,
                                                  byte second)
                                           throws IllegalArgumentException

      Make 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.
      See Also:
        `makeTime(Calendar)`, `makeTime(byte, byte, byte, byte)`, `timeNow()`

    - #### makeTime

          public static final TimeStruct makeTime(byte hour,
                                                  byte minute,
                                                  byte second,
                                                  byte fraction)
                                           throws IllegalArgumentException

      Make 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.
      See Also:
        `makeTime(Calendar)`, `makeTime(byte, byte, byte)`, `timeNow()`

    - #### makeTime

          public static final TimeStruct makeTime(Calendar timeAsCalendar)
                                           throws NullPointerException,
                                                  IllegalArgumentException

      Make a new time structure from the given calendar value.

      Parameters:
        `timeAsCalendar` - Calendar item to use to create a new time structure.
      Throws:
        `NullPointerException` - The given calendar value for the time is `null`.
        `IllegalArgumentException` - The given calendar value contains out-of-range values.
      See Also:
        `makeTime(byte, byte, byte)`, `makeTime(byte, byte, byte, byte)`, `timeNow()`

    - #### timeNow

          public static final TimeStruct timeNow()

      Makes a time only value representing the time now.

      To make a time stamp value representing both today's date and the time now, use `now()`.

      Returns:
        The time now.
      See Also:
        `todaysDate()`, `now()`

    - #### parseVersion

          public static final VersionType parseVersion(String versionAsAString)
                                                throws NullPointerException,
                                                       ParseException

      Make a version type value by parsing the given string representation. The value must contain a '`.`' to be valid. The major and minor parts of the version numbers, before and after the dot respectively, must range between 0 and 255.

      This method will parse values created by `VersionType.toString()`.

      Parameters:
        `versionAsAString` - String representation of a version number.
      Returns:
        Version number value.
      Throws:
        `NullPointerException` - The given version number string is `null`.
        `ParseException` - The given version number string causes parse or number range errors that prevent it from being converted into a version number value.
      See Also:
        `VersionType.toString()`

    - #### makeVersion

          public static final VersionType makeVersion(@Int8
                                                      byte major,
                                                      @Int8
                                                      byte minor)

      Make a version type value from its component major and minor values.

      Parameters:
        `major` - Major part of the version number.
        `minor` - Minor part of the version number.
      Returns:
        Version number created from the given components.
      See Also:
        `zeroVersion()`

    - #### zeroVersion

          public static final VersionType zeroVersion()

      Make a zero version number, where both major and minor parts are zero.

      Returns:
        Zero version number.
      See Also:
        `makeVersion(byte, byte)`

    - #### originalSource

          public static final SourceReferenceValue originalSource()

      Makes a new source reference that indicates the reference is to essence that is the original source. The source package identifier will be the zero package identifier, the source track identifier will be zero and so will the start position.

      Returns:
        Source reference to original source.
      See Also:
        `SourceReferenceValue.isOriginalSource()`, `PackageID.isZero()`, `inContextReference(int)`, `inContextReference(int, Long)`

    - #### inContextReference

          public static final SourceReferenceValue inContextReference(@TrackID
                                                                      int sourceTrackID)
                                                               throws IllegalArgumentException

      Makes a new source reference to static material in a track within the same context as the package in which the reference is specified. This method version omits the start position property - use `inContextReference(int, Long)` to set a start position value for timeline- or event-based material.

      Parameters:
        `sourceTrackID` - Track to reference within the same package that this reference is defined in.
      Returns:
        Contextual source reference.
      Throws:
        `IllegalArgumentException` - The given source track id is a negative value.
      See Also:
        `StaticTrack`, `SourceReferenceValue.isContextual()`, `originalSource()`, `inContextReference(int, Long)`

    - #### inContextReference

          public static final SourceReferenceValue inContextReference(@TrackID
                                                                      int sourceTrackID,
                                                                      @PositionType
                                                                      Long startPosition)
                                                               throws IllegalArgumentException

      Makes a new source reference to timeline- or event-based material in a track within the same context as the package in which the reference is specified. Use the `inContextReference(int)` to create a reference to static material.

      Parameters:
        `sourceTrackID` - Track to reference within the same package that this reference is defined in.
        `startPosition` - Specifies the offset from the origin of the referenced package's track in edit units determined by the associated source clip object's context.
      Returns:
        Contextual source reference.
      Throws:
        `IllegalArgumentException` - The source track id cannot be set to a negative value.
      See Also:
        `TimelineTrack`, `EventTrack`, `SourceReferenceValue.isContextual()`, `inContextReference(int)`, `originalSource()`

    - #### makeReference

          public static final SourceReferenceValue makeReference(@PackageIDType
                                                                 PackageID sourcePackageID,
                                                                 @TrackID
                                                                 int sourceTrackID,
                                                                 @PositionType
                                                                 Long startPosition)
                                                          throws IllegalArgumentException

      Make a new source reference value that contains a source package identifier, source track identifier and start position. If the given source package identifier is the zero package id, values for source track id and start position are set to zero to comply with source reference constraints.

      Parameters:
        `sourcePackageID` - Identifies the package that is the target of the new reference. If the property is set to the zero package id, it means that the package owning the source reference describes the original source. If this optional property is omitted by setting its value to `null`, the given track refers to another track within the same package as the reference.
        `sourceTrackID` - Specifies the track id of a track within the specified package. If the source package id is the zero package id, then the source track id shall have a 0 value.
        `startPosition` - Specifies the position offset from the origin of the referenced package's track in edit units determined by the associated source clip's context. If the source package id is the zero package id, then the start position shall have a 0 value. Set the value to `null` to omit this optional property in the case that the new reference is to static material.
      Throws:
        `IllegalArgumentException` - The source track id cannot be set to a negative value.
      See Also:
        `PackageID.isZero()`, `zeroPackageID()`

    - #### make

          public static final <T extends MetadataObject> T make(Class<T> type,
                                                                boolean strict,
                                                                Object... properties)
                                                         throws NullPointerException,
                                                                IllegalArgumentException

      Create new instances of metadata objects using the definition of its primary interface and its initial property values. Property values must be provided for all required properties and may also be provided for optional values. This is with the exception of required sets and arrays that are initialized to empty and will require at least one element to be added to become initialized.

      The type of object to create is provided by its defining Java interface or class. The property values are provided by a list of property identifier and value pairs, where each identifier is followed by its value. The property identifier can by a name, AUID or property definition. The values are either instances of the `PropertyValue` interface or Java values compatible with the type definition, as defined in the type mapping table.

      Here is an example of how to use this method:

                  TimelineTrack videoTrack = MediaEngine.make(
                    TimelineTrack.class,
                    "TrackID", 1,
                    "EditRate", "25/1",
                    "Origin", 0l,
                    "TrackSegment", videoSequence);

      In the example, an instance of the timeline track type is created. Its track identifier is initialized to 1, edit rate to 25/1 using a string representation of the value, origin to 0 and track to a variable called `videoSequence`.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `type` - Java class representing the type to return.
        `strict` - Should the method be strict about required properties or use defaults provided by the implementation?
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeByName(String, String, Object...)`, `makeAAF(String, Object...)`, `ClassDefinition.createInstance()`

    - #### make

          public static final <T extends MetadataObject> T make(Class<T> type,
                                                                Object... properties)
                                                         throws NullPointerException,
                                                                IllegalArgumentException

      Create new instances of metadata objects using the definition of its primary interface and its initial property values without being strict about required properties. See the description of `make(Class, boolean, Object...)` for more details.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `type` - Java class representing the type to return.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, boolean, Object...)`, `makeByName(String, String, Object...)`, `ClassDefinition.createInstance()`

    - #### makeByName

          public static final <T extends MetadataObject> T makeByName(String namespace,
                                                                      String typeName,
                                                                      boolean strict,
                                                                      Object... properties)
                                                               throws NullPointerException,
                                                                      IllegalArgumentException

      Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values. Property values must be provided for all required properties and may also be provided for optional values. This is with the exception of required sets and arrays that are initialized to empty and will require at least one element to be added to become initialized.

      The type of object to create is provided by its defining Java interface or class. The property values are provided by a list of property identifier and value pairs, where each identifier is followed by its value. The property identifier can by a name, AUID or property definition. The values are either instances of the `PropertyValue` interface or Java values compatible with the type definition, as defined in the type mapping table.

      Here is an example of how to use this method:

                  TimelineTrack videoTrack = MediaEngine.make(
                    "http://www.smpte-ra.org/schemas/2001-2/2007/aaf", "TimelineTrack",
                    "TrackID", 1,
                    "EditRate", "25/1",
                    "Origin", 0l,
                    "TrackSegment", videoSequence);

      In the example, an instance of the timeline track type is created. Its track identifier is initialized to 1, edit rate to 25/1 using a string representation of the value, origin to 0 and track to a variable called `videoSequence`. Note that the default AAF XML namespace is set as static string `CommonConstants.AAF_XML_NAMESPACE`.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `namespace` - Namespace in which the type for the new instance is defined.
        `typeName` - Name of the type of instance to create within the given namespace.
        `strict` - Should the method be strict about required properties or use defaults provided by the implementation?
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

    - #### makeByName

          public static final <T extends MetadataObject> T makeByName(String namespace,
                                                                      String typeName,
                                                                      Object... properties)
                                                               throws NullPointerException,
                                                                      IllegalArgumentException

      Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values, and also without being strict about required properties. For more details about this method, see the documentation for the `makeByName(String, String, boolean, Object...)` method.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `namespace` - Namespace in which the type for the new instance is defined.
        `typeName` - Name of the type of instance to create within the given namespace.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `make(Class, boolean, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeAAF(String, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

    - #### makeAAF

          public static final <T extends MetadataObject> T makeAAF(String typeName,
                                                                   Object... properties)
                                                            throws NullPointerException,
                                                                   IllegalArgumentException

      Create new instances of AAF baseline metadata objects using the name of the type and its initial property values, and also without being strict about required properties.

      For more details about this method, see the documentation for the `makeByName(String, String, boolean, Object...)` method. This method is the same as calling that method with the namespace set to the AAF namespace.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `typeName` - Name of the AAF baseline type of instance to create.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `make(Class, boolean, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeByName(String, String, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

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