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

Inheritance diagram for org.libelektra.Key:

Collaboration diagram for org.libelektra.Key:

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

byte[]	getBinary ()

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	setBinary (byte[] value)
	Sets the key's binary 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	copy (Key source, int flags)
	Copies the information from the. More...

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

Optional< ReadableKey >	nextMeta ()
	Gets the next element of this key's internal meta information iterator. More...

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

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

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

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

Key	dup (int flags)
	Duplicates this ReadableKey as Key. More...

int	compareTo (ReadableKey other)
	Compares this key with the. More...

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

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

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

boolean	isBinary ()

boolean	isString ()

String	getName ()

int	getNameSize ()

String	getBaseName ()

int	getBaseNameSize ()

int	getValueSize ()

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

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

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

Protected Member Functions inherited from org.libelektra.ReadableKey
	ReadableKey (Pointer pointer)
	Constructor associating a new ReadableKey instance with a JNA pointer. More...

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

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

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

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

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
	)

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() [2/2]

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
IllegalStateException	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 error (format pattern)
args	Custom arguments to the format pattern text

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 ( )

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

Exceptions

KeyException on allocation problems

See also: release()

◆ create() [2/5]

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() [3/5]

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	Name of the key (first part of key-value pair)
value	Optional Value of key. will be determine from the object by calling {}. To set a binary value, please see #setBinary(byte[])}. meta Metadata that should be added to this key, null keys will be filtered away New key KeyException if the key name is invalid or there have been allocation problems #release()

◆ create() [4/5]

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

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

See also: release()

◆ create() [5/5]

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

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

See also: CreateArgumentTag; release()

◆ currentMeta()

ReadableKey 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

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

See also: rewindMeta(); nextMeta()

◆ 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 {}, if metaName was not found IllegalStateException if this Key} has already been released IllegalArgumentException if metaName is String#isBlank() blank}

◆ iterator()

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

inline

Returns: KeySetIterator for the meta data of this Key

◆ nextMeta()

Optional<ReadableKey> org.libelektra.Key.nextMeta ( )

inline

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

Returns: New Key object containing the requested meta information or {}, if no next meta key is available IllegalStateException if this Key} has already been released #rewindMeta() #currentMeta()

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

Reimplemented from org.libelektra.ReadableKey.

◆ 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

◆ rewindMeta()

Key org.libelektra.Key.rewindMeta ( )

inline

Rewinds the internal iterator for meta information of this key.

Exceptions

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

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	(	String	text,
		Object...	args
	)

inline

Sets proper error meta for key.

Parameters

text	Reason for the error (format pattern)
args	Custom arguments to the format pattern text

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

◆ 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

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Key() [1/2]

◆ Key() [2/2]

Member Function Documentation

◆ addBaseName()

◆ addWarning()

◆ copy()

◆ copyAllMeta()

◆ copyMeta()

◆ create() [1/5]

◆ create() [2/5]

◆ create() [3/5]

◆ create() [4/5]

◆ create() [5/5]

◆ currentMeta()

◆ getBinary()

◆ getMeta()

◆ iterator()

◆ nextMeta()

◆ release()

◆ removeMeta()

◆ rewindMeta()

◆ setBaseName()

◆ setBinary()

◆ setBoolean()

◆ setByte()

◆ setDouble()

◆ setError()

◆ setFloat()

◆ setInt()

◆ setLong()

◆ setMeta()

◆ setName()

◆ setShort()

◆ setString()