LP#1640255 Native messaging WIP -- docs, warnings

Signed-off-by: Bill Erickson <berickxx@gmail.com>

diff --git a/run.sh b/run.sh
index 3400107..11292c7 100755 (executable)
--- a/run.sh
+++ b/run.sh
@@ -2,7 +2,7 @@ JAVA_HOME=jdk1.8
 CP=lib:lib/json-20160810.jar
 
 # compile
-$JAVA_HOME/bin/javac -cp $CP -d lib src/org/evergreen_ils/hatch/*.java
+$JAVA_HOME/bin/javac -Xlint:unchecked -cp $CP -d lib src/org/evergreen_ils/hatch/*.java
 
 [ -z "$1" ] && exit;
 

diff --git a/src/org/evergreen_ils/hatch/Hatch.java b/src/org/evergreen_ils/hatch/Hatch.java
index 05400ab..22e553b 100644 (file)
--- a/src/org/evergreen_ils/hatch/Hatch.java
+++ b/src/org/evergreen_ils/hatch/Hatch.java
@@ -91,7 +91,7 @@ public class Hatch extends Application {
 
         browser.webEngine.getLoadWorker()
             .stateProperty()
-            .addListener( (ChangeListener) (obsValue, oldState, newState) -> {
+            .addListener( (ChangeListener<State>) (obsValue, oldState, newState) -> {
                 logger.info("browser load state " + newState);
                 if (newState == State.SUCCEEDED) {
                     logger.info("Print browser page load completed");

diff --git a/src/org/evergreen_ils/hatch/MessageIO.java b/src/org/evergreen_ils/hatch/MessageIO.java
index 63aa13b..bda965b 100644 (file)
--- a/src/org/evergreen_ils/hatch/MessageIO.java
+++ b/src/org/evergreen_ils/hatch/MessageIO.java
@@ -6,7 +6,12 @@ import java.nio.ByteBuffer;
 import java.io.IOException;
 import org.json.*;
 
-
+/**
+ * Reads and writes JSON strings from STDIN / to STDOUT.
+ *
+ * Each string is prefixed with a 4-byte message length header.  All I/O
+ * occurs in a separate thread, so no blocking of the main thread occurs.
+ */
 public class MessageIO {
 
     private LinkedBlockingQueue<JSONObject> inQueue;
@@ -23,11 +28,19 @@ public class MessageIO {
         writer = new MessageWriter();
     }
 
+    /**
+     * Starts the read and write threads.
+     */
     public void listen() {
         writer.start();
         reader.start();
     }
 
+    /**
+     * Receive one message from STDIN.
+     *
+     * This call blocks the current thread until a message is available.
+     */
     public JSONObject recvMessage() {
         while (true) {
             try {
@@ -36,14 +49,30 @@ public class MessageIO {
         }
     }
 
+    /**
+     * Queue a message for sending to STDOUT.
+     */
     public void sendMessage(JSONObject msg) {
         outQueue.offer(msg);
     }
 
+    /**
+     * Thrown when STDIN or STDOUT are closed.
+     */
     class EndOfStreamException extends IOException { }
 
+    /**
+     * Reads JSON-encoded strings from STDIN.
+     *
+     * As messages arrive, they are enqueued for access by recvMessage().
+     *
+     * Each message is prefixed with a 4-byte message length header.
+     */
     class MessageReader extends Thread {
 
+        /**
+         * Converts a 4-byte array to its integer value.
+         */
         private int bytesToInt(byte[] bytes) {
             return 
                   (bytes[3] << 24) & 0xff000000 
@@ -52,6 +81,11 @@ public class MessageIO {
                 | (bytes[0] <<  0) & 0x000000ff;
         }
 
+        /**
+         * Reads one message from STDIN.
+         *
+         * This method blocks until a message is available.
+         */
         private String readOneMessage() throws EndOfStreamException, IOException {
             byte[] lenBytes = new byte[4];
             int bytesRead = System.in.read(lenBytes);
@@ -83,6 +117,9 @@ public class MessageIO {
             return message;
         }
 
+        /**
+         * Read messages from STDIN until STDIN is closed or the application exits.
+         */
         public void run() {
 
             while (true) {
@@ -118,8 +155,17 @@ public class MessageIO {
         }
     }
 
+    /**
+     * Writes JSON-encoded strings from STDOUT.
+     *
+     * As messages are queued for delivery, each is serialized as a JSON
+     * string and stamped with a 4-byte length header.
+     */
     class MessageWriter extends Thread {
 
+        /**
+         * Returns the 4-byte array representation of an integer.
+         */
         private byte[] intToBytes(int length) {
             byte[] bytes = new byte[4];
             bytes[0] = (byte) (length & 0xFF);
@@ -129,12 +175,19 @@ public class MessageIO {
             return bytes;
         }
 
+        /**
+         * Encodes and writes one message to STDOUT.
+         */
         public void writeOneMessage(String message) throws IOException {
             System.out.write(intToBytes(message.length()));
             System.out.write(message.getBytes("UTF-8"));
             System.out.flush();
         }
 
+        /**
+         * Waits for messages to be queued for delivery and writes
+         * each to STDOUT until STDOUT is closed or the application exits.
+         */
         public void run() {
 
             while (true) {

diff --git a/src/org/evergreen_ils/hatch/PrintManager.java b/src/org/evergreen_ils/hatch/PrintManager.java
index f63d7e7..d6f7e71 100644 (file)
--- a/src/org/evergreen_ils/hatch/PrintManager.java
+++ b/src/org/evergreen_ils/hatch/PrintManager.java
@@ -59,6 +59,7 @@ public class PrintManager {
     public Map<String,Object> configurePrinter(
         Map<String,Object> params) throws IllegalArgumentException {
 
+        @SuppressWarnings("unchecked")
         Map<String,Object> settings = 
             (Map<String,Object>) params.get("config");
 
@@ -89,6 +90,7 @@ public class PrintManager {
         Long msgid = (Long) params.get("msgid");
         Boolean showDialog = (Boolean) params.get("showDialog");
 
+        @SuppressWarnings("unchecked")
         Map<String,Object> settings = 
             (Map<String,Object>) params.get("config");
 
@@ -171,6 +173,7 @@ public class PrintManager {
             Map<String,Object> settings, Printer printer) {
 
         // modify the default page layout with our settings
+        @SuppressWarnings("unchecked")
         Map<String,Object> layoutMap = 
             (Map<String,Object>) settings.get("pageLayout");