com.espertech.esper.runtime.client.EPIterable Maven / Gradle / Ivy

Go to download
/*
 ***************************************************************************************
 *  Copyright (C) 2006 EsperTech, Inc. All rights reserved.                            *
 *  http://www.espertech.com/esper                                                     *
 *  http://www.espertech.com                                                           *
 *  ---------------------------------------------------------------------------------- *
 *  The software in this package is published under the terms of the GPL license       *
 *  a copy of which has been included with this distribution in the license.txt file.  *
 ***************************************************************************************
 */
package com.espertech.esper.runtime.client;

import com.espertech.esper.common.client.EventBean;
import com.espertech.esper.common.client.context.ContextPartitionSelector;
import com.espertech.esper.common.client.util.SafeIterator;

import java.util.Iterator;

/**
 * Interface to iterate over events.
 */
public interface EPIterable {
    /**
     * Returns a concurrency-unsafe iterator over events representing statement results (pull API).
     * 
     * The iterator is useful for applications that are single-threaded, or that coordinate the iterating thread
     * with event processing threads that use the sendEvent method using application code locks or synchronization.
     * 

     * The iterator returned by this method does not make any guarantees towards correctness of
     * results and fail-behavior, if your application processes events into the runtime instance
     * using the sendEvent method by multiple threads.
     * 

     * Use the safeIterator method for concurrency-safe iteration. Note the safe iterator requires
     * applications to explicitly close the safe iterator when done iterating.
     *
     * @return event iterator
     */
    Iterator iterator();

    /**
     * Returns a concurrency-safe iterator that iterates over events representing statement results (pull API)
     * in the face of concurrent event processing by further threads.
     * 

     * In comparison to the regular iterator, the safe iterator guarantees correct results even
     * as events are being processed by other threads. The cost is that the iterator holds
     * one or more locks that must be released via the close method. Any locks are acquired
     * at the time this method is called.
     * 

     * This method is a blocking method. It may block until statement processing locks are released
     * such that the safe iterator can acquire any required locks.
     * 

     * An application MUST explicitly close the safe iterator instance using the close method, to release locks held by the
     * iterator. The call to the close method should be done in a finally block to make sure
     * the iterator gets closed.
     * 
     * Multiple safe iterators may be not be used at the same time by different application threads.
     * A single application thread may hold and use multiple safe iterators however this is discouraged.
     *
     * @return safe iterator; NOTE: Must use the close method to close the safe iterator, preferably in a finally block
     */
    SafeIterator safeIterator();

    /**
     * For use with statements that have a context declared and that may therefore have multiple context partitions,
     * allows to iterate over context partitions selectively.
     *
     * @param selector selects context partitions to consider
     * @return iterator
     */
    Iterator iterator(ContextPartitionSelector selector);

    /**
     * For use with statements that have a context declared and that may therefore have multiple context partitions,
     * allows to safe-iterate over context partitions selectively.
     *
     * @param selector selects context partitions to consider
     * @return safe iterator
     */
    SafeIterator safeIterator(ContextPartitionSelector selector);
}