Module com.github.robtimus.os.windows.registry

Package com.github.robtimus.os.windows.registry

Class RegistryKey.Handle

java.lang.Object

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

All Implemented Interfaces:

AutoCloseable

Enclosing class:

RegistryKey

public abstract class RegistryKey.Handle
extends Object
implements AutoCloseable

A handle to a registry key. This offers mostly the same functionality as RegistryKey itself. However, it reuses the same link to the Windows registry instead of creating a new one every time. That makes it more efficient if multiple operations on the same registry key are needed. Handle instances should be closed when they are no longer needed to release the link to the Windows registry.

Note that the way the handle is created may limit the available operations. For instance, if RegistryKey.HandleOption.MANAGE_VALUES isn't given, trying to set or delete registry values will lead to RegistryAccessDeniedExceptions.

Author:

Rob Spoor

Method Summary

Modifier and Type	Method	Description
RegistryKey.Attributes	attributes()	Returns attributes for the registry key from which this handle was retrieved.
abstract void	close()	Closes this registry handle.
void	deleteValue(String name)	Deletes a registry value.
boolean	deleteValueIfExists(String name)	Deletes a registry value if it 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.
Instant	lastWriteTime()	Returns the instant when the registry key from which this handle was retrieved was last written to.
void	setValue(SettableRegistryValue value)	Sets a registry value.
Stream<RegistryKey>	subKeys()	Returns all direct sub keys of the registry key from which this handle was retrieved.
Stream<RegistryValue>	values()	Returns all values of the registry key from which this handle was retrieved.
Stream<RegistryValue>	values(RegistryValue.Filter filter)	Returns all values of the registry key from which this handle was retrieved.

Methods inherited from class java.lang.Object

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

Method Detail

lastWriteTime

public Instant lastWriteTime()

Returns the instant when the registry key from which this handle was retrieved was last written to.

Returns:

The instant when the registry key from which this handle was retrieved was last written to.

Since:

1.1

attributes

public RegistryKey.Attributes attributes()

Returns attributes for the registry key from which this handle was retrieved.

Returns:

Attributes for the registry key from which this handle was retrieved.

Since:

1.1

subKeys

public Stream<RegistryKey> subKeys()

Returns all direct sub keys of the registry key from which this handle was retrieved. This stream is valid until this handle is closed, and does not need to 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 the registry key from which this handle was retrieved.

Throws:

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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

values

public Stream<RegistryValue> values()

Returns all values of the registry key from which this handle was retrieved. This stream is valid until this handle is closed, and does not need to 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 the registry key from which this handle was retrieved.

Throws:

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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

values

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

Returns all values of the registry key from which this handle was retrieved. This stream is valid until this handle is closed, and does not need to 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 the registry key from which this handle was retrieved.

Throws:

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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.

InvalidRegistryHandleException - If this handle is no longer valid.

NoSuchRegistryKeyException - If the registry key from which this handle was retrieved no longer exists.

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

close

public abstract void close()

Closes this registry handle.

Specified by:

close in interface AutoCloseable

Throws:

RegistryException - If the registry handle could not be closed.