001/*
002 * Copyright (c) 2012, the Last.fm Java Project and Committers
003 * All rights reserved.
004 *
005 * Redistribution and use of this software in source and binary forms, with or without modification, are
006 * permitted provided that the following conditions are met:
007 *
008 * - Redistributions of source code must retain the above
009 *   copyright notice, this list of conditions and the
010 *   following disclaimer.
011 *
012 * - Redistributions in binary form must reproduce the above
013 *   copyright notice, this list of conditions and the
014 *   following disclaimer in the documentation and/or other
015 *   materials provided with the distribution.
016 *
017 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
018 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
019 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
020 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
021 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
022 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
023 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
024 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
025 */
026
027package de.umass.lastfm;
028
029import java.util.Collection;
030import java.util.Iterator;
031
032/**
033 * A <code>PaginatedResult</code> is returned by methods which result set might be so large that it needs
034 * to be paginated. Each <code>PaginatedResult</code> contains the total number of result pages, the current
035 * page and a <code>Collection</code> of entries for the current page.
036 *
037 * @author Janni Kovacs
038 */
039public class PaginatedResult<T> implements Iterable<T> {
040
041        private int page;
042        private int totalPages;
043        private Collection<T> pageResults;
044
045        PaginatedResult(int page, int totalPages, Collection<T> pageResults) {
046                this.page = page;
047                this.totalPages = totalPages;
048                this.pageResults = pageResults;
049        }
050
051        /**
052         * Returns the page number of this result.
053         *
054         * @return page number
055         */
056        public int getPage() {
057                return page;
058        }
059
060        /**
061         * Returns a list of entries of the type <code>T</code> for this page.
062         *
063         * @return page results
064         */
065        public Collection<T> getPageResults() {
066                return pageResults;
067        }
068
069        /**
070         * Returns the total number of pages available.
071         *
072         * @return total pages
073         */
074        public int getTotalPages() {
075                return totalPages;
076        }
077
078        /**
079         * Returns <code>true</code> if this Result contains no elements, which is the case for service calls that would have returned a
080         * <code>PaginatedResult</code> but fail.
081         *
082         * @return <code>true</code> if this result contains no elements
083         */
084        public boolean isEmpty() {
085                return pageResults == null || pageResults.isEmpty();
086        }
087
088        public Iterator<T> iterator() {
089                return getPageResults().iterator();
090        }
091}