org.apache.commons.configuration2.tree.DefaultConfigurationKey Maven / Gradle / Ivy
Show all versions of commons-configuration2 Show documentation
/*
* 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.configuration2.tree;
import java.util.Iterator;
import java.util.NoSuchElementException;
import org.apache.commons.lang3.StringUtils;
/**
*
* A simple class that supports creation of and iteration on configuration keys
* supported by a {@link DefaultExpressionEngine} object.
*
*
* For key creation the class works similar to a StringBuffer: 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.
*
*
* 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.
*
*
* Instances of this class are always associated with an instance of
* {@link DefaultExpressionEngine}, from which the current
* delimiters are obtained. So key creation and parsing is specific to this
* associated expression engine.
*
*
* @since 1.3
* @author Commons
* Configuration team
*/
public class DefaultConfigurationKey
{
/** Constant for the initial StringBuffer size. */
private static final int INITIAL_SIZE = 32;
/** Stores a reference to the associated expression engine. */
private final DefaultExpressionEngine expressionEngine;
/** Holds a buffer with the so far created key. */
private final StringBuilder keyBuffer;
/**
* Creates a new instance of {@code DefaultConfigurationKey} and sets
* the associated expression engine.
*
* @param engine the expression engine (must not be null)
* @throws IllegalArgumentException if the expression engine is null
*/
public DefaultConfigurationKey(final DefaultExpressionEngine engine)
{
this(engine, null);
}
/**
* Creates a new instance of {@code DefaultConfigurationKey} and sets the
* associated expression engine and an initial key.
*
* @param engine the expression engine (must not be null)
* @param key the key to be wrapped
* @throws IllegalArgumentException if the expression engine is null
*/
public DefaultConfigurationKey(final DefaultExpressionEngine engine, final String key)
{
if (engine == null)
{
throw new IllegalArgumentException(
"Expression engine must not be null!");
}
expressionEngine = engine;
if (key != null)
{
keyBuffer = new StringBuilder(trim(key));
}
else
{
keyBuffer = new StringBuilder(INITIAL_SIZE);
}
}
/**
* Returns the associated default expression engine.
*
* @return the associated expression engine
*/
public DefaultExpressionEngine getExpressionEngine()
{
return expressionEngine;
}
/**
* Appends the name of a property to this key. If necessary, a property
* delimiter will be added. If the boolean argument is set to true,
* property delimiters contained in the property name will be escaped.
*
* @param property the name of the property to be added
* @param escape a flag if property delimiters in the passed in property name
* should be escaped
* @return a reference to this object
*/
public DefaultConfigurationKey append(final String property, final boolean escape)
{
String key;
if (escape && property != null)
{
key = escapeDelimiters(property);
}
else
{
key = property;
}
key = trim(key);
if (keyBuffer.length() > 0 && !isAttributeKey(property)
&& key.length() > 0)
{
keyBuffer.append(getSymbols().getPropertyDelimiter());
}
keyBuffer.append(key);
return this;
}
/**
* Appends the name of a property to this key. If necessary, a property
* delimiter will be added. Property delimiters in the given string will not
* be escaped.
*
* @param property the name of the property to be added
* @return a reference to this object
*/
public DefaultConfigurationKey append(final String property)
{
return append(property, false);
}
/**
* Appends an index to this configuration key.
*
* @param index the index to be appended
* @return a reference to this object
*/
public DefaultConfigurationKey appendIndex(final int index)
{
keyBuffer.append(getSymbols().getIndexStart());
keyBuffer.append(index);
keyBuffer.append(getSymbols().getIndexEnd());
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 DefaultConfigurationKey appendAttribute(final String attr)
{
keyBuffer.append(constructAttributeKey(attr));
return this;
}
/**
* 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(final int len)
{
keyBuffer.setLength(len);
}
/**
* 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 DefaultConfigurationKey commonKey(final DefaultConfigurationKey other)
{
if (other == null)
{
throw new IllegalArgumentException("Other key must no be null!");
}
final DefaultConfigurationKey result = new DefaultConfigurationKey(getExpressionEngine());
final KeyIterator it1 = iterator();
final 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 "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:
* {@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 DefaultConfigurationKey differenceKey(final DefaultConfigurationKey other)
{
final DefaultConfigurationKey common = commonKey(other);
final DefaultConfigurationKey result = new DefaultConfigurationKey(getExpressionEngine());
if (common.length() < other.length())
{
final String k = other.toString().substring(common.length());
// skip trailing delimiters
int i = 0;
while (i < k.length()
&& String.valueOf(k.charAt(i)).equals(
getSymbols().getPropertyDelimiter()))
{
i++;
}
if (i < k.length())
{
result.append(k.substring(i));
}
}
return result;
}
/**
* Checks if two {@code ConfigurationKey} objects are equal. Two instances
* of this class are considered equal if they have the same content (i.e.
* their internal string representation is equal). The expression engine
* property is not taken into account.
*
* @param obj the object to compare
* @return a flag if both objects are equal
*/
@Override
public boolean equals(final Object obj)
{
if (this == obj)
{
return true;
}
if (!(obj instanceof DefaultConfigurationKey))
{
return false;
}
final DefaultConfigurationKey c = (DefaultConfigurationKey) obj;
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 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();
}
/**
* Tests if the specified key represents an attribute according to the
* current expression engine.
*
* @param key the key to be checked
* @return true if this is an attribute key, false otherwise
*/
public boolean isAttributeKey(final String key)
{
if (key == null)
{
return false;
}
return key.startsWith(getSymbols().getAttributeStart())
&& (getSymbols().getAttributeEnd() == null || key
.endsWith(getSymbols().getAttributeEnd()));
}
/**
* Decorates the given key so that it represents an attribute. Adds special
* start and end markers. The passed in string will be modified only if does
* not already represent an attribute.
*
* @param key the key to be decorated
* @return the decorated attribute key
*/
public String constructAttributeKey(final String key)
{
if (key == null)
{
return StringUtils.EMPTY;
}
if (isAttributeKey(key))
{
return key;
}
final StringBuilder buf = new StringBuilder();
buf.append(getSymbols().getAttributeStart()).append(key);
if (getSymbols().getAttributeEnd() != null)
{
buf.append(getSymbols().getAttributeEnd());
}
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 String attributeName(final String key)
{
return isAttributeKey(key) ? removeAttributeMarkers(key) : key;
}
/**
* Removes leading property delimiters from the specified key.
*
* @param key the key
* @return the key with removed leading property delimiters
*/
public String trimLeft(final String key)
{
if (key == null)
{
return StringUtils.EMPTY;
}
String result = key;
while (hasLeadingDelimiter(result))
{
result = result.substring(getSymbols()
.getPropertyDelimiter().length());
}
return result;
}
/**
* Removes trailing property delimiters from the specified key.
*
* @param key the key
* @return the key with removed trailing property delimiters
*/
public String trimRight(final String key)
{
if (key == null)
{
return StringUtils.EMPTY;
}
String result = key;
while (hasTrailingDelimiter(result))
{
result = result
.substring(0, result.length()
- getSymbols().getPropertyDelimiter()
.length());
}
return result;
}
/**
* Removes delimiters at the beginning and the end of the specified key.
*
* @param key the key
* @return the key with removed property delimiters
*/
public String trim(final String key)
{
return trimRight(trimLeft(key));
}
/**
* 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();
}
/**
* Helper method that checks if the specified key ends with a property
* delimiter.
*
* @param key the key to check
* @return a flag if there is a trailing delimiter
*/
private boolean hasTrailingDelimiter(final String key)
{
return key.endsWith(getSymbols().getPropertyDelimiter())
&& (getSymbols().getEscapedDelimiter() == null || !key
.endsWith(getSymbols().getEscapedDelimiter()));
}
/**
* Helper method that checks if the specified key starts with a property
* delimiter.
*
* @param key the key to check
* @return a flag if there is a leading delimiter
*/
private boolean hasLeadingDelimiter(final String key)
{
return key.startsWith(getSymbols().getPropertyDelimiter())
&& (getSymbols().getEscapedDelimiter() == null || !key
.startsWith(getSymbols().getEscapedDelimiter()));
}
/**
* Helper method for removing attribute markers from a key.
*
* @param key the key
* @return the key with removed attribute markers
*/
private String removeAttributeMarkers(final String key)
{
return key
.substring(
getSymbols().getAttributeStart().length(),
key.length()
- ((getSymbols().getAttributeEnd() != null) ? getSymbols()
.getAttributeEnd().length()
: 0));
}
/**
* Unescapes the delimiters in the specified string.
*
* @param key the key to be unescaped
* @return the unescaped key
*/
private String unescapeDelimiters(final String key)
{
return (getSymbols().getEscapedDelimiter() == null) ? key
: StringUtils.replace(key, getSymbols()
.getEscapedDelimiter(), getSymbols()
.getPropertyDelimiter());
}
/**
* Returns the symbols object from the associated expression engine.
*
* @return the {@code DefaultExpressionEngineSymbols}
*/
private DefaultExpressionEngineSymbols getSymbols()
{
return getExpressionEngine().getSymbols();
}
/**
* Escapes the delimiters in the specified string.
*
* @param key the key to be escaped
* @return the escaped key
*/
private String escapeDelimiters(final String key)
{
return (getSymbols().getEscapedDelimiter() == null || key
.indexOf(getSymbols().getPropertyDelimiter()) < 0) ? key
: StringUtils.replace(key, getSymbols()
.getPropertyDelimiter(), getSymbols()
.getEscapedDelimiter());
}
/**
* 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(final KeyIterator it1, final 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