ca.beq.util.win32.registry
Class RegistryKey

java.lang.Object
  |
  +--ca.beq.util.win32.registry.RegistryKey

public class RegistryKey
extends Object

A representation of system registry keys, RegistryKey is the principle class of the ca.beq.util.win32.registry package.

A RegistryKey is composed of two components (specified at creation):

  1. A root key, and
  2. A path

The root key component is defined to be any valid RootKey object. The path component is similar to a file-system pathname; it is a series of zero or more string names separated by backslahes ("\\"). Unlike file-system pathnames there is no "optional prefix", and each name defines a registry key. For example, Software\\BEQ Technologies\\Test is a valid registry key, whereas \\Software\\BEQ Technologies\\Test is not.

The following code snippet demonstrates creating, reading, and deleting values in the registry using RegistryKey:

    // create a new key, "Test", under HKLM
    RegistryKey r = new RegistryKey(RootKey.HKEY_LOCAL_MACHINE, "Test");
    if(!r.exists()) {
       r.create();
    } // if

    // create value entries
    RegistryValue v = new RegistryValue("aString", ValueType.REG_SZ, "test");
    r.setValue(v);

    v.setName("aDword");
    v.setType(ValueType.REG_DWORD);
    v.setData(new Integer(0x1001001));
    r.setValue(v);

    // read value entries
    Iterator i = r.values();
    while(i.hasNext()) {
       v = (RegistryValue)i.next();
       System.out.println(v.toString());
    } // while

    // delete registry key
    r.delete();
 

Version:
1.0
Author:
BEQ Technologies Inc.

Constructor Summary
RegistryKey()
          Constructs a new RegistryKey referencing the root path of the RootKey.HKEY_CURRENT_USER root key.
RegistryKey(RootKey root)
          Constructs a new RegistryKey referencing the root path of the specified RootKey.
RegistryKey(RootKey root, String path)
          Constructs a new RegistryKey referencing the specified path of the specified RootKey.
RegistryKey(String path)
          Constructs a new RegistryKey referencing the specified path of the RootKey.HKEY_CURRENT_USER root key.
 
Method Summary
 void create()
          Creates this registry key in the system registry.
 RegistryKey createSubkey(String name)
          Creates the specified subkey.
 void delete()
          Deletes this registry key and any subkeys or values from the system registry.
 void deleteValue(String name)
          Deletes the specified value from this registry key.
 boolean exists()
          Tests if this registry key, as defined by the RootKey and path, currently exists in the system registry.
 String getName()
          Returns this RegistryKey's name.
 String getPath()
          Returns this RegistryKey's path.
 RootKey getRootKey()
          Returns this RegistryKey's root key.
 RegistryValue getValue(String name)
          Returns a RegistryValue representing the specified value.
 boolean hasSubkey(String name)
          Tests if this registry key possesses the specified subkey.
 boolean hasSubkeys()
          Tests if this registry key possesses subkeys.
 boolean hasValue(String name)
          Tests if this registry key possess the specified value.
 boolean hasValues()
          Tests if this registry key possess any values.
 void setValue(RegistryValue value)
          Sets the properties of a registry value according to the properties of the specified RegistryValue.
 Iterator subkeys()
          Returns an iterator for available subkeys.
 String toString()
          Returns a string representation of this RegistryKey.
 Iterator values()
          Returns an iterator for available values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RegistryKey

public RegistryKey()
Constructs a new RegistryKey referencing the root path of the RootKey.HKEY_CURRENT_USER root key.

RegistryKey

public RegistryKey(RootKey root)
Constructs a new RegistryKey referencing the root path of the specified RootKey.
Parameters:
root - the root key of this RegistryKey

RegistryKey

public RegistryKey(String path)
Constructs a new RegistryKey referencing the specified path of the RootKey.HKEY_CURRENT_USER root key.
Parameters:
path - the path of this RegistryKey

RegistryKey

public RegistryKey(RootKey root,
                   String path)
Constructs a new RegistryKey referencing the specified path of the specified RootKey.
Parameters:
root - the root key of this RegistryKey
path - the path of this RegistryKey
Method Detail

getRootKey

public RootKey getRootKey()
Returns this RegistryKey's root key.
Returns:
the root key

getPath

public String getPath()
Returns this RegistryKey's path.
Returns:
the path

getName

public String getName()
Returns this RegistryKey's name. The name is last portion of a path. For example, for the path Software\\BEQ Technologies\\TestKey, the name would be TestKey.
Returns:
the name

exists

public boolean exists()
Tests if this registry key, as defined by the RootKey and path, currently exists in the system registry.
Returns:
true if this key exists in the registry

create

public void create()
Creates this registry key in the system registry.
Throws:
RegistryException - if this registry key already exists in the registry

createSubkey

public RegistryKey createSubkey(String name)
Creates the specified subkey.
Parameters:
name - name the subkey to be created
Returns:
the created subkey
Throws:
RegistryException - if this registry key does not exist in the registry, or if the specified subkey name already exists.

delete

public void delete()
Deletes this registry key and any subkeys or values from the system registry.

WARNING: This method can potentially cause catastrophic damage to the system registry. USE WITH EXTREME CARE!

Throws:
RegistryException - if this registry key does not already exist in the registry

hasSubkeys

public boolean hasSubkeys()
Tests if this registry key possesses subkeys. Use subkeys to retrieve an iterator for available subkeys.
Returns:
true if this registry key possesses subkeys
Throws:
RegistryException - if this registry key does not already exist in the registry

hasSubkey

public boolean hasSubkey(String name)
Tests if this registry key possesses the specified subkey.
Parameters:
name - the subkey to test for
Returns:
true if this registry key possesses subkeys
Throws:
RegistryException - if this registry key does not already exist in the registry

subkeys

public Iterator subkeys()
Returns an iterator for available subkeys.
Returns:
an iterator of RegistryKey's
Throws:
RegistryException - if this registry key does not already exist in the registry

values

public Iterator values()
Returns an iterator for available values.
Returns:
an iterator of RegistryValue's
Throws:
RegistryException - if this registry key does not already exist in the registry

hasValue

public boolean hasValue(String name)
Tests if this registry key possess the specified value.
Parameters:
name - the name of the value to be tested
Returns:
true if this registry keys possess the specified value
Throws:
RegistryException - if this registry key does not already exist in the registry

hasValues

public boolean hasValues()
Tests if this registry key possess any values.
Returns:
true if this registry keys possess any values
Throws:
RegistryException - if this registry key does not already exist in the registry

getValue

public RegistryValue getValue(String name)
Returns a RegistryValue representing the specified value.
Parameters:
name - the name of the value to be retreived
Returns:
the RegistryValue of the specified value name
Throws:
RegistryException - if this registry key does not already exist in the registry, or if this registry key does not possess the specified value

setValue

public void setValue(RegistryValue value)
Sets the properties of a registry value according to the properties of the specified RegistryValue. If the specified value exists, it will be modified; if not, it will be created.
Parameters:
value - the RegistryValue
Throws:
RegistryException - if this registry key does not already exist in the registry

deleteValue

public void deleteValue(String name)
Deletes the specified value from this registry key.
Parameters:
name - the name of the value to be deleted
Throws:
RegistryException - if this registry key does not already exist in the registry, or if the specified value is not possess by this registry key

toString

public String toString()
Returns a string representation of this RegistryKey.
Overrides:
toString in class Object
Returns:
a string representation of this RegistryKey