Java client BECN implementation (#155)

Java/src/XPlaneConnect.java

@@ -25,6 +25,8 @@
 
 package gov.nasa.xpc;
 
+import gov.nasa.xpc.discovery.Beacon;
+
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.lang.AutoCloseable;
@@ -136,6 +138,19 @@ public class XPlaneConnect implements AutoCloseable
         this(xpHost, xpPort, port, 100);
     }
 
+
+    /**
+     * Initializes a new instance of the {@code XPlaneConnect} class from a received discovery Beacon
+     * @param beacon The beacon received from {@code XPlaneConnectDiscovery}
+     * @throws SocketException If this instance is unable to bind to the specified port.
+     */
+    public XPlaneConnect(Beacon beacon) throws SocketException {
+        this.socket = new DatagramSocket(0);
+        this.xplaneAddr = beacon.getXplaneAddress();
+        this.xplanePort = beacon.getPluginPort();
+        this.socket.setSoTimeout(100);
+    }
+
     /**
      * Initializes a new instance of the {@code XPlaneConnect} class using the specified ports, hostname, and timeout.
      *

Java/src/discovery/Beacon.java

@@ -0,0 +1,45 @@
+package gov.nasa.xpc.discovery;
+
+import java.net.InetAddress;
+
+
+public class Beacon {
+
+    private InetAddress xplaneAddress;
+    private int pluginPort;
+    private String pluginVersion;
+    private int xPlaneVersion;
+
+
+    public Beacon(InetAddress xplaneAddress, int pluginPort, String pluginVersion, int xPlaneVersion) {
+        this.xplaneAddress = xplaneAddress;
+        this.pluginPort = pluginPort;
+        this.pluginVersion = pluginVersion;
+        this.xPlaneVersion = xPlaneVersion;
+    }
+
+    public String getHost() {
+        return xplaneAddress.getHostAddress();
+    }
+
+    public String getPluginVersion() {
+        return pluginVersion;
+    }
+
+    public String getXplaneVersion() {
+        return String.format("%.2f", xPlaneVersion / 100.0);
+    }
+
+    public int getPluginPort() {
+        return pluginPort;
+    }
+
+    public InetAddress getXplaneAddress() {
+        return xplaneAddress;
+    }
+
+    @Override
+    public String toString() {
+        return "host: " + getHost() + ":" + getPluginPort() +" version: " + getPluginVersion() + " X-Plane Version: " + getXplaneVersion();
+    }
+}

Java/src/discovery/BeaconParser.java

@@ -0,0 +1,54 @@
+package gov.nasa.xpc.discovery;
+
+import java.io.IOException;
+import java.net.DatagramPacket;
+import java.net.InetAddress;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+
+/**
+ * Parser class that parses the UDP discovery BECN packet. The format of the packet is
+ * - 4 bytes: BECN
+ * - 1 byte: 0
+ * - 2 bytes: XPlaneConnect server port e.g. '49009'
+ * - 4 bytes: X-Plane version e.g. '11260'
+ * - null terminated string: XPlaneConnect plugin version e.g. '1.3-rc.1'
+ */
+public class BeaconParser {
+
+    private static String BECN = "BECN";
+
+    private static int XPC_PORT_OFFSET = BECN.length() + 1;
+    private static int XPC_PORT_LEN = 2;
+    private static int XPC_VERSION_OFFSET = XPC_PORT_OFFSET + XPC_PORT_LEN;
+    private static int XPC_VERSION_LEN = 4;
+    private static int XPC_PLUGIN_VERSION_OFFSET = XPC_VERSION_OFFSET + XPC_VERSION_LEN;
+
+
+    public Beacon readBCN(DatagramPacket packet) throws IOException {
+        if (packet.getLength() < BECN.length()) {
+            throw new IOException("BECN response too short");
+        }
+
+        byte[] data = packet.getData();
+
+        String command = new String(data, 0, BECN.length());
+        if (!command.equals(BECN)) {
+            throw new IOException("Expected " + BECN + " got '" + command + "'");
+        }
+
+        InetAddress address = packet.getAddress();
+        ByteBuffer bb = ByteBuffer.wrap(data);
+        bb.order(ByteOrder.LITTLE_ENDIAN);
+        // 2 bytes: port as short + converted to an int
+        int port = bb.getShort(XPC_PORT_OFFSET) & 0xffff;
+
+        // 4 bytes: x plane version as int
+        int version = bb.getInt(XPC_VERSION_OFFSET);
+
+        // plugin version
+        String pluginVersion = new String(data, XPC_PLUGIN_VERSION_OFFSET, packet.getLength() - XPC_PLUGIN_VERSION_OFFSET);
+
+        return new Beacon(address, port, pluginVersion.trim(), version);
+    }
+}

Java/src/discovery/BeaconReceivedListener.java

@@ -0,0 +1,10 @@
+package gov.nasa.xpc.discovery;
+
+public interface BeaconReceivedListener {
+
+    /**
+     * Called every time a BECN packet is received
+     * @param beacon The parsed beacon
+     */
+    void onBeaconReceived(Beacon beacon);
+}

Java/src/discovery/DiscoveryConnectionCallback.java

@@ -0,0 +1,14 @@
+package gov.nasa.xpc.discovery;
+
+import gov.nasa.xpc.XPlaneConnect;
+
+public interface DiscoveryConnectionCallback {
+
+    /**
+     * Helper callback called when a 1st XPlanePlugin is discovered. When the 1st packet is received, an XPlaneConnect
+     * instance is created and the discovery is stopped.
+     *
+     * @param xpc The XPlaneConnect instance configured with the discovered
+     */
+    void onConnectionEstablished(XPlaneConnect xpc);
+}

Java/src/discovery/XPlaneConnectDiscovery.java

@@ -0,0 +1,94 @@
+package gov.nasa.xpc.discovery;
+
+import gov.nasa.xpc.XPlaneConnect;
+
+import java.io.IOException;
+import java.net.DatagramPacket;
+import java.net.InetAddress;
+import java.net.MulticastSocket;
+import java.net.SocketException;
+
+
+/**
+ * The XPlaneConnectDiscovery joins a UDP multi cast group and listens for BECN packets published by
+ * XPlaneConnect server plugin. It allows to clients to discover XPlane instances and be sure that the XPlanePlugin is
+ * installed.
+ */
+public class XPlaneConnectDiscovery implements AutoCloseable {
+
+    private static int DEFAULT_PORT = 49710;
+    private static String DEFAULT_ADDRESS = "239.255.1.1";
+
+    private BeaconReceivedListener mListener;
+
+    private MulticastSocket socket = null;
+    private byte[] buf = new byte[256];
+
+    private int mPort;
+    private String mAddress;
+    private BeaconParser parser = new BeaconParser();
+
+    private XPlaneConnectDiscovery(int port, String address) {
+        mPort = port;
+        mAddress = address;
+    }
+
+    public XPlaneConnectDiscovery() {
+        this(DEFAULT_PORT, DEFAULT_ADDRESS);
+    }
+
+    public void start(DiscoveryConnectionCallback callback) throws IOException {
+        onBeaconReceived(beacon -> {
+            this.close();
+
+            try {
+                XPlaneConnect xpc = new XPlaneConnect(beacon);
+                callback.onConnectionEstablished(xpc);
+            } catch (SocketException e) {
+                System.err.println("Could not connect to a discovered XplaneConnect " +beacon+ ": " + e.getMessage());
+            }
+        });
+        start();
+
+    }
+
+    public void start() throws IOException {
+        System.out.println("Starting XPlane Connect discovery");
+        socket = new MulticastSocket(mPort);
+        InetAddress group = InetAddress.getByName(mAddress);
+        socket.joinGroup(group);
+        while (socket != null) {
+            DatagramPacket packet = new DatagramPacket(buf, buf.length);
+            socket.receive(packet);
+            if (mListener == null) {
+                continue;
+            }
+            try {
+                Beacon beacon = parser.readBCN(packet);
+                mListener.onBeaconReceived(beacon);
+            } catch (IOException ex) {
+                System.err.println("Received packet on discovery group but could not parse it: " + ex);
+            }
+        }
+
+        close();
+        System.out.println("XPlane Connect discovery ended");
+    }
+
+
+    public void onBeaconReceived(BeaconReceivedListener mListener) {
+        this.mListener = mListener;
+    }
+
+    @Override
+    public void close() {
+        if (socket != null) {
+            socket.close();
+            socket = null;
+        }
+    }
+
+    public void stop() {
+        close();
+    }
+}