AUID (MAJ API)

Overview

Package

Class

Tree

Deprecated

Index

Media Authoring
with Java API

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

tv.amwa.maj.embeddable
Class AUID

java.lang.Object
  tv.amwa.maj.embeddable.AUID

All Implemented Interfaces:: Serializable, Cloneable, MAJCommon, XMLSerializable, AUID

public final class AUID
extends Object
implements AUID, Serializable, XMLSerializable, Cloneable, MAJCommon
extends Object
implements AUID, Serializable, XMLSerializable, Cloneable, MAJCommon

Implementation of a 16 byte unique identifier whose value is a SMPTE 298M Universal Label or a UUID or GUID. This implementation provides methods for generating AUIDs that are UUIDs and can be embedded within an entity to become its primary key.

This class supports transformation of AUIDs to and from string representations as Unique Resource Names (URNs), as defined in RFC 2141. Use the toString() method and static parseAUID(String) methods to do this.

This class makes a best effort to generate unique identifiers from the information provided to it and the features provided by the Java APIs. However, there is no 100% guarantee that it will generate a UUID that is totally unique. This class is provided with out any warranty whatsoever and its use is entirely at the users own risk.

The internal representation of an AUID used by the MAJ API is an array of 16 bytes. This array can be manipulated by an application using the getAUIDValue(), setAUIDValue(byte[]) and AUID(byte[]) methods. The database schema for an AUID value is a column defined as follows:

     `Identification` binary(16)

Author:: Richard Cartwright
See Also:: AUIDGeneration, MobID, DefinitionObject.getAUID(), UUID, TypeDefinitionRecord.AUID, AUIDArray, Serialized Form

Constructor Summary
`AUID()` Create a new UUID as an AUID using the random generation method.
`AUID(byte[] auidValue)` Create a new AUID value from a 16-byte array representing its internal value.
`AUID(int data1, short data2, short data3, byte[] data4)` Create a new AUID from its component parts.

Method Summary
`void`	`appendXMLChildren(Node parent)` Append child elements to the given parent node to serialize the value of an object to an XML fragment.
`static AUID`	`auidFactory(AUIDGeneration type, byte[] extraData)` Generates a new UUID as an AUID using the given `generation method`.
`static boolean`	`auidsEqual(AUID auid1, AUID auid2)` Compares two AUIDs to see if they represent equal values.
`static AUID`	`castFromInterface(AUID alien)` Create an instance of this AUID implementation using a possibly alien implementation that at least implements `tv.amwa.maj.record.AUID`.
`AUID`	`clone()` Creates a cloned deep copy of this embeddable value.
`boolean`	`equals(Object o)` Checks to see if two AUID values are equal.
`byte[]`	`getAUIDValue()` Returns a copy of the array of bytes used to represent this AUID internally.
`int`	`getData1()` Returns the time-low part of the AUID.
`short`	`getData2()` Returns the time-mid part of the AUID.
`short`	`getData3()` Returns the time-hi and version parts of the AUID.
`byte[]`	`getData4()` Returns the variant, clock sequence and node parts of the AUID as an 8-byte array.
`int`	`hashCode()` Returns a hash code value for this embeddable object.
`boolean`	`isNil()` Check to see if all the component values of this AUID are set to 0, the only non-unique value for an AUID.
`boolean`	`isUniversalLabel()` Returns `true` if this AUID value is a SMPTE Universal Label, as defined in SMPTE 298M-1997.
`static AUID`	`namebasedAUID(byte[] nameData)` Creates a new UUID as an AUID generated with the name-based method, type 3.
`static AUID`	`parseAUID(String auidValue)` Create 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:`").
`static AUID`	`randomAUID()` Create a new AUID using pseudo-random number generation, type 4.
`void`	`setAUIDValue(byte[] auidValue)` Sets the array of bytes used to represent this AUID internally.
`void`	`setData1(int data1)` Sets the time-low part of the AUID.
`void`	`setData2(short data2)` Sets the time-mid part of the AUID.
`void`	`setData3(short data3)` Sets the time-hi and version parts of the AUID.
`void`	`setData4(byte[] data4)` Sets the variant, clock sequence and node parts of the AUID using an 8-byte array.
`static void`	`setLocalNodeID(byte[] localNodeId)` Set the local node ID to use in the generation of timebased UUIDs as AUIDs.
`void`	`setPropertiesFromInterface(AUID castFrom)` Set the properties of this instance value from those available in the given value, which is specified by the AUID interface.
`static AUID`	`timebasedAUID()` Create and return 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 id.
`String`	`toString()` Create a string representation of this AUID as either an URN for a Universal Label (starting with "`urn:x-ul:`") or an URN for an UUID (starting with "`urn:uuid:`").

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

AUID

public AUID(@UInt32
            int data1,
            @UInt16
            short data2,
            @UInt16
            short data3,
            @UInt8
            byte[] data4)
     throws NullPointerException

Create a new AUID from its component parts.

Parameters:: data1 - Integer value ... the first 4 bytes, also known as the "time_low" part.; data2 - Short value ... the next 2 bytes, also known as the "time_mid" part.; data3 - Short value ... the next 2 bytes, also known as the "time_mid_and_version" part.; data4 - Array of 8 bytes ... the final 8 bytes, containing the variant, clock sequence and node parts. The value will be truncated or padded if more or less than 8 bytes are provided respectively.
Throws:: NullPointerException

AUID

public AUID(byte[] auidValue)
     throws NullPointerException

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

Parameters:: auidValue - Byte array to use to set the value of the new AUID.
Throws:: NullPointerException - Argument is null.

AUID

public AUID()

Create a new UUID as an AUID using the random generation method. Creating an AUID with this constructor has the same result as calling the static factory method randomAUID().

See Also:: randomAUID()

Method Detail

setLocalNodeID

public static final void setLocalNodeID(byte[] localNodeId)

Set the local node ID to use in the generation of timebased 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 id (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 id of the system can be set, or any other 6-byte unique identifier for the host.

Parameters:: localNodeId - A guaranteed to be unique identifier for the node on which this class is loaded. The value will be padded or truncated to 6-bytes.
See Also:: timebasedAUID()

timebasedAUID

public static final AUID timebasedAUID()

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

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

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

randomAUID

public static final AUID randomAUID()

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

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

namebasedAUID

public static final AUID namebasedAUID(byte[] nameData)

Creates 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 algorithm.

Parameters:: nameData - Name data to use to create a namebased UUID.
Returns:: Namebased UUID as an AUID.
Throws:: NullPointerException - The name data argument is null.
See Also:: auidFactory(AUIDGeneration, byte[]), UUID.nameUUIDFromBytes(byte[])

timebasedAUID

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

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

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

auidFactory

public static final AUID auidFactory(AUIDGeneration type,
                                     byte[] extraData)
                              throws NullPointerException

Generates a new UUID as an AUID using the given generation method. Three different types are supported by this factory:

AUIDGeneration.IETF_Type1 or AUIDGeneration.Timebased: Generate a time and location based UUID as an AUID. If the extra data is null then this method is equivalent to calling timebasedAUID() and if extra data is provided, this method is equivalent to calling timebasedAUID(byte[]).
AUIDGeneration.IETF_Type3 or AUIDGeneration.Namebased: Generate a name based UUID as an AUID. Extra data must be provided and this method is equivalent to calling namebasedAUID(byte[]).
AUIDGeneration.IETF_Type4 or AUIDGeneration.Random: Generate a random UUID as an AUID. The value of the extra data argument is ignored and this method is equivalent to calling randomAUID().

Parameters:: type - Generator type for a new UUID as an AUID.; extraData - Additional data that may be required by the given generation method.
Returns:: Newly generated UUID as an AUID.
Throws:: NullPointerException - The type and/or extra data arguments is/are null.
See Also:: randomAUID(), timebasedAUID(), namebasedAUID(byte[]), umidFactory()

castFromInterface

public static final AUID castFromInterface(AUID alien)
                                    throws NullPointerException

Create an instance of this AUID implementation using a possibly alien implementation that at least implements tv.amwa.maj.record.AUID. If the given value is an instance of this class, the value is returned directly, otherwise a new AUID is constructed with an equivalent value to the given value.

Parameters:: alien - Object implementing AUID to use to create an instance of this implementation from.
Returns:: Instance of this AUID implementation with a value equivalent to that of the given object.
Throws:: NullPointerException - The alien value argument is null.
See Also:: setPropertiesFromInterface(tv.amwa.maj.record.AUID)

setPropertiesFromInterface

public final void setPropertiesFromInterface(AUID castFrom)
                                      throws NullPointerException

Set the properties of this instance value from those available in the given value, which is specified by the AUID interface.

Parameters:: castFrom - Value to extract properties from.
Throws:: NullPointerException - The given value to use to set this value is null.
See Also:: castFromInterface(tv.amwa.maj.record.AUID)