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

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< KeygetMeta (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< Keycreate (@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
nativePointerNative 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
nativePointerNative pointer to key in long format
suppressCleanUpTrue 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
pointerJNA 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
baseNameNew key base name to add
Returns
This Key, enabling a fluent interface
Exceptions
KeyNameExceptionif
baseName
is invalid, the key was inserted in a key set before or the key name is read-only
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
baseName
is blank

◆ addWarning()

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

Adds warning meta for key.

Parameters
textReason for the warning
argsCustom 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
otherOther 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
KeyReleasedExceptionif this or the
other
Key has already been released
IllegalArgumentExceptionif
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
sourceSource Key object containing the information to copy
flagsFlags indicating which parts of the key to copy
Example:
KEY_CP_NAME | KEY_CP_VALUE
Returns
This Key, enabling a fluent interface
Exceptions
KeyExceptionif copying failed
KeyReleasedExceptionif this or the
source
Key has already been released
IllegalArgumentExceptionif
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
sourceKey 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
KeyMetaExceptionif copying failed
KeyReleasedExceptionif this or the
source
Key has already been released
IllegalArgumentExceptionif
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
sourceKey used as source
metaNameKey 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
KeyMetaExceptionif this key's meta information is read-only of copying failed
KeyReleasedExceptionif this or the
source
Key has already been released
IllegalArgumentExceptionif
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
pointerOptional 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
nameKey name; first part of key-value pair
valueKey value; will be determine from the object by calling Object#toString(), null is supported too
metaMetadata that should be added to this key, null keys will be filtered away
Returns
New key
Exceptions
KeyNameExceptionif 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
nameKey name; first part of key-value pair
metaMetadata that should be added to this key. Will filter null values.
Returns
New key object
Exceptions
KeyNameExceptionif 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
nameKey name; first part of key-value pair
argsArguments used for key value
Example:
CreateArgumentTag#KEY_VALUE, "custom key value", CreateArgumentTag#KEY_END
Returns
New key
Exceptions
KeyNameExceptionif 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
KeyReleasedExceptionif this Key has already been released
NoSuchElementExceptionif 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
KeyReleasedExceptionif 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
KeyExceptionif copying failed
KeyReleasedExceptionif 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
flagsFlags 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
KeyExceptionif copying failed
KeyReleasedExceptionif 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
KeyReleasedExceptionif this Key has already been released

◆ getBaseNameSize()

int org.libelektra.Key.getBaseNameSize ( )
inline
Returns
Length of key's base name
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ getBoolean()

boolean org.libelektra.Key.getBoolean ( )
inline
Returns
getString() interpreted as boolean value
Exceptions
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getByte()

byte org.libelektra.Key.getByte ( )
inline
Returns
getString() parsed as
byte
Exceptions
NumberFormatExceptionif the getString() does not return a parsable
byte
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getDouble()

double org.libelektra.Key.getDouble ( )
inline
Returns
getString() parsed as
double
Exceptions
NumberFormatExceptionif the getString() does not return a parsable
double
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getFloat()

float org.libelektra.Key.getFloat ( )
inline
Returns
getString() parsed as
float
Exceptions
NumberFormatExceptionif the getString() does not return a parsable
float
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getInt()

int org.libelektra.Key.getInt ( )
inline
Returns
getString() parsed as integer
Exceptions
NumberFormatExceptionif the getString() does not return a parsable integer
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getLong()

long org.libelektra.Key.getLong ( )
inline
Returns
getString() parsed as
long
Exceptions
NumberFormatExceptionif the getString() does not return a parsable
long
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getMeta()

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

Getter for meta information.

Parameters
metaNameKey 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
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
metaName
is blank
See also
release()

◆ getName()

String org.libelektra.Key.getName ( )
inline
Returns
Key name (key part of "key-value" pair)
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ getNameSize()

int org.libelektra.Key.getNameSize ( )
inline
Returns
Length of key name
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ getPointer()

Pointer org.libelektra.Key.getPointer ( )
inlineprotected
Returns
JNA pointer to the native pointer for this key
Exceptions
KeyReleasedExceptionif 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
KeyReleasedExceptionif this Key has already been released

◆ getShort()

short org.libelektra.Key.getShort ( )
inline
Returns
getString() parsed as
short
Exceptions
NumberFormatExceptionif the getString() does not return a parsable
short
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getString()

String org.libelektra.Key.getString ( ) throws KeyBinaryTypeNotSupportedException
inline
Returns
This key's value as string
Exceptions
KeyBinaryTypeNotSupportedExceptionif the underlying native key is of type binary
KeyReleasedExceptionif this Key has already been released

◆ getValueSize()

int org.libelektra.Key.getValueSize ( )
inline
Returns
Length/Size of key value
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ incRef()

Key org.libelektra.Key.incRef ( )
inlineprotected

Increments the reference counter for the underlying native key.

Exceptions
KeyReleasedExceptionif 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
otherKey that is used in check as parent key
Returns
Boolean if this key is (non-direct) sub-key of other-key
Exceptions
KeyReleasedExceptionif this or the
other
Key has already been released
IllegalArgumentExceptionif
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
otherKey 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
KeyReleasedExceptionif this or the
other
Key has already been released
IllegalArgumentExceptionif
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
KeyReleasedExceptionif 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
otherKey that is used in check as parent key
Returns
Boolean if this key is direct sub-key of other key ("child")
Exceptions
KeyReleasedExceptionif this or the
other
Key has already been released
IllegalArgumentExceptionif
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
KeyReleasedExceptionif this Key has already been released

◆ iterator()

Iterator<String> org.libelektra.Key.iterator ( )
inline
Returns
New KeyNameIterator backed by this Key
Exceptions
KeyReleasedExceptionif 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
KeyReleasedExceptionif this Key has already been released
NoSuchElementExceptionif 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
metaNameKey name of meta information to be removed
Returns
This Key, enabling a fluent interface
Exceptions
KeyMetaExceptionif
metaName
is invalid
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
metaName
is blank

◆ rewindMeta()

Key org.libelektra.Key.rewindMeta ( )
inline

Rewinds the internal iterator for meta information of this key.

Exceptions
KeyReleasedExceptionif 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
baseNameNew key base name to use
Returns
This Key, enabling a fluent interface
Exceptions
KeyNameExceptionif
baseName
is invalid, the key was inserted in a key set before or the key name is read-only
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
baseName
is
null

◆ setBoolean()

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

Sets the key's value by converting.

value

to string

Parameters
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ setError()

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

Sets proper error meta for key.

Parameters
textReason for the error
argsCustom 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ setMeta()

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

Sets meta information.

Parameters
metaNameKey name of meta information to be set
newMetaStringMeta value to be set
Returns
This Key, enabling a fluent interface
Exceptions
KeyMetaExceptionif
metaName
is invalid
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
metaName
is blank or
newMetaString
is
null

◆ setName()

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

Sets the key's name.

Parameters
nameNew key name to use
Returns
This Key, enabling a fluent interface
Exceptions
KeyNameExceptionif
name
is invalid, the key was inserted in a key set before or the key name is read-only
KeyReleasedExceptionif this Key has already been released
IllegalArgumentExceptionif
baseName
is blank

◆ setShort()

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

Sets the key's value by converting.

value

to string

Parameters
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif this Key has already been released

◆ setString()

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

Sets the key's value.

Parameters
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
KeyReleasedExceptionif 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: