Class RegistryKey

java.lang.Object

com.github.robtimus.os.windows.registry.RegistryKey

All Implemented Interfaces:

Comparable<RegistryKey>

public abstract sealed class RegistryKey
extends Object
implements Comparable<RegistryKey>

A representation of registry keys.

Author:

Rob Spoor

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	RegistryKey.Attributes	Attributes associated with a registry key.
class	RegistryKey.Handle	A handle to a registry key.
static enum	RegistryKey.HandleOption	An enumeration over the possible options for opening Windows registry handles.
static enum	RegistryKey.TraverseOption	An enumeration over the possible options for traversing a registry key.

Method Summary

Modifier and Type	Method	Description
RegistryKey.Attributes	attributes()	Returns attributes for this registry key.
int	compareTo(RegistryKey key)
abstract void	create()	Creates this registry key if it does not exist already.
abstract boolean	createIfNotExists()	Creates this registry key if it does not exist already.
abstract void	delete()	Deletes this registry key and all of its values.
abstract boolean	deleteIfExists()	Deletes this registry key and all of its values if it exists.
void	deleteValue(String name)	Deletes a registry value.
boolean	deleteValueIfExists(String name)	Deletes a registry value if it exists.
abstract boolean	equals(Object o)
abstract boolean	exists()	Tests whether or not this registry key exists.
OptionalInt	findDWordValue(String name)	Tries to return a registry value as a DWORD.
OptionalLong	findQWordValue(String name)	Tries to return a registry value as a QWORD.
Optional<String>	findStringValue(String name)	Tries to return a registry value as a string.
<V extends RegistryValue> Optional<V>	findValue(String name, Class<V> valueType)	Tries to return a registry value.
int	getDWordValue(String name)	Returns a registry value as a DWORD.
long	getQWordValue(String name)	Returns a registry value as a QWORD.
String	getStringValue(String name)	Returns a registry value as a string.
<V extends RegistryValue> V	getValue(String name, Class<V> valueType)	Returns a registry value.
RegistryKey.Handle	handle()	Creates a handle to this registry key.
RegistryKey.Handle	handle(RegistryKey.HandleOption... options)	Creates a handle to this registry key.
abstract int	hashCode()
void	ifAccessible(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)	Runs an action on a RegistryKey.Handle if this registry key is accessible.
<R> Optional<R>	ifAccessible(Function<? super RegistryKey.Handle, ? extends R> action, RegistryKey.HandleOption... options)	Runs an action on a RegistryKey.Handle if this registry key is accessible.
void	ifExists(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)	Runs an action on a RegistryKey.Handle if this registry key exists.
<R> Optional<R>	ifExists(Function<? super RegistryKey.Handle, ? extends R> action, RegistryKey.HandleOption... options)	Runs an action on a RegistryKey.Handle if this registry key exists.
abstract boolean	isAccessible()	Tests whether or not this registry key is accessible.
abstract boolean	isRoot()	Returns whether or not this registry key is a root registry key.
Instant	lastWriteTime()	Returns the instant when this registry key was last written to.
abstract String	name()	Returns the name of the registry key.
abstract Optional<RegistryKey>	parent()	Returns the parent registry key.
abstract String	path()	Returns the full path to the registry key.
abstract RegistryKey	renameTo(String newName)	Renames this registry key.
abstract RegistryKey	resolve(String relativePath)	Returns a registry key relative to this registry key.
abstract RegistryKey	root()	Returns the root of the registry key.
void	setValue(SettableRegistryValue value)	Sets a registry value.
Stream<RegistryKey>	subKeys()	Returns all direct sub keys of this registry key.
String	toString()
Stream<RegistryKey>	traverse(int maxDepth, RegistryKey.TraverseOption... options)	Returns a Stream that traverses through this registry keys and all of its nested keys.
Stream<RegistryKey>	traverse(RegistryKey.TraverseOption... options)	Returns a Stream that traverses through this registry keys and all of its nested keys.
Stream<RegistryValue>	values()	Returns all values of this registry key.
Stream<RegistryValue>	values(RegistryValue.Filter filter)	Returns all values of this registry key.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

name

public abstract String name()

Returns the name of the registry key.

Returns:

The name of the registry key.

path

public abstract String path()

Returns the full path to the registry key.

Returns:

The full path to the registry key.

lastWriteTime

public Instant lastWriteTime()

Returns the instant when this registry key was last written to.

Returns:

The instant when this registry key was last written to.

Since:

1.1

attributes

public RegistryKey.Attributes attributes()

Returns attributes for this registry key.

Returns:

Attributes for this registry key.

Since:

1.1

isRoot

public abstract boolean isRoot()

Returns whether or not this registry key is a root registry key.

Returns:

true if this registry key is a root registry key, or false otherwise.

See Also:

• root()
• LocalRegistry.HKEY_CLASSES_ROOT
• LocalRegistry.HKEY_CURRENT_USER
• LocalRegistry.HKEY_LOCAL_MACHINE
• LocalRegistry.HKEY_USERS
• LocalRegistry.HKEY_CURRENT_CONFIG
• RemoteRegistry.HKEY_LOCAL_MACHINE
• RemoteRegistry.HKEY_USERS

root

public abstract RegistryKey root()

Returns the root of the registry key.

Returns:

The root of the registry key.

See Also:

• isRoot()
• LocalRegistry.HKEY_CLASSES_ROOT
• LocalRegistry.HKEY_CURRENT_USER
• LocalRegistry.HKEY_LOCAL_MACHINE
• LocalRegistry.HKEY_USERS
• LocalRegistry.HKEY_CURRENT_CONFIG
• RemoteRegistry.HKEY_LOCAL_MACHINE
• RemoteRegistry.HKEY_USERS

parent

public abstract Optional<RegistryKey> parent()

Returns the parent registry key.

Returns:

An Optional with the parent registry key, or Optional.empty() if this registry key is a root key.

resolve

public abstract RegistryKey resolve(String relativePath)

Returns a registry key relative to this registry key. If the relative path is empty or a single ., this registry key is returned.

Note that this method will never leave the root key.

Parameters:

relativePath - The path for the new registry key, relative to this registry key. Since registry keys can contain forward slashes, registry keys must be separated using backslashes (\).

Returns:

The resulting registry key.

Throws:

NullPointerException - If the given relative path is null.

subKeys

public Stream<RegistryKey> subKeys()

Returns all direct sub keys of this registry key. This stream should be closed afterwards.

Note that nothing can be said about the order of sub keys in the stream. It's also unspecified what happens if sub keys are removed while consuming the stream.

Returns:

A stream with all direct sub keys of this registry key.

Throws:

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the sub keys cannot be queried for another reason.

traverse

public Stream<RegistryKey> traverse(RegistryKey.TraverseOption... options)

Returns a Stream that traverses through this registry keys and all of its nested keys. This stream should be closed afterwards.

Note that nothing can be said about the order of registry keys in the stream. It's also unspecified what happens if registry keys are removed while consuming the stream.

Parameters:

options - The options to configure the traversal.

Returns:

A Stream that traverses through this registry keys and all of its nested keys

traverse

public Stream<RegistryKey> traverse(int maxDepth,
 RegistryKey.TraverseOption... options)

Returns a Stream that traverses through this registry keys and all of its nested keys. This stream should be closed afterwards.

Note that nothing can be said about the order of registry keys in the stream. It's also unspecified what happens if registry keys are removed while consuming the stream.

Parameters:

maxDepth - The maximum number of registry key levels to visit. A value of 0 indicates that only this registry key should be returned; a value of 1 indicates that only this registry key and its direct sub keys should be returned.

options - The options to configure the traversal.

Returns:

A Stream that traverses through this registry keys and all of its nested keys

Throws:

IllegalArgumentException - If the given maximum depth is negative.

values

public Stream<RegistryValue> values()

Returns all values of this registry key. This stream should be closed afterwards.

Note that nothing can be said about the order of values in the stream. It's also unspecified what happens if values are removed while consuming the stream.

Returns:

A stream with all values of this registry key.

Throws:

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the values cannot be queried for another reason.

values

public Stream<RegistryValue> values(RegistryValue.Filter filter)

Returns all values of this registry key. This stream should be closed afterwards.

While filtering can be done on a stream returned by values(), this method allows limited filtering before any objects are even created for registry values. This offers a small performance gain.

Note that nothing can be said about the order of values in the stream. It's also unspecified what happens if values are removed while consuming the stream.

Parameters:

filter - A filter that can be used to limit which registry values are returned.

Returns:

A stream with all values of this registry key.

Throws:

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the values cannot be queried for another reason.

getValue

public <V extends RegistryValue> V getValue(String name,
 Class<V> valueType)

Returns a registry value.

Type Parameters:

V - The type of registry value to return.

Parameters:

name - The name of the registry value to return.

valueType - The type of registry value to return.

Returns:

The registry value with the given name.

Throws:

NullPointerException - If the given name or value type is null.

NoSuchRegistryKeyException - If this registry key does not exist.

NoSuchRegistryValueException - If there is no such registry value.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name cannot be cast to the given value type.

findValue

public <V extends RegistryValue> Optional<V> findValue(String name,
 Class<V> valueType)

Tries to return a registry value.

Type Parameters:

V - The type of registry value to return.

Parameters:

name - The name of the registry value to return.

valueType - The type of registry value to return.

Returns:

An Optional with the registry value with the given name, or Optional.empty() if there is no such registry value.

Throws:

NullPointerException - If the given name or value type is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name cannot be cast to the given value type.

getStringValue

public String getStringValue(String name)

Returns a registry value as a string. This method is shorthand for calling getValue(name, StringValue.class).value().

Parameters:

name - The name of the registry value to return.

Returns:

The registry value with the given name as a string.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

NoSuchRegistryValueException - If there is no such registry value.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a string.

See Also:

• getValue(String, Class)
• StringValue.value()

findStringValue

public Optional<String> findStringValue(String name)

Tries to return a registry value as a string. This method is shorthand for calling getValue(name, StringValue.class).map(StringValue::value).

Parameters:

name - The name of the registry value to return.

Returns:

An Optional with the registry value with the given name as a string, or Optional.empty() if there is no such registry value.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a string.

See Also:

• findValue(String, Class)
• StringValue.value()

getDWordValue

public int getDWordValue(String name)

Returns a registry value as a DWORD. This method is shorthand for calling getValue(name, DWordValue.class).value().

Parameters:

name - The name of the registry value to return.

Returns:

The registry value with the given name as a DWORD.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

NoSuchRegistryValueException - If there is no such registry value.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a DWORD.

See Also:

• getValue(String, Class)
• DWordValue.value()

findDWordValue

public OptionalInt findDWordValue(String name)

Tries to return a registry value as a DWORD. This method is shorthand for calling findValue(name, DWordValue.class).mapToInt(DWordValue::value), if Optional had a method mapToInt.

Parameters:

name - The name of the registry value to return.

Returns:

An Optional with the registry value with the given name as a DWORD, or Optional.empty() if there is no such registry value.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a DWORD.

See Also:

• findValue(String, Class)
• DWordValue.value()

getQWordValue

public long getQWordValue(String name)

Returns a registry value as a QWORD. This method is shorthand for calling getValue(name, QWordValue.class).value().

Parameters:

name - The name of the registry value to return.

Returns:

The registry value with the given name as a QWORD.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

NoSuchRegistryValueException - If there is no such registry value.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a QWORD.

See Also:

• getValue(String, Class)
• QWordValue.value()

findQWordValue

public OptionalLong findQWordValue(String name)

Tries to return a registry value as a QWORD. This method is shorthand for calling findValue(name, QWordValue.class).mapToLong(QWordValue::value), if Optional had a method mapToLong.

Parameters:

name - The name of the registry value to return.

Returns:

An Optional with the registry value with the given name as a QWORD, or Optional.empty() if there is no such registry value.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be returned for another reason.

ClassCastException - If the registry value with the given name is not a QWORD.

See Also:

• findValue(String, Class)
• QWordValue.value()

setValue

public void setValue(SettableRegistryValue value)

Sets a registry value.

Parameters:

value - The registry value to set.

Throws:

NullPointerException - If the given registry value is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be set for another reason.

deleteValue

public void deleteValue(String name)

Deletes a registry value.

Parameters:

name - The name of the registry value to exist.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

NoSuchRegistryValueException - If the registry value does not exist.

RegistryException - If the value cannot be deleted for another reason.

deleteValueIfExists

public boolean deleteValueIfExists(String name)

Deletes a registry value if it exists.

Parameters:

name - The name of the registry value to exist.

Returns:

true if the registry value existed and was deleted, or false if it didn't exist.

Throws:

NullPointerException - If the given name is null.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the value cannot be deleted for another reason.

exists

public abstract boolean exists()

Tests whether or not this registry key exists.

Returns:

true if this registry key exists, or false otherwise.

Throws:

RegistryException - If the existence of this registry cannot be determined.

ifExists

public void ifExists(Consumer<? super RegistryKey.Handle> action,
 RegistryKey.HandleOption... options)

Runs an action on a RegistryKey.Handle if this registry key exists. The handle will be open only during the execution of the action.

Parameters:

action - The action to run.

options - The options that define how the handle is created. If RegistryKey.HandleOption.CREATE is given it will be ignored.

Throws:

NullPointerException - If the given action is null.

Since:

1.1

See Also:

• exists()
• handle(HandleOption...)

ifExists

public <R> Optional<R> ifExists(Function<? super RegistryKey.Handle, ? extends R> action,
 RegistryKey.HandleOption... options)

Runs an action on a RegistryKey.Handle if this registry key exists. The handle will be open only during the execution of the action.

Type Parameters:

R - The type of result of the action.

Parameters:

action - The action to run.

options - The options that define how the handle is created. If RegistryKey.HandleOption.CREATE is given it will be ignored.

Returns:

An Optional with the return of calling the action on the handle, or Optional.empty() if this registry key does not exist.

Throws:

NullPointerException - If the given action is null.

Since:

1.1

See Also:

• exists()
• handle(HandleOption...)

isAccessible

public abstract boolean isAccessible()

Tests whether or not this registry key is accessible. Accessible means that accessing it will not throw a RegistryAccessDeniedException.

The following are the relations between this method and exists():

• If isAccessible() returns true then exists() will return true.
• If exists() returns false then isAccessible() will return false.
• If isAccessible() returns false then exists() will not necessarily return false; existing keys may not be accessible.
• If exists() returns true then isAccessible() will not necessarily return true; existing keys may not be accessible.

Returns:

true if this registry key is accessible, or false otherwise.

Throws:

RegistryException - If the accessibility of this registry cannot be determined.

Since:

1.1

ifAccessible

public void ifAccessible(Consumer<? super RegistryKey.Handle> action,
 RegistryKey.HandleOption... options)

Runs an action on a RegistryKey.Handle if this registry key is accessible. The handle will be open only during the execution of the action.

Parameters:

action - The action to run.

options - The options that define how the handle is created. If RegistryKey.HandleOption.CREATE is given it will be ignored.

Throws:

NullPointerException - If the given action is null.

Since:

1.1

See Also:

• isAccessible()
• handle(HandleOption...)

ifAccessible

public <R> Optional<R> ifAccessible(Function<? super RegistryKey.Handle, ? extends R> action,
 RegistryKey.HandleOption... options)

Runs an action on a RegistryKey.Handle if this registry key is accessible. The handle will be open only during the execution of the action.

Type Parameters:

R - The type of result of the action.

Parameters:

action - The action to run.

options - The options that define how the handle is created. If RegistryKey.HandleOption.CREATE is given it will be ignored.

Returns:

An Optional with the return of calling the action on the handle, or Optional.empty() if this registry key is not accessible.

Throws:

NullPointerException - If the given action is null.

Since:

1.1

See Also:

• isAccessible()
• handle(HandleOption...)

create

public abstract void create()

Creates this registry key if it does not exist already.

Throws:

RegistryKeyAlreadyExistsException - If this registry key already exists.

RegistryException - If this registry key cannot be created for another reason.

createIfNotExists

public abstract boolean createIfNotExists()

Creates this registry key if it does not exist already. It will also create any missing parent registry keys that are missing.

Returns:

true if the registry key was created, or false if it already existed.

Throws:

RegistryException - If this registry key cannot be created.

renameTo

public abstract RegistryKey renameTo(String newName)

Renames this registry key.

Note: this method requires Windows Vista or later, or Windows Server 2008 or later.

Parameters:

newName - The new registry key name.

Returns:

A new registry key object representing the renamed registry key.

Throws:

UnsupportedOperationException - If trying to rename one of the root keys, or if the current Windows version does not support renaming registry keys.

NullPointerException - If the given name is null.

IllegalArgumentException - If the given name contains a backslash (\).

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryKeyAlreadyExistsException - If this registry key's parent key already contains a sub key with the given name.

RegistryException - If this registry key could not be renamed for another reason.

See Also:

• RegistryFeature.RENAME_KEY

delete

public abstract void delete()

Deletes this registry key and all of its values.

Throws:

UnsupportedOperationException - If trying to delete one of the root keys.

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the registry key cannot be deleted for another reason.

deleteIfExists

public abstract boolean deleteIfExists()

Deletes this registry key and all of its values if it exists.

Returns:

true if this registry key existed and has been removed, or false if it didn't exist.

Throws:

UnsupportedOperationException - If trying to delete one of the root keys.

RegistryException - If the registry key cannot be deleted for another reason.

handle

public RegistryKey.Handle handle()

Creates a handle to this registry key. This allows multiple operations on this registry key to be performed without creating a new link to the Windows registry for each operation. The returned handle should be closed when it is no longer needed.

This method will be like calling handle(HandleOption...) without any options. As a result, it will not be possible to set or delete registry values using the returned handle.

Returns:

The created handle.

Throws:

NoSuchRegistryKeyException - If this registry key does not exist.

RegistryException - If the handle could not be created for another reason.

handle

public RegistryKey.Handle handle(RegistryKey.HandleOption... options)

Creates a handle to this registry key. This allows multiple operations on this registry key to be performed without creating a new link to the Windows registry for each operation. The returned handle should be closed when it is no longer needed.

Parameters:

options - The options that define how the handle is created.

Returns:

The created handle.

Throws:

NoSuchRegistryKeyException - If this registry key does not exist, and RegistryKey.HandleOption.CREATE is not one of the given options.

RegistryException - If the handle could not be created for another reason.

compareTo

public int compareTo(RegistryKey key)

Specified by:

compareTo in interface Comparable<RegistryKey>

equals

public abstract boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public abstract int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object