Permalink
Browse files

Updated Javadoc (fixing issues creating warnings/errors in Javadoc 10).

  • Loading branch information...
Jean-Philippe Gariépy Jean-Philippe Gariépy
Jean-Philippe Gariépy authored and Jean-Philippe Gariépy committed Sep 25, 2018
1 parent 153b5ab commit d50255a183d04f3428ffa0a4d8e10831231ccf5e
@@ -1,16 +1,17 @@
<hmtl>

<body>
<p>Rivr is a lightweight open-source dialogue engine enabling Java developers to easily create
enterprise-grade VoiceXML applications.</p>
<p>Rivr is a lightweight open-source dialogue engine enabling Java developers to easily create enterprise-grade
VoiceXML applications.</p>

<p>Additionnal ressources:
<ul>
<li><a href="http://rivr.nuecho.com" target="_blank">Rivr website</a></li>
<li><a href="http://github.com/nuecho/rivr" target="_blank">Rivr at Gihtub</a></li>
<li><a href="http://github.com/nuecho/rivr-cookbook/wiki" target="_blank">Rivr cookbook</a>
- Learn by examples - A collection a various recipes explaining how to achieve various tasks
with Rvir</li>
<li><a href="https://github.com/nuecho/rivr" target="_blank">Rivr at Gihtub</a></li>
<li><a href="https://github.com/nuecho/rivr-cookbook/wiki" target="_blank">Rivr cookbook</a> - Learn by
examples - A collection a various recipes explaining how to achieve various tasks with Rivr</li>
<li>Voice Extensible Markup Language (VoiceXML) W3C Recommendation &ndash; <a
href="https://www.w3.org/TR/voicexml20/" target="_blank">Version 2.0</a>, <a
href="https://www.w3.org/TR/voicexml21/" target="_blank">Version 2.1</a></li>
</ul>

<p>Rivr is split into two modules:
@@ -19,9 +20,9 @@
<dd>Base engine allowing HTTP requests to interact with a dialogue.</dd>

<dt>VoiceXML</dt>
<dd>VoiceXML driver for generating W3C VoiceXML 2.1-compliant dialogues. This is the place
you look when coding VoiceXML dialogues with Rivr.</dd>
<dd>VoiceXML driver for generating W3C VoiceXML 2.1-compliant dialogues. This is the place you look when coding
VoiceXML dialogues with Rivr.</dd>
</dl>

</body>
</hmtl>
</hmtl>
@@ -19,7 +19,7 @@
* <p>
* Note: The {@link DialogueChannel} is typically wrapped in
* {@link DialogueContext}.
*
*
* @param <O> type of {@link OutputTurn}
* @param <I> type of {@link InputTurn}
* @author Nu Echo Inc.
@@ -29,7 +29,7 @@
/**
* Performs a turn exchange: the dialogue channel will return the
* {@link InputTurn}
*
*
* @param outputTurn The output turn to send. Cannot be <code>null</code>.
* @param timeout maximum time allowed to receive the turn from the
* dialogue. If <code>null</code>, uses the default value of this
@@ -45,11 +45,15 @@

/**
* Adds a listener to this dialogue channel.
*
* @param listener the listener to add.
*/
void addListener(DialogueChannelListener<I, O> listener);

/**
* Removes a listener from this dialogue channel.
*
* @param listener the listener to remove.
*/
void removeListener(DialogueChannelListener<I, O> listener);
}
@@ -13,7 +13,6 @@
* {@link com.nuecho.rivr.core.dialogue.DialogueContext}
* <p>
* How a dialogue is executed:
* <p>
* <ol>
* <li>The {@link com.nuecho.rivr.core.dialogue.Dialogue#run
* dialogue.run(FirstTurn firstTurn, DialogueContext context)} method is called
@@ -32,24 +32,26 @@
* send input turns to the dialogue. In exchange, the
* {@link SynchronousDialogueChannel} will return a {@link Step}:
* <ul>
* <li>{@link OutputTurnStep}: if the dialogue sends an OutputTurn in response</li>
* <li>{@link OutputTurnStep}: if the dialogue sends an OutputTurn in
* response</li>
* <li>{@link LastTurnStep}: when the dialogue is done</li>
* <li>{@link ErrorStep}: if an error occurred following the delivery of the
* {@link InputTurn}</li>
* </ul>
* <h3>States</h3>
* <p>
* <h3>States</h3> The {@link SynchronousDialogueChannel} has states related to
* the dialogue:
* The {@link SynchronousDialogueChannel} has states related to the dialogue:
* <ul>
* <li>started</li>
* <li>done</li>
* </ul>
* The {@link #isDialogueStarted()} and {@link #isDialogueDone()} methods
* correspond to those states. Additionally, the {@link #isDialogueActive()}
* method tells if the dialogue is <i>started</i> but not yet <i>done</i>.
* <h3>Time-out values</h3>
* <p>
* <h3>Time-out values</h3> The {@link SynchronousDialogueChannel} internally
* keeps two {@link SynchronousQueue SynchronousQueues}:
* The {@link SynchronousDialogueChannel} internally keeps two
* {@link SynchronousQueue SynchronousQueues}:
* <ul>
* <li>one for communication of output turn from the {@link Dialogue} to the
* controller</li>
@@ -81,7 +83,7 @@
* <b>5 seconds</b>. This property can be set with the
* {@link #setSendTimeout(Duration)} property.
* <p>
*
*
* @param <F> type of {@link FirstTurn}
* @param <L> type of {@link LastTurn}
* @param <O> type of {@link OutputTurn}
@@ -120,6 +122,8 @@
* when the controller sends the input turn to the dialogue and when the
* dialogue send the output turn, the last turn or an error to the
* controller.
*
* @return send duration
*/
public Duration getSendTimeout() {
return mSendTimeout;
@@ -133,7 +137,7 @@ public Duration getSendTimeout() {
* in a waiting state when the other thread sends the turn, the send
* operation should not block. For this reason, the default value for this
* property is <b>5 seconds</b>.
*
*
* @param sendTimeout The timeout value. Cannot be <code>null</code>. A
* value of Duration.ZERO (or equivalent) means to wait forever.
*/
@@ -147,6 +151,10 @@ public void setSendTimeout(Duration sendTimeout) {
* occurs when the controller sends the input turn to the dialogue and when
* the dialogue send the output turn, the last turn or an error to the
* controller.
*
* @return default time allowed for the dialogue to generate the next output
* turn, the last turn or an error when not specified by the
* controller.
*/
public Duration getDefaultReceiveFromDialogueTimeout() {
return mDefaultReceiveFromDialogueTimeout;
@@ -156,7 +164,7 @@ public Duration getDefaultReceiveFromDialogueTimeout() {
* Sets the maximum duration the controller thread can wait for a turn or an
* error from the dialogue thread when not specified by the controller. If
* this method is not called, it defaults to 1 minute.
*
*
* @param defaultReceiveFromDialogueTimeout The default timeout to use when
* not specified by the controller. Cannot be <code>null</code>.
*/
@@ -166,8 +174,11 @@ public void setDefaultReceiveFromDialogueTimeout(Duration defaultReceiveFromDial
}

/**
* Gets the maximum duration the controller thread can wait for a turn or an
* error from the dialogue thread when not specified by the controller.
* Gets the maximum duration the dialogue thread can wait for a turn from
* the controller thread when not specified by the dialogue.
*
* @return the maximum time allowed for the dialogue to wait for the
* controller.
*/
public Duration getDefaultReceiveFromControllerTimeout() {
return mDefaultReceiveFromControllerTimeout;
@@ -176,7 +187,7 @@ public Duration getDefaultReceiveFromControllerTimeout() {
/**
* Sets the maximum duration the dialogue thread can wait for a turn from
* the controller thread when not specified by the dialogue.
*
*
* @param defaultReceiveFromControllerTimeout The default timeout to use
* when not specified by the dialogue. Cannot be
* <code>null</code>.
@@ -188,7 +199,7 @@ public void setDefaultReceiveFromControllerTimeout(Duration defaultReceiveFromCo

/**
* Sets the logger for this dialogue channel.
*
*
* @param logger The logger. Cannot be <code>null</code>.
*/
public void setLogger(Logger logger) {
@@ -198,7 +209,7 @@ public void setLogger(Logger logger) {

/**
* Starts a {@link Dialogue} in a new thread.
*
*
* @param dialogue Dialogue to start. Cannot be <code>null</code>.
* @param firstTurn First turn used passed to
* {@link Dialogue#run(FirstTurn, DialogueContext)} method of the
@@ -210,8 +221,10 @@ public void setLogger(Logger logger) {
* @param context Dialogue context to pass to
* {@link Dialogue#run(FirstTurn, DialogueContext)} method of the
* dialogue. Cannot be <code>null</code>.
* @return the first Step of the dialogue.
* @throws Timeout If no result can be obtain from dialogue after delay
* specified by <code>timeout</code> parameter.
* @throws InterruptedException if the dialogue has been interrupted.
*/
public Step<O, L> start(final Dialogue<I, O, F, L, C> dialogue, final F firstTurn, Duration timeout, final C context)
throws Timeout, InterruptedException {
@@ -266,7 +279,7 @@ public void run() {

/**
* Tells if the dialogue has started.
*
*
* @return <code>true</code> if the dialogue has started, <code>false</code>
* otherwise.
*/
@@ -276,7 +289,7 @@ public boolean isDialogueStarted() {

/**
* Tells if the dialogue has ended.
*
*
* @return <code>true</code> if the dialogue has ended, <code>false</code>
* otherwise.
*/
@@ -286,7 +299,7 @@ public boolean isDialogueDone() {

/**
* Tells if the dialogue has started but not yet ended.
*
*
* @return <code>true</code> if the dialogue has started but not ended yet,
* <code>false</code> otherwise.
*/
@@ -296,9 +309,11 @@ public boolean isDialogueActive() {

/**
* Stops the dialogue and wait for the dialogue thread to end.
*
*
* @param timeout Time to wait for dialogue thread to terminate. A value of
* Duration.ZERO (or equivalent) means to wait forever.
* @throws InterruptedException if the current thread was interrupted while
* waiting for the dialogue thread to terminate.
*/
public void stop(Duration timeout) throws InterruptedException {
stop();
@@ -315,9 +330,11 @@ public void stop() {

/**
* Waits for the dialogue thread to end.
*
*
* @param timeout maximum time to wait for the thread to end. A value of
* Duration.ZERO (or equivalent) means to wait forever.
* @throws InterruptedException if the current thread was interrupted while
* waiting for the dialogue thread to terminate.
*/
public void join(Duration timeout) throws InterruptedException {
mDialogueThread.join(timeout.getMilliseconds());
@@ -326,7 +343,7 @@ public void join(Duration timeout) throws InterruptedException {
/**
* Performs a turn exchange: the dialogue channel will return the
* {@link InputTurn}
*
*
* @param turn The output turn to send. Cannot be <code>null</code>.
* @param timeout maximum time allowed to receive the turn from the
* dialogue. If <code>null</code>, uses the
@@ -352,14 +369,16 @@ public I doTurn(O turn, Duration timeout) throws Timeout, InterruptedException {

/**
* Performs a turn exchange: the dialogue channel will return the Step
*
*
* @param turn the input turn to send to the dialogue
* @param timeout maximum time allowed to receive the turn from the
* dialogue. If <code>null</code>, uses the
* <code>defaultReceiveFromDialogueTimeout</code> property. A
* value of Duration.ZERO (or equivalent) means to wait forever.
* @throws Timeout If no result can be obtain from dialogue after delay
* specified by <code>timeout</code> parameter.
* @throws InterruptedException if the thread was interrupted wile waiting
* for the dialogue step.
* @return the {@link Step} wrapping the dialogue next step
*/
public Step<O, L> doTurn(I turn, Duration timeout) throws Timeout, InterruptedException {
@@ -14,7 +14,7 @@
* interface or its subtypes. This interface provides a single method performing
* the dialogue, i.e. sequence of turn exchanges with the
* {@link DialogueChannel} and dialogue-related logic.
*
*
* @param <F> type of {@link FirstTurn}
* @param <L> type of {@link LastTurn}
* @param <O> type of {@link OutputTurn}
@@ -31,14 +31,16 @@
* allows the dialogue to access the {@link DialogueChannel} on which turn
* exchanges can be performed (i.e. exchanges of {@link OutputTurn
* OutputTurns} and {@link InputTurn InputTurns}).
*
*
* @param firstTurn First turn. Contains dialogue initialization
* information. Cannot be <code>null</code>.
* @param context Dialogue context. This context gives access to
* {@link DialogueChannel}, a {@link Logger} and the dialogue ID.
* Cannot be <code>null</code>.
* @return the result of the dialogue as a {@link LastTurn}. Cannot be
* <code>null</code>.
* @throws Exception when something prevents the dialogue from completing
* normally.
*/
L run(F firstTurn, C context) throws Exception;

@@ -9,7 +9,7 @@

/**
* Utility class for dialogue-related operations.
*
*
* @author Nu Echo Inc.
*/
public final class DialogueUtils {
@@ -20,6 +20,16 @@ private DialogueUtils() {

/**
* Performs turn exchange with default timeout.
*
* @param <I> input turn type.
* @param <O> output turn type.
* @param outputTurn the output turn to return to the controller (i.e. the
* servlet).
* @param context the dialogue context.
* @return the input turn provided by the controller.
* @throws Timeout if controller did not provided the input turn within the
* allocated time (default timeout)
* @throws InterruptedException if the dialogue was interrupted.
*/
public static <I extends InputTurn, O extends OutputTurn> I doTurn(O outputTurn, DialogueContext<I, O> context)
throws Timeout, InterruptedException {
@@ -28,6 +38,19 @@ private DialogueUtils() {

/**
* Performs turn exchange with specified timeout.
*
* @param <I> input turn type.
* @param <O> output turn type.
* @param outputTurn the output turn to return to the controller (i.e. the
* servlet).
* @param context the dialogue context.
* @param timeout maximum delay for the controller to provide the input
* turn.
* @return the input turn provided by the controller.
* @throws Timeout if controller did not provided the input turn within the
* allocated time (as provided by the <code>timeout</code>
* parameter)
* @throws InterruptedException if the dialogue was interrupted.
*/
public static <I extends InputTurn, O extends OutputTurn> I doTurn(O outputTurn,
DialogueContext<I, O> context,
Oops, something went wrong.

0 comments on commit d50255a

Please sign in to comment.