org.apache.commons.configuration

Class ConfigurationKey

public class ConfigurationKey extends Object implements Serializable

A simple class that supports creation of and iteration on complex configuration keys.

For key creation the class works similar to a StringBuffer: There are several appendXXXX() methods with which single parts of a key can be constructed. All these methods return a reference to the actual object so they can be written in a chain. When using this methods the exact syntax for keys need not be known.

This class also defines a specialized iterator for configuration keys. With such an iterator a key can be tokenized into its single parts. For each part it can be checked whether it has an associated index.

Version: $Id: ConfigurationKey.java 439648 2006-09-02 20:42:10Z oheger $

Author: Oliver Heger

Nested Class Summary
classConfigurationKey.KeyIterator
A specialized iterator class for tokenizing a configuration key.
Field Summary
static StringATTRIBUTE_END
Constant for an attribute end marker.
static StringATTRIBUTE_START
Constant for an attribute start marker.
static StringESCAPED_DELIMITER
Constant for an escaped delimiter.
static charINDEX_END
Constant for an index end marker.
static charINDEX_START
Constant for an index start marker.
static intINITIAL_SIZE
Constant for the initial StringBuffer size.
StringBufferkeyBuffer
Holds a buffer with the so far created key.
static charPROPERTY_DELIMITER
Constant for a property delimiter.
static longserialVersionUID
The serial version ID.
Constructor Summary
ConfigurationKey()
Creates a new, empty instance of ConfigurationKey.
ConfigurationKey(String key)
Creates a new instance of ConfigurationKey and initializes it with the given key.
Method Summary
ConfigurationKeyappend(String property)
Appends the name of a property to this key.
ConfigurationKeyappendAttribute(String attr)
Appends an attribute to this configuration key.
ConfigurationKeyappendIndex(int index)
Appends an index to this configuration key.
static StringattributeName(String key)
Extracts the name of the attribute from the given attribute key.
ConfigurationKeycommonKey(ConfigurationKey other)
Returns a configuration key object that is initialized with the part of the key that is common to this key and the passed in key.
static StringconstructAttributeKey(String key)
Decorates the given key so that it represents an attribute.
ConfigurationKeydifferenceKey(ConfigurationKey other)
Returns the "difference key" to a given key.
booleanequals(Object c)
Checks if two ConfigurationKey objects are equal.
booleanhasDelimiter()
Helper method that checks if the actual buffer ends with a property delimiter.
inthashCode()
Returns the hash code for this object.
booleanisAttributeKey()
Checks if this key is an attribute key.
static booleanisAttributeKey(String key)
Checks if the passed in key is an attribute key.
ConfigurationKey.KeyIteratoriterator()
Returns an iterator for iterating over the single components of this configuration key.
intlength()
Returns the actual length of this configuration key.
static booleanpartsEqual(ConfigurationKey.KeyIterator it1, ConfigurationKey.KeyIterator it2)
Helper method for comparing two key parts.
static StringremoveAttributeMarkers(String key)
Helper method for removing attribute markers from a key.
voidremoveTrailingDelimiter()
Removes a trailing delimiter if there is any.
voidsetLength(int len)
Sets the new length of this configuration key.
StringtoString()
Returns a string representation of this object.

Field Detail

ATTRIBUTE_END

private static final String ATTRIBUTE_END
Constant for an attribute end marker.

ATTRIBUTE_START

private static final String ATTRIBUTE_START
Constant for an attribute start marker.

ESCAPED_DELIMITER

public static final String ESCAPED_DELIMITER
Constant for an escaped delimiter.

INDEX_END

private static final char INDEX_END
Constant for an index end marker.

INDEX_START

private static final char INDEX_START
Constant for an index start marker.

INITIAL_SIZE

private static final int INITIAL_SIZE
Constant for the initial StringBuffer size.

keyBuffer

private StringBuffer keyBuffer
Holds a buffer with the so far created key.

PROPERTY_DELIMITER

public static final char PROPERTY_DELIMITER
Constant for a property delimiter.

serialVersionUID

private static final long serialVersionUID
The serial version ID.

Constructor Detail

ConfigurationKey

public ConfigurationKey()
Creates a new, empty instance of ConfigurationKey.

ConfigurationKey

public ConfigurationKey(String key)
Creates a new instance of ConfigurationKey and initializes it with the given key.

Parameters: key the key as a string

Method Detail

append

public ConfigurationKey append(String property)
Appends the name of a property to this key. If necessary, a property delimiter will be added.

Parameters: property the name of the property to be added

Returns: a reference to this object

appendAttribute

public ConfigurationKey appendAttribute(String attr)
Appends an attribute to this configuration key.

Parameters: attr the name of the attribute to be appended

Returns: a reference to this object

appendIndex

public ConfigurationKey appendIndex(int index)
Appends an index to this configuration key.

Parameters: index the index to be appended

Returns: a reference to this object

attributeName

public static String attributeName(String key)
Extracts the name of the attribute from the given attribute key. This method removes the attribute markers - if any - from the specified key.

Parameters: key the attribute key

Returns: the name of the corresponding attribute

commonKey

public ConfigurationKey commonKey(ConfigurationKey other)
Returns a configuration key object that is initialized with the part of the key that is common to this key and the passed in key.

Parameters: other the other key

Returns: a key object with the common key part

constructAttributeKey

public static String constructAttributeKey(String key)
Decorates the given key so that it represents an attribute. Adds special start and end markers.

Parameters: key the key to be decorated

Returns: the decorated attribute key

differenceKey

public ConfigurationKey differenceKey(ConfigurationKey other)
Returns the "difference key" to a given key. This value is the part of the passed in key that differs from this key. There is the following relation: other = key.commonKey(other) + key.differenceKey(other) for an arbitrary configuration key key.

Parameters: other the key for which the difference is to be calculated

Returns: the difference key

equals

public boolean equals(Object c)
Checks if two ConfigurationKey objects are equal. The method can be called with strings or other objects, too.

Parameters: c the object to compare

Returns: a flag if both objects are equal

hasDelimiter

private boolean hasDelimiter()
Helper method that checks if the actual buffer ends with a property delimiter.

Returns: a flag if there is a trailing delimiter

hashCode

public int hashCode()
Returns the hash code for this object.

Returns: the hash code

isAttributeKey

public boolean isAttributeKey()
Checks if this key is an attribute key.

Returns: a flag if this key is an attribute key

isAttributeKey

public static boolean isAttributeKey(String key)
Checks if the passed in key is an attribute key. Such attribute keys start and end with certain marker strings. In some cases they must be treated slightly different.

Parameters: key the key (part) to be checked

Returns: a flag if this key is an attribute key

iterator

public ConfigurationKey.KeyIterator iterator()
Returns an iterator for iterating over the single components of this configuration key.

Returns: an iterator for this key

length

public int length()
Returns the actual length of this configuration key.

Returns: the length of this key

partsEqual

private static boolean partsEqual(ConfigurationKey.KeyIterator it1, ConfigurationKey.KeyIterator it2)
Helper method for comparing two key parts.

Parameters: it1 the iterator with the first part it2 the iterator with the second part

Returns: a flag if both parts are equal

removeAttributeMarkers

static String removeAttributeMarkers(String key)
Helper method for removing attribute markers from a key.

Parameters: key the key

Returns: the key with removed attribute markers

removeTrailingDelimiter

private void removeTrailingDelimiter()
Removes a trailing delimiter if there is any.

setLength

public void setLength(int len)
Sets the new length of this configuration key. With this method it is possible to truncate the key, e.g. to return to a state prior calling some append() methods. The semantic is the same as the setLength() method of StringBuffer.

Parameters: len the new length of the key

toString

public String toString()
Returns a string representation of this object. This is the configuration key as a plain string.

Returns: a string for this object