GuidFactory (CMDB Model API)
Keywords: com.collation.platform.model.GuidFactory class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.collation.platform.model
Class GuidFactory

    java.lang.Object
      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:

  - The Guids generated at different times from the same name in the same namespace must be equal.
  - The Guids generated from two different names in the same namespace should be different (with very high probability).
  - The Guids generated from the same name in two different namespaces should be different with (very high probability).
  - If two Guids that were generated from names are equal, then they were generated from the same name in the same namespace (with very high probability).

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD