/*
 * 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;

import java.util.Iterator;

import org.apache.commons.configuration2.convert.ListDelimiterHandler;

A subset of another configuration. The new Configuration object contains
every key from the parent Configuration that starts with prefix. The prefix
is removed from the keys in the subset.
It is usually not necessary to use this class directly. Instead the Configuration.subset(String) method should be used, which will return a correctly initialized instance.
/**
 * <p>A subset of another configuration. The new Configuration object contains
 * every key from the parent Configuration that starts with prefix. The prefix
 * is removed from the keys in the subset.</p>
 * <p>It is usually not necessary to use this class directly. Instead the
 * {@link Configuration#subset(String)} method should be used,
 * which will return a correctly initialized instance.</p>
 *
 */
public class SubsetConfiguration extends AbstractConfiguration
{
    
The parent configuration. /** The parent configuration. */
    protected Configuration parent;

    
The prefix used to select the properties. /** The prefix used to select the properties. */
    protected String prefix;

    
The prefix delimiter /** The prefix delimiter */
    protected String delimiter;

    
Create a subset of the specified configuration
Params:
parent – The parent configuration (must not be null)
prefix – The prefix used to select the properties
Throws:
IllegalArgumentException – if the parent configuration is null/**
     * Create a subset of the specified configuration
     *
     * @param parent The parent configuration (must not be <b>null</b>)
     * @param prefix The prefix used to select the properties
     * @throws IllegalArgumentException if the parent configuration is <b>null</b>
     */
    public SubsetConfiguration(final Configuration parent, final String prefix)
    {
        this(parent, prefix, null);
    }

    
Create a subset of the specified configuration
Params:
parent – The parent configuration (must not be null)
prefix –    The prefix used to select the properties
delimiter – The prefix delimiter
Throws:
IllegalArgumentException – if the parent configuration is null/**
     * Create a subset of the specified configuration
     *
     * @param parent The parent configuration (must not be <b>null</b>)
     * @param prefix    The prefix used to select the properties
     * @param delimiter The prefix delimiter
     * @throws IllegalArgumentException if the parent configuration is <b>null</b>
     */
    public SubsetConfiguration(final Configuration parent, final String prefix, final String delimiter)
    {
        if (parent == null)
        {
            throw new IllegalArgumentException(
                    "Parent configuration must not be null!");
        }

        this.parent = parent;
        this.prefix = prefix;
        this.delimiter = delimiter;
        initInterpolator();
    }

    
Return the key in the parent configuration associated to the specified
key in this subset.
Params:
key – The key in the subset.
Returns:
the key as to be used by the parent/**
     * Return the key in the parent configuration associated to the specified
     * key in this subset.
     *
     * @param key The key in the subset.
     * @return the key as to be used by the parent
     */
    protected String getParentKey(final String key)
    {
        if ("".equals(key) || key == null)
        {
            return prefix;
        }
        return delimiter == null ? prefix + key : prefix + delimiter + key;
    }

    
Return the key in the subset configuration associated to the specified
key in the parent configuration.
Params:
key – The key in the parent configuration.
Returns:
the key in the context of this subset configuration/**
     * Return the key in the subset configuration associated to the specified
     * key in the parent configuration.
     *
     * @param key The key in the parent configuration.
     * @return the key in the context of this subset configuration
     */
    protected String getChildKey(final String key)
    {
        if (!key.startsWith(prefix))
        {
            throw new IllegalArgumentException("The parent key '" + key + "' is not in the subset.");
        }
        String modifiedKey = null;
        if (key.length() == prefix.length())
        {
            modifiedKey = "";
        }
        else
        {
            final int i = prefix.length() + (delimiter != null ? delimiter.length() : 0);
            modifiedKey = key.substring(i);
        }

        return modifiedKey;
    }

    
Return the parent configuration for this subset.
Returns:
the parent configuration/**
     * Return the parent configuration for this subset.
     *
     * @return the parent configuration
     */
    public Configuration getParent()
    {
        return parent;
    }

    
Return the prefix used to select the properties in the parent configuration.
Returns:
the prefix used by this subset/**
     * Return the prefix used to select the properties in the parent configuration.
     *
     * @return the prefix used by this subset
     */
    public String getPrefix()
    {
        return prefix;
    }

    
Set the prefix used to select the properties in the parent configuration.
Params:
prefix – the prefix/**
     * Set the prefix used to select the properties in the parent configuration.
     *
     * @param prefix the prefix
     */
    public void setPrefix(final String prefix)
    {
        this.prefix = prefix;
    }

    @Override
    public Configuration subset(final String prefix)
    {
        return parent.subset(getParentKey(prefix));
    }

    @Override
    protected boolean isEmptyInternal()
    {
        return !getKeysInternal().hasNext();
    }

    @Override
    protected boolean containsKeyInternal(final String key)
    {
        return parent.containsKey(getParentKey(key));
    }

    @Override
    public void addPropertyDirect(final String key, final Object value)
    {
        parent.addProperty(getParentKey(key), value);
    }

    @Override
    protected void clearPropertyDirect(final String key)
    {
        parent.clearProperty(getParentKey(key));
    }

    @Override
    protected Object getPropertyInternal(final String key)
    {
        return parent.getProperty(getParentKey(key));
    }

    @Override
    protected Iterator<String> getKeysInternal(final String prefix)
    {
        return new SubsetIterator(parent.getKeys(getParentKey(prefix)));
    }

    @Override
    protected Iterator<String> getKeysInternal()
    {
        return new SubsetIterator(parent.getKeys(prefix));
    }

    
{@inheritDoc}
Change the behavior of the parent configuration if it supports this feature.
/**
     * {@inheritDoc}
     *
     * Change the behavior of the parent configuration if it supports this feature.
     */
    @Override
    public void setThrowExceptionOnMissing(final boolean throwExceptionOnMissing)
    {
        if (parent instanceof AbstractConfiguration)
        {
            ((AbstractConfiguration) parent).setThrowExceptionOnMissing(throwExceptionOnMissing);
        }
        else
        {
            super.setThrowExceptionOnMissing(throwExceptionOnMissing);
        }
    }

    
{@inheritDoc}
The subset inherits this feature from its parent if it supports this feature.
/**
     * {@inheritDoc}
     *
     * The subset inherits this feature from its parent if it supports this feature.
     */
    @Override
    public boolean isThrowExceptionOnMissing()
    {
        if (parent instanceof AbstractConfiguration)
        {
            return ((AbstractConfiguration) parent).isThrowExceptionOnMissing();
        }
        return super.isThrowExceptionOnMissing();
    }

    
{@inheritDoc} If the parent configuration extends AbstractConfiguration, the list delimiter handler is obtained from there. /**
     * {@inheritDoc} If the parent configuration extends
     * {@link AbstractConfiguration}, the list delimiter handler is obtained
     * from there.
     */
    @Override
    public ListDelimiterHandler getListDelimiterHandler()
    {
        return parent instanceof AbstractConfiguration ? ((AbstractConfiguration) parent)
                .getListDelimiterHandler() : super.getListDelimiterHandler();
    }

    
{@inheritDoc} If the parent configuration extends AbstractConfiguration, the list delimiter handler is passed to the parent. /**
     * {@inheritDoc} If the parent configuration extends
     * {@link AbstractConfiguration}, the list delimiter handler is passed to
     * the parent.
     */
    @Override
    public void setListDelimiterHandler(
            final ListDelimiterHandler listDelimiterHandler)
    {
        if (parent instanceof AbstractConfiguration)
        {
            ((AbstractConfiguration) parent)
                    .setListDelimiterHandler(listDelimiterHandler);
        }
        else
        {
            super.setListDelimiterHandler(listDelimiterHandler);
        }
    }

    
Initializes the ConfigurationInterpolator for this sub configuration. This is a standard ConfigurationInterpolator which also references the ConfigurationInterpolator of the parent configuration. /**
     * Initializes the {@code ConfigurationInterpolator} for this sub configuration.
     * This is a standard {@code ConfigurationInterpolator} which also references
     * the {@code ConfigurationInterpolator} of the parent configuration.
     */
    private void initInterpolator()
    {
        getInterpolator().setParentInterpolator(getParent().getInterpolator());
    }

    
A specialized iterator to be returned by the getKeys() methods. This implementation wraps an iterator from the parent configuration. The keys returned by this iterator are correspondingly transformed. /**
     * A specialized iterator to be returned by the {@code getKeys()}
     * methods. This implementation wraps an iterator from the parent
     * configuration. The keys returned by this iterator are correspondingly
     * transformed.
     */
    private class SubsetIterator implements Iterator<String>
    {
        
Stores the wrapped iterator. /** Stores the wrapped iterator. */
        private final Iterator<String> parentIterator;

        
Creates a new instance of SubsetIterator and initializes it with the parent iterator. 
Params:
it – the iterator of the parent configuration/**
         * Creates a new instance of {@code SubsetIterator} and
         * initializes it with the parent iterator.
         *
         * @param it the iterator of the parent configuration
         */
        public SubsetIterator(final Iterator<String> it)
        {
            parentIterator = it;
        }

        
Checks whether there are more elements. Delegates to the parent
iterator.
Returns:
a flag whether there are more elements/**
         * Checks whether there are more elements. Delegates to the parent
         * iterator.
         *
         * @return a flag whether there are more elements
         */
        @Override
        public boolean hasNext()
        {
            return parentIterator.hasNext();
        }

        
Returns the next element in the iteration. This is the next key from
the parent configuration, transformed to correspond to the point of
view of this subset configuration.
Returns:
the next element/**
         * Returns the next element in the iteration. This is the next key from
         * the parent configuration, transformed to correspond to the point of
         * view of this subset configuration.
         *
         * @return the next element
         */
        @Override
        public String next()
        {
            return getChildKey(parentIterator.next());
        }

        
Removes the current element from the iteration. Delegates to the
parent iterator.
/**
         * Removes the current element from the iteration. Delegates to the
         * parent iterator.
         */
        @Override
        public void remove()
        {
            parentIterator.remove();
        }
    }
}