/*

  * 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.configuration.tree.xpath;

 import java.util.List;

 import org.apache.commons.configuration.tree.ConfigurationNode;

 import org.apache.commons.jxpath.ri.model.NodeIterator;

 import org.apache.commons.jxpath.ri.model.NodePointer;

 /**

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

  *

  * @since 1.3

  * @author Oliver Heger

  * @version $Id: ConfigurationNodeIteratorBase.java 439648 2006-09-02 20:42:10Z oheger $

  */

 abstract class ConfigurationNodeIteratorBase implements NodeIterator

 {

     /** Stores the parent node pointer. */

     private NodePointer parent;

     /** Stores the list with the sub nodes. */

     private List subNodes;

     /** Stores the current position. */

     private int position;

     /** Stores the start offset of the iterator. */

     private int startOffset;

     /** Stores the reverse flag. */

     private boolean reverse;

     /**

      * Creates a new instance of <code>ConfigurationNodeIteratorBase</code>

      * and initializes it.

      *

      * @param parent the parent pointer

      * @param reverse the reverse flag

      */

     protected ConfigurationNodeIteratorBase(NodePointer parent, boolean reverse)

     {

         this.parent = parent;

         this.reverse = reverse;

     }

     /**

      * Returns the position of the iteration.

      *

      * @return the position

      */

     public int getPosition()

     {

         return position;

     }

     /**

      * Sets the position of the iteration.

      *

      * @param pos the new position

      * @return a flag if this is a valid position

      */

     public boolean setPosition(int pos)

     {

         position = pos;

         return pos >= 1 && pos <= getMaxPosition();

     }

     /**

      * Returns the current node pointer.

      *

      * @return the current pointer in this iteration

      */

     public NodePointer getNodePointer()

     {

         if (getPosition() < 1 && !setPosition(1))

         {

             return null;

         }

         return createNodePointer((ConfigurationNode) subNodes

                 .get(positionToIndex(getPosition())));

     }

     /**

      * Returns the parent node pointer.

      *

      * @return the parent node pointer

      */

     protected NodePointer getParent()

     {

         return parent;

     }

     /**

      * Returns the start offset of the iteration.

      *

      * @return the start offset

      */

     protected int getStartOffset()

     {

         return startOffset;

     }

     /**

      * Sets the start offset of the iteration. This is used when a start element

      * was set.

      *

      * @param startOffset the start offset

      */

     protected void setStartOffset(int startOffset)

     {

         this.startOffset = startOffset;

         if (reverse)

         {

             this.startOffset--;

         }

         else

         {

             this.startOffset++;

         }

     }

     /**

      * Initializes the list of sub nodes for the iteration. This method must be

      * called during initialization phase.

      *

      * @param nodes the list with the sub nodes

      */

     protected void initSubNodeList(List nodes)

     {

         subNodes = nodes;

         if (reverse)

         {

             setStartOffset(subNodes.size());

         }

     }

     /**

      * Returns the maximum position for this iterator.

      *

      * @return the maximum allowed position

      */

     protected int getMaxPosition()

     {

         return reverse ? getStartOffset() + 1 : subNodes.size()

                 - getStartOffset();

     }

     /**

      * Creates the configuration node pointer for the current position. This

      * method is called by <code>getNodePointer()</code>. Derived classes

      * must create the correct pointer object.

      *

      * @param node the current configuration node

      * @return the node pointer

      */

     protected NodePointer createNodePointer(ConfigurationNode node)

     {

         return new ConfigurationNodePointer(getParent(), node);

     }

     /**

      * 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(int pos)

     {

         return (reverse ? 1 - pos : pos - 1) + getStartOffset();

     }

 }