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:
org.libelektra.ReadableKey

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< ReadableKeygetMeta (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< ReadableKeyiterator ()
 
- 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.
 
Pointer getPointer ()
 

Static Protected Member Functions

static Optional< Keycreate (@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< ReadableKeycreateReadOnly (@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 
)
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 @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
pointerJNA 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
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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif baseName is blank

◆ addWarning()

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

Adds warning meta for key.

Parameters
codeErrorCode of the warning
reasonReason 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
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
IllegalStateExceptionif this or the source Key has already been released
IllegalArgumentExceptionif 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
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
IllegalStateExceptionif 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
IllegalStateExceptionif this or the source Key has already been released
IllegalArgumentExceptionif 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
KeyExceptionon allocation problems

◆ 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
pointerOptional 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 
)
inlinestatic

Constructs a new Key with the specified content and arguments

Parameters
nameName of the key (first part of key-value pair)
valueOptional Value of key. will be determine from the object by calling Object#toString(). To set a binary value, please see setBinary(byte[]).
metaMetadata that should be added to this key, null keys will be filtered away
Returns
New key
Exceptions
KeyExceptionif the key name is invalid or there have been allocation problems

◆ create() [4/5]

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
KeyExceptionif the key name is invalid or there have been allocation problems

◆ 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
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
KeyExceptionif 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
KeyBinaryValueExceptionif the underlying native key is not of type binary
IllegalStateExceptionif this Key has already been released

◆ getMeta()

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

Getter for meta information.

Parameters
metaNameKey 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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif 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
KeyMetaExceptionif k is invalid
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif k is null}

◆ 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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif 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
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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif baseName is null

◆ setBinary()

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

Sets the key's binary value.

Parameters
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif value is null
KeyExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
IllegalStateExceptionif 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
IllegalStateExceptionif 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
IllegalStateExceptionif this Key has already been released

◆ setError()

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

Sets proper error meta for key.

Parameters
codeErrorCode of the error
reasonReason 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
IllegalStateExceptionif 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
IllegalStateExceptionif 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
IllegalStateExceptionif 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
IllegalStateExceptionif 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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif 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
IllegalStateExceptionif this Key has already been released
KeyExceptionif 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
valueValue to set
Returns
This Key, enabling a fluent interface
Exceptions
IllegalStateExceptionif 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
IllegalStateExceptionif this Key has already been released
IllegalArgumentExceptionif value is null
KeyExceptionif the key's value is read-only or there have been allocation problems

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