Merge pull request #5 from ControlSystemStudio/update_readme

Update readme

Author: georgweiss

README.md

@@ -1 +1,72 @@
 This is an attempt to port the original work https://github.com/ornl-epics/pvws to a Spring Boot-based web application. While the code is adapted to the web socket APIs of Spring Boot, most of the code is essentially unchanged.
+
+Requirements
+------------
+
+To build: JDK 17, Maven 3.8+
+
+To run: JRE 17
+
+Build
+=====
+
+Executable jar
+--------------
+
+To build an executable Spring Boot jar (embedded Tomcat):
+
+``>mvn clean install``
+
+Output is ``pvws.jar`` in the ``target`` directory.
+
+Tomcat war
+----------
+
+To build war for deployment in Tomcat container:
+
+``>mvn -Pwar clean install``
+
+Output is ``pvws.war`` in the ``target`` directory.
+
+Run
+===
+
+Settings
+--------
+
+Bundled ``application.properties`` defines a few settings (e.g. default protocol). To define other settings or override
+settings, one may create a file named exactly ``application.properties`` and edit as needed. This
+file must be readable by the user account owning the application process.
+
+Executable jar
+--------------
+
+Launch like so:
+
+``>java -Dspring.config.location=file:/path/to/directory/ -jar /path/to/pvws.jar``
+
+where ``/path/to/directory/`` is the directory holding ``application.properties``. Note that
+this string **must** end in a slash ("/").
+
+It is also possible to define properties on the command line, e.g. 
+
+``>java -Dspring.config.location=file:/path/to/directory/ -DEPICS_PVA_ADDR_LIST=1.2.3.4 -jar /path/to/pvws.jar``
+
+Combining ``application.properties`` with JVM options is possible.
+Command line options will override definitions in ``application.properties``.
+
+Tomcat war
+----------
+
+**NOTE:** Verified on Tomcat 9 only.
+
+Copy ``pvws.war`` to ``TOMCAT_ROOT/webapps``. Set environment variable:
+
+``>export JAVA_OPTS=-Dspring.config.location=file:/path/to/directory/``
+
+and launch Tomcat.
+
+
+
+
+

src/main/java/org/phoebus/pvws/PvwsWebListener.java

@@ -38,7 +38,6 @@ public class PvwsWebListener implements ServletContextListener {
 
     @Override
     public void contextDestroyed(ServletContextEvent event) {
-        System.out.println("sdjhgfdfugh");
         WebApplicationContext context = ContextLoader.getCurrentWebApplicationContext();
         sockets = (List<WebSocket>) context.getBean("sockets");
         if (sockets == null) {

src/main/java/org/phoebus/pvws/ws/Vtype2Json.java

@@ -17,7 +17,9 @@
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.nio.DoubleBuffer;
+import java.nio.FloatBuffer;
 import java.nio.IntBuffer;
+import java.nio.ShortBuffer;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.text.DecimalFormat;
@@ -58,15 +60,15 @@ else if (value instanceof VString)
         else if (value instanceof VEnum)
             handleEnum(g, (VEnum) value, last_value);
         else if (value instanceof VByteArray)
-            handleLongString(g, (VByteArray) value);
+            handleBytes(g, (VNumberArray) value, last_value);
 
         // Serialize double and float arrays as b64dbl
         else if (value instanceof VDoubleArray)
             handleDoubles(g, (VNumberArray) value, last_value);
         else if (value instanceof VFloatArray)
-            handleDoubles(g, (VNumberArray) value, last_value);
+            handleFloats(g, (VNumberArray) value, last_value);
 
-        // Serialize remaining number arrays (int, short) as b64int
+            // Serialize remaining number arrays (int) as b64int
         else if (value instanceof VNumberArray)
             handleInts(g, (VNumberArray) value, last_value);
 
@@ -239,7 +241,7 @@ private static void handleInts(final JsonGenerator g, final VNumberArray value,
         {
             // Add severity if it changed
             if ((last_value instanceof VNumber)  &&
-                ((VNumber) last_value).getAlarm().getSeverity() != severity)
+                    ((VNumber) last_value).getAlarm().getSeverity() != severity)
                 g.writeStringField("severity", severity.name());
         }
 
@@ -256,6 +258,7 @@ private static void handleInts(final JsonGenerator g, final VNumberArray value,
     }
 
 
+
     private static void handleEnum(final JsonGenerator g, final VEnum value, final VType last_value) throws Exception
     {
         final AlarmSeverity severity = value.getAlarm().getSeverity();
@@ -275,11 +278,98 @@ private static void handleEnum(final JsonGenerator g, final VEnum value, final V
         {
             // Add severity if it changed
             if ((last_value instanceof VNumber)  &&
-                ((VNumber) last_value).getAlarm().getSeverity() != severity)
+                    ((VNumber) last_value).getAlarm().getSeverity() != severity)
                 g.writeStringField("severity", severity.name());
         }
 
         g.writeNumberField("value",  value.getIndex());
         g.writeStringField("text",  value.getValue());
     }
+
+    private static void handleFloats(final JsonGenerator g, final VNumberArray value, final VType last_value) throws Exception
+    {
+        final AlarmSeverity severity = value.getAlarm().getSeverity();
+        if (last_value == null)
+        {
+            // Initially, add complete metadata
+            g.writeStringField("vtype", VType.typeOf(value).getSimpleName());
+            handleDisplay(g, value.getDisplay());
+            // Initial severity
+            g.writeStringField("severity", severity.name());
+        }
+        else
+        {
+            // Add severity if it changed
+            if ((last_value instanceof VNumber)  &&
+                    ((VNumber) last_value).getAlarm().getSeverity() != severity)
+                g.writeStringField("severity", severity.name());
+        }
+
+        final ListNumber data = value.getData();
+        final int N = data.size();
+        final ByteBuffer buf = ByteBuffer.allocate(N * Float.BYTES);
+        buf.order(ByteOrder.LITTLE_ENDIAN);
+        final FloatBuffer fltbuf = buf.asFloatBuffer();
+        for (int i=0; i<N; ++i)
+            fltbuf.put(data.getFloat(i));
+        g.writeStringField("b64flt", Base64.getEncoder().encodeToString(buf.array()));
+    }
+
+    private static void handleShorts(final JsonGenerator g, final VNumberArray value, final VType last_value) throws Exception
+    {
+        final AlarmSeverity severity = value.getAlarm().getSeverity();
+        if (last_value == null)
+        {
+            // Initially, add complete metadata
+            g.writeStringField("vtype", VType.typeOf(value).getSimpleName());
+            handleDisplay(g, value.getDisplay());
+            // Initial severity
+            g.writeStringField("severity", severity.name());
+        }
+        else
+        {
+            // Add severity if it changed
+            if ((last_value instanceof VNumber)  &&
+                    ((VNumber) last_value).getAlarm().getSeverity() != severity)
+                g.writeStringField("severity", severity.name());
+        }
+
+        final ListNumber data = value.getData();
+        final int N = data.size();
+        final ByteBuffer buf = ByteBuffer.allocate(N * Short.BYTES);
+        buf.order(ByteOrder.LITTLE_ENDIAN);
+        final ShortBuffer srtbuf = buf.asShortBuffer();
+        for (int i=0; i<N; ++i)
+            srtbuf.put(data.getShort(i));
+        g.writeStringField("b64srt", Base64.getEncoder().encodeToString(buf.array()));
+    }
+
+    private static void handleBytes(final JsonGenerator g, final VNumberArray value, final VType last_value) throws Exception
+    {
+        final AlarmSeverity severity = value.getAlarm().getSeverity();
+        if (last_value == null)
+        {
+            // Initially, add complete metadata
+            g.writeStringField("vtype", VType.typeOf(value).getSimpleName());
+            handleDisplay(g, value.getDisplay());
+            // Initial severity
+            g.writeStringField("severity", severity.name());
+        }
+        else
+        {
+            // Add severity if it changed
+            if ((last_value instanceof VNumber)  &&
+                    ((VNumber) last_value).getAlarm().getSeverity() != severity)
+                g.writeStringField("severity", severity.name());
+        }
+
+        // Convert into Base64 int64 array
+        final ListNumber data = value.getData();
+        final int N = data.size();
+        final ByteBuffer buf = ByteBuffer.allocate(N * Byte.BYTES);
+        buf.order(ByteOrder.LITTLE_ENDIAN);
+        for (int i=0; i<N; ++i)
+            buf.put(data.getByte(i));
+        g.writeStringField("b64byt", Base64.getEncoder().encodeToString(buf.array()));
+    }
 }