Added EventMessage overload to event broadcast and some documentation

Author: cesmec

src/main/scala/org/codeoverflow/chatoverflow/framework/manager/PluginManagerImpl.scala

@@ -4,9 +4,7 @@ import java.util
 
 import org.codeoverflow.chatoverflow.WithLogger
 import org.codeoverflow.chatoverflow.api.plugin.{PluginLogMessage, PluginManager}
-import org.codeoverflow.chatoverflow.ui.web.rest.events.EventsDispatcher
-import org.json4s.DefaultFormats
-import org.json4s.jackson.Serialization
+import org.codeoverflow.chatoverflow.ui.web.rest.events.{EventMessage, EventsDispatcher}
 
 import scala.collection.JavaConverters._
 import scala.collection.mutable.ListBuffer
@@ -33,9 +31,11 @@ class PluginManagerImpl(pluginInstanceName: String, logOutputOnConsole: Boolean)
       logger info s"[$pluginInstanceName] $message"
     }
 
-    implicit val formats: DefaultFormats.type = DefaultFormats
-    val data = Map(("message", message), ("timestamp", logMessage.getTimestamp.toString))
-    EventsDispatcher.broadcast("instance", Serialization.write(Map(("name", pluginInstanceName), ("action", "log"), ("data", data))))
+    EventsDispatcher.broadcast("instance", EventMessage("log", Map(
+      ("name", pluginInstanceName),
+      ("message", message),
+      ("timestamp", logMessage.getTimestamp.toString)
+    )))
   }
 
   /**

src/main/scala/org/codeoverflow/chatoverflow/instance/PluginInstance.scala

@@ -8,9 +8,7 @@ import org.codeoverflow.chatoverflow.api.plugin.{Plugin, PluginManager}
 import org.codeoverflow.chatoverflow.framework.PluginCompatibilityState.PluginCompatibilityState
 import org.codeoverflow.chatoverflow.framework.manager.{PluginManagerImpl, PluginManagerStub}
 import org.codeoverflow.chatoverflow.framework.{PluginCompatibilityState, PluginType}
-import org.codeoverflow.chatoverflow.ui.web.rest.events.EventsDispatcher
-import org.json4s.DefaultFormats
-import org.json4s.jackson.Serialization
+import org.codeoverflow.chatoverflow.ui.web.rest.events.{EventMessage, EventsDispatcher}
 
 /**
   * A plugin instance holds all the general information of the plugin type and specific information of
@@ -152,8 +150,7 @@ class PluginInstance(val instanceName: String, pluginType: PluginType) extends W
             logger info s"Starting plugin '$instanceName' in new thread!"
             try {
               instanceThread = new Thread(() => {
-                implicit val formats: DefaultFormats.type = DefaultFormats
-                EventsDispatcher.broadcast("instance", Serialization.write(Map(("name", instanceName), ("action", "start"))))
+                EventsDispatcher.broadcast("instance", EventMessage("start", Map(("name", instanceName))))
 
                 try {
 
@@ -197,7 +194,7 @@ class PluginInstance(val instanceName: String, pluginType: PluginType) extends W
                     requirement.asInstanceOf[Requirement[Output]].get().shutdown()
                   })
 
-                  EventsDispatcher.broadcast("instance", Serialization.write(Map(("name", instanceName), ("action", "stop"))))
+                  EventsDispatcher.broadcast("instance", EventMessage("stop", Map(("name", instanceName))))
                 }
               })
               instanceThread.start()

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/events/EventMessage.scala

@@ -0,0 +1,3 @@
+package org.codeoverflow.chatoverflow.ui.web.rest.events
+
+case class EventMessage[T](action: String, data: T)

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/events/EventsController.scala

@@ -36,6 +36,16 @@ class EventsController(implicit val swagger: Swagger) extends JsonServlet with S
   }
 
   private def sendMessage(writer: PrintWriter, messageType: String, message: String): Unit = {
+    /*
+      Every message has the following format and ends with two line feeds (\n):
+      event: [name of event]
+      data: [first line]
+      data: [second line]
+      ...
+
+      See also: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Examples
+     */
+
     var msg = "event: " + messageType.replace("\n", "") + "\n"
     if (message != null)
       msg += "data: " + message.replace("\n", "\ndata: ") + "\n\n"

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/events/EventsDispatcher.scala

@@ -1,18 +1,48 @@
 package org.codeoverflow.chatoverflow.ui.web.rest.events
 
+import org.json4s.{DefaultFormats, Formats}
+import org.json4s.jackson.Serialization
+
+/**
+  * The EventsDispatcher is the central point for realtime communication to the clients
+  */
 object EventsDispatcher {
   private var controller: EventsController = _
+  implicit val formats: Formats = DefaultFormats
 
+  /**
+    * Initializes the EventsDispatcher with the registered controller
+    * Only to be used from the bootstrap
+    * @param eventsController registered controller that accepts the incoming connections
+    */
   def init(eventsController: EventsController): Unit = {
     if (controller == null)
       controller = eventsController
   }
 
+  /**
+    * Sends the message to all connected clients
+    * @param messageType type of the message / event
+    * @param message the message to send
+    * @tparam T type of the message data
+    */
+  def broadcast[T](messageType: String, message: EventMessage[T]): Unit = {
+    broadcast(messageType, Serialization.write(message))
+  }
+
+  /**
+    * Sends the message to all connected clients
+    * @param messageType type of the message / event
+    * @param message the message to send
+    */
   def broadcast(messageType: String, message: String = null): Unit = {
     if (controller != null)
       controller.broadcast(messageType, message)
   }
 
+  /**
+    * Sends a close message to all connected clients and closes the connections
+    */
   def close(): Unit = {
     if (controller != null)
       controller.closeConnections()