Class RegistryKey
- java.lang.Object
-
- com.github.robtimus.os.windows.registry.RegistryKey
-
- All Implemented Interfaces:
Comparable<RegistryKey>
- Direct Known Subclasses:
RemoteRegistryKey
public abstract 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 class
RegistryKey.Attributes
Attributes associated with a registry key.class
RegistryKey.Handle
A handle to a registry key.static class
RegistryKey.HandleOption
An enumeration over the possible options for opening Windows registry handles.static class
RegistryKey.TraverseOption
An enumeration over the possible options for traversing a registry key.
-
Field Summary
Fields Modifier and Type Field Description static RegistryKey
HKEY_CLASSES_ROOT
The HKEY_CLASSES_ROOT root key.static RegistryKey
HKEY_CURRENT_CONFIG
The HKEY_CURRENT_CONFIG root key.static RegistryKey
HKEY_CURRENT_USER
The HKEY_CURRENT_USER root key.static RegistryKey
HKEY_LOCAL_MACHINE
The HKEY_LOCAL_MACHINE root key.static RegistryKey
HKEY_USERS
The HKEY_USERS root key.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods 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>
VgetValue(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 aRegistryKey.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 aRegistryKey.Handle
if this registry key is accessible.void
ifExists(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)
Runs an action on aRegistryKey.Handle
if this registry key exists.<R> Optional<R>
ifExists(Function<? super RegistryKey.Handle,? extends R> action, RegistryKey.HandleOption... options)
Runs an action on aRegistryKey.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 aStream
that traverses through this registry keys and all of its nested keys.Stream<RegistryKey>
traverse(RegistryKey.TraverseOption... options)
Returns aStream
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.
-
-
-
Field Detail
-
HKEY_CLASSES_ROOT
public static final RegistryKey HKEY_CLASSES_ROOT
The HKEY_CLASSES_ROOT root key.
-
HKEY_CURRENT_USER
public static final RegistryKey HKEY_CURRENT_USER
The HKEY_CURRENT_USER root key.
-
HKEY_LOCAL_MACHINE
public static final RegistryKey HKEY_LOCAL_MACHINE
The HKEY_LOCAL_MACHINE root key.
-
HKEY_USERS
public static final RegistryKey HKEY_USERS
The HKEY_USERS root key.
-
HKEY_CURRENT_CONFIG
public static final RegistryKey HKEY_CURRENT_CONFIG
The HKEY_CURRENT_CONFIG root key.
-
-
Method Detail
-
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, orfalse
otherwise.- See Also:
root()
,HKEY_CLASSES_ROOT
,HKEY_CURRENT_USER
,HKEY_LOCAL_MACHINE
,HKEY_USERS
,HKEY_CURRENT_CONFIG
-
root
public abstract RegistryKey root()
Returns the root of the registry key.- Returns:
- The root of the registry key.
- See Also:
isRoot()
,HKEY_CLASSES_ROOT
,HKEY_CURRENT_USER
,HKEY_LOCAL_MACHINE
,HKEY_USERS
,HKEY_CURRENT_CONFIG
-
parent
public abstract Optional<RegistryKey> parent()
Returns the parent registry key.- Returns:
- An
Optional
with the parent registry key, orOptional.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 isnull
.
-
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 notexist
.RegistryException
- If the sub keys cannot be queried for another reason.
-
traverse
public Stream<RegistryKey> traverse(RegistryKey.TraverseOption... options)
Returns aStream
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 aStream
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 directsub 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 notexist
.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 notexist
.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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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, orOptional.empty()
if there is no such registry value. - Throws:
NullPointerException
- If the given name or value type isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callinggetValue(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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callinggetValue(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, orOptional.empty()
if there is no such registry value. - Throws:
NullPointerException
- If the given name isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callinggetValue(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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callingfindValue(name, DWordValue.class).mapToInt(DWordValue::value)
, ifOptional
had a methodmapToInt
.- Parameters:
name
- The name of the registry value to return.- Returns:
- An
Optional
with the registry value with the given name as a DWORD, orOptional.empty()
if there is no such registry value. - Throws:
NullPointerException
- If the given name isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callinggetValue(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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 callingfindValue(name, QWordValue.class).mapToLong(QWordValue::value)
, ifOptional
had a methodmapToLong
.- Parameters:
name
- The name of the registry value to return.- Returns:
- An
Optional
with the registry value with the given name as a QWORD, orOptional.empty()
if there is no such registry value. - Throws:
NullPointerException
- If the given name isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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 isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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, orfalse
if it didn't exist.- Throws:
NullPointerException
- If the given name isnull
.NoSuchRegistryKeyException
- If this registry key does notexist
.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, orfalse
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 aRegistryKey.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. IfRegistryKey.HandleOption.CREATE
is given it will be ignored.- Throws:
NullPointerException
- If the given action isnull
.- 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 aRegistryKey.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. IfRegistryKey.HandleOption.CREATE
is given it will be ignored.- Returns:
- An
Optional
with the return of calling the action on the handle, orOptional.empty()
if this registry key does not exist. - Throws:
NullPointerException
- If the given action isnull
.- 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 aRegistryAccessDeniedException
.The following are the relations between this method and
exists()
:- If
isAccessible()
returnstrue
thenexists()
will returntrue
. - If
exists()
returnsfalse
thenisAccessible()
will returnfalse
. - If
isAccessible()
returnsfalse
thenexists()
will not necessarily returnfalse
; existing keys may not be accessible. - If
exists()
returnstrue
thenisAccessible()
will not necessarily returntrue
; existing keys may not be accessible.
- Returns:
true
if this registry key is accessible, orfalse
otherwise.- Throws:
RegistryException
- If the accessibility of this registry cannot be determined.- Since:
- 1.1
- If
-
ifAccessible
public void ifAccessible(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)
Runs an action on aRegistryKey.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. IfRegistryKey.HandleOption.CREATE
is given it will be ignored.- Throws:
NullPointerException
- If the given action isnull
.- 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 aRegistryKey.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. IfRegistryKey.HandleOption.CREATE
is given it will be ignored.- Returns:
- An
Optional
with the return of calling the action on the handle, orOptional.empty()
if this registry key is not accessible. - Throws:
NullPointerException
- If the given action isnull
.- 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 alreadyexists
.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, orfalse
if it alreadyexisted
.- 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 isnull
.IllegalArgumentException
- If the given name contains a backslash (\
).NoSuchRegistryKeyException
- If this registry key does notexist
.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.
-
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 notexist
.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, orfalse
if it didn'texist
.- 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 notexist
.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 notexist
, andRegistryKey.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 interfaceComparable<RegistryKey>
-
-