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

nuecho · Sep 25, 2018 · d50255a · d50255a
1 parent 153b5ab
commit d50255a
Show file tree

Hide file tree

Showing 14 changed files with 270 additions and 115 deletions.
diff --git a/doc/javadoc-extra/overview.html b/doc/javadoc-extra/overview.html
@@ -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>
diff --git a/rivr-core/src/main/java/com/nuecho/rivr/core/channel/DialogueChannel.java b/rivr-core/src/main/java/com/nuecho/rivr/core/channel/DialogueChannel.java
@@ -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 @@ public interface DialogueChannel<I extends InputTurn, O extends OutputTurn> {
     /**
      * 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 @@ public interface DialogueChannel<I extends InputTurn, O extends OutputTurn> {
 
     /**
      * 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);
 }
diff --git a/rivr-core/src/main/java/com/nuecho/rivr/core/channel/package-info.java b/rivr-core/src/main/java/com/nuecho/rivr/core/channel/package-info.java
@@ -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

diff --git a/...re/src/main/java/com/nuecho/rivr/core/channel/synchronous/SynchronousDialogueChannel.java b/...re/src/main/java/com/nuecho/rivr/core/channel/synchronous/SynchronousDialogueChannel.java
@@ -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 @@ public final class SynchronousDialogueChannel<I extends InputTurn, O extends Out
      * 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 {

diff --git a/rivr-core/src/main/java/com/nuecho/rivr/core/dialogue/Dialogue.java b/rivr-core/src/main/java/com/nuecho/rivr/core/dialogue/Dialogue.java
@@ -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 @@ public interface Dialogue<I extends InputTurn, O extends OutputTurn, F extends F
      * 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;
 

diff --git a/rivr-core/src/main/java/com/nuecho/rivr/core/dialogue/DialogueUtils.java b/rivr-core/src/main/java/com/nuecho/rivr/core/dialogue/DialogueUtils.java
@@ -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 @@ public static <I extends InputTurn, O extends OutputTurn> I doTurn(O outputTurn,
 
     /**
      * 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,