feature: clearer SpokestackAdapter method names

This change adds convenience methods to the SpokestackAdapter
abstract class, allowing clients to override methods whose names
are more distinct when implemented together with the others.

Traces and errors are also duplicated from all individual modules
into new purpose-built listener methods.

src/main/java/io/spokestack/spokestack/SpokestackAdapter.java

@@ -9,7 +9,7 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * An abstract adapter class for receiving events from Spokestack subsystems.
+ * An abstract adapter class for receiving events from Spokestack modules.
  *
  * <p>
  * This class provides empty implementations of all Spokestack listener methods.
@@ -26,33 +26,53 @@ public abstract class SpokestackAdapter implements
     /**
      * Receive events from the speech pipeline.
      *
+     * <p>
+     * Clients should typically override {@link #speechEvent(SpeechContext.Event,
+     * SpeechContext)} instead of this method.
+     * </p>
+     *
      * @param event   The name of the event that was raised.
      * @param context The current speech context.
      */
     @Override
     public void onEvent(@NotNull SpeechContext.Event event,
                         @NotNull SpeechContext context) {
+        if (event == SpeechContext.Event.TRACE) {
+            trace(SpokestackModule.SPEECH_PIPELINE, context.getMessage());
+        } else if (event == SpeechContext.Event.ERROR) {
+            error(SpokestackModule.SPEECH_PIPELINE, context.getError());
+        }
+        speechEvent(event, context);
     }
 
     /**
-     * Receive trace messages from the NLU subsystem.
+     * Receive events from the speech pipeline.
      *
-     * @param level   The trace event's severity level.
-     * @param message the trace event's message.
+     * @param event   The name of the event that was raised.
+     * @param context The current speech context.
      */
-    @Override
-    public void onTrace(@NotNull EventTracer.Level level,
-                        @NotNull String message) {
+    public void speechEvent(@NotNull SpeechContext.Event event,
+                            @NotNull SpeechContext context) {
     }
 
     /**
-     * Receive events from the TTS subsystem.
+     * Called when an NLU classification result is available if this class is
+     * registered as a callback at classification time. Adapters added to a
+     * {@link Spokestack} class at build time are automatically registered for
+     * all classifications.
+     *
+     * <p>
+     * Clients should typically override {@link #nluResult(NLUResult)} instead
+     * of this method.
+     * </p>
      *
-     * @param event The event from the TTS subsystem.
+     * @param result The NLU result.
+     * @see io.spokestack.spokestack.nlu.tensorflow.TensorflowNLU#classify(String)
+     * @see io.spokestack.spokestack.util.AsyncResult
      */
     @Override
-    public void eventReceived(@NotNull TTSEvent event) {
-
+    public void call(@NotNull NLUResult result) {
+        nluResult(result);
     }
 
     /**
@@ -65,9 +85,7 @@ public void eventReceived(@NotNull TTSEvent event) {
      * @see io.spokestack.spokestack.nlu.tensorflow.TensorflowNLU#classify(String)
      * @see io.spokestack.spokestack.util.AsyncResult
      */
-    @Override
-    public void call(@NotNull NLUResult result) {
-
+    public void nluResult(@NotNull NLUResult result) {
     }
 
     /**
@@ -76,12 +94,80 @@ public void call(@NotNull NLUResult result) {
      * added to a {@link Spokestack} class at build time are automatically
      * registered for all classifications.
      *
+     * <p>
+     * Clients should typically override {@link #error(SpokestackModule,
+     * Throwable)} instead of this method.
+     * </p>
+     *
      * @param err An error generated during expected NLU classification.
      * @see io.spokestack.spokestack.nlu.tensorflow.TensorflowNLU#classify(String)
      * @see io.spokestack.spokestack.util.AsyncResult
      */
     @Override
     public void onError(@NotNull Throwable err) {
+        error(SpokestackModule.NLU, err);
+    }
+
+    /**
+     * Receive trace messages from the NLU module.
+     *
+     * <p>
+     * Clients should typically override {@link #trace(SpokestackModule,
+     * String)} instead of this method.
+     * </p>
+     *
+     * @param level   The trace event's severity level.
+     * @param message the trace event's message.
+     */
+    @Override
+    public void onTrace(@NotNull EventTracer.Level level,
+                        @NotNull String message) {
+        trace(SpokestackModule.NLU, message);
+    }
+
+    /**
+     * Receive events from the TTS module.
+     *
+     * <p>
+     * Clients should typically override {@link #ttsEvent(TTSEvent)} instead of
+     * this method.
+     * </p>
+     *
+     * @param event The event from the TTS module.
+     */
+    @Override
+    public void eventReceived(@NotNull TTSEvent event) {
+        if (event.type == TTSEvent.Type.ERROR) {
+            error(SpokestackModule.TTS, event.getError());
+        }
+        ttsEvent(event);
+    }
 
+    /**
+     * Receive events from the TTS module.
+     *
+     * @param event The event from the TTS module.
+     */
+    public void ttsEvent(@NotNull TTSEvent event) {
+    }
+
+    /**
+     * Receive trace messages from any module.
+     *
+     * @param module  The module where the message originated.
+     * @param message the trace event's message.
+     */
+    public void trace(@NotNull SpokestackModule module,
+                      @NotNull String message) {
+    }
+
+    /**
+     * Receive notifications of errors from any module.
+     *
+     * @param module The module where the error originated.
+     * @param err    An error generated during Spokestack operation.
+     */
+    public void error(@NotNull SpokestackModule module,
+                      @NotNull Throwable err) {
     }
 }

src/main/java/io/spokestack/spokestack/SpokestackModule.java

@@ -0,0 +1,12 @@
+package io.spokestack.spokestack;
+
+/**
+ * A simple list of Spokestack modules used for unified event dispatching.
+ */
+@SuppressWarnings("checkstyle:javadocvariable")
+public enum SpokestackModule {
+
+    SPEECH_PIPELINE,
+    NLU,
+    TTS
+}

src/test/java/io/spokestack/spokestack/SpokestackTest.java

@@ -284,6 +284,8 @@ static class TestAdapter extends SpokestackAdapter {
         LinkedBlockingQueue<TTSEvent> ttsEvents = new LinkedBlockingQueue<>();
         LinkedBlockingQueue<SpeechContext.Event> speechEvents =
               new LinkedBlockingQueue<>();
+        LinkedBlockingQueue<String> traces = new LinkedBlockingQueue<>();
+        LinkedBlockingQueue<Throwable> errors = new LinkedBlockingQueue<>();
 
         public void setSpokestack(Spokestack spokestack) {
             this.spokestack = spokestack;
@@ -294,28 +296,42 @@ public void clear() {
             this.speechEvents.clear();
             this.nluResults.clear();
             this.ttsEvents.clear();
+            this.traces.clear();
+            this.errors.clear();
         }
 
         @Override
-        public void onEvent(@NotNull SpeechContext.Event event,
-                            @NotNull SpeechContext context) {
+        public void speechEvent(@NotNull SpeechContext.Event event,
+                                @NotNull SpeechContext context) {
             this.speechEvents.add(event);
             this.speechContext = context;
         }
 
         @Override
-        public void eventReceived(@NotNull TTSEvent event) {
+        public void ttsEvent(@NotNull TTSEvent event) {
             this.ttsEvents.add(event);
         }
 
         @Override
-        public void call(@NotNull NLUResult result) {
+        public void nluResult(@NotNull NLUResult result) {
             this.nluResults.add(result);
             if (this.spokestack != null) {
                 SynthesisRequest request =
                       new SynthesisRequest.Builder(result.getIntent()).build();
                 this.spokestack.synthesize(request);
             }
         }
+
+        @Override
+        public void trace(@NotNull SpokestackModule module,
+                          @NotNull String message) {
+            this.traces.add(message);
+        }
+
+        @Override
+        public void error(@NotNull SpokestackModule module,
+                          @NotNull Throwable error) {
+            this.errors.add(error);
+        }
     }
 }