| Elektra 0.11.0

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

Key represents a native Elektra key providing access to its name, value and meta information. More...

Inheritance diagram for org.libelektra.Key:

## Classes
enum | CreateArgumentTag
| Argument tags for use with `create(String, Object...)`. More...

## Public Member Functions
byte[] | getBinary ()
Key | setBoolean (boolean value)
| Sets the key's value by converting `value` to string.
Key | setByte (byte value)
| Sets the key's value by converting `value` to string.
Key | setShort (short value)
| Sets the key's value by converting `value` to string.
Key | setInt (int value)
| Sets the key's value by converting `value` to string.
Key | setLong (long value)
| Sets the key's value by converting `value` to string.
Key | setFloat (float value)
| Sets the key's value by converting `value` to string.
Key | setDouble (double value)
| Sets the key's value by converting `value` to string.
Key | setString (String value)
| Sets the key's value.
Key | setBinary (byte[] value)
| Sets the key's binary value.
Key | setNull ()
| Removes the key's value without changing the type.
Key | setError (ErrorCode code, String reason)
| Sets proper error meta for key.
Key | addWarning (ErrorCode code, String reason)
| Adds warning meta for key.
Key | copy (Key source, int flags)
| Copies the information from the `source` key into this key.
boolean | copyMeta (Key source, String metaName)
| Copies some meta information from a `source` key to this key.
boolean | copyAllMeta (Key source)
| Copies all meta information from a `source` key to this key.
Optional< ReadableKey > | getMeta (String metaName)
| Getter for meta information.
Key | setMeta (String metaName, String newMetaString)
| Sets meta information.
Key | removeMeta (String metaName)
| Removes meta information.
KeySet | meta ()
| Get KeySet with metakeys.
Key | setName (String name)
| Sets the key's name.
Key | setBaseName (String baseName) throws KeyNameException
| Sets the key's base name; will replace current base name with new base name.
Key | addBaseName (String baseName)
| Adds key base name; will add given base name to current key so that new key is sub key of current key.
Iterator< ReadableKey > | iterator ()
Public Member Functions inherited from org.libelektra.ReadableKey
String | toString ()
Iterator< String > | keyNameIterator ()
boolean | getBoolean ()
byte | getByte ()
short | getShort ()
int | getInt ()
long | getLong ()
float | getFloat ()
double | getDouble ()
String | getString ()
Key | dup ()
| Duplicates this `ReadableKey` as `Key`.
Key | dup (int flags)
| Duplicates this `ReadableKey` as `Key`.
int | compareTo (ReadableKey other)
| Compares this key with the `other` key by comparing the key name with string comparison.
boolean | isBelow (ReadableKey other)
| Checks whether this key is sub-key of the `other` key.
boolean | isBelowOrSame (ReadableKey other)
| Checks whether this key is the same as the `other` key or a sub-key of the `other` key.
boolean | isDirectlyBelow (ReadableKey other)
| Checks whether this key is direct sub-key of the `other` key.
boolean | isBinary ()
boolean | isString ()
String | getName ()
int | getNameSize ()
String | getBaseName ()
int | getBaseNameSize ()
int | getValueSize ()
boolean | isNull ()

## Static Public Member Functions
static Key | create ()
| Constructs a temporary nameless `Key` which cannot be saved to the key data base but used for transferring warnings and error information.
static Key | create (String name, @Nullable Object value, Key... meta)
| Constructs a new `Key` with the specified content and arguments
static Key | create (String name, Key... meta)
| Basic constructor of key class.

## Protected Member Functions
| Key (long nativePointer, boolean suppressCleanUp)
| Constructor associating a new `Key` instance with a native pointer in long format Suppressing clean-up has been introduced for usage of this binding as JNI plug-in and should normally not be used in any other case.
| Key (Pointer pointer)
| Constructor associating a new `Key` instance with a JNA pointer.
void | release ()
| Clean-up method to release key reference by first decrementing its reference counter and then trying to free the native reference `keys`, will get cleaned up by garbage collection as soon as they get phantom reachable.
Protected Member Functions inherited from org.libelektra.ReadableKey
| ReadableKey (Pointer pointer)
| Constructor associating a new `ReadableKey` instance with a JNA pointer.
| ReadableKey (Pointer pointer, boolean suppressCleanUp)
| Constructor associating a new `ReadableKey` instance with a JNA pointer Suppressing clean-up has been introduced for usage of this binding as JNI plug-in and should normally not be used in any other case.
void | release ()
| Clean-up method to release key reference by first decrementing its reference counter and then trying to free the native reference `keys`, will get cleaned up by garbage collection as soon as they get phantom reachable.
Pointer | getPointer ()

## Static Protected Member Functions
static Optional< Key > | create (@Nullable Pointer pointer)
| Constructs a new `Key` instance associated with a JNA pointer.
static Key | create (String name, Object... args)
| Constructs a new `Key` with the specified content and arguments
Static Protected Member Functions inherited from org.libelektra.ReadableKey
static Optional< ReadableKey > | createReadOnly (@Nullable Pointer pointer)
| Constructs a new `ReadableKey` instance associated with a JNA pointer.

## Additional Inherited Members
Static Public Attributes inherited from org.libelektra.ReadableKey
static final int | KEY_CP_NAME = 1 << 0
| Flag for use with `Key#copy(Key, int)` and `dup(int)` for copying the key name.
static final int | KEY_CP_STRING = 1 << 1
| Flag for use with `Key#copy(Key, int)` and `dup(int)` for copying the key value, if it is a string.
static final int | KEY_CP_VALUE = 1 << 2
| Flag for use with `Key#copy(Key, int)` and `dup(int)` for copying the key value.
static final int | KEY_CP_META = 1 << 3
| Flag for use with `Key#copy(Key, int)` and `dup(int)` for copying the key metadata.
static final int | KEY_CP_ALL = KEY_CP_NAME | KEY_CP_VALUE | KEY_CP_META
| Flag for use with `Key#copy(Key, int)` and `dup(int)` for copying the key name, value and metadata.

## Detailed Description

Key represents a native Elektra key providing access to its name, value and meta information.

## Constructor & Destructor Documentation

## ◆ Key() [1/2]

org.libelektra.Key.Key | ( | long | nativePointer,
|  | boolean | suppressCleanUp
| ) |  |
| inline protected

Constructor associating a new `Key` instance with a native pointer in long format
Suppressing clean-up has been introduced for usage of this binding as JNI plug-in and should normally not be used in any other case.

Parameters

  nativePointer | Native pointer to key in long format
  suppressCleanUp | True to suppress native reference clean-up as soon as this `Key` instance becomes phantom reachable, false otherwise @implNote Increased the native key's reference counter, even if `suppressCleanUp` is `true`

## ◆ Key() [2/2]

org.libelektra.Key.Key | ( | Pointer | pointer | ) |
| inline protected

Constructor associating a new `Key` instance with a JNA pointer.

Parameters

  pointer | JNA `Pointer` to key

## Member Function Documentation

## ◆ addBaseName()

Key org.libelektra.Key.addBaseName | ( | String | baseName | ) |
| inline

Adds key base name; will add given base name to current key so that new key is sub key of current key.

Parameters

  baseName | New key base name to add

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyNameException | if `baseName` is invalid, the key was inserted in a key set before or the key name is read-only
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `baseName` is `blank`

## ◆ addWarning()

Key org.libelektra.Key.addWarning | ( | ErrorCode | code,
|  | String | reason
| ) |  |
| inline

Adds warning meta for key.

Parameters

  code | `ErrorCode` of the warning
  reason | Reason for the error

Returns
  This `Key`, enabling a fluent interface

## ◆ copy()

Key org.libelektra.Key.copy | ( | Key | source,
|  | int | flags
| ) |  |
| inline

Copies the information from the `source` key into this key.

Parameters

  source | Source Key object containing the information to copy
  flags | Flags indicating which parts of the key to copy Example: `KEY_CP_NAME` | `KEY_CP_VALUE`

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyException | if copying failed
  IllegalStateException | if this or the `source` `Key` has already been released
  IllegalArgumentException | if `source` is `null`

See also
  #dup()
  #dup(int)
  KEY_CP_ALL
  KEY_CP_META
  KEY_CP_NAME
  KEY_CP_STRING
  KEY_CP_VALUE

## ◆ copyAllMeta()

boolean org.libelektra.Key.copyAllMeta | ( | Key | source | ) |
| inline

Copies all meta information from a `source` key to this key.

Parameters

  source | Key used as source

Returns
  True, if meta was successfully copied, false if `source` does not contain any meta and nothing had to be done

Exceptions

  KeyMetaException | if copying failed
  IllegalStateException | if this or the `source` `Key` has already been released
  IllegalArgumentException | if `source` is `null`

See also
  #copyMeta(Key, String)

## ◆ copyMeta()

boolean org.libelektra.Key.copyMeta | ( | Key | source,
|  | String | metaName
| ) |  |
| inline

Copies some meta information from a `source` key to this key.

Parameters

  source | Key used as source
  metaName | Key name of the meta information to be copied

Returns
  True, if meta was successfully copied, false if source does not contain the specified meta information and nothing had to be done

Exceptions

  KeyMetaException | if this key's meta information is read-only of copying failed
  IllegalStateException | if this or the `source` `Key` has already been released
  IllegalArgumentException | if `source` is `null` or `metaName` is `blank`

See also
  #copyAllMeta(Key)

## ◆ create() [1/5]

static Key org.libelektra.Key.create | ( |  | ) |
| inline static

Constructs a temporary nameless `Key` which cannot be saved to the key data base but used for transferring warnings and error information.

Returns
  New nameless key

Exceptions

  KeyException | on allocation problems

## ◆ create() [2/5]

static Optional< Key > org.libelektra.Key.create | ( | @Nullable Pointer | pointer | ) |
| inline static protected

Constructs a new `Key` instance associated with a JNA pointer.

Parameters

  pointer | Optional JNA `Pointer` to key

Returns
  New `Key` instance if `pointer` is non-null, `Optional#empty()` otherwise

## ◆ create() [3/5]

static Key org.libelektra.Key.create | ( | String | name,
|  | @Nullable Object | value,
|  | Key... | meta
| ) |  |
| inline static

Constructs a new `Key` with the specified content and arguments

Parameters

  name | Name of the key (first part of key-value pair)
  value | Optional Value of key. will be determine from the object by calling `Object#toString()`. To set a binary value, please see `setBinary(byte[])`.
  meta | Metadata that should be added to this key, null keys will be filtered away

Returns
  New key

Exceptions

  KeyException | if the key name is invalid or there have been allocation problems

## ◆ create() [4/5]

static Key org.libelektra.Key.create | ( | String | name,
|  | Key... | meta
| ) |  |
| inline static

Basic constructor of key class.

Parameters

  name | Key name; first part of key-value pair
  meta | Metadata that should be added to this key. Will filter null values.

Returns
  New key object

Exceptions

  KeyException | if the key name is invalid or there have been allocation problems

## ◆ create() [5/5]

static Key org.libelektra.Key.create | ( | String | name,
|  | Object... | args
| ) |  |
| inline static protected

Constructs a new `Key` with the specified content and arguments

Parameters

  name | Key name; first part of key-value pair
  args | Arguments used for key value Example: `CreateArgumentTag#KEY_VALUE`, "custom key value", `CreateArgumentTag#KEY_END`

Returns
  New key

Exceptions

  KeyException | if the key name is invalid or there have been allocation problems

See also
  CreateArgumentTag

## ◆ getBinary()

byte[] org.libelektra.Key.getBinary | ( |  | ) |
| inline

Returns
  This key's value as string

Exceptions

  KeyBinaryValueException | if the underlying native key is not of type binary
  IllegalStateException | if this `Key` has already been released

## ◆ getMeta()

Optional< ReadableKey > org.libelektra.Key.getMeta | ( | String | metaName | ) |
| inline

Getter for meta information.

Parameters

  metaName | Key name of meta information to be fetched

Returns
  New `ReadableKey` object containing the requested meta information or `Optional#empty()`, if `metaName` was not found

Exceptions

  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `metaName` is `blank`

## ◆ iterator()

Iterator< ReadableKey > org.libelektra.Key.iterator | ( |  | ) |
| inline

Returns
  `KeySetIterator` for the `meta data` of this `Key`

## ◆ meta()

KeySet org.libelektra.Key.meta | ( |  | ) |
| inline

Get KeySet with metakeys.

Returns
  A KeySet with all metakeys if the given key

Exceptions

  KeyMetaException | if `k` is invalid
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `k` is null}

## ◆ removeMeta()

Key org.libelektra.Key.removeMeta | ( | String | metaName | ) |
| inline

Removes meta information.

Parameters

  metaName | Key name of meta information to be removed

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyMetaException | if `metaName` is invalid
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `metaName` is `blank`

## ◆ setBaseName()

Key org.libelektra.Key.setBaseName | ( | String | baseName | ) | throws KeyNameException
| inline

Sets the key's base name; will replace current base name with new base name.

Parameters

  baseName | New key base name to use

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyNameException | if `baseName` is invalid, the key was inserted in a key set before or the key name is read-only
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `baseName` is `null`

## ◆ setBinary()

Key org.libelektra.Key.setBinary | ( | byte[] | value | ) |
| inline

Sets the key's binary value.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `value` is `null`
  KeyException | if the key's value is read-only or there have been allocation problems

## ◆ setBoolean()

Key org.libelektra.Key.setBoolean | ( | boolean | value | ) |
| inline

Sets the key's value by converting `value` to string.

See also
  Definition of Bool

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setByte()

Key org.libelektra.Key.setByte | ( | byte | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setDouble()

Key org.libelektra.Key.setDouble | ( | double | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setError()

Key org.libelektra.Key.setError | ( | ErrorCode | code,
|  | String | reason
| ) |  |
| inline

Sets proper error meta for key.

Parameters

  code | `ErrorCode` of the error
  reason | Reason for the error

Returns
  This `Key`, enabling a fluent interface

## ◆ setFloat()

Key org.libelektra.Key.setFloat | ( | float | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setInt()

Key org.libelektra.Key.setInt | ( | int | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setLong()

Key org.libelektra.Key.setLong | ( | long | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setMeta()

Key org.libelektra.Key.setMeta | ( | String | metaName,
|  | String | newMetaString
| ) |  |
| inline

Sets meta information.

Parameters

  metaName | Key name of meta information to be set
  newMetaString | Meta value to be set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyMetaException | if `metaName` is invalid
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `metaName` is `blank` or `newMetaString` is `null`

## ◆ setName()

Key org.libelektra.Key.setName | ( | String | name | ) |
| inline

Sets the key's name.

Parameters

  name | New key name to use

Returns
  This `Key`, enabling a fluent interface

Exceptions

  KeyNameException | if `name` is invalid, the key was inserted in a key set before or the key name is read-only
  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `baseName` is `blank`

## ◆ setNull()

Key org.libelektra.Key.setNull | ( |  | ) |
| inline

Removes the key's value without changing the type.

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released
  KeyException | if the key's value is read-only or there have been allocation problems

## ◆ setShort()

Key org.libelektra.Key.setShort | ( | short | value | ) |
| inline

Sets the key's value by converting `value` to string.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released

## ◆ setString()

Key org.libelektra.Key.setString | ( | String | value | ) |
| inline

Sets the key's value.

Parameters

  value | Value to set

Returns
  This `Key`, enabling a fluent interface

Exceptions

  IllegalStateException | if this `Key` has already been released
  IllegalArgumentException | if `value` is `null`
  KeyException | if the key's value is read-only or there have been allocation problems

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

- Key.java