001/*
002 * Copyright (c) 2013 Nu Echo Inc. All rights reserved.
003 */
004
005package com.nuecho.rivr.core.channel;
006
007import com.nuecho.rivr.core.dialogue.*;
008import com.nuecho.rivr.core.servlet.*;
009import com.nuecho.rivr.core.util.*;
010
011/**
012 * Core concept of Rivr, a {@link DialogueChannel} is the interface between the
013 * {@link Dialogue} and the controller (such as the {@link DialogueServlet}).
014 * <p>
015 * The dialogue produces {@link OutputTurn OutputTurns} and sends them to the
016 * controller via the {@link #doTurn(OutputTurn, Duration)} method. The
017 * DialogueChannel will return the response from the controller as an
018 * {@link InputTurn}.
019 * <p>
020 * Note: The {@link DialogueChannel} is typically wrapped in
021 * {@link DialogueContext}.
022 *
023 * @param <O> type of {@link OutputTurn}
024 * @param <I> type of {@link InputTurn}
025 * @author Nu Echo Inc.
026 */
027public interface DialogueChannel<I extends InputTurn, O extends OutputTurn> {
028
029    /**
030     * Performs a turn exchange: the dialogue channel will return the
031     * {@link InputTurn}
032     *
033     * @param outputTurn The output turn to send. Cannot be <code>null</code>.
034     * @param timeout maximum time allowed to receive the turn from the
035     *            dialogue. If <code>null</code>, uses the default value of this
036     *            dialogue channel. A value of Duration.ZERO (or equivalent)
037     *            means to wait forever.
038     * @return the received {@link InputTurn}. Cannot be <code>null</code>.
039     * @throws Timeout if the dialogue channel has not been able to give the
040     *             InputTurn before <code>timeout</code> parameter.
041     * @throws InterruptedException if the thread has been interrupted while
042     *             waiting for the result.
043     */
044    I doTurn(O outputTurn, Duration timeout) throws Timeout, InterruptedException;
045
046    /**
047     * Adds a listener to this dialogue channel.
048     *
049     * @param listener the listener to add.
050     */
051    void addListener(DialogueChannelListener<I, O> listener);
052
053    /**
054     * Removes a listener from this dialogue channel.
055     *
056     * @param listener the listener to remove.
057     */
058    void removeListener(DialogueChannelListener<I, O> listener);
059}