forester/java/src/org/forester/phylogeny/iterators/LevelOrderTreeIterator.java

   1 // $Id:
   2 // FORESTER -- software libraries and applications
   3 // for evolutionary biology research and applications.
   4 //
   5 // Copyright (C) 2008-2009 Christian M. Zmasek
   6 // Copyright (C) 2008-2009 Burnham Institute for Medical Research
   7 // All rights reserved
   8 //
   9 // This library is free software; you can redistribute it and/or
  10 // modify it under the terms of the GNU Lesser General Public
  11 // License as published by the Free Software Foundation; either
  12 // version 2.1 of the License, or (at your option) any later version.
  13 //
  14 // This library is distributed in the hope that it will be useful,
  15 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17 // Lesser General Public License for more details.
  18 //
  19 // You should have received a copy of the GNU Lesser General Public
  20 // License along with this library; if not, write to the Free Software
  21 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  22 //
  23 // Contact: phylosoft @ gmail . com
  24 // WWW: www.phylosoft.org/forester
  25
  26 package org.forester.phylogeny.iterators;
  27
  28 import java.util.NoSuchElementException;
  29
  30 import org.forester.datastructures.Queue;
  31 import org.forester.phylogeny.Phylogeny;
  32 import org.forester.phylogeny.PhylogenyNode;
  33
  34 /*
  35  * An iterator to iterate a Phylogeny in level order.
  36  *
  37  * Created: 10/23/2005 by Christian M. Zmasek. Last modified: 10/23/2005 by
  38  * Christian M. Zmasek.
  39  *
  40  * @author Christian M. Zmasek
  41  *
  42  * @version 1.000
  43  */
  44 public class LevelOrderTreeIterator implements PhylogenyNodeIterator {
  45
  46     // Instance variables
  47     // ------------------
  48     private final Queue         _queue;
  49     private final PhylogenyNode _root;
  50
  51     // Constructors
  52     // ------------
  53     /**
  54      * Creates a new LevelOrderTreeIterator for iterating over all the nodes of
  55      * Phylogeny phylogeny
  56      *
  57      * @param phylogeny
  58      *            the Phylogeny to iterate over
  59      * @throws IllegalArgumentException
  60      *             if phylogeny is empty
  61      */
  62     public LevelOrderTreeIterator( final Phylogeny phylogeny ) throws IllegalArgumentException {
  63         this( phylogeny.getRoot() );
  64         if ( phylogeny.isEmpty() ) {
  65             throw new IllegalArgumentException( "Attempt to use LevelOrderTreeIterator on an empty phylogeny." );
  66         }
  67     }
  68
  69     /**
  70      * Creates a new LevelOrderTreeIterator for iterating over all the child
  71      * nodes of PhylogenyNode node (including node itself).
  72      *
  73      * @param node
  74      *            the parent of the nodes to iterate over
  75      */
  76     public LevelOrderTreeIterator( final PhylogenyNode node ) {
  77         _queue = new Queue();
  78         _root = node;
  79         reset();
  80     }
  81
  82     // Private methods
  83     // ---------------
  84     /**
  85      * Returns the queue upon which this iterator is based.
  86      *
  87      */
  88     private Queue getQueue() {
  89         return _queue;
  90     }
  91
  92     /**
  93      * Returns the root of the phylogeny this iterators parses over.
  94      *
  95      * @return the root of the phylogeny this iterators parses over.
  96      */
  97     private PhylogenyNode getRoot() {
  98         return _root;
  99     }
 100
 101     // Public methods
 102     // --------------
 103     /**
 104      * Returns true is this iterator has at least one more element, false
 105      * otherwise.
 106      *
 107      * @return true is this iterator has at least one more element, false
 108      *         otherwise
 109      */
 110     @Override
 111     public boolean hasNext() {
 112         return !getQueue().isEmpty();
 113     }
 114
 115     /**
 116      * Returns the next PhylogenyNode.
 117      *
 118      * @return the next PhylogenyNode
 119      * @throws NoSuchElementException
 120      *             if iteration is complete
 121      */
 122     @Override
 123     public PhylogenyNode next() throws NoSuchElementException {
 124         if ( !hasNext() ) {
 125             throw new NoSuchElementException( "Attempt to call \"next()\" on iterator which has no more next elements." );
 126         }
 127         final PhylogenyNode node = ( PhylogenyNode ) getQueue().dequeue();
 128         for( int i = 0; i < node.getNumberOfDescendants(); ++i ) {
 129             getQueue().enqueue( node.getChildNode( i ) );
 130         }
 131         return node;
 132     }
 133
 134     /**
 135      * Not supported.
 136      *
 137      */
 138     @Override
 139     public void remove() {
 140         throw new UnsupportedOperationException();
 141     }
 142
 143     /**
 144      * Resets the iterator.
 145      */
 146     @Override
 147     public void reset() {
 148         getQueue().clear();
 149         getQueue().enqueue( getRoot() );
 150     }
 151 } // enod of class LevelOrderTreeIterator