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

Inherits Iterable< String >.

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

Public Member Functions
void	release ()
	Clean-up method to release key reference by first decrementing its reference counter and then trying to free the native reference Call this method if you do not longer need a Key and obtained it via any of its public methods or the public methods of KeySet. More...

String	toString ()

Iterator< String >	iterator ()

boolean	getBoolean ()

byte	getByte ()

short	getShort ()

int	getInt ()

long	getLong ()

float	getFloat ()

double	getDouble ()

String	getString () throws KeyBinaryTypeNotSupportedException

Key	setBoolean (boolean value)
	Sets the key's value by converting. More...

Key	setByte (byte value)
	Sets the key's value by converting. More...

Key	setShort (short value)
	Sets the key's value by converting. More...

Key	setInt (int value)
	Sets the key's value by converting. More...

Key	setLong (long value)
	Sets the key's value by converting. More...

Key	setFloat (float value)
	Sets the key's value by converting. More...

Key	setDouble (double value)
	Sets the key's value by converting. More...

Key	setString (String value)
	Sets the key's value. More...

Key	setError (String text, Object... args)
	Sets proper error meta for key. More...

Key	addWarning (String text, Object... args)
	Adds warning meta for key. More...

Key	dup ()
	Duplicates the key. More...

Key	dup (int flags)
	Duplicates the key. More...

Key	copy (Key source, int flags)
	Copies the information from the. More...

Key	rewindMeta ()
	Rewinds the internal iterator for meta information of this key. More...

Key	nextMeta ()
	Gets the next element of this key's internal meta information iterator. More...

Key	currentMeta ()
	Gets the current element of this key's internal meta information iterator. More...

boolean	copyMeta (Key source, String metaName)
	Copies some meta information from a. More...

boolean	copyAllMeta (Key source)
	Copies all meta information from a. More...

Optional< Key >	getMeta (String metaName)
	Getter for meta information. More...

Key	setMeta (String metaName, String newMetaString)
	Sets meta information. More...

Key	removeMeta (String metaName)
	Removes meta information. More...

int	cmp (Key other)
	Compares this key with the. More...

boolean	isBelow (Key other)
	Checks whether this key is sub-key of the. More...

boolean	isBelowOrSame (Key other)
	Checks whether this key is the same as the. More...

boolean	isDirectBelow (Key other)
	Checks whether this key is direct sub-key of the. More...

boolean	isBinary ()

boolean	isString ()

String	getName ()

int	getNameSize ()

Key	setName (String name)
	Sets the key's name. More...

String	getBaseName ()

int	getBaseNameSize ()

Key	setBaseName (String baseName) throws KeyNameException
	Sets the key's base name; will replace current base name with new base name. More...

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. More...

int	getValueSize ()

Static Public Member Functions
static Key	createNameless ()
	Constructs a temporary nameless Key which cannot be saved to the key data base but used for transferring warnings and error information. More...

static Key	create (String name, @Nullable Object value, Key... meta)
	Constructs a new Key with the specified content and arguments More...

static Key	create (String name, Key... meta)
	Basic constructor of key class. More...

Static Public Attributes
static final int	KEY_CP_NAME = 1 << 0
	Flag for use with copy(Key, int) for copying the key name.

static final int	KEY_CP_STRING = 1 << 1
	Flag for use with copy(Key, int) for copying the key value, if it is a string. More...

static final int	KEY_CP_VALUE = 1 << 2
	Flag for use with copy(Key, int) for copying the key value. More...

static final int	KEY_CP_META = 1 << 3
	Flag for use with copy(Key, 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 copy(Key, int) for copying the key name, value and metadata.

Protected Member Functions
	Key (long nativePointer)
	Constructor associating a new Key instance with a native pointer in long format. More...

	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. More...

	Key (Pointer pointer)
	Constructor associating a new Key instance with a JNA pointer. More...

Key	incRef ()
	Increments the reference counter for the underlying native key. More...

void	decRef ()
	Decrements the reference counter for the underlying native key. More...

int	getRef ()
	Gets the reference counter for the underlying native key. More...

Pointer	getPointer ()

Static Protected Member Functions
static Optional< Key >	create (@Nullable Pointer pointer)
	Constructs a new Key instance associated with a JNA pointer. More...

static Key	create (String name, Object... args)
	Constructs a new Key with the specified content and arguments More...

Detailed Description

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

Constructor & Destructor Documentation

◆ Key() [1/3]

org.libelektra.Key.Key ( long nativePointer )

inlineprotected

Constructor associating a new Key instance with a native pointer in long format.

Parameters

nativePointer Native pointer to key in long format

See also: release() @implNote Increased the native Key's reference counter

◆ Key() [2/3]

org.libelektra.Key.Key	(	long	nativePointer,
		boolean	suppressCleanUp
	)

inlineprotected

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

See also: release() @implNote Increased the native Key's reference counter, even if
suppressCleanUp

is
true

◆ Key() [3/3]

org.libelektra.Key.Key ( Pointer pointer )

inlineprotected

Constructor associating a new Key instance with a JNA pointer.

Parameters

pointer JNA Pointer to key

See also: release()

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
KeyReleasedException	if this Key has already been released
IllegalArgumentException	if baseName is blank

◆ addWarning()

Key org.libelektra.Key.addWarning	(	String	text,
		Object...	args
	)

inline

Adds warning meta for key.

Parameters

text	Reason for the warning
args	Custom arguments

Returns: This Key, enabling a fluent interface

◆ cmp()

int org.libelektra.Key.cmp ( Key other )

inline

Compares this key with the.

other

keys by comparing the key name with string comparison

Parameters

other Other key to compare this key to

Returns

0 if key name is equal
-1 if this key name has lower alphabetical order than the
other

key
1 if this key has higher alphabetical order

Exceptions

KeyReleasedException	if this or the other Key has already been released
IllegalArgumentException	if other is null

◆ 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
KeyReleasedException	if this or the source Key has already been released
IllegalArgumentException	if source is null

See also: dup(); dup(int)

◆ 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
KeyReleasedException	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
KeyReleasedException	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/4]

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

inlinestaticprotected

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

See also: release()

◆ create() [2/4]

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

inlinestatic

Constructs a new Key with the specified content and arguments

Parameters

name	Key name; first part of key-value pair
value	Key value; will be determine from the object by calling Object#toString(), null is supported too
meta	Metadata that should be added to this key, null keys will be filtered away

Returns: New key

Exceptions

KeyNameException if the key name is invalid

See also: release()

◆ create() [3/4]

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

inlinestatic

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

KeyNameException if the key name is invalid

See also: release()

◆ create() [4/4]

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

inlinestaticprotected

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

KeyNameException if the key name is invalid

See also: CreateArgumentTag; release()

◆ createNameless()

static Key org.libelektra.Key.createNameless ( )

inlinestatic

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

See also: release()

◆ currentMeta()

Key org.libelektra.Key.currentMeta ( )

inline

Gets the current element of this key's internal meta information iterator.

Returns: new Key object containing the current meta information

Exceptions

KeyReleasedException	if this Key has already been released
NoSuchElementException	if no next meta key is available or internal iterator has been reset

See also: rewindMeta(); nextMeta(); release()

◆ decRef()

void org.libelektra.Key.decRef ( )

inlineprotected

Decrements the reference counter for the underlying native key.

Exceptions

KeyReleasedException if this Key has already been released

◆ dup() [1/2]

Key org.libelektra.Key.dup ( )

inline

Duplicates the key.

Returns: New Key object containing the same information as this key

Exceptions

KeyException	if copying failed
KeyReleasedException	if this Key has already been released

See also: dup(int); copy(Key, int); release()

◆ dup() [2/2]

Key org.libelektra.Key.dup ( int flags )

inline

Duplicates the key.

Parameters

flags Flags indicating which parts of the key to copy
Example:
KEY_CP_NAME | KEY_CP_VALUE

Returns: New Key object containing the same information as this key

Exceptions

KeyException	if copying failed
KeyReleasedException	if this Key has already been released

See also: dup(); copy(Key, int); release()

◆ getBaseName()

String org.libelektra.Key.getBaseName ( )

inline

Returns: Key's base name as String

Exceptions

KeyReleasedException if this Key has already been released

◆ getBaseNameSize()

int org.libelektra.Key.getBaseNameSize ( )

inline

Returns: Length of key's base name

Exceptions

KeyReleasedException if this Key has already been released

◆ getBoolean()

boolean org.libelektra.Key.getBoolean ( )

inline

Returns: getString() interpreted as boolean value

Exceptions

KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getByte()

byte org.libelektra.Key.getByte ( )

inline

Returns: getString() parsed as
byte

Exceptions

NumberFormatException	if the getString() does not return a parsable byte
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getDouble()

double org.libelektra.Key.getDouble ( )

inline

Returns: getString() parsed as
double

Exceptions

NumberFormatException	if the getString() does not return a parsable double
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getFloat()

float org.libelektra.Key.getFloat ( )

inline

Returns: getString() parsed as
float

Exceptions

NumberFormatException	if the getString() does not return a parsable float
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getInt()

int org.libelektra.Key.getInt ( )

inline

Returns: getString() parsed as integer

Exceptions

NumberFormatException	if the getString() does not return a parsable integer
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getLong()

long org.libelektra.Key.getLong ( )

inline

Returns: getString() parsed as
long

Exceptions

NumberFormatException	if the getString() does not return a parsable long
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getMeta()

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

inline

Getter for meta information.

Parameters

metaName Key name of meta information to be fetched

Returns: New Key object containing the requested meta information or Optional#empty(), if
metaName

was not found

Exceptions

KeyReleasedException	if this Key has already been released
IllegalArgumentException	if metaName is blank

See also: release()

◆ getName()

String org.libelektra.Key.getName ( )

inline

Returns: Key name (key part of "key-value" pair)

Exceptions

KeyReleasedException if this Key has already been released

◆ getNameSize()

int org.libelektra.Key.getNameSize ( )

inline

Returns: Length of key name

Exceptions

KeyReleasedException if this Key has already been released

◆ getPointer()

Pointer org.libelektra.Key.getPointer ( )

inlineprotected

Returns: JNA pointer to the native pointer for this key

Exceptions

KeyReleasedException if this Key has already been released

◆ getRef()

int org.libelektra.Key.getRef ( )

inlineprotected

Gets the reference counter for the underlying native key.

Returns: Current reference counter value

Exceptions

KeyReleasedException if this Key has already been released

◆ getShort()

short org.libelektra.Key.getShort ( )

inline

Returns: getString() parsed as
short

Exceptions

NumberFormatException	if the getString() does not return a parsable short
KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getString()

String org.libelektra.Key.getString ( ) throws KeyBinaryTypeNotSupportedException

inline

Returns: This key's value as string

Exceptions

KeyBinaryTypeNotSupportedException	if the underlying native key is of type binary
KeyReleasedException	if this Key has already been released

◆ getValueSize()

int org.libelektra.Key.getValueSize ( )

inline

Returns: Length/Size of key value

Exceptions

KeyReleasedException if this Key has already been released

◆ incRef()

Key org.libelektra.Key.incRef ( )

inlineprotected

Increments the reference counter for the underlying native key.

Exceptions

KeyReleasedException if this Key has already been released

Returns: This Key, enabling a fluent interface

◆ isBelow()

boolean org.libelektra.Key.isBelow ( Key other )

inline

Checks whether this key is sub-key of the.

other

key

Parameters

other Key that is used in check as parent key

Returns: Boolean if this key is (non-direct) sub-key of other-key

Exceptions

KeyReleasedException	if this or the other Key has already been released
IllegalArgumentException	if other is null

◆ isBelowOrSame()

boolean org.libelektra.Key.isBelowOrSame ( Key other )

inline

Checks whether this key is the same as the.

other

key or a sub-key of the

other

key

Parameters

other Key that is used in check as parent key

Returns: Boolean if this key is other key or (non-direct) sub-key of other-key

Exceptions

KeyReleasedException	if this or the other Key has already been released
IllegalArgumentException	if other is null

◆ isBinary()

boolean org.libelektra.Key.isBinary ( )

inline

Returns: True if the underlying native key's value is of type binary, false otherwise

Exceptions

KeyReleasedException if this Key has already been released

◆ isDirectBelow()

boolean org.libelektra.Key.isDirectBelow ( Key other )

inline

Checks whether this key is direct sub-key of the.

other

key

Parameters

other Key that is used in check as parent key

Returns: Boolean if this key is direct sub-key of other key ("child")

Exceptions

KeyReleasedException	if this or the other Key has already been released
IllegalArgumentException	if other is null

◆ isString()

boolean org.libelektra.Key.isString ( )

inline

Returns: True if the underlying native key's value is a valid string, false otherwise

Exceptions

KeyReleasedException if this Key has already been released

◆ iterator()

Iterator<String> org.libelektra.Key.iterator ( )

inline

Returns: New KeyNameIterator backed by this Key

Exceptions

KeyReleasedException if this Key has already been released

◆ nextMeta()

Key org.libelektra.Key.nextMeta ( )

inline

Gets the next element of this key's internal meta information iterator.

Returns: new Key object containing the next meta information

Exceptions

KeyReleasedException	if this Key has already been released
NoSuchElementException	if no next meta key is available

See also: rewindMeta(); currentMeta(); release()

◆ release()

void org.libelektra.Key.release ( )

inline

Clean-up method to release key reference by first decrementing its reference counter and then trying to free the native reference

Call this method if you do not longer need a Key and obtained it via any of its public methods or the public methods of KeySet.

If you do not manually release such keys, they will get cleaned up by garbage collection as soon as they get phantom reachable. Therefore its encouraged to release key instances as soon as you do not use them anymore.

◆ 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
KeyReleasedException	if this Key has already been released
IllegalArgumentException	if metaName is blank

◆ rewindMeta()

Key org.libelektra.Key.rewindMeta ( )

inline

Rewinds the internal iterator for meta information of this key.

Exceptions

KeyReleasedException if this Key has already been released

Returns: This Key, enabling a fluent interface

See also: nextMeta(); currentMeta()

◆ 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
KeyReleasedException	if this Key has already been released
IllegalArgumentException	if baseName is null

◆ setBoolean()

Key org.libelektra.Key.setBoolean ( boolean 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

KeyReleasedException 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

KeyReleasedException 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

KeyReleasedException if this Key has already been released

◆ setError()

Key org.libelektra.Key.setError	(	String	text,
		Object...	args
	)

inline

Sets proper error meta for key.

Parameters

text	Reason for the error
args	Custom arguments

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

KeyReleasedException 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

KeyReleasedException 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

KeyReleasedException 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
KeyReleasedException	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
KeyReleasedException	if this Key has already been released
IllegalArgumentException	if baseName is blank

◆ 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

KeyReleasedException 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

KeyReleasedException if this Key has already been released

◆ toString()

String org.libelektra.Key.toString ( )

inline

Returns: Key name in string format as returned by getName()

Member Data Documentation

◆ KEY_CP_STRING

final int org.libelektra.Key.KEY_CP_STRING = 1 << 1

static

Flag for use with copy(Key, int) for copying the key value, if it is a string.

@apiNote Do not use together with KEY_CP_VALUE

◆ KEY_CP_VALUE

final int org.libelektra.Key.KEY_CP_VALUE = 1 << 2

static

Flag for use with copy(Key, int) for copying the key value.

@apiNote Do not use together with KEY_CP_STRING

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

Key.java

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Key() [1/3]

◆ Key() [2/3]

◆ Key() [3/3]

Member Function Documentation

◆ addBaseName()

◆ addWarning()

◆ cmp()

◆ copy()

◆ copyAllMeta()

◆ copyMeta()

◆ create() [1/4]

◆ create() [2/4]

◆ create() [3/4]

◆ create() [4/4]

◆ createNameless()

◆ currentMeta()

◆ decRef()

◆ dup() [1/2]

◆ dup() [2/2]

◆ getBaseName()

◆ getBaseNameSize()

◆ getBoolean()

◆ getByte()

◆ getDouble()

◆ getFloat()

◆ getInt()

◆ getLong()

◆ getMeta()

◆ getName()

◆ getNameSize()

◆ getPointer()

◆ getRef()

◆ getShort()

◆ getString()

◆ getValueSize()

◆ incRef()

◆ isBelow()

◆ isBelowOrSame()

◆ isBinary()

◆ isDirectBelow()

◆ isString()

◆ iterator()

◆ nextMeta()

◆ release()

◆ removeMeta()

◆ rewindMeta()

◆ setBaseName()

◆ setBoolean()

◆ setByte()

◆ setDouble()

◆ setError()

◆ setFloat()

◆ setInt()

◆ setLong()

◆ setMeta()

◆ setName()

◆ setShort()

◆ setString()

◆ toString()

Member Data Documentation

◆ KEY_CP_STRING

◆ KEY_CP_VALUE