001/*
002 *  Copyright 2016 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.repository;
017
018import java.util.Iterator;
019import java.util.NoSuchElementException;
020
021/**
022 * Iterates over {@link AmetysObject}s.
023 * @param <A> the actual type of {@link AmetysObject}s.
024 */
025public interface AmetysObjectIterator<A extends AmetysObject> extends Iterator<A>
026{
027    /**
028     * Returns the current position within the iterator. The number
029     * returned is the 0-based index of the next element in the iterator,
030     * i.e. the one that will be returned on the subsequent <code>next</code> call.
031     * <br>
032     * Note that this method does not check if there is a next element,
033     * i.e. an empty iterator will always return 0.
034     *
035     * @return a long
036     */
037    long getPosition();
038    
039    /**
040     * Returns the number of elements in the iterator.
041     * If this information is unavailable, returns -1.
042     * @return a long
043     */
044    long getSize();
045    
046    /**
047     * Skip a number of elements in the iterator. <br>
048     * The default implementation simply calls <code>skipNum</code> times {@link #next()}.
049     * @param skipNum the non-negative number of elements to skip
050     * @throws java.util.NoSuchElementException if skipped past the last element in the iterator.
051     */
052    default void skip(long skipNum)
053    {
054        if (skipNum == 0)
055        {
056            return;
057        }
058        
059        if (skipNum < 0)
060        {
061            throw new AmetysRepositoryException("Cannot skip with a negative number");
062        }
063        
064        long size = getSize();
065        if (size != -1 && skipNum > size - getPosition())
066        {
067            throw new NoSuchElementException();
068        }
069        
070        for (long i = skipNum; i > 0; i--)
071        {
072            next();
073        }
074    }
075}