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}