public final class PackageIDImpl extends Object implements PackageID, Serializable, XMLSerializable, Cloneable
Implementation of a 32 byte package id unique identifier that can hold a SMPTE UMID, as specified in SMPTE 330M. Material object identifiers represented by this class are 32-byte - yes, byte - numbers that can be generated at source with a high degree of likelihood that two independently generated identifiers will not clash. For most systems, package ids are and should be treated as dumb numbers whose bit pattern structure is of no significance. However, for the purposes of id generation and consistent representation between systems, a package id can be viewed as consisting of:
One common form of package id is the SMPTE Unique Material Identifier (UMID), as defined in SMPTE
S330M-2004. A number of helper methods are provided that allow the package id to be created and managed
as a UMID, including a factory method
(umidFactory()) and
the ability to generate the next UMID instance number for an existing piece of material
(nextInstance()). To decrease the likelihood of two UMIDs being the same within a
network of systems, the adoption of the same material number generation and instance number
generation schemes is advisable.
A package id can be represented as a string in four sections, consisting of the universal label, followed
by the length, then instance number and finally the material number. It is an informal convention that the
string representation of a UMID, which is generated by a call to toString(), starts with
"urn:x-umid:". For example:
urn:x-umid:060a2b340101010101010f13-13-0098ef-4dfc94b90124509571af322ec0a801baThe value above is structured according to the SMPTE UMID specification as follows:
urn:x-umid:<label>-<length>-<instance number>-<material number>This class does not represent SMPTE extended UMIDs, which are 64 bytes in length.
Package ids can be used as embeddable identifiers for entities that represent material. The internal
representation of a package id is a 32 byte array, which can be accessed with the getPackageIDValue() method
and set using the setPackageIDValue(byte[]) method. A database column
defined to hold a package id may be defined as follows:
`PackageID` binary(32) NOT NULL
All methods assume network byte order.
Package ids were previously known as package ids and may still be referred to as such in AAF-specific documentation.
| Modifier and Type | Field and Description |
|---|---|
static String |
MYSQL_COLUMN_DEFINITION |
static char[] |
persistTemplate |
BaseUniversalLabel| Constructor and Description |
|---|
PackageIDImpl()
Generate a new package id using a secure random number generator.
|
PackageIDImpl(byte[] packageID)
Creates a new package id from an array of bytes.
|
PackageIDImpl(byte[] label,
byte length,
byte instanceHigh,
byte instanceMid,
byte instanceLow,
AUID material)
Create a new package id from the specified parameters.
|
| Modifier and Type | Method and Description |
|---|---|
void |
appendXMLChildren(Node parent)
Append extra child elements to the given parent node to serialize the value of an object
to an XML fragment.
|
PackageID |
clone()
Create a cloned copy of this package id.
|
static PackageID |
createFromBuffer(ByteBuffer buffer) |
boolean |
equals(Object o) |
static PackageID |
fromPersistentForm(String packageID) |
static void |
generateEmbeddableORM(Node parent,
String namespace,
String prefix) |
static void |
generateEmbeddedORM(Node parent,
String ownerName,
String namespace,
String prefix) |
static byte[] |
getBaseUniversalLabel()
Returns a base universal label that identifies a package id as compatible with the SMPTE
Unique Material Identifier (UMID) specification, as documented in SMPTE 330M.
|
String |
getComment()
Include a comment when serializing a value to XML.
|
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.
|
MaterialType |
getMaterialType()
Returns the material type for this package id.
|
byte[] |
getPackageIDValue()
Returns a copy of all 32 bytes representing the value of this package id as a byte array.
|
byte[] |
getUniversalLabel()
Returns the universal label that makes up bytes 1 to 12 of a package id.
|
static PackageID |
getZeroPackageID()
Returns a copy of the zero package id, for which every component byte of the package id is set to 0.
|
int |
hashCode() |
boolean |
isZero()
Returns
true if this package identifier the special zero package identifier, where all
32-bytes of the identifier are zero; otherwise false. |
static long |
lengthAsBuffer(PackageID packageID) |
PackageID |
nextInstance()
Returns a new package id with the same material number as this one and a newly created instance
number.
|
static PackageIDImpl |
parseFactory(String packageIdURN)
Parse a package id formatted as a URN-style UMID string and convert it into a newly
instantiated package id with an equivalent value.
|
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 |
setPackageIDValue(byte[] packageID)
Sets the value of this package id using the given byte array, which should contain 32 bytes
of data.
|
void |
setUniversalLabel(byte[] label)
Sets the universal label that makes up bytes 1 to 12 of a package id.
|
static String |
toPersistentForm(PackageID packageID) |
String |
toString()
Formats the value of this package id as a URN-style UMID string, starting with
"
urn:smpte:umid:". |
static PackageIDImpl |
umidFactory(MaterialType materialType,
MaterialNumberGeneration materialNumberGeneration,
InstanceNumberGeneration instanceNumberGeneration,
byte[] extraData)
Factory that manufactures new package ids according to the given SMPTE UMID generation specification.
|
static void |
writeToBuffer(PackageID packageID,
ByteBuffer buffer) |
public static final char[] persistTemplate
public static final String MYSQL_COLUMN_DEFINITION
public PackageIDImpl(byte[] label,
@UInt8
byte length,
@UInt8
byte instanceHigh,
@UInt8
byte instanceMid,
@UInt8
byte instanceLow,
AUID material)
throws NullPointerException
Create a new package id from the specified parameters. The label and material values are copied to ensure that subsequent external changes do not effect the newly created package id.
A default universal label to set the package id to be a SMPTE UMID is available by calling
getBaseUniversalLabel().
Note that this method does not generate a new package id, it creates one using the given parameters.
To generate values, use #PackageID() or the
UMID factory method.
label - Universal label component of the package id.length - Length of the following data.instanceHigh - Most significant part of the instance number component of the package id.instanceMid - Second most significant part the instance number component of the package id.instanceLow - Least significant part of the instance number component of the package id.material - Unique identifier for the identified material, the material number component of the
package id.NullPointerExceptionpublic PackageIDImpl(byte[] packageID)
throws NullPointerException
Creates a new package id from an array of bytes. The array should be 32 bytes in length and prepared to be considered as a package id. If the array is too short or too long, it will be padded with 0s or truncated to make it 32 bytes. The passed array value is cloned to avoid external changes to the array affecting this value.
packageID - Byte array to use to create a new package id value.NullPointerException - The given byte array is null.setPackageIDValue(byte[]),
getPackageIDValue()public PackageIDImpl()
Generate a new package id using a secure random number generator. The value created is a SMPTE UMID with the following properties:
This method is provided as a quick way to generate a package id. Statistically, it is highly unlikely that package ids generated this way will clash with one another . For more control over generating globally unique package ids, use the UMID factory method.
public static final byte[] getBaseUniversalLabel()
Returns a base universal label that identifies a package id as compatible with the SMPTE Unique Material Identifier (UMID) specification, as documented in SMPTE 330M. This default label has:
getUniversalLabel(),
setUniversalLabel(byte[])public static final PackageID getZeroPackageID()
Returns a copy of the zero package id, for which every component byte of the package id is set to 0. The zero package id is used as a flag in certain properties, such as to indicate that a source clip is the original source.
isZero(),
AUIDImpl.isNil(),
SourceReferenceValueImpl.isOriginalSource()public static final PackageIDImpl umidFactory(MaterialType materialType, MaterialNumberGeneration materialNumberGeneration, InstanceNumberGeneration instanceNumberGeneration, byte[] extraData) throws GenerationMethodNotSupportedException, NullPointerException
Factory that manufactures new package ids according to the given SMPTE UMID generation specification.
Some of the generation methods documented in appendix A of SMPTE 330M are difficult to support in Java as the core API does not support all the required features, such as access to the ethernet address of a system. This additional data can be provided using the extra data parameter, as described below. Results produced by this factory are only as good as the extra data provided and so this factory method should be considered as not fully compliant with 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 id.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 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 nextInstance() for the new package id.
materialType - Type of material represented by the new package id.materialNumberGeneration - Method to use to generate the material number of the package id.instanceNumberGeneration - Method to use to generate the first and next instance
numbers for the package id.extraData - Additional data required by the material number generation method.GenerationMethodNotSupportedException - The given material or instance number generation
method is not supported.NullPointerException - One or more of the arguments is null and all are
required.public final byte[] getPackageIDValue()
Returns a copy of all 32 bytes representing the value of this package id as a byte array. The internal representation of a package id in the MAJ API is as a 32-byte array.
public final void setPackageIDValue(byte[] packageID)
throws NullPointerException
Sets the value of this package id using the given byte array, which should contain 32 bytes of data. If the array is smaller than required, it will be padded with zeros. If the array is larger than required, it will be truncated. The given array is cloned so that subsequent changes do not affect the internal representation within this package id.
packageID - Data to use to set the value of this package id.NullPointerException - The given package id data is null.#PackageID(byte[])public final byte[] getUniversalLabel()
PackageIDReturns the universal label that makes up bytes 1 to 12 of a package id.
getUniversalLabel in interface PackageIDgetBaseUniversalLabel()public final void setUniversalLabel(byte[] label)
throws NullPointerException
PackageIDSets the universal label that makes up bytes 1 to 12 of a package id.
setUniversalLabel in interface PackageIDlabel - Universal label component of the package id.NullPointerException - The given universal label for this package id is null.getBaseUniversalLabel()@UInt8 public final byte getLength()
PackageIDReturns 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.
public final void setLength(@UInt8 byte length)
PackageIDReturns 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.
@UInt32 public final int getInstanceNumber()
PackageIDReturns 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.
getInstanceNumber in interface PackageIDPackageID.getInstanceGenerator()@UInt8 public final byte getInstanceHigh()
PackageIDReturns 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.
getInstanceHigh in interface PackageIDpublic final void setInstanceHigh(@UInt8 byte instanceHigh)
PackageIDSets 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.
setInstanceHigh in interface PackageIDinstanceHigh - Most significant byte of the instance number component of the package id.@UInt8 public final byte getInstanceMid()
PackageIDReturns 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.
getInstanceMid in interface PackageIDpublic final void setInstanceMid(@UInt8 byte instanceMid)
PackageIDSets 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.
setInstanceMid in interface PackageIDinstanceMid - Middle byte of the instance number component of the package id.@UInt8 public final byte getInstanceLow()
PackageIDReturns 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.
getInstanceLow in interface PackageIDpublic final void setInstanceLow(@UInt8 byte instanceLow)
PackageIDSets 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.
setInstanceLow in interface PackageIDinstanceLow - Least significant byte of the instance number component of the package id.public final AUID getMaterial()
PackageIDReturns the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
getMaterial in interface PackageIDpublic final void setMaterial(AUID material) throws NullPointerException
PackageIDSets the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
setMaterial in interface PackageIDmaterial - Material number component of the package idNullPointerException - The given material number is null.public final boolean isZero()
PackageIDReturns 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.
isZero in interface PackageIDForge.zeroPackageID(),
SourceReferenceValue.isOriginalSource(),
SourceReferenceSegment.getSourcePackageID(),
AUID.isNil()public final String toString()
Formats the value of this package id 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 ids using the parseFactory(String)
static method. The canonical form of formatted values created by this implementation uses
lower case letters for hexadecimal digits.
toString in interface PackageIDtoString in class ObjectObject.toString(),
parseFactory(String)public static final PackageIDImpl parseFactory(String packageIdURN) throws NullPointerException, ParseException
Parse a package id 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 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.
packageIdURN - Package id value formatted as a URN-style UMID string.NullPointerException - The package id urn argument 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.toString()public final PackageID clone()
PackageIDCreate a cloned copy of this package id.
public final MaterialNumberGeneration getMaterialNumberGenerator()
Returns the material number generation method for this package identifier.
getMaterialNumberGenerator in interface PackageIDForge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration);,
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])public final InstanceNumberGeneration getInstanceGenerator()
PackageIDReturns the instance number generation method for this package identifier.
getInstanceGenerator in interface PackageIDForge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID),
Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[]),
PackageID.nextInstance()public final MaterialType getMaterialType()
Returns the material type for this package id. This value only makes sense if the package id is a SMPTE UMID.
umidFactory(MaterialType, MaterialNumberGeneration, InstanceNumberGeneration, byte[])public final PackageID nextInstance() throws InstanceOverflowException, GenerationMethodNotSupportedException
Returns a new package id 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 id's universal
label and can be found by calling getInstanceGenerator().
The package ids 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.nextInstance in interface PackageIDInstanceOverflowException - 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()public final void appendXMLChildren(Node parent)
XMLSerializableAppend extra child elements to the given parent node to serialize the value of an object
to an XML fragment. Methods of the XMLBuilder class are provided to help with this
process.
appendXMLChildren in interface XMLSerializableparent - XML parent element to append child nodes to.public String getComment()
XMLSerializableInclude a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.
getComment in interface XMLSerializablepublic static final PackageID createFromBuffer(ByteBuffer buffer) throws NullPointerException, EndOfDataException
public static final long lengthAsBuffer(PackageID packageID) throws NullPointerException
NullPointerExceptionpublic static final void writeToBuffer(PackageID packageID, ByteBuffer buffer) throws NullPointerException, InsufficientSpaceException
public static final void generateEmbeddableORM(Node parent, String namespace, String prefix)
public static final void generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)
(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.