com.gurock.smartinspect

Class LookupTable

java.lang.Object

com.gurock.smartinspect.LookupTable

public class LookupTable
extends Object

Represents a simple collection of key/value pairs.

The LookupTable class is responsible for storing and returning values which are organized by keys. Values can be added with the put method. To query a String value for a given key, the getStringValue method can be used. To query and automatically convert values to types other than String, please have a look at the get method family.

This class is not guaranteed to be threadsafe.

Constructor Summary

Constructors

Constructor and Description
LookupTable() Creates and initializes a LookupTable instance.

Method Summary

Modifier and Type	Method and Description
void	add(String key, String value) Adds a new element with a specified key and value to the LookupTable.
void	clear() Removes all key/value pairs of the collection
boolean	contains(String key) Tests if the collection contains a value for a given key.
boolean	getBooleanValue(String key, boolean defaultValue) Returns a value of an element converted to a boolean for a given key.
byte[]	getBytesValue(String key, int size, byte[] defaultValue) Returns a byte array value of an element for a given key.
Color	getColorValue(String key, Color defaultValue) Returns a Color value of an element for a given key.
int	getCount() Returns the number of key/value pairs of this collection.
int	getIntegerValue(String key, int defaultValue) Returns a value of an element converted to an integer for a given key.
Level	getLevelValue(String key, Level defaultValue) Returns a value of an element converted to a Level value for a given key.
FileRotate	getRotateValue(String key, FileRotate defaultValue) Returns a value of an element converted to a FileRotate value for a given key.
long	getSizeValue(String key, long defaultValue) Returns a value of an element converted to an integer for a given key.
String	getStringValue(String key, String defaultValue) Returns a value of an element for a given key.
long	getTimespanValue(String key, long defaultValue) Returns a value of an element converted to an integer for a given key.
void	put(String key, String value) Adds or updates an element with a specified key and value to the LookupTable.
void	remove(String key) Removes an existing element with a given key from this lookup table.
static long	sizeToLong(String value, long defaultResult)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LookupTable

public LookupTable()

Creates and initializes a LookupTable instance.

Method Detail

put

public void put(String key,
                String value)

Adds or updates an element with a specified key and value to the LookupTable.

This method adds a new element with a given key and value to the collection of key/value pairs. If an element for the given key already exists, the original element's value is updated.

Parameters:

key - The key of the element

value - The value of the element

Throws:

NullPointerException - if the key or value argument is null

add

public void add(String key,
                String value)

Adds a new element with a specified key and value to the LookupTable.

This method adds a new element with a given key and value to the collection of key/value pairs. If an element for the given key already exists, the original element's value is not updated.

Parameters:

key - The key of the element

value - The value of the element

Throws:

NullPointerException - if the key or value argument is null

remove

public void remove(String key)

Removes an existing element with a given key from this lookup table. This method removes the element with the given key from the internal list. Nothing happens if no element with the given key can be found.

Parameters:

key - The key of the element to remove

Throws:

NullPointerException - if the key argument is null

contains

public boolean contains(String key)

Tests if the collection contains a value for a given key.

Parameters:

key - The key to test for

Returns:

True if a value exists for the given key and false otherwise

Throws:

NullPointerException - if the key argument is null

clear

public void clear()

Removes all key/value pairs of the collection

getCount

public int getCount()

Returns the number of key/value pairs of this collection.

Returns:

The number of key/value pairs of this collection

getStringValue

public String getStringValue(String key,
                             String defaultValue)

Returns a value of an element for a given key.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value for a given key if an element with the given key exists or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getBooleanValue

public boolean getBooleanValue(String key,
                               boolean defaultValue)

Returns a value of an element converted to a boolean for a given key.

This method returns a boolean value of true if the found value of the given key matches either "true", "1" or "yes" and false otherwise. If the supplied key is unknown, the defaultValue argument is returned.

Parameters:

key - The key whose value to return. Cannot be null

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to a boolean for the given key if an element with the given key exists or defaultValue otherwise

Throws:

NullPointerException - if the key argument is null

getIntegerValue

public int getIntegerValue(String key,
                           int defaultValue)

Returns a value of an element converted to an integer for a given key. This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid int. Only non-negative integer values are recognized as valid.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to an int for the given key if an element with the given key exists and the found value is a valid int or defaultValue otherwise

Throws:

NullPointerException - if the key argument is null

getLevelValue

public Level getLevelValue(String key,
                           Level defaultValue)

Returns a value of an element converted to a Level value for a given key. This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value. Please see the Level enum for more information on the available values.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to the corresponding Level value for the given key if an element with the given key exists and the found value is a valid Level value or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getSizeValue

public long getSizeValue(String key,
                         long defaultValue)

Returns a value of an element converted to an integer for a given key. The integer value is interpreted as a byte size and it is supported to specify byte units.

This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown byte unit. Only non-negative integer values are recognized as valid.

It is possible to specify a size unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1KB", the return value of this function would be 1024.

The following table lists the available units together with a short description and the corresponding factor:

Size units

Unit Name	Description	Factor
KB	Kilo Byte	1024
MB	Mega Byte	1024^2
GB	Giga Byte	1024^3

If no unit is specified, this function defaults to the KB unit.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise

Throws:

NullPointerException - if the key argument is null

sizeToLong

public static long sizeToLong(String value,
                              long defaultResult)

getTimespanValue

public long getTimespanValue(String key,
                             long defaultValue)

Returns a value of an element converted to an integer for a given key. The integer value is interpreted as a time span, and it is supported to specify time span units.

This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown time span unit.

It is possible to specify a time span unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1s", the return value of this function would be 1000.

The following table lists the available units together with a short description and the corresponding factor.

   Unit Name  Description  Factor
   -          -            -
   s          Seconds      1000
   m          Minutes      60*s
   h          Hours        60*m
   d          Days         24*h
 

If no unit is specified, this function defaults to the Seconds unit. Please note that the value is always returned in milliseconds.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise. The value is returned in milliseconds

Throws:

NullPointerException - if the key argument is null

getRotateValue

public FileRotate getRotateValue(String key,
                                 FileRotate defaultValue)

Returns a value of an element converted to a FileRotate value for a given key.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to a FileRotate value for the given key if an element with the given key exists and the found value is a valid FileRotate or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getColorValue

public Color getColorValue(String key,
                           Color defaultValue)

Returns a Color value of an element for a given key. The element value must be specified as hexadecimal string. To indicate that the element value represents a hexadecimal string, the element value must begin with "0x", "&H" or "$". A '0' nibble is appended if the hexadecimal string has an odd length. The hexadecimal value must represent a three or four byte integer value. The hexadecimal value is handled as follows.

Formats

Bytes	Format
3	RRGGBB
4	AARRGGBB
Other	Ignored

A stands for the alpha channel and R, G and B represent the red, green and blue channels, respectively. If the value is not given as hexadecimal value with a length of 6 or 8 characters excluding the hexadecimal prefix identifier or if the value does not have a valid hexadecimal format, this method returns defaultValue.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown or if the found value has an invalid format

Returns:

Either the value converted to a Color value for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getBytesValue

public byte[] getBytesValue(String key,
                            int size,
                            byte[] defaultValue)

Returns a byte array value of an element for a given key. The returned byte array always has the desired length as specified by the size argument. If the element value does not have the required size after conversion, it is shortened or padded (with zeros) automatically. This method returns the defaultValue argument if either the supplied key is unknown or the found value does not have a valid format (e.g. invalid characters when using hexadecimal strings).

Parameters:

key - The key whose value to return. This parameter should not be null. Throws NullPointerException if the key argument is null.

size - The desired size in bytes of the returned byte array. If the element value does not have the expected size, it is shortened or padded automatically.

defaultValue - The value to return if the given key is unknown or if the found value has an invalid format.

Returns:

Either the value converted to a byte array for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise.