/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
 */
package org.apache.edgent.topology.tester;

import java.util.List;
import java.util.concurrent.TimeUnit;

import org.apache.edgent.execution.Job;
import org.apache.edgent.execution.Submitter;
import org.apache.edgent.topology.TStream;
import org.apache.edgent.topology.Topology;
import org.apache.edgent.topology.TopologyElement;

import com.google.gson.JsonObject;

/**
 * A {@code Tester} adds the ability to test a org.apache.edgent.org.apache.edgent.topology in a test framework such
 * as JUnit.
 * 
 * The main feature is the ability to capture tuples from a {@link TStream} in
 * order to perform some form of verification on them. There are two mechanisms
 * to perform verifications:
 * <UL>
 * <LI>did the stream produce the correct number of tuples.</LI>
 * <LI>did the stream produce the correct tuples.</LI>
 * </UL>
 * Currently, only streams that are instances of
 * {@code TStream<String>} can have conditions or handlers attached.
 * <P>
 * A {@code Tester} modifies its {@link Topology} to achieve the above purpose.
 * </P>
 */
public interface Tester extends TopologyElement {

    /**
     * Return a condition that evaluates if {@code stream} has submitted exactly
     * {@code expectedCount} number of tuples. The function may be evaluated
     * after the {@link Submitter#submit(Object, JsonObject) submit}
     * call has returned. <BR>
     * The {@link Condition#getResult() result} of the returned
     * {@code Condition} is the number of tuples seen on {@code stream} so far.
     * <BR>
     * If the org.apache.edgent.org.apache.edgent.topology is still executing then the returned values from
     * {@link Condition#valid()} and {@link Condition#getResult()} may change as
     * more tuples are seen on {@code stream}. <BR>
     * 
     * @param stream
     *            Stream to be tested.
     * @param expectedCount
     *            Number of tuples expected on {@code stream}.
     * @return True if the stream has submitted exactly {@code expectedCount}
     *         number of tuples, false otherwise.
     */
    Condition<Long> tupleCount(TStream<?> stream, long expectedCount);

    /**
     * Return a condition that evaluates if {@code stream} has submitted at
     * least {@code expectedCount} number of tuples. The function may be
     * evaluated after the
     * {@link Submitter#submit(Object, JsonObject) submit} call has returned. <BR>
     * The {@link Condition#getResult() result} of the returned
     * {@code Condition} is the number of tuples seen on {@code stream} so far.
     * <BR>
     * If the org.apache.edgent.org.apache.edgent.topology is still executing then the returned values from
     * {@link Condition#valid()} and {@link Condition#getResult()} may change as
     * more tuples are seen on {@code stream}. <BR>
     * 
     * @param stream
     *            Stream to be tested.
     * @param expectedCount
     *            Number of tuples expected on {@code stream}.
     * @return Condition that will return true the stream has submitted at least
     *         {@code expectedCount} number of tuples, false otherwise.
     */
    Condition<Long> atLeastTupleCount(TStream<?> stream, long expectedCount);

    /**
     * Return a condition that evaluates if {@code stream} has submitted
     * tuples matching {@code values} in the same order. <BR>
     * The {@link Condition#getResult() result} of the returned
     * {@code Condition} is the tuples seen on {@code stream} so far. <BR>
     * If the org.apache.edgent.org.apache.edgent.topology is still executing then the returned values from
     * {@link Condition#valid()} and {@link Condition#getResult()} may change as
     * more tuples are seen on {@code stream}. <BR>
     * 
     * @param <T> Tuple type
     * @param stream
     *            Stream to be tested.
     * @param values
     *            Expected tuples on {@code stream}.
     * @return Condition that will return true if the stream has submitted at
     *         least tuples matching {@code values} in the same order, false
     *         otherwise.
     */
    <T> Condition<List<T>> streamContents(TStream<T> stream, @SuppressWarnings("unchecked") T... values);

    /**
     * Return a condition that evaluates if {@code stream} has submitted
     * tuples matching {@code values} in any order. <BR>
     * The {@link Condition#getResult() result} of the returned
     * {@code Condition} is the tuples seen on {@code stream} so far. <BR>
     * If the org.apache.edgent.org.apache.edgent.topology is still executing then the returned values from
     * {@link Condition#valid()} and {@link Condition#getResult()} may change as
     * more tuples are seen on {@code stream}. <BR>
     *
     * @param <T> Tuple type
     * @param stream
     *            Stream to be tested.
     * @param values
     *            Expected tuples on {@code stream}.
     * @return Condition that will return true if the stream has submitted at
     *         least tuples matching {@code values} in the any order, false
     *         otherwise.
     */
    <T> Condition<List<T>> contentsUnordered(TStream<T> stream, @SuppressWarnings("unchecked") T... values);
    
    /**
     * Return a condition that is valid only if all of {@code conditions} are valid.
     * The result of the condition is {@link Condition#valid()}
     * @param conditions Conditions to AND together.
     * @return condition that is valid only if all of {@code conditions} are valid.
     */
    Condition<Boolean> and(final Condition<?>... conditions);

    /**
     * Submit the org.apache.edgent.org.apache.edgent.topology for this tester and wait for it to complete, or reach
     * an end condition. If the org.apache.edgent.org.apache.edgent.topology does not complete or reach its end
     * condition before {@code timeout} then it is terminated.
     * <P>
     * End condition is usually a {@link Condition} returned from
     * {@link #atLeastTupleCount(TStream, long)} or
     * {@link #tupleCount(TStream, long)} so that this method returns once the
     * stream has submitted a sufficient number of tuples. <BR>
     * Note that the condition will be only checked periodically up to
     * {@code timeout}, so that if the condition is only valid for a brief
     * period of time, then its valid state may not be seen, and thus this
     * method will wait for the timeout period.
     * </P>
     * 
     * @param submitter the {@link Submitter}
     * @param config
     *            submission configuration.
     * @param endCondition
     *            Condition that will cause this method to return if it is true.
     * @param timeout
     *            Maximum time to wait for the org.apache.edgent.org.apache.edgent.topology to complete or reach its
     *            end condition.
     * @param unit
     *            Unit for {@code timeout}.
     * @return The value of {@code endCondition.valid()}.
     * 
     * @throws Exception
     *             Failure submitting or executing the org.apache.edgent.org.apache.edgent.topology.
     */
    boolean complete(Submitter<Topology, ? extends Job> submitter, JsonObject config, Condition<?> endCondition,
            long timeout, TimeUnit unit) throws Exception;
    
    /**
     * Get the {@code Job} reference for the org.apache.edgent.org.apache.edgent.topology submitted by {@code complete()}.
     * @return {@code Job} reference for the org.apache.edgent.org.apache.edgent.topology submitted by {@code complete()}.
     * Null if the {@code complete()} has not been called or the {@code Job} instance is not yet available.
     */
    Job getJob();
}