001 /**
002 * Copyright (c) 2010, SIB. All rights reserved.
003 *
004 * SIB (Swiss Institute of Bioinformatics) - http://www.isb-sib.ch Host -
005 * https://sourceforge.net/projects/javaprotlib/
006 *
007 * Redistribution and use in source and binary forms, with or without
008 * modification, are permitted provided that the following conditions are met:
009 * Redistributions of source code must retain the above copyright notice, this
010 * list of conditions and the following disclaimer. Redistributions in binary
011 * form must reproduce the above copyright notice, this list of conditions and
012 * the following disclaimer in the documentation and/or other materials provided
013 * with the distribution. Neither the name of the SIB/GENEBIO nor the names of
014 * its contributors may be used to endorse or promote products derived from this
015 * software without specific prior written permission.
016 *
017 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
018 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
019 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
020 * ARE DISCLAIMED. IN NO EVENT SHALL SIB/GENEBIO BE LIABLE FOR ANY DIRECT,
021 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
022 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
023 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
024 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
026 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027 */
028 package org.expasy.jpl.commons.collection;
029
030
031 import java.util.ArrayList;
032 import java.util.Iterator;
033 import java.util.List;
034
035
036 /**
037 * {@code ExtraIterable} inherits from {@code Iterable} and adds the
038 * functionality of returning its next elements into a list.
039 * <p>
040 * The {@code Iterable} JPL object and the way iteration will be done are
041 * tightly coupled in this interface : the implementer will have to code an
042 * Iterator inner class that extends {@code AbstractIterator} and override
043 * {@code hasNext()} and {@code next()} methods.
044 *
045 * @param <T> the type of element in iteration.
046 *
047 * @author nikitin
048 *
049 * @version 1.0
050 *
051 */
052 public interface ExtraIterable<T> extends Iterable<T> {
053
054 /**
055 * Abstract inner class with default implementation of
056 * <code>nextToList</code> methods. <br>
057 * <code>hasNext()</code> and <code>next()</code> will have to be
058 * implemented.
059 */
060 public abstract class AbstractExtraIterator<T> implements Iterator<T> {
061
062 /** remove is not supported. */
063 public void remove() {
064 throw new UnsupportedOperationException("remove is not supported"
065 + " for JPLIterator");
066 }
067
068 /**
069 * Return a list with the next elements up to nValues. The number of
070 * element in the list can be lower than nValues if there is no more
071 * element to return.
072 *
073 * @param nValues the max number of elements to return.
074 * @return a list with the next elements.
075 */
076 public List<T> nextToList(final int nValues) {
077 final List<T> list = new ArrayList<T>();
078
079 int count = 0;
080 while (hasNext() && count < nValues) {
081 list.add(next());
082 count++;
083 }
084
085 return list;
086 }
087
088 /**
089 * Returns all elements into a list.
090 *
091 * @return a list with all the next elements up to the end.
092 */
093 public List<T> nextToList() {
094 final ArrayList<T> list = new ArrayList<T>();
095
096 while (hasNext()) {
097 list.add(next());
098 }
099
100 return list;
101 }
102 }
103
104 /**
105 * Returns a JPL iterator over a set of elements of type T.
106 *
107 * @return a JPL iterator.
108 */
109 public AbstractExtraIterator<T> iterator();
110 }