Elektra 0.11.0
org.libelektra.KDB Class Reference

Represents a session with the Elektra key database. More...

Public Member Functions

void close () throws KDBException
 Closes the KDB session and frees native resources associated with it.
 
void close (Key warningsKey) throws KDBException
 Closes the KDB session and frees native resources associated with it.
 
KeySet get (Key parentKey) throws KDBException
 Fetches at least all keys that are sub-keys or children of sub-keys of the supplied parent key.
 
KDB get (KeySet keySet, Key parentKey) throws KDBException
 Fetches at least all keys that are sub-keys or children of sub-keys of the supplied parent key.
 
KDB set (KeySet keySet, Key parentKey) throws KDBException
 Will update changed keys of the given keySet in the backend.
 

Static Public Member Functions

static KDB open () throws KDBException
 Opens a new KDB session.
 
static KDB open (KeySet contract) throws KDBException
 Opens KDB session using the specified contract @endiliteral.

 
static KDB open (Key warningsKey) throws KDBException
 Opens a new KDB session.
 
static KDB open (KeySet contract, Key warningsKey) throws KDBException
 Opens KDB session using the specified contract @endiliteral.

 
static KeySet goptsContract (String[] args, String[] env, Key parentKey, KeySet goptsConfig)
 Creates a contract KeySet for use with KDB#open(KeySet) that mounts and configures the gopts plugin.
 
static void goptsContract (KeySet contract, String[] args, String[] env, Key parentKey, KeySet goptsConfig)
 Writes a contract into a specified KeySet for use with KDB#open(KeySet) that mounts and configures the gopts plugin.
 

Protected Member Functions

Pointer getPointer ()
 

Detailed Description

Represents a session with the Elektra key database.

@apiNote Close after usage, or simply use a try-with-resources statement

Member Function Documentation

◆ close() [1/2]

void org.libelektra.KDB.close ( ) throws KDBException
inline

Closes the KDB session and frees native resources associated with it.

Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException
KDBClosedExceptionif this session has already been closed

◆ close() [2/2]

void org.libelektra.KDB.close ( Key warningsKey) throws KDBException
inline

Closes the KDB session and frees native resources associated with it.

Parameters
warningsKeyUsed to store warnings, which may occur during closing the session, in this key's meta data
Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException
KDBClosedExceptionif this session has already been closed
IllegalStateExceptionif parentKey has already been released
IllegalArgumentExceptionif warningsKey is null
See also
Key.create()

◆ get() [1/2]

KeySet org.libelektra.KDB.get ( Key parentKey) throws KDBException
inline

Fetches at least all keys that are sub-keys or children of sub-keys of the supplied parent key.

Note: Resulting key set may contain more keys than requested

Parameters
parentKeyRoot key which name is used to fetch keys below. This key is also used to store warnings, which may occur during the operation, in this key's meta data.
Returns
New KeySet containing the fetched keys
Exceptions
KDBExceptionif loading keys fails - see specialization of KDBException
KDBClosedExceptionif this session has already been closed
IllegalStateExceptionif parentKey has already been released
IllegalArgumentExceptionparentKey is null

◆ get() [2/2]

KDB org.libelektra.KDB.get ( KeySet keySet,
Key parentKey ) throws KDBException
inline

Fetches at least all keys that are sub-keys or children of sub-keys of the supplied parent key.

Note: Resulting key set may contain more keys than requested

Parameters
keySetKeySet used to store the fetched keys
parentKeyRoot key which name is used to fetch keys below it. This key is also used to store warnings, which may occur during the operation, in this key's meta data. It is recommended to use the most specific parentKey possible. (e.g. using
system:/
is rarely the most specific)
Returns
This KDB session, enabling a fluent interface
Exceptions
KDBExceptionif loading keys fails - see specialization of KDBException
KDBClosedExceptionif this session has already been closed
IllegalStateExceptionif keySet or parentKey has already been released
IllegalArgumentExceptionif keySet or parentKey is null
See also
get(Key)

◆ getPointer()

Pointer org.libelektra.KDB.getPointer ( )
inlineprotected
Returns
JNA pointer to the native pointer for this key set
Exceptions
KDBClosedExceptionif this KDB session has already been closed

◆ goptsContract() [1/2]

static void org.libelektra.KDB.goptsContract ( KeySet contract,
String[] args,
String[] env,
Key parentKey,
KeySet goptsConfig )
inlinestatic

Writes a contract into a specified KeySet for use with KDB#open(KeySet) that mounts and configures the gopts plugin.

Parameters
contractKey set to write the contract to
argsArguments that will be converted into argc and argv for
gopts
envEnvironment variables that gopts will use
parentKeyParent key that should be used by gopts. Only the key name is copied. The key can be deleted immediately after calling this function.
goptsConfigConfig used for mounting the gopts plugin
Exceptions
IllegalArgumentExceptionif any of the arguments are null
IllegalStateExceptionif contract, goptsConfig or parentKey has already been released
IllegalArgumentExceptionif any of the specified parameters is null

◆ goptsContract() [2/2]

static KeySet org.libelektra.KDB.goptsContract ( String[] args,
String[] env,
Key parentKey,
KeySet goptsConfig )
inlinestatic

Creates a contract KeySet for use with KDB#open(KeySet) that mounts and configures the gopts plugin.

Parameters
argsArguments that will be converted into argc and argv for
gopts
envEnvironment variables that gopts will use
parentKeyParent key that should be used by gopts. Only the key name is copied. The key can be deleted immediately after calling this function.
goptsConfigConfig used for mounting the gopts plugin
Returns
New KeySet containing the contract
Exceptions
IllegalArgumentExceptionif any of the arguments are null
IllegalStateExceptionif goptsConfig or parentKey has already been released
IllegalArgumentExceptionif any of the specified parameters is null

◆ open() [1/4]

static KDB org.libelektra.KDB.open ( ) throws KDBException
inlinestatic

Opens a new KDB session.

Returns
New KDB session
Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException

◆ open() [2/4]

static KDB org.libelektra.KDB.open ( Key warningsKey) throws KDBException
inlinestatic

Opens a new KDB session.

Parameters
warningsKeyUsed to store warnings, which may occur during opening the session, in this key's meta data
Returns
New KDB session
Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException
IllegalStateExceptionif warningsKey has already been released
IllegalArgumentExceptionif warningsKey is null
See also
Key.create()

◆ open() [3/4]

static KDB org.libelektra.KDB.open ( KeySet contract) throws KDBException
inlinestatic

Opens KDB session using the specified contract @endiliteral.

Parameters
contractContract configuring the gopts plugin
Returns
New KDB session
Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException
IllegalStateExceptionif contract has already been released
IllegalArgumentExceptionif contract is null
See also
goptsContract(String[], String[], Key, KeySet)
goptsContract(KeySet, String[], String[], Key, KeySet)

◆ open() [4/4]

static KDB org.libelektra.KDB.open ( KeySet contract,
Key warningsKey ) throws KDBException
inlinestatic

Opens KDB session using the specified contract @endiliteral.

Parameters
contractContract configuring the gopts plugin
warningsKeyUsed to store warnings, which may occur during opening the session, in this key's meta data
Returns
New KDB session
Exceptions
KDBExceptionif opening the session fails - see specialization of KDBException
IllegalStateExceptionif contract or warningsKey has already been released
IllegalArgumentExceptionif contract or warningsKey is null
See also
goptsContract(String[], String[], Key, KeySet)
goptsContract(KeySet, String[], String[], Key, KeySet)

◆ set()

KDB org.libelektra.KDB.set ( KeySet keySet,
Key parentKey ) throws KDBException
inline

Will update changed keys of the given keySet in the backend.

get(Key) or get(KeySet, Key) has to be called before this function may be executed.

Parameters
keySetKeySet which contains keys to be updated in the backend
parentKeySpecify which part of the given keySet is of interest for you. This key is also used to store warnings, which may occur during the operation, in this key's meta data. In general it is highly recommended, that you use the same parentKey used to fetch the keySet with get(Key) or get(KeySet, Key). You promise to only modify or remove keys below this key. All others would be passed back as they were retrieved by keySet with get(Key). Cascading keys (starting with /) will set the path in all namespaces. A nameless key as created by Key#create() will commit all changes in the keySet. This parameter is an optimization to only save keys of mountpoints affected by the specified parentKey. This does not necessarily mean that only changes to keys below that parentKey are saved.
Returns
This KDB session, enabling a fluent interface
Exceptions
KDBExceptionif storing keys fails - see specialization of KDBException
KDBClosedExceptionif this session has already been closed
IllegalStateExceptionif keySet or parentKey has already been released
IllegalArgumentExceptionif keySet or parentKey is null

The documentation for this class was generated from the following file: