## org.apache.commons.configuration
Class ConfigurationKey

    java.lang.Object
      org.apache.commons.configuration.ConfigurationKey

All Implemented Interfaces:
  Serializable

    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
See Also:
  Serialized Form

Nested Class Summary
`class` `ConfigurationKey.KeyIterator` A specialized iterator class for tokenizing a configuration key.

Field Summary
`static String` `ESCAPED_DELIMITER` Constant for an escaped delimiter.
`static char` `PROPERTY_DELIMITER` Constant for a property delimiter.

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
`ConfigurationKey` `append(String property)` Appends the name of a property to this key.
`ConfigurationKey` `appendAttribute(String attr)` Appends an attribute to this configuration key.
`ConfigurationKey` `appendIndex(int index)` Appends an index to this configuration key.
`static String` `attributeName(String key)` Extracts the name of the attribute from the given attribute key.
`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.
`static String` `constructAttributeKey(String key)` Decorates the given key so that it represents an attribute.
`ConfigurationKey` `differenceKey(ConfigurationKey other)` Returns the "difference key" to a given key.
`boolean` `equals(Object c)` Checks if two `ConfigurationKey` objects are equal.
`int` `hashCode()` Returns the hash code for this object.
`boolean` `isAttributeKey()` Checks if this key is an attribute key.
`static boolean` `isAttributeKey(String key)` Checks if the passed in key is an attribute key.
`ConfigurationKey.KeyIterator` `iterator()` Returns an iterator for iterating over the single components of this configuration key.
`int` `length()` Returns the actual length of this configuration key.
`(package private) static String` `removeAttributeMarkers(String key)` Helper method for removing attribute markers from a key.
`void` `setLength(int len)` Sets the new length of this configuration key.
`String` `toString()` Returns a string representation of this object.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### PROPERTY_DELIMITER

    public static final char PROPERTY_DELIMITER

  Constant for a property delimiter.

  See Also:
    Constant Field Values

### ESCAPED_DELIMITER

    public static final String ESCAPED_DELIMITER

  Constant for an escaped delimiter.

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

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

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

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

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

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

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

### toString

    public String toString()

  Returns a string representation of this object. This is the configuration key as a plain string.

  Overrides:
    `toString` in class `Object`
  Returns:
    a string for this object

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

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

### equals

    public boolean equals(Object c)

  Checks if two `ConfigurationKey` objects are equal. The method can be called with strings or other objects, too.

  Overrides:
    `equals` in class `Object`
  Parameters:
    `c` - the object to compare
  Returns:
    a flag if both objects are equal

### hashCode

    public int hashCode()

  Returns the hash code for this object.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    the hash code

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

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

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.