package net.myvietnam.mvncore.configuration;

/* ====================================================================
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowlegement:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowlegement may appear in the software itself,
 *    if and wherever such third-party acknowlegements normally appear.
 *
 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 */

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 StringBuffer: There are
 * several <code>appendXXXX()</code> 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="mailto:oliver.heger@t-online.de">Oliver Heger</a>
 * @version $Id: ConfigurationKey.java,v 1.2 2004/10/10 16:51:13 minhnn Exp $
 */
public class ConfigurationKey implements Serializable
{
    /** 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 a property delimiter.*/
    private static final char PROPERTY_DELIMITER = '.';

    /** 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 StringBuffer size.*/
    private static final int INITIAL_SIZE = 32;

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

    /**
     * Creates a new, empty instance of <code>ConfigurationKey</code>.
     */
    public ConfigurationKey()
    {
        keyBuffer = new StringBuffer(INITIAL_SIZE);
    }

    /**
     * Creates a new instance of <code>ConfigurationKey</code> and
     * initializes it with the given key.
     * @param key the key as a string
     */
    public ConfigurationKey(String key)
    {
        keyBuffer = new StringBuffer(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);
        }  /* if */

        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 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)
    {
        StringBuffer buf = new StringBuffer();
        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
     */
    private 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()
    {
        return keyBuffer.length() > 0
        && keyBuffer.charAt(keyBuffer.length()-1) == PROPERTY_DELIMITER;
    }

    /**
     * Removes a trailing delimiter if there is any.
     */
    private void removeTrailingDelimiter()
    {
        while(hasDelimiter())
        {
            keyBuffer.deleteCharAt(keyBuffer.length()-1);
        }  /* while */
    }

    /**
     * Returns a string representation of this object. This is the
     * configuration key as a plain string.
     * @return a string for this object
     */
    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()</code> methods. The semantic is the same as
     * the <code>setLength()</code> method of <code>StringBuffer</code>.
     * @param len the new length of the key
     */
    public void setLength(int len)
    {
        keyBuffer.setLength(len);
    }

    /**
     * Checks if two <code>ConfigurationKey</code> 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
     */
    public boolean equals(Object c)
    {
        if(c == null)
        {
            return false;
        }  /* if */

        return keyBuffer.toString().equals(c.toString());
    }

    /**
     * Returns the hash code for this object.
     * @return the hash code
     */
    public int hashCode()
    {
        return 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!");
        }  /* if */

        ConfigurationKey result = new ConfigurationKey();
        KeyIterator it1 = iterator();
        KeyIterator it2 = other.iterator();

        while(it1.hasNext() && it2.hasNext()
        && partsEqual(it1, it2))
        {