/*
    * 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.tree.xpath;
  
  import org.apache.commons.configuration2.tree.NodeHandler;
  import org.apache.commons.jxpath.ri.QName;
  import org.apache.commons.jxpath.ri.model.NodeIterator;
  import org.apache.commons.jxpath.ri.model.NodePointer;
  import org.apache.commons.lang3.StringUtils;
  
  /**
   * <p>
   * A base class for implementing iterators over configuration nodes.
   * </p>
   * <p>
   * This class already provides common functionality for implementing the iteration process. Derived classes will
   * implement specific behavior based on the concrete node type (child node or attribute node).
   * </p>
   *
   * @param <T> the type of the nodes this iterator deals with
   * @since 1.3
   */
  abstract class AbstractConfigurationNodeIterator<T> implements NodeIterator {
      /** Constant for the prefix separator. */
      private static final String PREFIX_SEPARATOR = ":";
  
      /** A format for constructing a node name with a namespace prefix. */
      private static final String FMT_NAMESPACE = "%s" + PREFIX_SEPARATOR + "%s";
  
      /**
       * Generates a qualified name with a namespace prefix.
       *
       * @param prefix the prefix
       * @param name the name (may be <strong>null</strong>)
       * @return the qualified name
       */
      protected static String prefixName(final String prefix, final String name) {
          return String.format(FMT_NAMESPACE, prefix, StringUtils.defaultString(name));
      }
  
      /**
       * Returns the qualified name from the given {@code QName}. If the name has no namespace, result is the simple name.
       * Otherwise, the namespace prefix is added.
       *
       * @param qName the {@code QName}
       * @return the qualified name
       */
      protected static String qualifiedName(final QName qName) {
          return qName.getPrefix() == null ? qName.getName() : prefixName(qName.getPrefix(), qName.getName());
      }
  
      /** Stores the parent node pointer. */
      private final ConfigurationNodePointer<T> parent;
  
      /** Stores the current position. */
      private int position;
  
      /** Stores the start offset of the iterator. */
      private int startOffset;
  
      /** Stores the reverse flag. */
      private final boolean reverse;
  
      /**
       * Creates a new instance of {@code ConfigurationNodeIteratorBase} and initializes it.
       *
       * @param parent the parent pointer
       * @param reverse the reverse flag
       */
      protected AbstractConfigurationNodeIterator(final ConfigurationNodePointer<T> parent, final boolean reverse) {
          this.parent = parent;
          this.reverse = reverse;
      }
  
      /**
       * Creates the configuration node pointer for the current position. This method is called by {@code getNodePointer()}.
       * Derived classes must create the correct pointer object.
       *
       * @param position the current position in the iteration
       * @return the node pointer
       */
      protected abstract NodePointer createNodePointer(int position);
  
      /**
       * Gets the maximum position for this iterator.
      *
      * @return the maximum allowed position
      */
     protected int getMaxPosition() {
         return reverse ? getStartOffset() + 1 : size() - getStartOffset();
     }
 
     /**
      * Gets the node handler for the managed nodes. This is a convenience method.
      *
      * @return the node handler
      */
     protected NodeHandler<T> getNodeHandler() {
         return getParent().getNodeHandler();
     }
 
     /**
      * Gets the current node pointer.
      *
      * @return the current pointer in this iteration
      */
     @Override
     public NodePointer getNodePointer() {
         if (getPosition() < 1 && !setPosition(1)) {
             return null;
         }
 
         return createNodePointer(positionToIndex(getPosition()));
     }
 
     /**
      * Gets the parent node pointer.
      *
      * @return the parent node pointer
      */
     protected ConfigurationNodePointer<T> getParent() {
         return parent;
     }
 
     /**
      * Gets the position of the iteration.
      *
      * @return the position
      */
     @Override
     public int getPosition() {
         return position;
     }
 
     /**
      * Gets the start offset of the iteration.
      *
      * @return the start offset
      */
     protected int getStartOffset() {
         return startOffset;
     }
 
     /**
      * Returns the index in the data list for the given position. This method also checks the reverse flag.
      *
      * @param pos the position (1-based)
      * @return the corresponding list index
      */
     protected int positionToIndex(final int pos) {
         return (reverse ? 1 - pos : pos - 1) + getStartOffset();
     }
 
     /**
      * Sets the position of the iteration.
      *
      * @param pos the new position
      * @return a flag if this is a valid position
      */
     @Override
     public boolean setPosition(final int pos) {
         position = pos;
         return pos >= 1 && pos <= getMaxPosition();
     }
 
     /**
      * Sets the start offset of the iteration. This is used when a start element was set.
      *
      * @param startOffset the start offset
      */
     protected void setStartOffset(final int startOffset) {
         this.startOffset = startOffset;
         if (reverse) {
             this.startOffset--;
         } else {
             this.startOffset++;
         }
     }
 
     /**
      * Returns the number of elements in this iteration.
      *
      * @return the number of elements
      */
     protected abstract int size();
 }