public interface PackageID
Specifies a 32 byte package identifier unique identifier that can hold a SMPTE UMID, as specified in SMPTE 330M. Bytes 14 to 32 of a UMID can be treated as a dumb number, the value of which has no intrinsic meaning.
A package identifer is globally unique. Please see section 4.3.1 of the AAF object specification v1.1 for details of the immutability of package ids.
Note that the description of byte positions used in the documentation for each method of this interface use 1-based indexing.
To make values of this type, use the following methods from the MAJ forge:
Forge.makePackageID(byte[]);Forge.makePackageID(byte[], byte, byte, byte, byte, AUID);Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID) and
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]);Forge.dCinemaUMID();toString():
Forge.parsePackageID(String).Package ids were previously known as mob ids (media object ids) and may still be referred to that way in AAF-specific documentation.
TypeDefinitions.PackageIDType,
PackageIDType,
AUID| Modifier and Type | Field and Description |
|---|---|
static byte[] |
BaseUniversalLabel
Base universal label to use to create SMPTE-compliant package identifiers.
|
| Modifier and Type | Method and Description |
|---|---|
PackageID |
clone()
Create a cloned copy of this package id.
|
InstanceNumberGeneration |
getInstanceGenerator()
Returns the instance number generation method for this package identifier.
|
byte |
getInstanceHigh()
Returns the most significant bit of the 3 byte instance number, which is stored as bytes 14
to 16 of the package id.
|
byte |
getInstanceLow()
Returns the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16
of the package id.
|
byte |
getInstanceMid()
Returns the middle byte of the 3 byte instance number, which is stored as bytes 14
to 16 of the package id.
|
int |
getInstanceNumber()
|
byte |
getLength()
Returns the length of the package id in terms of the number of bytes following this byte, as stored at
byte 13 of the package id.
|
AUID |
getMaterial()
Returns the material number of the package id, represented as an AUID, which is taken from
bytes 17 to 32 of the package id.
|
MaterialNumberGeneration |
getMaterialNumberGenerator()
Returns the material number generation method for this package identifier.
|
byte[] |
getUniversalLabel()
Returns the universal label that makes up bytes 1 to 12 of a package id.
|
boolean |
isZero()
Returns
true if this package identifier the special zero package identifier, where all
32-bytes of the identifier are zero; otherwise false. |
PackageID |
nextInstance()
Returns a new package identifier with the same material number as this one and a newly created instance
number.
|
void |
setInstanceHigh(byte instanceHigh)
Sets the most significant bit of the 3 byte instance number, which is stored as bytes 14
to 16 of the package id.
|
void |
setInstanceLow(byte instanceLow)
Sets the least significant byte of the 3 byte instance number, which is stored as bytes 14
to 16 of the package id.
|
void |
setInstanceMid(byte instanceMid)
Sets the middle byte of the 3 byte instance number, which is stored as bytes 14
to 16 of the package id.
|
void |
setLength(byte length)
Returns the length of the package id in terms of the number of bytes following this byte, as stored at
byte 13 of the package id.
|
void |
setMaterial(AUID material)
Sets the material number of the package id, represented as an AUID, which is taken from
bytes 17 to 32 of the package id.
|
void |
setUniversalLabel(byte[] label)
Sets the universal label that makes up bytes 1 to 12 of a package id.
|
String |
toString()
Formats the value of this package identifier as a URN-style UMID string, starting with
"
urn:smpte:umid:". |
static final byte[] BaseUniversalLabel
Base universal label to use to create SMPTE-compliant package identifiers. This value represents a UMID value with material type and generation methods not identified.
@UInt8 byte[] getUniversalLabel()
Returns the universal label that makes up bytes 1 to 12 of a package id.
void setUniversalLabel(@UInt8 byte[] label) throws NullPointerException
Sets the universal label that makes up bytes 1 to 12 of a package id.
label - Universal label component of the package id.NullPointerException - The given universal label for this package id is null.@UInt8 byte getLength()
Returns the length of the package id in terms of the number of bytes following this byte, as stored at
byte 13 of the package id. This value is normally 19 (0x13) for a 32 byte package id.
void setLength(@UInt8 byte length)
Returns the length of the package id in terms of the number of bytes following this byte, as stored at
byte 13 of the package id. This value is normally 19 (0x13) for a 32 byte package id.
length - Length component of the package id.@UInt8 byte getInstanceHigh()
Returns the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 14th byte of the package id.
void setInstanceHigh(@UInt8 byte instanceHigh)
Sets the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 14th byte of the package id.
instanceHigh - Most significant byte of the instance number component of the package id.@UInt8 byte getInstanceMid()
Returns the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 15th byte of the package id.
void setInstanceMid(@UInt8 byte instanceMid)
Sets the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 15th byte of the package id.
instanceMid - Middle byte of the instance number component of the package id.@UInt8 byte getInstanceLow()
Returns the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 16th byte of the package id.
void setInstanceLow(@UInt8 byte instanceLow)
Sets the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 16th byte of the package id.
instanceLow - Least significant byte of the instance number component of the package id.AUID getMaterial()
Returns the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
void setMaterial(AUID material) throws NullPointerException
Sets the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
material - Material number component of the package idNullPointerException - The given material number is null.boolean isZero()
Returns true if this package identifier the special zero package identifier, where all
32-bytes of the identifier are zero; otherwise false. The zero package identifier
is represented as a URN as follows:
urn:x-umid:000000000000000000000000-00-000000-00000000000000000000000000000000
Zero package ids are used to specify original source references for source clips, indicating that a package represents the original source of essence or data.
Forge.zeroPackageID(),
SourceReferenceValue.isOriginalSource(),
SourceReferenceSegment.getSourcePackageID(),
AUID.isNil()PackageID nextInstance() throws InstanceOverflowException, GenerationMethodNotSupportedException
Returns a new package identifier with the same material number as this one and a newly created instance
number. The method of generation of the instance number is set as part of the package identifier's universal
label and can be found by calling getInstanceGenerator().
The package identifiers generated by this method are only unique within the local context and are not thread safe where clones exist or safe for use across more than one virtual machine. It is up to a user of this method to ensure instance uniqueness in their own local context, using techniques such as transaction management and persistence mapping to a central store.
The relationship between the current and new instance number for each type of generator is:
InstanceNumberGeneration.LocalRegistration - The instance high, mid and low bytes
are treated as the most significant, middle and least significant bytes of an unsigned 24-bit
integer value representing the local registration number of the package id for the given material
number. The instance number of the new package id is set to be one greater than current instance
number, as returned by getInstanceNumber().InstanceNumberGeneration.CopyAndPseudoRandom16Bit - The instance high byte is
incremented by one to make the instance high byte of the new package id. If the counter exceeds
255, an InstanceOverflowException is thrown, which gives the caller the
option of resetting the counter to 0 or to take their own choice of action. The
middle and low instance bytes are set using a random number generator. This implementation
ensures that any two consecutive current and new instances do not have the same middle and low
instance values.InstanceNumberGeneration.PseudoRandom24Bit - The instance high, middle and low
values are set using 24 randomly generated bits. The method ensures that any two consecutive
current and new instance numbers do not have the same values. InstanceNumberGeneration.LiveStream - Not supported by the MAJ API and throws a
GenerationMethodNotSupportedException.InstanceNumberGeneration.NotDefined - Same as InstanceNumberGeneration.PseudoRandom24Bit.InstanceOverflowException - For methods that increment counters to define the next instance
package id, the counter has overflowed.GenerationMethodNotSupportedException - The instance number generation method is not supported,
which is currently the case for the live stream method.getInstanceGenerator(),
getInstanceNumber(),
getInstanceHigh(),
getInstanceMid(),
getInstanceLow()PackageID clone()
Create a cloned copy of this package id.
String toString()
Formats the value of this package identifier as a URN-style UMID string, starting with
"urn:smpte:umid:". For example:
urn:smpte:umid:060a2b34.01010101.01010f13.1300b347.53b933d9.18245095.ca82322e.c0a801baValues from this method can be turned back into package identifiers using the
Forge.parsePackageID(String) method.
The canonical form of formatted values created by this implementation uses lower case letters for hexadecimal digits.
toString in class ObjectForge.parsePackageID(String)InstanceNumberGeneration getInstanceGenerator()
Returns the instance number generation method for this package identifier.
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
nextInstance()MaterialNumberGeneration getMaterialNumberGenerator()
Returns the material number generation method for this package identifier.
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])@UInt32 int getInstanceNumber()
Returns the instance number as an unsigned integer made up from its constituent high, middle and low parts. This method is intended for use with the local registration instance number generation strategy.
getInstanceGenerator()(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.