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().| 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> |
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> |
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> |
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> |
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> |
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()
|
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.
|
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-F0E96C160D7Durn:uuid:00000000-0000-0000-0000-000000000000urn:smpte:ul:0602b34.010101ff.42464141.000d4d4fauidAsString - String value to use to create a new AUID.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.ParseExceptionAUID.toString(),
makeAUID(byte[])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.
setLocalNodeID(byte[]),
randomAUID(),
namebasedAUID(byte[])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.
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.NullPointerException - The given byte array is null.timebasedAUID(),
Utilities.createLocalHostID(int),
Utilities.getLocalHostID()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.
nodeID - Unique identifier for this computational node, which must contain at least
6 bytes.NullPointerException - The node ID byte array argument is null.IllegalArgumentException - The node identifier must contain at least 6 bytes.timebasedAUID(),
namebasedAUID(byte[]),
randomAUID()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.
nameData - Name data to use to create a name-based UUID.NullPointerException - The name data provided is null.UUID.nameUUIDFromBytes(byte[]),
namebasedAUID(String),
timebasedAUID(),
randomAUID()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.
nameData - Name data to use to create a name-based UUID as a string.NullPointerException - The name data provided is null.UUID.nameUUIDFromBytes(byte[]),
String.getBytes(),
namebasedAUID(byte[]),
timebasedAUID(),
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.
Utilities.seedRandomMaker(),
timebasedAUID(),
namebasedAUID(byte[])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.
bytes - Byte array to use to set the value of the new AUID.NullPointerException - The given array of bytes is null.makeAUID(int, short, short, byte[]),
parseAUID(String)public static final AUID makeAUID(int data1, short data2, short data3, byte[] data4) throws NullPointerException
Makes a new AUID value from its constituent parts.
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.NullPointerException - The given data4 value byte array is null.makeAUID(byte[]),
parseAUID(String)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.
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".
dateAsString - Date value represented as a string.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.DateStruct.toString(),
parseTime(String),
parseTimeStamp(String)public static final DateStruct todaysDate()
Make a date structure representing the current date.
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.
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.IllegalArgumentException - One or more of the arguments has a value outside of
an acceptable range.DateStruct.getDay(),
DateStruct.getMonth(),
DateStruct.getYear(),
DateStruct.setDate(byte, byte, short)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.
dateAsCalendar - Calendar value to use to extract a day, month and year from.NullPointerException - The given calendar value is null.DateStruct.getDateValue()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.
edgeCodeAsString - Pseudo-XML representation of an edge code value.NullPointerException - The given string value is null.ParseException - A problem occurred when trying to decode the given string.EdgeCodeValue.toString()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.
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.
startFrame - Specifies the edge code at the beginning of the corresponding segment.filmKind - Specifies the type of film.codeFormat - Specifies the edge code format.NullPointerException - One or more of the arguments is/are null.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.
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.NullPointerException - One or more of the arguments is/are null.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.
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.NullPointerException - One or more of the arguments is/are null.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.c0a801baHexadecimal 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-53b933d918245095ca82322ec0a801bapackageIDAsString - Package identifier value formatted as a URN-style UMID string.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.PackageID.toString()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.
makePackageID(byte[]),
makePackageID(byte[], byte, byte, byte, byte, AUID)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.
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.NullPointerException - One or both of the universal label or material number numbers are
null.zeroPackageID(),
makePackageID(byte[]),
PackageID.BaseUniversalLabelpublic 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.
bytes - Byte array representing the elements of a package identifier.NullPointerException - The given array of byte elements is null.zeroPackageID(),
makePackageID(byte[], byte, byte, byte, byte, AUID)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.
materialNumber - Material number part of the new package identifier.NullPointerException - Cannot use a null material number to generate a package identifier.dCinemaUMID(),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])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.
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.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.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
generatePackageID(AUID),
dCinemaUMID()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.
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.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.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
generatePackageID(AUID),
dCinemaUMID()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.
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.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.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
generatePackageID(AUID),
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.78529D78generatePackageID(AUID),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
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.
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
dCinemaUMID()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.
versionAsAString - Pseudo-XML string to convert into a product version instance.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.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.
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.NullPointerException - The product release type argument is null.IllegalArgumentException - One of more of the major, minor, tertiary or patch level
values is negative.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.
makeProductVersion(short, short, short, short, ProductReleaseType)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().
rationalAsString - String to use to create a rational value.NullPointerException - The rational as string argument is null.PraseException - The string is not formatted as a rational number
representation.ParseExceptionRational.toString()public static final Rational makeRational(@Int32 int numerator, @Int32 int denominator)
Make a rational value from its numerator and denominator.
numerator - denominator - zeroRational()public static final Rational zeroRational()
Make a rational value of zero, with numerator of 0 and denominator of 1.
makeRational(int, int)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.
rgbaComponentAsString - Pseudo-XML string to convert into a RGBA component instance.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.RGBAComponent.toString(),
TypeDefinitions.RGBAComponent,
TypeDefinitions.RGBALayoutpublic static final RGBAComponent makeRGBAComponent(RGBAComponentKind code, @UInt8 byte size) throws NullPointerException, IllegalArgumentException
Make an element of an RGBA layout array.
code - Code for the component.size - Size of the component in bits.NullPointerException - The code argument is null.IllegalArgumentException - The size argument is negative.zeroRGBAComponent(),
TypeDefinitions.RGBALayoutpublic static final RGBAComponent zeroRGBAComponent()
Make an element of an RGBA layout array
with a RGBAComponentKind.Null code and a size of 0.
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:
:<minute>:<second>:<frame>(.<framePair>)?:<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".
timecodeAsAString - String representation of a timecode value.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.TimecodeValue.toString(),
parseTimecode(String, short, boolean)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:
:<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".
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.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.TimecodeValue.toString(),
parseTimecode(String)public static final TimecodeValue makeTimecode(@FrameOffset long startFrame, @UInt16 short fps, boolean drop) throws IllegalArgumentException
Make a timecode value from its actual component parts.
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).IllegalArgumentException - The frames per second value is not a positive value.calculateTimecode(short, short, short, short, short, boolean),
zeroTimecode()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);
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?IllegalArgumentException - The number of frames per second is not a positive (greater than zero)
number.makeTimecode(long, short, boolean),
calculateTimecode(short, short, short, short, short, short, boolean),
zeroTimecode()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);
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?IllegalArgumentException - The number of frames per second is not a positive (greater than zero)
number.makeTimecode(long, short, boolean),
calculateTimecode(short, short, short, short, short, boolean),
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.
makeTimecode(long, short, boolean),
calculateTimecode(short, short, short, short, short, boolean)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.
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).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.LengthType,
calculateEndTimecode(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)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.
startValue - Start timecode at the beginning of a segment of media.duration - Duration of the media specified as a timecode value.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.calculateDuration(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)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:
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().
timeStampAsAString - String representation of a time stamp value.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.TimeStamp.toString(),
parseTime(String),
parseDate(String)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.
date - Date component of the time stamp to create.time - Time component of the time stamp to create.NullPointerException - One or more of the arguments is null.IllegalArgumentException - The resulting time stamp value would not be valid.makeTimeStamp(Calendar),
makeTimeStamp(short, byte, byte, byte, byte, byte, byte),
now()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.
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.IllegalArgumentException - The resulting time stamp value would not be valid.makeTimeStamp(DateStruct, TimeStruct),
makeTimeStamp(Calendar),
now()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().
timeStampAsCalendar - Calendar value to use to set the value of this time stamp.NullPointerException - The given calendar value is null.IllegalArgumentException - The given calendar value is not a valid date or time.makeTimeStamp(DateStruct, TimeStruct),
makeTimeStamp(short, byte, byte, byte, byte, byte, byte),
now()public static final TimeStamp now()
Make a timestamp representing the date and time now.
todaysDate(),
timeNow()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:
Note that if a timezone value different from UTC ("+0000"), the time value will be converted to its UTC equivalent.
timeAsAString - UTC-style string time value.NullPointerException - Provided time as a string value is null.ParseException - The given value could not be converted into a time structure value.TimeStruct.toString(),
parseTimeStamp(String),
parseDate(String)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.
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.IllegalArgumentException - One or more of the parameters is out of range.makeTime(Calendar),
makeTime(byte, byte, byte, byte),
timeNow()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.
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.IllegalArgumentException - One or more of the parameters is out of range.makeTime(Calendar),
makeTime(byte, byte, byte),
timeNow()public static final TimeStruct makeTime(Calendar timeAsCalendar) throws NullPointerException, IllegalArgumentException
Make a new time structure from the given calendar value.
timeAsCalendar - Calendar item to use to create a new time structure.NullPointerException - The given calendar value for the time is null.IllegalArgumentException - The given calendar value contains out-of-range
values.makeTime(byte, byte, byte),
makeTime(byte, byte, byte, byte),
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().
todaysDate(),
now()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().
versionAsAString - String representation of a version number.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.VersionType.toString()public static final VersionType makeVersion(@Int8 byte major, @Int8 byte minor)
Make a version type value from its component major and minor values.
major - Major part of the version number.minor - Minor part of the version number.zeroVersion()public static final VersionType zeroVersion()
Make a zero version number, where both major and minor parts are zero.
makeVersion(byte, byte)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.
SourceReferenceValue.isOriginalSource(),
PackageID.isZero(),
inContextReference(int),
inContextReference(int, Long)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.
sourceTrackID - Track to reference within the same package that this reference is defined in.IllegalArgumentException - The given source track id is a negative value.StaticTrack,
SourceReferenceValue.isContextual(),
originalSource(),
inContextReference(int, Long)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.
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.IllegalArgumentException - The source track id cannot be set to a negative value.TimelineTrack,
EventTrack,
SourceReferenceValue.isContextual(),
inContextReference(int),
originalSource()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.
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.IllegalArgumentException - The source track id cannot be set to a negative value.PackageID.isZero(),
zeroPackageID()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.
T - Type of value to make and return.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.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.make(Class, Object...),
makeByName(String, String, boolean, Object...),
makeByName(String, String, Object...),
makeAAF(String, Object...),
ClassDefinition.createInstance()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.
T - Type of value to make and return.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.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.make(Class, boolean, Object...),
makeByName(String, String, Object...),
ClassDefinition.createInstance()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.
T - Type of value to make and return.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.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.make(Class, Object...),
ClassDefinition.createInstance(),
MediaClass.namespace(),
CommonConstants.AAF_XML_NAMESPACEpublic 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.
T - Type of value to make and return.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.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.make(Class, Object...),
make(Class, boolean, Object...),
makeByName(String, String, boolean, Object...),
makeAAF(String, Object...),
ClassDefinition.createInstance(),
MediaClass.namespace(),
CommonConstants.AAF_XML_NAMESPACEpublic 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.
T - Type of value to make and return.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.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.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.