/*
    * 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
    *
    *     https://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 java.util.Objects;
  
  import org.apache.commons.configuration2.convert.ListDelimiterHandler;
  import org.apache.commons.lang3.StringUtils;
  
  /**
   * <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 {
  
      /**
       * 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 final class SubsetIterator implements Iterator<String> {
  
          /** Stores the wrapped iterator. */
          private final Iterator<String> parentIterator;
  
          /**
           * 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.
           *
           * @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.
           *
           * @return the next element
           */
          @Override
          public String next() {
              return getChildKey(parentIterator.next());
          }
  
          /**
           * Removes the current element from the iteration. Delegates to the parent iterator.
           */
          @Override
          public void remove() {
              parentIterator.remove();
          }
      }
  
      /** The parent configuration. */
      protected Configuration parent;
  
      /** The prefix used to select the properties. */
      protected String prefix;
  
      /** The prefix delimiter */
      protected String delimiter;
  
      /**
       * Create a subset of the specified configuration
       *
       * @param parent The parent configuration (must not be <strong>null</strong>)
       * @param prefix The prefix used to select the properties
      * @throws IllegalArgumentException if the parent configuration is <strong>null</strong>
      */
     public SubsetConfiguration(final Configuration parent, final String prefix) {
         this(parent, prefix, null);
     }
 
     /**
      * Create a subset of the specified configuration
      *
      * @param parent The parent configuration (must not be <strong>null</strong>)
      * @param prefix The prefix used to select the properties
      * @param delimiter The prefix delimiter
      * @throws NullPointerException if the parent configuration is <strong>null</strong>
      */
     public SubsetConfiguration(final Configuration parent, final String prefix, final String delimiter) {
         this.parent = Objects.requireNonNull(parent, "parent");
         this.prefix = prefix;
         this.delimiter = delimiter;
         initInterpolator();
     }
 
     @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 boolean containsKeyInternal(final String key) {
         return parent.containsKey(getParentKey(key));
     }
 
     /**
      * Tests whether this configuration contains one or more matches to this value. This operation stops at first match
      * but may be more expensive than the containsKey method.
      *
      * @since 2.11.0
      */
     @Override
     protected boolean containsValueInternal(final Object value) {
         return parent.containsValue(value);
     }
 
     /**
      * Gets 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;
     }
 
     @Override
     protected Iterator<String> getKeysInternal() {
         return new SubsetIterator(parent.getKeys(prefix, delimiter));
     }
 
     @Override
     protected Iterator<String> getKeysInternal(final String prefix) {
         return new SubsetIterator(parent.getKeys(getParentKey(prefix)));
     }
 
     /**
      * {@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();
     }
 
     /**
      * Gets the parent configuration for this subset.
      *
      * @return the parent configuration
      */
     public Configuration getParent() {
         return parent;
     }
 
     /**
      * Gets 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 (StringUtils.isEmpty(key)) {
             return prefix;
         }
         return delimiter == null ? prefix + key : prefix + delimiter + key;
     }
 
     /**
      * Gets the prefix used to select the properties in the parent configuration.
      *
      * @return the prefix used by this subset
      */
     public String getPrefix() {
         return prefix;
     }
 
     @Override
     protected Object getPropertyInternal(final String key) {
         return parent.getProperty(getParentKey(key));
     }
 
     /**
      * 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());
     }
 
     @Override
     protected boolean isEmptyInternal() {
         return !getKeysInternal().hasNext();
     }
 
     /**
      * {@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 {@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);
         }
     }
 
     /**
      * Sets the prefix used to select the properties in the parent configuration.
      *
      * @param prefix the prefix
      */
     public void setPrefix(final String prefix) {
         this.prefix = prefix;
     }
 
     /**
      * {@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);
         }
     }
 
     @Override
     public Configuration subset(final String prefix) {
         return parent.subset(getParentKey(prefix));
     }
 }