Coverage Report

Coverage Report - org.apache.commons.configuration.ConfigurationKey

Classes in this File

Line Coverage

Branch Coverage

Complexity

ConfigurationKey

98%

65/66

88%

44/50

2,306

ConfigurationKey$KeyIterator

90%

55/61

91%

33/36

2,306

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.apache.commons.configuration;
 
 import java.io.Serializable;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 
 /**
  * <p>A simple class that supports creation of and iteration on complex
  * configuration keys.</p>
  *
  * <p>For key creation the class works similar to a StringBuilder: There are
  * several {@code 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.</p>
  *
  * <p>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.</p>
  *
  * @author <a
  * href="http://commons.apache.org/configuration/team-list.html">Commons
  * Configuration team</a>
  * @version $Id: ConfigurationKey.java 1231749 2012-01-15 20:48:56Z oheger $
  * @deprecated Use {@link org.apache.commons.configuration.tree.DefaultConfigurationKey}
  * instead. It is associated with a {@code DefaultExpressionEngine} and thus
  * can produce correct keys even if key separators have been changed.
  */
 @Deprecated
 public class ConfigurationKey implements Serializable
 {
     /** Constant for a property delimiter.*/
     public static final char PROPERTY_DELIMITER = '.';
 
     /** Constant for an escaped delimiter. */
     public static final String ESCAPED_DELIMITER =
         String.valueOf(PROPERTY_DELIMITER) + String.valueOf(PROPERTY_DELIMITER);
 
     /** Constant for an attribute start marker.*/
     private static final String ATTRIBUTE_START = "[@";
 
     /** Constant for an attribute end marker.*/
     private static final String ATTRIBUTE_END = "]";
 
     /** Constant for an index start marker.*/
     private static final char INDEX_START = '(';
 
     /** Constant for an index end marker.*/
     private static final char INDEX_END = ')';
 
     /** Constant for the initial StringBuilder size.*/
     private static final int INITIAL_SIZE = 32;
 
     /**
      * The serial version ID.
      */
     private static final long serialVersionUID = -4299732083605277656L;
 
     /** Holds a buffer with the so far created key.*/
     private StringBuilder keyBuffer;
 
     /**
      * Creates a new, empty instance of {@code ConfigurationKey}.
      */
     public ConfigurationKey()
     {
         keyBuffer = new StringBuilder(INITIAL_SIZE);
     }
 
     /**
      * Creates a new instance of {@code ConfigurationKey} and
      * initializes it with the given key.
      *
      * @param key the key as a string
      */
     public ConfigurationKey(String key)
     {
         keyBuffer = new StringBuilder(key);
         removeTrailingDelimiter();
     }
 
     /**
      * Appends the name of a property to this key. If necessary, a
      * property delimiter will be added.
      *
      * @param property the name of the property to be added
      * @return a reference to this object
      */
     public ConfigurationKey append(String property)
     {
         if (keyBuffer.length() > 0 && !hasDelimiter() && !isAttributeKey(property))
         {
             keyBuffer.append(PROPERTY_DELIMITER);
         }
 
         keyBuffer.append(property);
         removeTrailingDelimiter();
         return this;
     }
 
     /**
      * Appends an index to this configuration key.
      *
      * @param index the index to be appended
      * @return a reference to this object
      */
     public ConfigurationKey appendIndex(int index)
     {
         keyBuffer.append(INDEX_START).append(index);
         keyBuffer.append(INDEX_END);
         return this;
     }
 
     /**
      * Appends an attribute to this configuration key.
      *
      * @param attr the name of the attribute to be appended
      * @return a reference to this object
      */
     public ConfigurationKey appendAttribute(String attr)
     {
         keyBuffer.append(constructAttributeKey(attr));
         return this;
     }
 
     /**
      * Checks if this key is an attribute key.
      *
      * @return a flag if this key is an attribute key
      */
     public boolean isAttributeKey()
     {
         return isAttributeKey(keyBuffer.toString());
     }
 
     /**
      * 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.
      *
      * @param key the key (part) to be checked
      * @return a flag if this key is an attribute key
      */
     public static boolean isAttributeKey(String key)
     {
         return key != null
         && key.startsWith(ATTRIBUTE_START)
         && key.endsWith(ATTRIBUTE_END);
     }
 
     /**
      * Decorates the given key so that it represents an attribute. Adds
      * special start and end markers.
      *
      * @param key the key to be decorated
      * @return the decorated attribute key
      */
     public static String constructAttributeKey(String key)
     {
         StringBuilder buf = new StringBuilder();
         buf.append(ATTRIBUTE_START).append(key).append(ATTRIBUTE_END);
         return buf.toString();
     }
 
     /**
      * Extracts the name of the attribute from the given attribute key.
      * This method removes the attribute markers - if any - from the
      * specified key.
      *
      * @param key the attribute key
      * @return the name of the corresponding attribute
      */
     public static String attributeName(String key)
     {
         return isAttributeKey(key) ? removeAttributeMarkers(key) : key;
     }
 
     /**
      * Helper method for removing attribute markers from a key.
      *
      * @param key the key
      * @return the key with removed attribute markers
      */
     static String removeAttributeMarkers(String key)
     {
         return key.substring(ATTRIBUTE_START.length(), key.length() - ATTRIBUTE_END.length());
     }
 
     /**
      * Helper method that checks if the actual buffer ends with a property
      * delimiter.
      *
      * @return a flag if there is a trailing delimiter
      */
     private boolean hasDelimiter()
     {
         int count = 0;
         for (int idx = keyBuffer.length() - 1; idx >= 0
                 && keyBuffer.charAt(idx) == PROPERTY_DELIMITER; idx--)
         {
             count++;
         }
         return count % 2 != 0;
     }
 
     /**
      * Removes a trailing delimiter if there is any.
      */
     private void removeTrailingDelimiter()
     {
         while (hasDelimiter())
         {
             keyBuffer.deleteCharAt(keyBuffer.length() - 1);
         }
     }
 
     /**
      * Returns a string representation of this object. This is the
      * configuration key as a plain string.
      *
      * @return a string for this object
      */
     @Override
     public String toString()
     {
         return keyBuffer.toString();
     }
 
     /**
      * Returns an iterator for iterating over the single components of
      * this configuration key.
      *
      * @return an iterator for this key
      */
     public KeyIterator iterator()
     {
         return new KeyIterator();
     }
 
     /**
      * Returns the actual length of this configuration key.
      *
      * @return the length of this key
      */
     public int length()
     {
         return keyBuffer.length();
     }
 
     /**
      * 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 {@code append()} methods. The semantic is the same as
      * the {@code setLength()} method of {@code StringBuilder}.
      *
      * @param len the new length of the key
      */
     public void setLength(int len)
     {
         keyBuffer.setLength(len);
     }
 
     /**
      * Checks if two {@code ConfigurationKey} objects are equal. The
      * method can be called with strings or other objects, too.
      *
      * @param c the object to compare
      * @return a flag if both objects are equal
      */
     @Override
     public boolean equals(Object c)
     {
         if (c == null)
         {
             return false;
         }
 
         return keyBuffer.toString().equals(c.toString());
     }
 
     /**
      * Returns the hash code for this object.
      *
      * @return the hash code
      */
     @Override
     public int hashCode()
     {
         return String.valueOf(keyBuffer).hashCode();
     }
 
     /**
      * 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.
      *
      * @param other the other key
      * @return a key object with the common key part
      */
     public ConfigurationKey commonKey(ConfigurationKey other)
     {
         if (other == null)
         {
             throw new IllegalArgumentException("Other key must no be null!");
         }
 
         ConfigurationKey result = new ConfigurationKey();
         KeyIterator it1 = iterator();
         KeyIterator it2 = other.iterator();
 
         while (it1.hasNext() && it2.hasNext() && partsEqual(it1, it2))
         {
             if (it1.isAttribute())
             {
                 result.appendAttribute(it1.currentKey());
             }
             else
             {
                 result.append(it1.currentKey());
                 if (it1.hasIndex)
                 {
                     result.appendIndex(it1.getIndex());
                 }
             }
         }
 
         return result;
     }
 
     /**
      * Returns the &quot;difference key&quot; to a given key. This value
      * is the part of the passed in key that differs from this key. There is
      * the following relation:
      * {@code other = key.commonKey(other) + key.differenceKey(other)}
      * for an arbitrary configuration key {@code key}.
      *
      * @param other the key for which the difference is to be calculated
      * @return the difference key
      */
     public ConfigurationKey differenceKey(ConfigurationKey other)
     {
         ConfigurationKey common = commonKey(other);
         ConfigurationKey result = new ConfigurationKey();
 
         if (common.length() < other.length())
         {
             String k = other.toString().substring(common.length());
             // skip trailing delimiters
             int i = 0;
             while (i < k.length() && k.charAt(i) == PROPERTY_DELIMITER)
             {
                 i++;
             }
 
             if (i < k.length())
             {
                 result.append(k.substring(i));
             }
         }
 
         return result;
     }
 
     /**
      * Helper method for comparing two key parts.
      *
      * @param it1 the iterator with the first part
      * @param it2 the iterator with the second part
      * @return a flag if both parts are equal
      */
     private static boolean partsEqual(KeyIterator it1, KeyIterator it2)
     {
         return it1.nextKey().equals(it2.nextKey())
         && it1.getIndex() == it2.getIndex()
         && it1.isAttribute() == it2.isAttribute();
     }
 
     /**
      * A specialized iterator class for tokenizing a configuration key.
      * This class implements the normal iterator interface. In addition it
      * provides some specific methods for configuration keys.
      */
     public class KeyIterator implements Iterator<Object>, Cloneable
     {
         /** Stores the current key name.*/
         private String current;
 
         /** Stores the start index of the actual token.*/
         private int startIndex;
 
         /** Stores the end index of the actual token.*/
         private int endIndex;
 
         /** Stores the index of the actual property if there is one.*/
         private int indexValue;
 
         /** Stores a flag if the actual property has an index.*/
         private boolean hasIndex;
 
         /** Stores a flag if the actual property is an attribute.*/
         private boolean attribute;
 
         /**
          * Helper method for determining the next indices.
          *
          * @return the next key part
          */
         private String findNextIndices()
         {
             startIndex = endIndex;
             // skip empty names
             while (startIndex < keyBuffer.length()
                     && keyBuffer.charAt(startIndex) == PROPERTY_DELIMITER)
             {
                 startIndex++;
             }
 
             // Key ends with a delimiter?
             if (startIndex >= keyBuffer.length())
             {
                 endIndex = keyBuffer.length();
                 startIndex = endIndex - 1;
                 return keyBuffer.substring(startIndex, endIndex);
             }
             else
             {
                 return nextKeyPart();
             }
         }
 
         /**
          * Helper method for extracting the next key part. Takes escaping of
          * delimiter characters into account.
          *
          * @return the next key part
          */
         private String nextKeyPart()
         {
             StringBuilder key = new StringBuilder(INITIAL_SIZE);
             int idx = startIndex;
             int endIdx = keyBuffer.toString().indexOf(ATTRIBUTE_START,
                     startIndex);
             if (endIdx < 0 || endIdx == startIndex)
             {
                 endIdx = keyBuffer.length();
             }
             boolean found = false;
 
             while (!found && idx < endIdx)
             {
                 char c = keyBuffer.charAt(idx);
                 if (c == PROPERTY_DELIMITER)
                 {
                     // a duplicated delimiter means escaping
                     if (idx == endIdx - 1
                             || keyBuffer.charAt(idx + 1) != PROPERTY_DELIMITER)
                     {
                         found = true;
                     }
                     else
                     {
                         idx++;
                     }
                 }
                 if (!found)
                 {
                     key.append(c);
                     idx++;
                 }
             }
 
             endIndex = idx;
             return key.toString();
         }
 
         /**
          * Returns the next key part of this configuration key. This is a short
          * form of {@code nextKey(false)}.
          *
          * @return the next key part
          */
         public String nextKey()
         {
             return nextKey(false);
         }
 
         /**
          * Returns the next key part of this configuration key. The boolean
          * parameter indicates wheter a decorated key should be returned. This
          * affects only attribute keys: if the parameter is <b>false</b>, the
          * attribute markers are stripped from the key; if it is <b>true</b>,
          * they remain.
          *
          * @param decorated a flag if the decorated key is to be returned
          * @return the next key part
          */
         public String nextKey(boolean decorated)
         {
             if (!hasNext())
             {
                 throw new NoSuchElementException("No more key parts!");
             }
 
             hasIndex = false;
             indexValue = -1;
             String key = findNextIndices();
 
             current = key;
             hasIndex = checkIndex(key);
             attribute = checkAttribute(current);
 
             return currentKey(decorated);
         }
 
         /**
          * Helper method for checking if the passed key is an attribute.
          * If this is the case, the internal fields will be set.
          *
          * @param key the key to be checked
          * @return a flag if the key is an attribute
          */
         private boolean checkAttribute(String key)
         {
             if (isAttributeKey(key))
             {
                 current = removeAttributeMarkers(key);
                 return true;
             }
             else
             {
                 return false;
             }
         }
 
         /**
          * Helper method for checking if the passed key contains an index.
          * If this is the case, internal fields will be set.
          *
          * @param key the key to be checked
          * @return a flag if an index is defined
          */
         private boolean checkIndex(String key)
         {
             boolean result = false;
 
             int idx = key.lastIndexOf(INDEX_START);
             if (idx > 0)
             {
                 int endidx = key.indexOf(INDEX_END, idx);
 
                 if (endidx > idx + 1)
                 {
                     indexValue = Integer.parseInt(key.substring(idx + 1, endidx));
                     current = key.substring(0, idx);
                     result = true;
                 }
             }
 
             return result;
         }
 
         /**
          * Checks if there is a next element.
          *
          * @return a flag if there is a next element
          */
         public boolean hasNext()
         {
             return endIndex < keyBuffer.length();
         }
 
         /**
          * Returns the next object in the iteration.
          *
          * @return the next object
          */
         public Object next()
         {
             return nextKey();
         }
 
         /**
          * Removes the current object in the iteration. This method is not
          * supported by this iterator type, so an exception is thrown.
          */
         public void remove()
         {
             throw new UnsupportedOperationException("Remove not supported!");
         }
 
         /**
          * Returns the current key of the iteration (without skipping to the
          * next element). This is the same key the previous {@code next()}
          * call had returned. (Short form of {@code currentKey(false)}.
          *
          * @return the current key
          */
         public String currentKey()
         {
             return currentKey(false);
         }
 
         /**
          * Returns the current key of the iteration (without skipping to the
          * next element). The boolean parameter indicates wheter a decorated
          * key should be returned. This affects only attribute keys: if the
          * parameter is <b>false</b>, the attribute markers are stripped from
          * the key; if it is <b>true</b>, they remain.
          *
          * @param decorated a flag if the decorated key is to be returned
          * @return the current key
          */
         public String currentKey(boolean decorated)
         {
             return (decorated && isAttribute()) ? constructAttributeKey(current) : current;
         }
 
         /**
          * Returns a flag if the current key is an attribute. This method can
          * be called after {@code next()}.
          *
          * @return a flag if the current key is an attribute
          */
         public boolean isAttribute()
         {
             return attribute;
         }
 
         /**
          * Returns the index value of the current key. If the current key does
          * not have an index, return value is -1. This method can be called
          * after {@code next()}.
          *
          * @return the index value of the current key
          */
         public int getIndex()
         {
             return indexValue;
         }
 
         /**
          * Returns a flag if the current key has an associated index.
          * This method can be called after {@code next()}.
          *
          * @return a flag if the current key has an index
          */
         public boolean hasIndex()
         {
             return hasIndex;
         }
 
         /**
          * Creates a clone of this object.
          *
          * @return a clone of this object
          */
         @Override
         public Object clone()
         {
             try
             {
                 return super.clone();
             }
             catch (CloneNotSupportedException cex)
             {
                 // should not happen
                 return null;
             }
         }
     }
 }

1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17
18		package org.apache.commons.configuration;
19
20		import java.io.Serializable;
21		import java.util.Iterator;
22		import java.util.NoSuchElementException;
23
24		/**
25		* <p>A simple class that supports creation of and iteration on complex
26		* configuration keys.</p>
27		*
28		* <p>For key creation the class works similar to a StringBuilder: There are
29		* several {@code appendXXXX()} methods with which single parts
30		* of a key can be constructed. All these methods return a reference to the
31		* actual object so they can be written in a chain. When using this methods
32		* the exact syntax for keys need not be known.</p>
33		*
34		* <p>This class also defines a specialized iterator for configuration keys.
35		* With such an iterator a key can be tokenized into its single parts. For
36		* each part it can be checked whether it has an associated index.</p>
37		*
38		* @author <a
39		* href="http://commons.apache.org/configuration/team-list.html">Commons
40		* Configuration team</a>
41		* @version $Id: ConfigurationKey.java 1231749 2012-01-15 20:48:56Z oheger $
42		* @deprecated Use {@link org.apache.commons.configuration.tree.DefaultConfigurationKey}
43		* instead. It is associated with a {@code DefaultExpressionEngine} and thus
44		* can produce correct keys even if key separators have been changed.
45		*/
46		@Deprecated
47	9120	public class ConfigurationKey implements Serializable
48		{
49		/** Constant for a property delimiter.*/
50		public static final char PROPERTY_DELIMITER = '.';
51
52		/** Constant for an escaped delimiter. */
53	1	public static final String ESCAPED_DELIMITER =
54		String.valueOf(PROPERTY_DELIMITER) + String.valueOf(PROPERTY_DELIMITER);
55
56		/** Constant for an attribute start marker.*/
57		private static final String ATTRIBUTE_START = "[@";
58
59		/** Constant for an attribute end marker.*/
60		private static final String ATTRIBUTE_END = "]";
61
62		/** Constant for an index start marker.*/
63		private static final char INDEX_START = '(';
64
65		/** Constant for an index end marker.*/
66		private static final char INDEX_END = ')';
67
68		/** Constant for the initial StringBuilder size.*/
69		private static final int INITIAL_SIZE = 32;
70
71		/**
72		* The serial version ID.
73		*/
74		private static final long serialVersionUID = -4299732083605277656L;
75
76		/** Holds a buffer with the so far created key.*/
77		private StringBuilder keyBuffer;
78
79		/**
80		* Creates a new, empty instance of {@code ConfigurationKey}.
81		*/
82		public ConfigurationKey()
83	178	{
84	178	keyBuffer = new StringBuilder(INITIAL_SIZE);
85	178	}
86
87		/**
88		* Creates a new instance of {@code ConfigurationKey} and
89		* initializes it with the given key.
90		*
91		* @param key the key as a string
92		*/
93		public ConfigurationKey(String key)
94	49	{
95	49	keyBuffer = new StringBuilder(key);
96	49	removeTrailingDelimiter();
97	49	}
98
99		/**
100		* Appends the name of a property to this key. If necessary, a
101		* property delimiter will be added.
102		*
103		* @param property the name of the property to be added
104		* @return a reference to this object
105		*/
106		public ConfigurationKey append(String property)
107		{
108	257	if (keyBuffer.length() > 0 && !hasDelimiter() && !isAttributeKey(property))
109		{
110	113	keyBuffer.append(PROPERTY_DELIMITER);
111		}
112
113	257	keyBuffer.append(property);
114	257	removeTrailingDelimiter();
115	257	return this;
116		}
117
118		/**
119		* Appends an index to this configuration key.
120		*
121		* @param index the index to be appended
122		* @return a reference to this object
123		*/
124		public ConfigurationKey appendIndex(int index)
125		{
126	10	keyBuffer.append(INDEX_START).append(index);
127	10	keyBuffer.append(INDEX_END);
128	10	return this;
129		}
130
131		/**
132		* Appends an attribute to this configuration key.
133		*
134		* @param attr the name of the attribute to be appended
135		* @return a reference to this object
136		*/
137		public ConfigurationKey appendAttribute(String attr)
138		{
139	4	keyBuffer.append(constructAttributeKey(attr));
140	4	return this;
141		}
142
143		/**
144		* Checks if this key is an attribute key.
145		*
146		* @return a flag if this key is an attribute key
147		*/
148		public boolean isAttributeKey()
149		{
150	0	return isAttributeKey(keyBuffer.toString());
151		}
152
153		/**
154		* Checks if the passed in key is an attribute key. Such attribute keys
155		* start and end with certain marker strings. In some cases they must be
156		* treated slightly different.
157		*
158		* @param key the key (part) to be checked
159		* @return a flag if this key is an attribute key
160		*/
161		public static boolean isAttributeKey(String key)
162		{
163	686	return key != null
164		&& key.startsWith(ATTRIBUTE_START)
165		&& key.endsWith(ATTRIBUTE_END);
166		}
167
168		/**
169		* Decorates the given key so that it represents an attribute. Adds
170		* special start and end markers.
171		*
172		* @param key the key to be decorated
173		* @return the decorated attribute key
174		*/
175		public static String constructAttributeKey(String key)
176		{
177	7	StringBuilder buf = new StringBuilder();
178	7	buf.append(ATTRIBUTE_START).append(key).append(ATTRIBUTE_END);
179	7	return buf.toString();
180		}
181
182		/**
183		* Extracts the name of the attribute from the given attribute key.
184		* This method removes the attribute markers - if any - from the
185		* specified key.
186		*
187		* @param key the attribute key
188		* @return the name of the corresponding attribute
189		*/
190		public static String attributeName(String key)
191		{
192	2	return isAttributeKey(key) ? removeAttributeMarkers(key) : key;
193		}
194
195		/**
196		* Helper method for removing attribute markers from a key.
197		*
198		* @param key the key
199		* @return the key with removed attribute markers
200		*/
201		static String removeAttributeMarkers(String key)
202		{
203	7	return key.substring(ATTRIBUTE_START.length(), key.length() - ATTRIBUTE_END.length());
204		}
205
206		/**
207		* Helper method that checks if the actual buffer ends with a property
208		* delimiter.
209		*
210		* @return a flag if there is a trailing delimiter
211		*/
212		private boolean hasDelimiter()
213		{
214	424	int count = 0;
215	424	for (int idx = keyBuffer.length() - 1; idx >= 0
216	440	&& keyBuffer.charAt(idx) == PROPERTY_DELIMITER; idx--)
217		{
218	8	count++;
219		}
220	424	return count % 2 != 0;
221		}
222
223		/**
224		* Removes a trailing delimiter if there is any.
225		*/
226		private void removeTrailingDelimiter()
227		{
228	310	while (hasDelimiter())
229		{
230	4	keyBuffer.deleteCharAt(keyBuffer.length() - 1);
231		}
232	306	}
233
234		/**
235		* Returns a string representation of this object. This is the
236		* configuration key as a plain string.
237		*
238		* @return a string for this object
239		*/
240		@Override
241		public String toString()
242		{
243	165	return keyBuffer.toString();
244		}
245
246		/**
247		* Returns an iterator for iterating over the single components of
248		* this configuration key.
249		*
250		* @return an iterator for this key
251		*/
252		public KeyIterator iterator()
253		{
254	277	return new KeyIterator();
255		}
256
257		/**
258		* Returns the actual length of this configuration key.
259		*
260		* @return the length of this key
261		*/
262		public int length()
263		{
264	231	return keyBuffer.length();
265		}
266
267		/**
268		* Sets the new length of this configuration key. With this method it is
269		* possible to truncate the key, e.g. to return to a state prior calling
270		* some {@code append()} methods. The semantic is the same as
271		* the {@code setLength()} method of {@code StringBuilder}.
272		*
273		* @param len the new length of the key
274		*/
275		public void setLength(int len)
276		{
277	29	keyBuffer.setLength(len);
278	29	}
279
280		/**
281		* Checks if two {@code ConfigurationKey} objects are equal. The
282		* method can be called with strings or other objects, too.
283		*
284		* @param c the object to compare
285		* @return a flag if both objects are equal
286		*/
287		@Override
288		public boolean equals(Object c)
289		{
290	11	if (c == null)
291		{
292	1	return false;
293		}
294
295	10	return keyBuffer.toString().equals(c.toString());
296		}
297
298		/**
299		* Returns the hash code for this object.
300		*
301		* @return the hash code
302		*/
303		@Override
304		public int hashCode()
305		{
306	2	return String.valueOf(keyBuffer).hashCode();
307		}
308
309		/**
310		* Returns a configuration key object that is initialized with the part
311		* of the key that is common to this key and the passed in key.
312		*
313		* @param other the other key
314		* @return a key object with the common key part
315		*/
316		public ConfigurationKey commonKey(ConfigurationKey other)
317		{
318	104	if (other == null)
319		{
320	1	throw new IllegalArgumentException("Other key must no be null!");
321		}
322
323	103	ConfigurationKey result = new ConfigurationKey();
324	103	KeyIterator it1 = iterator();
325	103	KeyIterator it2 = other.iterator();
326
327	247	while (it1.hasNext() && it2.hasNext() && partsEqual(it1, it2))
328		{
329	144	if (it1.isAttribute())
330		{
331	2	result.appendAttribute(it1.currentKey());
332		}
333		else
334		{
335	142	result.append(it1.currentKey());
336	142	if (it1.hasIndex)
337		{
338	7	result.appendIndex(it1.getIndex());
339		}
340		}
341		}
342
343	103	return result;
344		}
345
346		/**
347		* Returns the "difference key" to a given key. This value
348		* is the part of the passed in key that differs from this key. There is
349		* the following relation:
350		* {@code other = key.commonKey(other) + key.differenceKey(other)}
351		* for an arbitrary configuration key {@code key}.
352		*
353		* @param other the key for which the difference is to be calculated
354		* @return the difference key
355		*/
356		public ConfigurationKey differenceKey(ConfigurationKey other)
357		{
358	67	ConfigurationKey common = commonKey(other);
359	67	ConfigurationKey result = new ConfigurationKey();
360
361	67	if (common.length() < other.length())
362		{
363	63	String k = other.toString().substring(common.length());
364		// skip trailing delimiters
365	63	int i = 0;
366	107	while (i < k.length() && k.charAt(i) == PROPERTY_DELIMITER)
367		{
368	44	i++;
369		}
370
371	63	if (i < k.length())
372		{
373	63	result.append(k.substring(i));
374		}
375		}
376
377	67	return result;
378		}
379
380		/**
381		* Helper method for comparing two key parts.
382		*
383		* @param it1 the iterator with the first part
384		* @param it2 the iterator with the second part
385		* @return a flag if both parts are equal
386		*/
387		private static boolean partsEqual(KeyIterator it1, KeyIterator it2)
388		{
389	232	return it1.nextKey().equals(it2.nextKey())
390		&& it1.getIndex() == it2.getIndex()
391		&& it1.isAttribute() == it2.isAttribute();
392		}
393
394		/**
395		* A specialized iterator class for tokenizing a configuration key.
396		* This class implements the normal iterator interface. In addition it
397		* provides some specific methods for configuration keys.
398		*/
399	419	public class KeyIterator implements Iterator<Object>, Cloneable
400		{
401		/** Stores the current key name.*/
402		private String current;
403
404		/** Stores the start index of the actual token.*/
405		private int startIndex;
406
407		/** Stores the end index of the actual token.*/
408		private int endIndex;
409
410		/** Stores the index of the actual property if there is one.*/
411		private int indexValue;
412
413		/** Stores a flag if the actual property has an index.*/
414		private boolean hasIndex;
415
416		/** Stores a flag if the actual property is an attribute.*/
417		private boolean attribute;
418
419		/**
420		* Helper method for determining the next indices.
421		*
422		* @return the next key part
423		*/
424		private String findNextIndices()
425		{
426	567	startIndex = endIndex;
427		// skip empty names
428		while (startIndex < keyBuffer.length()
429	883	&& keyBuffer.charAt(startIndex) == PROPERTY_DELIMITER)
430		{
431	316	startIndex++;
432		}
433
434		// Key ends with a delimiter?
435	567	if (startIndex >= keyBuffer.length())
436		{
437	0	endIndex = keyBuffer.length();
438	0	startIndex = endIndex - 1;
439	0	return keyBuffer.substring(startIndex, endIndex);
440		}
441		else
442		{
443	567	return nextKeyPart();
444		}
445		}
446
447		/**
448		* Helper method for extracting the next key part. Takes escaping of
449		* delimiter characters into account.
450		*
451		* @return the next key part
452		*/
453		private String nextKeyPart()
454		{
455	567	StringBuilder key = new StringBuilder(INITIAL_SIZE);
456	567	int idx = startIndex;
457	567	int endIdx = keyBuffer.toString().indexOf(ATTRIBUTE_START,
458		startIndex);
459	567	if (endIdx < 0 \|\| endIdx == startIndex)
460		{
461	532	endIdx = keyBuffer.length();
462		}
463	567	boolean found = false;
464
465	4687	while (!found && idx < endIdx)
466		{
467	4120	char c = keyBuffer.charAt(idx);
468	4120	if (c == PROPERTY_DELIMITER)
469		{
470		// a duplicated delimiter means escaping
471	385	if (idx == endIdx - 1
472		\|\| keyBuffer.charAt(idx + 1) != PROPERTY_DELIMITER)
473		{
474	382	found = true;
475		}
476		else
477		{
478	3	idx++;
479		}
480		}
481	4120	if (!found)
482		{
483	3738	key.append(c);
484	3738	idx++;
485		}
486	4120	}
487
488	567	endIndex = idx;
489	567	return key.toString();
490		}
491
492		/**
493		* Returns the next key part of this configuration key. This is a short
494		* form of {@code nextKey(false)}.
495		*
496		* @return the next key part
497		*/
498		public String nextKey()
499		{
500	566	return nextKey(false);
501		}
502
503		/**
504		* Returns the next key part of this configuration key. The boolean
505		* parameter indicates wheter a decorated key should be returned. This
506		* affects only attribute keys: if the parameter is <b>false</b>, the
507		* attribute markers are stripped from the key; if it is <b>true</b>,
508		* they remain.
509		*
510		* @param decorated a flag if the decorated key is to be returned
511		* @return the next key part
512		*/
513		public String nextKey(boolean decorated)
514		{
515	568	if (!hasNext())
516		{
517	1	throw new NoSuchElementException("No more key parts!");
518		}
519
520	567	hasIndex = false;
521	567	indexValue = -1;
522	567	String key = findNextIndices();
523
524	567	current = key;
525	567	hasIndex = checkIndex(key);
526	567	attribute = checkAttribute(current);
527
528	567	return currentKey(decorated);
529		}
530
531		/**
532		* Helper method for checking if the passed key is an attribute.
533		* If this is the case, the internal fields will be set.
534		*
535		* @param key the key to be checked
536		* @return a flag if the key is an attribute
537		*/
538		private boolean checkAttribute(String key)
539		{
540	567	if (isAttributeKey(key))
541		{
542	6	current = removeAttributeMarkers(key);
543	6	return true;
544		}
545		else
546		{
547	561	return false;
548		}
549		}
550
551		/**
552		* Helper method for checking if the passed key contains an index.
553		* If this is the case, internal fields will be set.
554		*
555		* @param key the key to be checked
556		* @return a flag if an index is defined
557		*/
558		private boolean checkIndex(String key)
559		{
560	567	boolean result = false;
561
562	567	int idx = key.lastIndexOf(INDEX_START);
563	567	if (idx > 0)
564		{
565	23	int endidx = key.indexOf(INDEX_END, idx);
566
567	23	if (endidx > idx + 1)
568		{
569	22	indexValue = Integer.parseInt(key.substring(idx + 1, endidx));
570	22	current = key.substring(0, idx);
571	22	result = true;
572		}
573		}
574
575	567	return result;
576		}
577
578		/**
579		* Checks if there is a next element.
580		*
581		* @return a flag if there is a next element
582		*/
583		public boolean hasNext()
584		{
585	1183	return endIndex < keyBuffer.length();
586		}
587
588		/**
589		* Returns the next object in the iteration.
590		*
591		* @return the next object
592		*/
593		public Object next()
594		{
595	5	return nextKey();
596		}
597
598		/**
599		* Removes the current object in the iteration. This method is not
600		* supported by this iterator type, so an exception is thrown.
601		*/
602		public void remove()
603		{
604	1	throw new UnsupportedOperationException("Remove not supported!");
605		}
606
607		/**
608		* Returns the current key of the iteration (without skipping to the
609		* next element). This is the same key the previous {@code next()}
610		* call had returned. (Short form of {@code currentKey(false)}.
611		*
612		* @return the current key
613		*/
614		public String currentKey()
615		{
616	144	return currentKey(false);
617		}
618
619		/**
620		* Returns the current key of the iteration (without skipping to the
621		* next element). The boolean parameter indicates wheter a decorated
622		* key should be returned. This affects only attribute keys: if the
623		* parameter is <b>false</b>, the attribute markers are stripped from
624		* the key; if it is <b>true</b>, they remain.
625		*
626		* @param decorated a flag if the decorated key is to be returned
627		* @return the current key
628		*/
629		public String currentKey(boolean decorated)
630		{
631	775	return (decorated && isAttribute()) ? constructAttributeKey(current) : current;
632		}
633
634		/**
635		* Returns a flag if the current key is an attribute. This method can
636		* be called after {@code next()}.
637		*
638		* @return a flag if the current key is an attribute
639		*/
640		public boolean isAttribute()
641		{
642	499	return attribute;
643		}
644
645		/**
646		* Returns the index value of the current key. If the current key does
647		* not have an index, return value is -1. This method can be called
648		* after {@code next()}.
649		*
650		* @return the index value of the current key
651		*/
652		public int getIndex()
653		{
654	303	return indexValue;
655		}
656
657		/**
658		* Returns a flag if the current key has an associated index.
659		* This method can be called after {@code next()}.
660		*
661		* @return a flag if the current key has an index
662		*/
663		public boolean hasIndex()
664		{
665	5	return hasIndex;
666		}
667
668		/**
669		* Creates a clone of this object.
670		*
671		* @return a clone of this object
672		*/
673		@Override
674		public Object clone()
675		{
676		try
677		{
678	0	return super.clone();
679		}
680	0	catch (CloneNotSupportedException cex)
681		{
682		// should not happen
683	0	return null;
684		}
685		}
686		}
687		}