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 classRegistryKey.AttributesAttributes associated with a registry key.classRegistryKey.HandleA handle to a registry key.static classRegistryKey.HandleOptionAn enumeration over the possible options for opening Windows registry handles.static classRegistryKey.TraverseOptionAn enumeration over the possible options for traversing a registry key.
-
Field Summary
Fields Modifier and Type Field Description static RegistryKeyHKEY_CLASSES_ROOTThe HKEY_CLASSES_ROOT root key.static RegistryKeyHKEY_CURRENT_CONFIGThe HKEY_CURRENT_CONFIG root key.static RegistryKeyHKEY_CURRENT_USERThe HKEY_CURRENT_USER root key.static RegistryKeyHKEY_LOCAL_MACHINEThe HKEY_LOCAL_MACHINE root key.static RegistryKeyHKEY_USERSThe HKEY_USERS root key.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description RegistryKey.Attributesattributes()Returns attributes for this registry key.intcompareTo(RegistryKey key)abstract voidcreate()Creates this registry key if it does not exist already.abstract booleancreateIfNotExists()Creates this registry key if it does not exist already.abstract voiddelete()Deletes this registry key and all of its values.abstract booleandeleteIfExists()Deletes this registry key and all of its values if it exists.voiddeleteValue(String name)Deletes a registry value.booleandeleteValueIfExists(String name)Deletes a registry value if it exists.abstract booleanequals(Object o)abstract booleanexists()Tests whether or not this registry key exists.OptionalIntfindDWordValue(String name)Tries to return a registry value as a DWORD.OptionalLongfindQWordValue(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.intgetDWordValue(String name)Returns a registry value as a DWORD.longgetQWordValue(String name)Returns a registry value as a QWORD.StringgetStringValue(String name)Returns a registry value as a string.<V extends RegistryValue>
VgetValue(String name, Class<V> valueType)Returns a registry value.RegistryKey.Handlehandle()Creates a handle to this registry key.RegistryKey.Handlehandle(RegistryKey.HandleOption... options)Creates a handle to this registry key.abstract inthashCode()voidifAccessible(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)Runs an action on aRegistryKey.Handleif this registry key is accessible.<R> Optional<R>ifAccessible(Function<? super RegistryKey.Handle,? extends R> action, RegistryKey.HandleOption... options)Runs an action on aRegistryKey.Handleif this registry key is accessible.voidifExists(Consumer<? super RegistryKey.Handle> action, RegistryKey.HandleOption... options)Runs an action on aRegistryKey.Handleif this registry key exists.<R> Optional<R>ifExists(Function<? super RegistryKey.Handle,? extends R> action, RegistryKey.HandleOption... options)Runs an action on aRegistryKey.Handleif this registry key exists.abstract booleanisAccessible()Tests whether or not this registry key is accessible.abstract booleanisRoot()Returns whether or not this registry key is a root registry key.InstantlastWriteTime()Returns the instant when this registry key was last written to.abstract Stringname()Returns the name of the registry key.abstract Optional<RegistryKey>parent()Returns the parent registry key.abstract Stringpath()Returns the full path to the registry key.abstract RegistryKeyrenameTo(String newName)Renames this registry key.abstract RegistryKeyresolve(String relativePath)Returns a registry key relative to this registry key.abstract RegistryKeyroot()Returns the root of the registry key.voidsetValue(SettableRegistryValue value)Sets a registry value.Stream<RegistryKey>subKeys()Returns all direct sub keys of this registry key.StringtoString()Stream<RegistryKey>traverse(int maxDepth, RegistryKey.TraverseOption... options)Returns aStreamthat traverses through this registry keys and all of its nested keys.Stream<RegistryKey>traverse(RegistryKey.TraverseOption... options)Returns aStreamthat 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:
trueif this registry key is a root registry key, orfalseotherwise.- 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
Optionalwith 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 aStreamthat 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
Streamthat traverses through this registry keys and all of its nested keys
-
traverse
public Stream<RegistryKey> traverse(int maxDepth, RegistryKey.TraverseOption... options)
Returns aStreamthat 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 keysshould be returned.options- The options to configure the traversal.- Returns:
- A
Streamthat 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
Optionalwith 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
Optionalwith 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), ifOptionalhad a methodmapToInt.- Parameters:
name- The name of the registry value to return.- Returns:
- An
Optionalwith 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), ifOptionalhad a methodmapToLong.- Parameters:
name- The name of the registry value to return.- Returns:
- An
Optionalwith 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:
trueif the registry value existed and was deleted, orfalseif 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:
trueif this registry key exists, orfalseotherwise.- 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.Handleif 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.CREATEis 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.Handleif 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.CREATEis given it will be ignored.- Returns:
- An
Optionalwith 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()returnstruethenexists()will returntrue. - If
exists()returnsfalsethenisAccessible()will returnfalse. - If
isAccessible()returnsfalsethenexists()will not necessarily returnfalse; existing keys may not be accessible. - If
exists()returnstruethenisAccessible()will not necessarily returntrue; existing keys may not be accessible.
- Returns:
trueif this registry key is accessible, orfalseotherwise.- 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.Handleif 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.CREATEis 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.Handleif 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.CREATEis given it will be ignored.- Returns:
- An
Optionalwith 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:
trueif the registry key was created, orfalseif 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:
trueif this registry key existed and has been removed, orfalseif 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.CREATEis 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:
compareToin interfaceComparable<RegistryKey>
-
-