com.ice.jni.registry
Class RegistryKey

java.lang.Object
  com.ice.jni.registry.RegistryKey

public class RegistryKey
extends java.lang.Object

The RegistryKey class represents a key in the registry. The class also provides all of the native interface calls. You should refer to the Windows Registry API documentation for the details of any of the native methods. The native implementation performs almost no processing before or after a given call, so their behavior should match the API's documented behavior precisely. Note that you can not open a subkey without an existing open RegistryKey. Thus, you need to start with one of the top level keys defined in the Registry class and open relative to that.

See Also:

Registry, RegistryValue

Field Summary

static int	ACCESS_ALL
static int	ACCESS_DEFAULT Constants used to determine the access level for newly opened keys.
static int	ACCESS_EXECUTE
static int	ACCESS_READ
static int	ACCESS_WRITE
protected boolean	created Used to indicate whether or not the key was created when method createSubKey() is called, otherwise false.
protected int	hKey This is the actual DWORD key that is returned from the Registry API.
protected java.lang.String	name The full pathname of this key.

Constructor Summary

RegistryKey(int hKey, java.lang.String name)

RegistryKey(int hKey, java.lang.String name, boolean created)

Method Summary

void	closeKey() Closes this subkey.
RegistryKey	connectRegistry(java.lang.String hostName) Connect to the remote registry on hostName.
RegistryKey	createSubKey(java.lang.String subkey, java.lang.String className) Create, and open, a Registry subkey of this key with WRITE access.
RegistryKey	createSubKey(java.lang.String subKey, java.lang.String className, int access) Create a new subkey, or open the existing one.
int	decrDoubleWord(java.lang.String valueName) This method will decrement the value of a REG_DWORD value.
void	deleteSubKey(java.lang.String subKey) Delete a named subkey.
void	deleteValue(java.lang.String valueName) Delete a named value.
static java.lang.String	expandEnvStrings(java.lang.String exString) This method will expand a string to include the definitions of System environment variables that are referenced via the %variable% construct.
void	export(java.io.PrintWriter out, boolean descend) Export this key's definition to the provided PrintWriter.
void	finalize() The finalize() override checks to be sure the key is closed.
void	flushKey() Guarentees that this key is written to disk.
java.lang.String	getDefaultValue() Get the data from the default value.
java.lang.String	getFullName() Get the full name of the key, from the top level down.
int	getMaxSubkeyLength() Obtains the maximum length of all of the subkey names.
int	getMaxValueDataLength() Obtains the maximum length of all of the value data.
int	getMaxValueNameLength() Obtains the maximum length of all of the value names.
java.lang.String	getName() Get the name of this key.
int	getNumberSubkeys() Obtains the number of subkeys that this key contains.
int	getNumberValues() Obtains the number of values that this key contains.
java.lang.String	getStringValue(java.lang.String valueName) Get the value of a REG_SZ or REG_EXPAND_SZ value.
RegistryValue	getValue(java.lang.String valueName) Get the data of a named value.
boolean	hasDefaultValue() Determines if this key has a default value.
boolean	hasOnlyDefaultValue() Determines if this key has only a default value.
int	incrDoubleWord(java.lang.String valueName) This method will increment the value of a REG_DWORD value.
java.util.Enumeration	keyElements() Returns a new Enumeration that will enum_varerate the names of the subkeys of this key,
RegistryKey	openSubKey(java.lang.String subkey) Open a Registry subkey of this key with READ access.
RegistryKey	openSubKey(java.lang.String subKey, int access) Open a Registry subkey of this key with the specified access.
java.lang.String	regEnumKey(int index) Obtains an enum_varerator for the subkeys of this key.
java.lang.String	regEnumValue(int index) Obtains an enum_varerator for the values of this key.
void	setCreated(boolean created) Used to set the created state of this key.
void	setValue(RegistryValue value) Set the value of this RegistryKey.
void	setValue(java.lang.String valueName, RegistryValue value) Set the name value to the given data.
java.util.Enumeration	valueElements() Returns a new Enumeration that will enum_varerate the names of the values of this key,
boolean	wasCreated() Determine if this key was opened or created and opened.

Methods inherited from class java.lang.Object

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

Field Detail

ACCESS_DEFAULT

public static final int ACCESS_DEFAULT

Constants used to determine the access level for newly opened keys.

See Also:

Constant Field Values

ACCESS_READ

public static final int ACCESS_READ

See Also:

Constant Field Values

ACCESS_WRITE

public static final int ACCESS_WRITE

See Also:

Constant Field Values

ACCESS_EXECUTE

public static final int ACCESS_EXECUTE

See Also:

Constant Field Values

ACCESS_ALL

public static final int ACCESS_ALL

See Also:

Constant Field Values

hKey

protected int hKey

This is the actual DWORD key that is returned from the Registry API. This value is totally opaque and should never be referenced.

name

protected java.lang.String name

The full pathname of this key.

created

protected boolean created

Used to indicate whether or not the key was created when method createSubKey() is called, otherwise false.

Constructor Detail

RegistryKey

public RegistryKey(int hKey,
                   java.lang.String name)

RegistryKey

public RegistryKey(int hKey,
                   java.lang.String name,
                   boolean created)

Method Detail

finalize

public void finalize()

The finalize() override checks to be sure the key is closed.

Overrides:

finalize in class java.lang.Object

getName

public java.lang.String getName()

Get the name of this key. This is not fully qualified, which means that the name will not contain any backslashes.

Returns:

The relative name of this key.

getFullName

public java.lang.String getFullName()

Get the full name of the key, from the top level down.

Returns:

The full name of the key.

wasCreated

public boolean wasCreated()

Determine if this key was opened or created and opened. The result can only be true if createSubKey() was called and the key did not exist, and the creation of the new subkey succeeded.

Returns:

True if the key was created new, else false.

setCreated

public void setCreated(boolean created)

Used to set the created state of this key.

Parameters:

created - The new created state.

openSubKey

public RegistryKey openSubKey(java.lang.String subkey)
                       throws NoSuchKeyException,
                              RegistryException

Open a Registry subkey of this key with READ access.

Parameters:

subkey - The name of the subkey to open.

Returns:

The newly opened RegistryKey.

Throws:

NoSuchKeyException - If the subkey does not exist.

RegistryException - Any other registry API error.

createSubKey

public RegistryKey createSubKey(java.lang.String subkey,
                                java.lang.String className)
                         throws RegistryException

Create, and open, a Registry subkey of this key with WRITE access. If the key already exists, it is opened, otherwise it is first created and then opened.

Parameters:

subkey - The name of the subkey to create.

className - The className of the created subkey.

Returns:

The newly created and opened RegistryKey.

Throws:

RegistryException - Any valid registry API error.

setValue

public void setValue(RegistryValue value)
              throws RegistryException

Set the value of this RegistryKey.

Parameters:

value - The value to set, including the value name.

Throws:

RegistryException - Any valid registry API error.

openSubKey

public RegistryKey openSubKey(java.lang.String subKey,
                              int access)
                       throws NoSuchKeyException,
                              RegistryException

Open a Registry subkey of this key with the specified access.

Parameters:

subKey - The name of the subkey to open.

access - The access level for the open.

Returns:

The newly opened RegistryKey.

Throws:

NoSuchKeyException - If the subkey does not exist.

RegistryException - Any other registry API error.

connectRegistry

public RegistryKey connectRegistry(java.lang.String hostName)
                            throws NoSuchKeyException,
                                   RegistryException

Connect to the remote registry on hostName. This method will only work when invoked on a toplevel key. The returned value will be the same toplevel key opened from the remote host's registry.

Parameters:

hostName - The remote computer's hostname.

Returns:

The remote top level key identical to this top level key.

Throws:

NoSuchKeyException - If the subkey does not exist.

RegistryException - Any other registry API error.

createSubKey

public RegistryKey createSubKey(java.lang.String subKey,
                                java.lang.String className,
                                int access)
                         throws RegistryException

Create a new subkey, or open the existing one. You can determine if the subkey was created, or whether an existing subkey was opened, via the wasCreated() method.

Parameters:

subKey - The name of the subkey to create/open.

className - The key's class name, or null.

access - The access level of the opened subkey.

Returns:

The newly created or opened subkey.

Throws:

RegistryException - Any valid registry API error.

closeKey

public void closeKey()
              throws RegistryException

Closes this subkey. You may chose to let the finalize() method do the close.

Throws:

RegistryException - Any valid registry API error.

deleteSubKey

public void deleteSubKey(java.lang.String subKey)
                  throws NoSuchKeyException,
                         RegistryException

Delete a named subkey.

Parameters:

subKey - The name of the subkey to delete.

Throws:

NoSuchKeyException - If the subkey does not exist.

RegistryException - Any other registry API error.

deleteValue

public void deleteValue(java.lang.String valueName)
                 throws NoSuchValueException,
                        RegistryException

Delete a named value.

Parameters:

valueName - The name of the value to delete.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

flushKey

public void flushKey()
              throws RegistryException

Guarentees that this key is written to disk. This method should be called only when needed, as it has a huge performance cost.

Throws:

RegistryException - Any valid registry API error.

setValue

public void setValue(java.lang.String valueName,
                     RegistryValue value)
              throws RegistryException

Set the name value to the given data.

Parameters:

valueName - The name of the value to set.

value - The data to set the named value.

Throws:

RegistryException - Any valid registry API error.

getValue

public RegistryValue getValue(java.lang.String valueName)
                       throws NoSuchValueException,
                              RegistryException

Get the data of a named value.

Parameters:

valueName - The name of the value to get.

Returns:

The data of the named value.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

getStringValue

public java.lang.String getStringValue(java.lang.String valueName)
                                throws NoSuchValueException,
                                       RegistryException

Get the value of a REG_SZ or REG_EXPAND_SZ value.

Parameters:

valueName - The name of the value to get.

Returns:

The string data of the named value.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

getDefaultValue

public java.lang.String getDefaultValue()
                                 throws NoSuchValueException,
                                        RegistryException

Get the data from the default value.

Returns:

The string data of the default value.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

hasDefaultValue

public boolean hasDefaultValue()
                        throws RegistryException

Determines if this key has a default value.

Returns:

True if there is a default value, else false.

Throws:

RegistryException - Any valid registry API error.

hasOnlyDefaultValue

public boolean hasOnlyDefaultValue()
                            throws RegistryException

Determines if this key has only a default value.

Returns:

True if there is only a default value, else false.

Throws:

RegistryException - Any valid registry API error.

getNumberSubkeys

public int getNumberSubkeys()
                     throws RegistryException

Obtains the number of subkeys that this key contains.

Returns:

The number of subkeys that this key contains.

Throws:

RegistryException - Any valid registry API error.

getMaxSubkeyLength

public int getMaxSubkeyLength()
                       throws RegistryException

Obtains the maximum length of all of the subkey names.

Returns:

The maximum length of all of the subkey names.

Throws:

RegistryException - Any valid registry API error.

regEnumKey

public java.lang.String regEnumKey(int index)
                            throws RegistryException

Obtains an enum_varerator for the subkeys of this key.

Returns:

The key enum_varerator.

Throws:

RegistryException - Any valid registry API error.

getNumberValues

public int getNumberValues()
                    throws RegistryException

Obtains the number of values that this key contains.

Returns:

The number of values that this key contains.

Throws:

RegistryException - Any valid registry API error.

getMaxValueDataLength

public int getMaxValueDataLength()
                          throws RegistryException

Obtains the maximum length of all of the value data.

Returns:

The maximum length of all of the value data.

Throws:

RegistryException - Any valid registry API error.

getMaxValueNameLength

public int getMaxValueNameLength()
                          throws RegistryException

Obtains the maximum length of all of the value names.

Returns:

The maximum length of all of the value names.

Throws:

RegistryException - Any valid registry API error.

regEnumValue

public java.lang.String regEnumValue(int index)
                              throws RegistryException

Obtains an enum_varerator for the values of this key.

Returns:

The value enum_varerator.

Throws:

RegistryException - Any valid registry API error.

incrDoubleWord

public int incrDoubleWord(java.lang.String valueName)
                   throws NoSuchValueException,
                          RegistryException

This method will increment the value of a REG_DWORD value.

Parameters:

valueName - The name of the value to increment.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

decrDoubleWord

public int decrDoubleWord(java.lang.String valueName)
                   throws NoSuchValueException,
                          RegistryException

This method will decrement the value of a REG_DWORD value.

Parameters:

valueName - The name of the value to increment.

Throws:

NoSuchValueException - If the value does not exist.

RegistryException - Any other registry API error.

expandEnvStrings

public static java.lang.String expandEnvStrings(java.lang.String exString)

This method will expand a string to include the definitions of System environment variables that are referenced via the %variable% construct. This method invokes EnvExpandStrings().

Parameters:

exString - The name of the value to increment.

keyElements

public java.util.Enumeration keyElements()
                                  throws RegistryException

Returns a new Enumeration that will enum_varerate the names of the subkeys of this key,

Returns:

A new Enumeration to enum_varerate subkey names.

Throws:

RegistryException - Any valid registry API error.

valueElements

public java.util.Enumeration valueElements()
                                    throws RegistryException

Returns a new Enumeration that will enum_varerate the names of the values of this key,

Returns:

A new Enumeration to enum_varerate value names.

Throws:

RegistryException - Any valid registry API error.

export

public void export(java.io.PrintWriter out,
                   boolean descend)
            throws NoSuchKeyException,
                   RegistryException

Export this key's definition to the provided PrintWriter. The resulting file can be imported via RegEdit.

Throws:

NoSuchKeyException - Thrown by openSubKey().

NoSuchValueException - Thrown by getValue().

RegistryException - Any other registry API error.