| Elektra 0.11.0

Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
org.libelektra.KDB Class Reference

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

Inherits AutoCloseable.

## 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

  KDBException | if opening the session fails - see specialization of `KDBException`
  KDBClosedException | if 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

  warningsKey | Used to store warnings, which may occur during closing the session, in this key's meta data

Exceptions

  KDBException | if opening the session fails - see specialization of `KDBException`
  KDBClosedException | if this session has already been closed
  IllegalStateException | if `parentKey` has already been released
  IllegalArgumentException | if `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

  parentKey | Root 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

  KDBException | if loading keys fails - see specialization of `KDBException`
  KDBClosedException | if this session has already been closed
  IllegalStateException | if `parentKey` has already been released
  IllegalArgumentException | `parentKey` 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

  keySet | `KeySet` used to store the fetched keys
  parentKey | Root 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

  KDBException | if loading keys fails - see specialization of `KDBException`
  KDBClosedException | if this session has already been closed
  IllegalStateException | if `keySet` or `parentKey` has already been released
  IllegalArgumentException | if `keySet` or `parentKey` is `null`

See also
  #get(Key)

## ◆ getPointer()

Pointer org.libelektra.KDB.getPointer | ( |  | ) |
| inline protected

Returns
  JNA pointer to the native pointer for this key set

Exceptions

  KDBClosedException | if 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
| ) |  |
| inline static

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

Parameters

  contract | Key set to write the contract to
  args | Arguments that will be converted into `argc` and `argv` for `gopts`
  env | Environment variables that `gopts` will use
  parentKey | Parent key that should be used by `gopts`. Only the key name is copied. The key can be deleted immediately after calling this function.
  goptsConfig | Config used for mounting the `gopts` plugin

Exceptions

  IllegalArgumentException | if any of the arguments are `null`
  IllegalStateException | if `contract`, `goptsConfig` or `parentKey` has already been released
  IllegalArgumentException | if any of the specified parameters is `null`

## ◆ goptsContract() [2/2]

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

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

Parameters

  args | Arguments that will be converted into `argc` and `argv` for `gopts`
  env | Environment variables that `gopts` will use
  parentKey | Parent key that should be used by `gopts`. Only the key name is copied. The key can be deleted immediately after calling this function.
  goptsConfig | Config used for mounting the `gopts` plugin

Returns
  New `KeySet` containing the contract

Exceptions

  IllegalArgumentException | if any of the arguments are `null`
  IllegalStateException | if `goptsConfig` or `parentKey` has already been released
  IllegalArgumentException | if any of the specified parameters is `null`

## ◆ open() [1/4]

static KDB org.libelektra.KDB.open | ( |  | ) | throws KDBException
| inline static

Opens a new KDB session.

Returns
  New KDB session

Exceptions

  KDBException | if opening the session fails - see specialization of `KDBException`

## ◆ open() [2/4]

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

Opens a new KDB session.

Parameters

  warningsKey | Used to store warnings, which may occur during opening the session, in this key's meta data

Returns
  New KDB session

Exceptions

  KDBException | if opening the session fails - see specialization of `KDBException`
  IllegalStateException | if `warningsKey` has already been released
  IllegalArgumentException | if `warningsKey` is `null`

See also
  Key::create()

## ◆ open() [3/4]

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

Opens KDB session using the specified `contract @endiliteral.
`

Parameters

  contract | Contract configuring the `gopts` plugin

Returns
  New KDB session

Exceptions

  KDBException | if opening the session fails - see specialization of `KDBException`
  IllegalStateException | if `contract` has already been released
  IllegalArgumentException | if `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
| inline static

Opens KDB session using the specified `contract @endiliteral.
`

Parameters

  contract | Contract configuring the `gopts` plugin
  warningsKey | Used to store warnings, which may occur during opening the session, in this key's meta data

Returns
  New KDB session

Exceptions

  KDBException | if opening the session fails - see specialization of `KDBException`
  IllegalStateException | if `contract` or `warningsKey` has already been released
  IllegalArgumentException | if `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

  keySet | KeySet which contains keys to be updated in the backend
  parentKey | Specify 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

  KDBException | if storing keys fails - see specialization of `KDBException`
  KDBClosedException | if this session has already been closed
  IllegalStateException | if `keySet` or `parentKey` has already been released
  IllegalArgumentException | if `keySet` or `parentKey` is `null`

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

- KDB.java