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}