001/* 002 * Copyright (c) 2013 Nu Echo Inc. All rights reserved. 003 */ 004 005package com.nuecho.rivr.core.dialogue; 006 007import org.slf4j.*; 008 009import com.nuecho.rivr.core.channel.*; 010import com.nuecho.rivr.core.servlet.*; 011 012/** 013 * Rivr applications are expected to provide one or many implementations of this 014 * interface or its subtypes. This interface provides a single method performing 015 * the dialogue, i.e. sequence of turn exchanges with the 016 * {@link DialogueChannel} and dialogue-related logic. 017 * 018 * @param <F> type of {@link FirstTurn} 019 * @param <L> type of {@link LastTurn} 020 * @param <O> type of {@link OutputTurn} 021 * @param <I> type of {@link InputTurn} 022 * @param <C> type of {@link DialogueContext} 023 * @author Nu Echo Inc. 024 */ 025public interface Dialogue<I extends InputTurn, O extends OutputTurn, F extends FirstTurn, L extends LastTurn, C extends DialogueContext<I, O>> { 026 027 /** 028 * Method called by the controller (e.g. {@link DialogueServlet}) to run the 029 * dialogue. It takes initial parameters from the <code>firstTurn</code> 030 * parameter and must return a {@link LastTurn}. The <code>context</code> 031 * allows the dialogue to access the {@link DialogueChannel} on which turn 032 * exchanges can be performed (i.e. exchanges of {@link OutputTurn 033 * OutputTurns} and {@link InputTurn InputTurns}). 034 * 035 * @param firstTurn First turn. Contains dialogue initialization 036 * information. Cannot be <code>null</code>. 037 * @param context Dialogue context. This context gives access to 038 * {@link DialogueChannel}, a {@link Logger} and the dialogue ID. 039 * Cannot be <code>null</code>. 040 * @return the result of the dialogue as a {@link LastTurn}. Cannot be 041 * <code>null</code>. 042 * @throws Exception when something prevents the dialogue from completing 043 * normally. 044 */ 045 L run(F firstTurn, C context) throws Exception; 046 047}