Package com.documentum.registry

# Class DfRegistry

java.lang.Object
com.documentum.registry.DfRegistry

All Implemented Interfaces:
  `IDfRegistry`

Direct Known Subclasses:
  `DfRegistryIniFile`, `DfRegistryWin32`, `DfRemoteRegistry`

public abstract class DfRegistry extends Object implements IDfRegistry
This class provides basic functionality for a platform independent registry storage and retrieval mechanisms. This class provides an array of values abstraction on top of the subclass simple (key,value) mechanism.

The basic structure of the registry framework is a nested heirarchy of keys with values. A key can have sub-keys or children keys. Each key has values which consist of pairs of names and data. Each value can have an associated type (e.g. String, binary, or integer) but it is not enforced directly.

This class is not exposed via COM since DfRegistryIniFile is not exposed via COM. Please see DfRegistryIniFile for more details.

Notes:

- All functions, except openKey( ) and isValidKey( ), operate on the current open key. It can be set by calling openKey( ). All names and sub-keys are relative to the open key.
- To set the open key to the root key, call openKey( "" ).
- All values and sub-keys are case insensitive and whitespace characters are allowed. The registry delimiter is not allowed as a valid key name character. Here is an example of setting data with beginning and trailing whitespace: setStringValue( "somevalue", "\" this is some data \"")
- Binary value operations use integer lists (arrays) instead of byte arrays due to the Java/COM data type mappings. When used each integer element will be truncated to the size of a byte.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String`
  `ARRAY_INDEX`
  Name for deliminating an array index.
  `protected static final String`
  `ARRAY_SIZE_INDEX`
  Name for deliminating an array size.

  ### Fields inherited from interface com.documentum.registry.IDfRegistry

  `ALL_ACCESS, ALTERNATE_FILEPATHS, DCTM_ROOT, HKEY_CLASSES_ROOT, HKEY_PERFORMANCE_DATA, HKEY_USERS, KEY_DELIMITER, LOCALMACHINE_ROOT, READ_ACCESS, USER_ROOT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DfRegistry()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `acquireInterProcessLock()`
  Acquires the inter-process lock.
  `protected void`
  `assertFunc(String param)`
  Used to check for valid parameters to functions.
  `abstract void`
  `closeKey()`
  Closes an open key freeing system resources.
  `protected abstract void`
  `closeRootKey()`
  `abstract void`
  `createKey()`
  `abstract void`
  `deleteSubKey(String subKey)`
  Deletes a sub-key of the open key.
  `abstract void`
  `deleteSubKeys()`
  Deletes the sub-keys under the open key.
  `abstract void`
  `deleteValue(String name)`
  Deletes a value and the value's data under the open key.
  `protected void`
  `finalize()`
  `void`
  `flush()`
  `abstract IDfList`
  `getBinaryValue(String name)`
  Returns a binary representation of the data at the given value.
  `IDfList`
  `getBinaryValueAt(String name, int index)`
  Gets a binary value at a given index of a given key.
  `IDfList`
  `getBinaryValues(String name)`
  Returns a binary array of the data at the given value.
  `int`
  `getInterprocessLockCount()`
  `abstract int`
  `getIntValue(String name)`
  Returns an integer representation of the data at the given value.
  `int`
  `getIntValueAt(String name, int index)`
  Gets an integer value at a given index of a given key.
  `IDfList`
  `getIntValues(String name)`
  Returns an integer array of the data at the given value.
  `abstract String`
  `getStringValue(String name)`
  Returns a String representation of the data at the given value.
  `String`
  `getStringValueAt(String name, int index)`
  Gets a String value at a given index of a given key.
  `IDfList`
  `getStringValues(String name)`
  Returns a String array of the data at the given value.
  `int`
  `getValuesSize(String name)`
  Returns the number of elements in a key with an array of values.
  `abstract boolean`
  `isSubKey(String subKey)`
  Returns a flag specifying if the given sub-key is a sub-key of the open key.
  `abstract void`
  `openKey(String subKey)`
  Set the open key.
  `int`
  `releaseInterProcessLock()`
  Releases the inter-process lock.
  `void`
  `reset()`
  `abstract void`
  `setBinaryValue(String name, IDfList data)`
  Sets the data field of the given value with binary data.
  `void`
  `setBinaryValueAt(String name, int index, IDfList data)`
  Sets a binary value at a given index of a given key.
  `void`
  `setBinaryValues(String name, IDfList data)`
  Sets the data field of the given value with binary values.
  `abstract void`
  `setIntValue(String name, int data)`
  Sets the data field of the given value with integer data.
  `void`
  `setIntValueAt(String name, int index, int data)`
  Sets an integer value at a given index of a given key.
  `void`
  `setIntValues(String name, IDfList data)`
  Sets the data field of the given value with integer values.
  `abstract void`
  `setStringValue(String name, String data)`
  Sets the data field of the given value with String data.
  `void`
  `setStringValueAt(String name, int index, String data)`
  Sets a String value at a given index of a given key.
  `protected abstract void`
  `setStringValues(RegistryEntriesHolder holder)`
  `void`
  `setStringValues(String name, IDfList data)`
  Sets the data field of the given value with String values.
  `void`
  `setValuesSize(String name, int size)`
  Set the size of an array name.
  `abstract IDfList`
  `subKeys()`
  Returns the sub-keys of the open key.
  `abstract IDfList`
  `values()`
  Returns the value names of the open key.

  ### Methods inherited from class java.lang.Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface com.documentum.registry.IDfRegistry

  `isValueNamePresent`

- ## Field Details

  - ### ARRAY_INDEX

    protected static final String ARRAY_INDEX
    Name for deliminating an array index.
    See Also:
      - Constant Field Values

  - ### ARRAY_SIZE_INDEX

    protected static final String ARRAY_SIZE_INDEX
    Name for deliminating an array size.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DfRegistry

    public DfRegistry()

- ## Method Details

  - ### openKey

    public abstract void openKey(String subKey) throws DfException
    Set the open key. The key is created if it does not exist. If there is an open key it is closed prior to opening a the new key.
    Specified by:
      `openKey` in interface `IDfRegistry`
    Parameters:
      `subKey` - a new or existing key in the registry storage.
    Throws:
      `DfException` - if the operation failed.

  - ### isSubKey

    public abstract boolean isSubKey(String subKey) throws DfException
    Returns a flag specifying if the given sub-key is a sub-key of the open key.
    Specified by:
      `isSubKey` in interface `IDfRegistry`
    Parameters:
      `subKey` - the key to be found.
    Returns:
      a flag specifying if the given sub-key is an actual sub-key.
    Throws:
      `DfException` - if the operation failed.

  - ### deleteValue

    public abstract void deleteValue(String name) throws DfException
    Deletes a value and the value's data under the open key.
    Specified by:
      `deleteValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value to be deleted.
    Throws:
      `DfException` - if the operation failed.

  - ### deleteSubKey

    public abstract void deleteSubKey(String subKey) throws DfException
    Deletes a sub-key of the open key.
    Specified by:
      `deleteSubKey` in interface `IDfRegistry`
    Parameters:
      `subKey` - the key to be deleted.
    Throws:
      `DfException` - if the operation failed.

  - ### deleteSubKeys

    public abstract void deleteSubKeys() throws DfException
    Deletes the sub-keys under the open key. The open key is not deleted.
    Specified by:
      `deleteSubKeys` in interface `IDfRegistry`
    Throws:
      `DfException` - if the operation failed.

  - ### closeKey

    public abstract void closeKey() throws DfException
    Closes an open key freeing system resources.
    Specified by:
      `closeKey` in interface `IDfRegistry`
    Throws:
      `DfException` - if the operation failed.

  - ### values

    public abstract IDfList values() throws DfException
    Returns the value names of the open key. To get the value's data, call get[TYPE]Value( ).
    Specified by:
      `values` in interface `IDfRegistry`
    Returns:
      a list of String value names of the top-level key.
    Throws:
      `DfException` - if the operation failed.

  - ### subKeys

    public abstract IDfList subKeys() throws DfException
    Returns the sub-keys of the open key.
    Specified by:
      `subKeys` in interface `IDfRegistry`
    Returns:
      a list of String sub-key names of the top-level key.
    Throws:
      `DfException` - if the operation failed.

  - ### getIntValue

    public abstract int getIntValue(String name) throws DfException
    Returns an integer representation of the data at the given value.
    Specified by:
      `getIntValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      an integer representation of the data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setIntValue

    public abstract void setIntValue(String name, int data) throws DfException
    Sets the data field of the given value with integer data.
    Specified by:
      `setIntValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to set.
    Throws:
      `DfException` - if the operation failed.

  - ### getStringValue

    public abstract String getStringValue(String name) throws DfException
    Returns a String representation of the data at the given value.
    Specified by:
      `getStringValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      a String representation of the data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setStringValue

    public abstract void setStringValue(String name, String data) throws DfException
    Sets the data field of the given value with String data.
    Specified by:
      `setStringValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to set.
    Throws:
      `DfException` - if the operation failed.

  - ### setStringValues

    protected abstract void setStringValues(RegistryEntriesHolder holder) throws DfException
    Throws:
      `DfException`

  - ### getBinaryValue

    public abstract IDfList getBinaryValue(String name) throws DfException
    Returns a binary representation of the data at the given value.
    Specified by:
      `getBinaryValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      a list with a binary representation of the data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setBinaryValue

    public abstract void setBinaryValue(String name, IDfList data) throws DfException
    Sets the data field of the given value with binary data.
    Specified by:
      `setBinaryValue` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to set. This must be a list of integers of which each will be truncated to byte size.
    Throws:
      `DfException` - if the operation failed.

  - ### reset

    public void reset() throws IOException, DfException
    Specified by:
      `reset` in interface `IDfRegistry`
    Throws:
      `IOException`
      `DfException`

  - ### flush

    public void flush() throws IOException, DfException
    Specified by:
      `flush` in interface `IDfRegistry`
    Throws:
      `IOException`
      `DfException`

  - ### createKey

    public abstract void createKey() throws DfException
    Specified by:
      `createKey` in interface `IDfRegistry`
    Throws:
      `DfException`

  - ### getIntValues

    public IDfList getIntValues(String name) throws DfException
    Returns an integer array of the data at the given value.
    Specified by:
      `getIntValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      an integer list of the data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setIntValues

    public void setIntValues(String name, IDfList data) throws DfException
    Sets the data field of the given value with integer values. The value can be previously a non-array value or non-existent.
    Specified by:
      `setIntValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to be set. This must be a list of integers.
    Throws:
      `DfException` - if the operation failed.

  - ### getIntValueAt

    public int getIntValueAt(String name, int index) throws DfException
    Gets an integer value at a given index of a given key.
    Specified by:
      `getIntValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the key to look up into.
      `index` - zero-based index into the values array.
    Returns:
      the integer value at the given index.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### setIntValueAt

    public void setIntValueAt(String name, int index, int data) throws DfException
    Sets an integer value at a given index of a given key. The index must be 0 if the value is not an array or does not exist. The index may be 1 + the current array size of the value causing this function to act as an append.
    Specified by:
      `setIntValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the value to set.
      `index` - zero-based index into the values array.
      `data` - the data to be set.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### getStringValues

    public IDfList getStringValues(String name) throws DfException
    Returns a String array of the data at the given value.
    Specified by:
      `getStringValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      a String list of the data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setStringValues

    public void setStringValues(String name, IDfList data) throws DfException
    Sets the data field of the given value with String values.
    Specified by:
      `setStringValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to be set. This must be a list of Strings.
    Throws:
      `DfException` - if the operation failed.

  - ### getStringValueAt

    public String getStringValueAt(String name, int index) throws DfException
    Gets a String value at a given index of a given key.
    Specified by:
      `getStringValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the key to look up into.
      `index` - zero-based index into the values array.
    Returns:
      the String value at the given index.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### setStringValueAt

    public void setStringValueAt(String name, int index, String data) throws DfException
    Sets a String value at a given index of a given key. The index must be 0 if the value is not an array or does not exist. The index may be 1 + the current array size of the value causing this function to act as an append.
    Specified by:
      `setStringValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the value to set.
      `index` - zero-based index into the values array.
      `data` - the data to be set.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### getBinaryValues

    public IDfList getBinaryValues(String name) throws DfException
    Returns a binary array of the data at the given value.
    Specified by:
      `getBinaryValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value to lookup.
    Returns:
      an integer list of integer lists each of which represent the binary data at the given value.
    Throws:
      `DfException` - if the operation failed.

  - ### setBinaryValues

    public void setBinaryValues(String name, IDfList data) throws DfException
    Sets the data field of the given value with binary values.
    Specified by:
      `setBinaryValues` in interface `IDfRegistry`
    Parameters:
      `name` - the value whose data is to be set.
      `data` - the data to be set. This must be a list of lists of integers.
    Throws:
      `DfException` - if the operation failed.

  - ### getBinaryValueAt

    public IDfList getBinaryValueAt(String name, int index) throws DfException
    Gets a binary value at a given index of a given key.
    Specified by:
      `getBinaryValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the key to look up into.
      `index` - zero-based index into the values array.
    Returns:
      a list representing the binary (byte) value at the given index.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### setBinaryValueAt

    public void setBinaryValueAt(String name, int index, IDfList data) throws DfException
    Sets a binary value at a given index of a given key. The index must be 0 if the value is not an array or does not exist. The index may be 1 + the current array size of the value causing this function to act as an append.
    Specified by:
      `setBinaryValueAt` in interface `IDfRegistry`
    Parameters:
      `name` - the value to set.
      `index` - zero-based index into the values array.
      `data` - the data to be set. This must be a list of integers each of which will be truncated to a byte.
    Throws:
      `DfException` - if the index is out of range or the operation failed.

  - ### getValuesSize

    public int getValuesSize(String name) throws DfException
    Returns the number of elements in a key with an array of values.
    Specified by:
      `getValuesSize` in interface `IDfRegistry`
    Parameters:
      `name` - the array name to get the size of.
    Returns:
      the number of elements in an array.
    Throws:
      `DfException` - if the name is not an array.

  - ### setValuesSize

    public void setValuesSize(String name, int size) throws DfException
    Set the size of an array name.
    Specified by:
      `setValuesSize` in interface `IDfRegistry`
    Parameters:
      `name` - the array name to set the size of.
      `size` - the new size to set.
    Throws:
      `DfException` - if the operation failed.

  - ### acquireInterProcessLock

    public int acquireInterProcessLock() throws DfException
    Acquires the inter-process lock. Inter-process lock will be acquired only if the OS in not Windows.
    Throws:
      `DfException`

  - ### releaseInterProcessLock

    public int releaseInterProcessLock()
    Releases the inter-process lock. Inter-process lock will be released only if the OS in not Windows.

  - ### getInterprocessLockCount

    public int getInterprocessLockCount()

  - ### assertFunc

    protected void assertFunc(String param) throws DfException
    Used to check for valid parameters to functions.
    Parameters:
      `param` - the string to test.
    Throws:
      `DfException` - if the parameter is invalid.

  - ### closeRootKey

    protected abstract void closeRootKey() throws DfException
    Throws:
      `DfException`

  - ### finalize

    protected void finalize()
    Overrides:
      `finalize` in class `Object`