001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Florent Guillaume
011 */
012package org.nuxeo.ecm.core.api;
013
014import java.io.Serializable;
015import java.util.Map;
016
017/**
018 * An iterable query result based on a cursor.
019 * <p>
020 * The {@link #close()} method MUST be called when the query result is no more needed, otherwise underlying resources
021 * will be leaked. There is no auto-closing at the end of the iteration.
022 */
023public interface IterableQueryResult extends Iterable<Map<String, Serializable>> {
024
025    /**
026     * Closes the query result and releases the underlying resources held by the cursor.
027     * <p>
028     * This MUST be called when the query result is no more needed, otherwise underlying resources will be leaked. There
029     * is no auto-closing at the end of the iteration.
030     */
031    void close();
032
033    /**
034     * Indicates if the query result has not been closed
035     * 
036     * @return
037     */
038    boolean isLife();
039
040    /**
041     * Gets the total size of the query result.
042     * <p>
043     * Note that this may be costly, and that some backends may not be able to do this operation, in which case
044     * {@code -1} will be returned.
045     *
046     * @return the size, or {@code -1} for an unknown size
047     */
048    long size();
049
050    /**
051     * Gets the current position in the iterator.
052     * <p>
053     * Positions start at {@code 0}.
054     *
055     * @return the position
056     */
057    long pos();
058
059    /**
060     * Skips to a given position in the iterator.
061     * <p>
062     * Positions start at {@code 0}.
063     */
064    void skipTo(long pos);
065
066}