com.collation.platform.model
Class GuidFactory

java.lang.Object
  extended by com.collation.platform.model.GuidFactory

public class GuidFactory
extends java.lang.Object

An instance of this class acts as the factory for version 3 and null Guid instances.

This factory supports only version 3 Guid instances and null Guids. Subclasses may support other versions.

All version 3 Guids created by this factory via the com.ibm.cdb.guid.GuidFactory#createGuid(String) method will be created within the namespace defined by the namespaceGuid property. The byte array identifying the namespace GUID is passed to the factory constructor and becomes an immutable property of the factory.

Note that Guids created via the com.ibm.cdb.guid.GuidFactory#createGuid(byte[]) or com.ibm.cdb.guid.GuidFactory#createGuidFromHex(String) methods are also validated to be version 3, however there is no way to validate that they are from the namespace defined by the namespaceGuid property.


Field Summary
static java.lang.String CHARACTER_SET
          Constant for Character Set used to encode the byte sequence
static byte GUID_RESERVED
          Constant for the Guid reserved variant field.
static byte GUID_RESERVED_MASK
           
static byte GUID_VERSION_1_MASK
           
static byte GUID_VERSION_3
          Constants for Guid versions.
static java.lang.String GUID_VERSION_3_ALGORITHM
           
static byte GUID_VERSION_MASK
           
static byte[] KEYMASTER_NAMESPACE_GUID
          The Type 1 GUID used for initialization of the factory instance for this JVM.
static byte[] URI_SCHEME_NAME_GUID
          The Type 3 GUID used for initialization of the default factory instance for this JVM.
static java.lang.String VALID_HEX_CHARACTERS
          Valid hex characters for strings passed to the com.ibm.cdb.guid.GuidFactory#createGuidFromHex(String) method.
 
Constructor Summary
GuidFactory(byte[] namespaceGUID)
          Constructor for GuidFactory.
 
Method Summary
 Guid createGuid(byte[] guidByteArray)
          Creates a Guid instance and assigns the byte array contents into the internal variables.
 Guid createGuid(java.lang.String name)
          Create a Version 3 style identifier and returns the instance.
 Guid createGuidFromDB(java.lang.String guidHexString)
          Creates a Guid instance and assigns the hexidecimal string representation into the internal variables.
 Guid createGuidFromHex(java.lang.String guidHexString)
          Creates a Guid instance and assigns the hexidecimal string representation into the internal variables.
 Guid createNullGuid()
          Creates a null instance of the Guid object.
static GuidFactory getDefaultGuidFactory()
          Returns the defaultGuidFactory.
 Guid getNamespaceGuid()
          Returns the namespaceGuid.
protected  Guid primCreateGuid(byte[] guidByteArray, boolean adopt)
          Creates a Guid instance and assigns the byte array contents into the internal variables.
protected  Guid primCreateGuid(java.security.MessageDigest md5, java.lang.String name)
          Create a Version 3 style identifier and returns the instance.
static void setDefaultGuidFactory(GuidFactory defaultGuidFactory)
          Sets the defaultGuidFactory.
protected  void validateOctets(byte[] octets)
          Checks to make sure the version and reserved variant fields in the bytes are valid for the settings on this factory.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GUID_VERSION_3

public static final byte GUID_VERSION_3
Constants for Guid versions.

The following table lists currently defined versions of the UUID.

   Msb0  Msb1  Msb2  Msb3  Version  Description

    0     0     0     1       1     The IEEE 802 address, time-based version.

    0     0     1     0       2     Reserved for DCE Security version, with
                                    embedded POSIX UIDs.

    0     0     1     1       3     The name-based version.

    0     1     0     0       4     The pseudo-randomly generated version
 

The version is stored in the 4 most significant bits if the 6th octet.

See Also:
Constant Field Values

GUID_VERSION_1_MASK

public static final byte GUID_VERSION_1_MASK
See Also:
Constant Field Values

GUID_VERSION_MASK

public static final byte GUID_VERSION_MASK
See Also:
Constant Field Values

GUID_VERSION_3_ALGORITHM

public static final java.lang.String GUID_VERSION_3_ALGORITHM
See Also:
Constant Field Values

CHARACTER_SET

public static final java.lang.String CHARACTER_SET
Constant for Character Set used to encode the byte sequence

See Also:
Constant Field Values

GUID_RESERVED

public static final byte GUID_RESERVED
Constant for the Guid reserved variant field. It occupies the two most significant bits in the 8th octet.

See Also:
Constant Field Values

GUID_RESERVED_MASK

public static final byte GUID_RESERVED_MASK
See Also:
Constant Field Values

VALID_HEX_CHARACTERS

public static final java.lang.String VALID_HEX_CHARACTERS
Valid hex characters for strings passed to the com.ibm.cdb.guid.GuidFactory#createGuidFromHex(String) method.

See Also:
Constant Field Values

KEYMASTER_NAMESPACE_GUID

public static final byte[] KEYMASTER_NAMESPACE_GUID
The Type 1 GUID used for initialization of the factory instance for this JVM. The Type 1 GUID is: 765ba611-a9a1-122a-9ae9-0000e28c7874 This Type 1 GUID is reserved for RR ***Metadata*** Creation. It should not be used for any other purposes.


URI_SCHEME_NAME_GUID

public static final byte[] URI_SCHEME_NAME_GUID
The Type 3 GUID used for initialization of the default factory instance for this JVM. The Type 3 GUID is: 1135e7f1-517b-3a73-86fb-97d7a6f31b02 This Type 3 GUID is to be used as a namespace for all instance creation. The namespace (contained within quotes) is : "ibm-cdm:"

Constructor Detail

GuidFactory

public GuidFactory(byte[] namespaceGUID)
            throws java.security.NoSuchAlgorithmException
Constructor for GuidFactory.

Parameters:
namespaceGUID - GUID identifying the factory's namespace GUID
Throws:
java.security.NoSuchAlgorithmException - if the MD5 algorithm is not available in the caller's environment.
Method Detail

createGuid

public Guid createGuid(byte[] guidByteArray)
Creates a Guid instance and assigns the byte array contents into the internal variables. The method is the inverse of the com.ibm.cdb.guid.Guid#toByteArray() method, so the following x.equals(y); is true, when x = guidFactory.createGuid(y.toByteArray());

This can be used to copy Guid objects, or more often used to create an object from the binary value that was stored in a file or database system.

Parameters:
guidByteArray - Array of bytes containing Guid information.
Throws:
java.lang.IllegalArgumentException - if the byte array does not form a valid set of Guid octets.
See Also:
Guid.toByteArray()

createGuid

public Guid createGuid(java.lang.String name)
                throws java.security.NoSuchAlgorithmException
Create a Version 3 style identifier and returns the instance. The namespace must have already received a Guid assignment that qualifies the name being passed.

The Version 3 Guid is meant for generating Guids from "names" that are drawn from, and unique within, some "name space". Some examples of names (and, implicitly, name spaces) might be DNS names, URLs, ISO Object IDs (OIDs), reserved words in a programming language, or X.500 Distinguished Names (DNs); thus, the concept of name and name space should be broadly construed, and not limited to textual names. The mechanisms or conventions for allocating names from, and ensuring their uniqueness within, their name spaces are beyond the scope of this specification.

The requirements for such Guids are as follows:

Parameters:
name - Name identifying a Guid in the factory's namespace
Returns:
a Version 3 Guid object.
Throws:
java.security.NoSuchAlgorithmException - if the MD5 algorithm is not available in the caller's environment.

createGuidFromHex

public Guid createGuidFromHex(java.lang.String guidHexString)
Creates a Guid instance and assigns the hexidecimal string representation into the internal variables. The method is the inverse of the com.ibm.cdb.guid.Guid#toString() method, so the following x.equals(y); is true, when x = guidFactory.createGuidFromHex(y.toString());

This can be used to copy Guid objects, or more often used to create an object from the hexidecimal representation is store in a configuration file.

Parameters:
String - containing valid Guid object
Throws:
java.lang.IllegalArgumentException - if the string does not have the valid format for a Guid string. a valid set of Guid octets.
See Also:
Guid.toString()

createGuidFromDB

public Guid createGuidFromDB(java.lang.String guidHexString)
Creates a Guid instance and assigns the hexidecimal string representation into the internal variables. The method is the inverse of the com.ibm.cdb.guid.Guid#toString() method, so the following x.equals(y); is true, when x = guidFactory.createGuidFromHex(y.toString());

This method is specifically for converting DB2 database byte string representations into useable Guid objects

Parameters:
String - containing valid Guid object
Throws:
java.lang.IllegalArgumentException - if the string does not have the valid format for a Guid string. a valid set of Guid octets.
See Also:
Guid.toString()

createNullGuid

public Guid createNullGuid()
Creates a null instance of the Guid object.

This creates an instance of the Guid object and returns it. A null Guid is defined as 128 zero bits in the internal variables.

Returns:
a null Guid object.
See Also:
Guid#isNull()

primCreateGuid

protected Guid primCreateGuid(byte[] guidByteArray,
                              boolean adopt)
Creates a Guid instance and assigns the byte array contents into the internal variables. The method is the inverse of the com.ibm.cdb.guid.Guid#toByteArray() method, so the following x.equals(y); is true, when x = guidFactory.createGuidFromByteArray(y.toByteArray());

This can be used to copy Guid objects, or more often used to create an object from the binary value that was stored in a file or database system.

Parameters:
guidByteArray - Array of bytes containign Guid information.
See Also:
Guid.toByteArray()

primCreateGuid

protected Guid primCreateGuid(java.security.MessageDigest md5,
                              java.lang.String name)
                       throws java.security.NoSuchAlgorithmException
Create a Version 3 style identifier and returns the instance. The MessageDigest must already be updated with the namespace if a namespace is to be used.

Parameters:
name - Name identifying a Guid in the factory's namespace
Returns:
a Version 3 Guid object.
Throws:
java.security.NoSuchAlgorithmException - if the MD5 algorithm is not available in the caller's environment.

validateOctets

protected void validateOctets(byte[] octets)
Checks to make sure the version and reserved variant fields in the bytes are valid for the settings on this factory.

Throws:
java.lang.IllegalArgumentException - if the byte array does not form a valid set of Guid octets.

getDefaultGuidFactory

public static GuidFactory getDefaultGuidFactory()
                                         throws java.security.NoSuchAlgorithmException
Returns the defaultGuidFactory.

Returns:
GuidFactory
Throws:
java.security.NoSuchAlgorithmException - if the property is null. This means the static initialization block could not find the MD5 algorithm or that the corresponding property setter has been used to set the property to null.

setDefaultGuidFactory

public static void setDefaultGuidFactory(GuidFactory defaultGuidFactory)
Sets the defaultGuidFactory. This is intended to only be used if recovery from the MD5 algorithm not being accessible during factory class initialization can be fixed by client code and a default factory can be created by the client code.

Parameters:
defaultGuidFactory - The defaultGuidFactory to set

getNamespaceGuid

public Guid getNamespaceGuid()
Returns the namespaceGuid. It is safe to return a direct reference to the name space Guid because Guid instances are immutable.

Returns:
Guid