From 56f8160af8e89e6981a5f67d23c307dcd1ef0f2a Mon Sep 17 00:00:00 2001
From: Grant Limberg <glimberg@gmail.com>
Date: Sat, 25 Apr 2015 17:29:07 -0700
Subject: generate javadocs for the Java SDK

---
 java/build.xml                                     |   7 +
 java/jni/ZT1_jniutils.cpp                          |   4 +-
 java/jni/com_zerotierone_sdk_Node.cpp              |   2 +-
 .../com/zerotierone/sdk/DataStoreGetListener.java  |  23 +++
 .../com/zerotierone/sdk/DataStorePutListener.java  |  22 +++
 java/src/com/zerotierone/sdk/Event.java            |  78 +++++++++
 java/src/com/zerotierone/sdk/EventListener.java    |  26 +++
 java/src/com/zerotierone/sdk/MulticastGroup.java   |  16 +-
 java/src/com/zerotierone/sdk/Node.java             | 184 ++++++++++++++++++++-
 java/src/com/zerotierone/sdk/NodeStatus.java       |  18 +-
 java/src/com/zerotierone/sdk/PacketSender.java     |  18 +-
 java/src/com/zerotierone/sdk/Peer.java             |  32 +++-
 java/src/com/zerotierone/sdk/PeerPhysicalPath.java |  23 ++-
 java/src/com/zerotierone/sdk/PeerRole.java         |  11 ++
 java/src/com/zerotierone/sdk/ResultCode.java       |  31 +++-
 java/src/com/zerotierone/sdk/Version.java          |   4 +-
 .../com/zerotierone/sdk/VirtualNetworkConfig.java  |  65 +++++++-
 .../sdk/VirtualNetworkConfigListener.java          |  23 +++
 .../sdk/VirtualNetworkConfigOperation.java         |  15 ++
 .../sdk/VirtualNetworkFrameListener.java           |  10 ++
 .../com/zerotierone/sdk/VirtualNetworkStatus.java  |  23 +++
 .../com/zerotierone/sdk/VirtualNetworkType.java    |   7 +
 22 files changed, 623 insertions(+), 19 deletions(-)

(limited to 'java')

diff --git a/java/build.xml b/java/build.xml
index af05cd00..c81f48de 100644
--- a/java/build.xml
+++ b/java/build.xml
@@ -25,6 +25,13 @@
         <jar destfile="bin/ZeroTierOneSDK.jar" basedir="classes"/>
     </target>
 
+    <target name="docs">
+      <echo message="Generating Javadocs"/>
+      <mkdir dir="doc/"/>
+      <javadoc sourcepath="src/"
+               destdir="doc/"/>
+    </target>
+
 <!--    <target name="android" depends="build">
         <echo message="OS is Android, installing..."/>
         <copy file="libs/armeabi/libZeroTierOneJNI.so" 
diff --git a/java/jni/ZT1_jniutils.cpp b/java/jni/ZT1_jniutils.cpp
index 8d1a25c4..af7a58bc 100644
--- a/java/jni/ZT1_jniutils.cpp
+++ b/java/jni/ZT1_jniutils.cpp
@@ -785,7 +785,7 @@ jobject newNetworkConfig(JNIEnv *env, const ZT1_VirtualNetworkConfig &vnetConfig
 
     if(portErrorField == NULL)
     {
-        portErrorField == env->GetFieldID(vnetConfigClass, "portError", "Z");
+        portErrorField == env->GetFieldID(vnetConfigClass, "portError", "I");
         if(portErrorField == NULL)
         {
             return NULL;
@@ -855,7 +855,7 @@ jobject newNetworkConfig(JNIEnv *env, const ZT1_VirtualNetworkConfig &vnetConfig
     env->SetBooleanField(vnetConfigObj, dhcpField, vnetConfig.dhcp);
     env->SetBooleanField(vnetConfigObj, bridgeField, vnetConfig.bridge);
     env->SetBooleanField(vnetConfigObj, broadcastEnabledField, vnetConfig.broadcastEnabled);
-    env->SetBooleanField(vnetConfigObj, portErrorField, vnetConfig.portError);
+    env->SetIntField(vnetConfigObj, portErrorField, vnetConfig.portError);
 
 
     jobject mcastSubsArrayObj = newArrayList(env);
diff --git a/java/jni/com_zerotierone_sdk_Node.cpp b/java/jni/com_zerotierone_sdk_Node.cpp
index fdbe0368..fef9b4d6 100644
--- a/java/jni/com_zerotierone_sdk_Node.cpp
+++ b/java/jni/com_zerotierone_sdk_Node.cpp
@@ -443,7 +443,7 @@ namespace {
         if(ref->packetSenderCallbackMethod == NULL)
         {
             ref->packetSenderCallbackMethod = env->GetMethodID(ref->packetSenderClass,
-                "onSendPacketRequested", "(Ljava/lang/String;I[B)I");
+                "onSendPacketRequested", "(Ljava/net/InetAddress;I[B)I");
             if(ref->packetSenderCallbackMethod == NULL)
             {
                 return -2;
diff --git a/java/src/com/zerotierone/sdk/DataStoreGetListener.java b/java/src/com/zerotierone/sdk/DataStoreGetListener.java
index 703b153b..eaf35f18 100644
--- a/java/src/com/zerotierone/sdk/DataStoreGetListener.java
+++ b/java/src/com/zerotierone/sdk/DataStoreGetListener.java
@@ -29,6 +29,29 @@ package com.zerotierone.sdk;
 import java.nio.ByteBuffer;
 
 public interface DataStoreGetListener {
+
+    /**
+     * Function to get an object from the data store
+     *
+     * <p>Object names can contain forward slash (/) path separators. They will
+     * never contain .. or backslash (\), so this is safe to map as a Unix-style
+     * path if the underlying storage permits. For security reasons we recommend
+     * returning errors if .. or \ are used.</p>
+     *
+     * <p>The function must return the actual number of bytes read. If the object
+     * doesn't exist, it should return -1. -2 should be returned on other errors
+     * such as errors accessing underlying storage.</p>
+     *
+     * <p>If the read doesn't fit in the buffer, the max number of bytes should be
+     * read. The caller may call the function multiple times to read the whole
+     * object.</p>
+     *
+     * @param name Name of the object in the data store
+     * @param out_buffer buffer to put the object in
+     * @param bufferIndex index in the object to start reading
+     * @param out_objectSize long[1] to be set to the actual size of the object if it exists.
+     * @return the actual number of bytes read.
+     */
     public long onDataStoreGet(
             String name,
             byte[] out_buffer,
diff --git a/java/src/com/zerotierone/sdk/DataStorePutListener.java b/java/src/com/zerotierone/sdk/DataStorePutListener.java
index bc884667..26ab1928 100644
--- a/java/src/com/zerotierone/sdk/DataStorePutListener.java
+++ b/java/src/com/zerotierone/sdk/DataStorePutListener.java
@@ -29,11 +29,33 @@ package com.zerotierone.sdk;
 import java.nio.ByteBuffer;
 
 public interface DataStorePutListener {
+
+    /**
+     * Function to store an object in the data store
+     *
+     * <p>If secure is true, the file should be set readable and writable only
+     * to the user running ZeroTier One. What this means is platform-specific.</p>
+     *
+     * <p>Name semantics are the same as {@link DataStoreGetListener}. This must return 
+     * zero on success. You can return any OS-specific error code on failure, as these
+     * may be visible in logs or error messages and might aid in debugging.</p>
+     *
+     * @param name Object name
+     * @param buffer data to store
+     * @param secure set to user read/write only.
+     * @return 0 on success.
+     */
     public int onDataStorePut(
         String name,
         byte[] buffer,
         boolean secure);
 
+    /**
+     * Function to delete an object from the data store
+     * 
+     * @param name Object name
+     * @return 0 on success.
+     */
     public int onDelete(
         String name);
 }
diff --git a/java/src/com/zerotierone/sdk/Event.java b/java/src/com/zerotierone/sdk/Event.java
index c5558676..382fbf48 100644
--- a/java/src/com/zerotierone/sdk/Event.java
+++ b/java/src/com/zerotierone/sdk/Event.java
@@ -28,11 +28,89 @@
 package com.zerotierone.sdk;
 
 public enum Event {
+    /**
+     * Node has been initialized
+     *
+     * This is the first event generated, and is always sent. It may occur
+     * before Node's constructor returns.
+     */
 	EVENT_UP,
+
+    /**
+     * Node is offline -- network does not seem to be reachable by any available strategy
+     */
 	EVENT_OFFLINE,
+
+    /**
+     * Node is shutting down
+     * 
+     * <p>This is generated within Node's destructor when it is being shut down.
+     * It's done for convenience, since cleaning up other state in the event
+     * handler may appear more idiomatic.</p>
+     */
 	EVENT_DOWN,
+
+    /**
+     * Your identity has collided with another node's ZeroTier address
+     * 
+     * <p>This happens if two different public keys both hash (via the algorithm
+     * in Identity::generate()) to the same 40-bit ZeroTier address.</p>
+     * 
+     * <p>This is something you should "never" see, where "never" is defined as
+     * once per 2^39 new node initializations / identity creations. If you do
+     * see it, you're going to see it very soon after a node is first
+     * initialized.</p>
+     * 
+     * <p>This is reported as an event rather than a return code since it's
+     * detected asynchronously via error messages from authoritative nodes.</p>
+     * 
+     * <p>If this occurs, you must shut down and delete the node, delete the
+     * identity.secret record/file from the data store, and restart to generate
+     * a new identity. If you don't do this, you will not be able to communicate
+     * with other nodes.</p>
+     * 
+     * <p>We'd automate this process, but we don't think silently deleting
+     * private keys or changing our address without telling the calling code
+     * is good form. It violates the principle of least surprise.</p>
+     * 
+     * <p>You can technically get away with not handling this, but we recommend
+     * doing so in a mature reliable application. Besides, handling this
+     * condition is a good way to make sure it never arises. It's like how
+     * umbrellas prevent rain and smoke detectors prevent fires. They do, right?</p>
+     */
 	EVENT_FATAL_ERROR_IDENTITY_COLLISION,
+    
+    /**
+     * A more recent version was observed on the network
+     * 
+     * <p>Right now this is only triggered if a hub or supernode reports a
+     * more recent version, and only once. It can be used to trigger a
+     * software update check.</p>
+     * 
+     * <p>Meta-data: {@link Version}, more recent version number</p>
+     */
+    EVENT_SAW_MORE_RECENT_VERSION,
+
+    /**
+     * A packet failed authentication
+     *
+     * <p>Meta-data: {@link InetAddress} containing origin address of packet</p>
+     */
 	EVENT_AUTHENTICATION_FAILURE,
+
+    /**
+     * A received packet was not valid
+     *
+     * <p>Meta-data: {@link InetAddress} containing origin address of packet</p>
+     */
 	EVENT_INVALID_PACKET,
+
+    /**
+     * Trace (debugging) message
+     *
+     * <p>These events are only generated if this is a TRACE-enabled build.</p>
+     *
+     * <p>Meta-data: {@link String}, TRACE message</p>
+     */
 	EVENT_TRACE
 }
\ No newline at end of file
diff --git a/java/src/com/zerotierone/sdk/EventListener.java b/java/src/com/zerotierone/sdk/EventListener.java
index 63030dfd..dedd271a 100644
--- a/java/src/com/zerotierone/sdk/EventListener.java
+++ b/java/src/com/zerotierone/sdk/EventListener.java
@@ -30,12 +30,38 @@ package com.zerotierone.sdk;
 import java.net.InetAddress;
 import java.lang.String;
 
+/**
+ * Interface to handle callbacks for ZeroTier One events.
+ */
 public interface EventListener {
+    /**
+     * Callback for events with no other associated metadata
+     * 
+     * @param event {@link Event} enum
+     */
     public void onEvent(Event event);
     
+    /**
+     * Callback for network error events: {@link Event.EVENT_AUTHENTICATION_FAILUER}, {link Event.EVENT_INVALID_PACKET}
+     *
+     * @param event {@link Event} enum
+     * @param source {@link InetAddress} containing the origin address of the packet
+     */
     public void onNetworkError(Event event, InetAddress source);
 
+    /**
+     * Callback when the node detects that it's out of date.
+     *
+     * @param newVersion {@link Version} object with the latest version of ZeroTier One
+     */
     public void onOutOfDate(Version newVersion);
 
+    /**
+     * Trace messages
+     * 
+     * <p>These events are only generated if the underlying ZeroTierOne SDK is a TRACE-enabled build.</p>
+     *
+     * @param message the trace message
+     */
     public void onTrace(String message);
 }
diff --git a/java/src/com/zerotierone/sdk/MulticastGroup.java b/java/src/com/zerotierone/sdk/MulticastGroup.java
index 89ba206f..aa75ab85 100644
--- a/java/src/com/zerotierone/sdk/MulticastGroup.java
+++ b/java/src/com/zerotierone/sdk/MulticastGroup.java
@@ -27,9 +27,23 @@
 package com.zerotierone.sdk;
 
 
-public class MulticastGroup {
+public final class MulticastGroup {
     private MulticastGroup() {}
 
     private long mac;
     private long adi;
+
+    /**
+     * MAC address (least significant 48 bits)
+     */
+    public final long getMacAddress() {
+        return mac;
+    }
+
+    /**
+     * Additional distinguishing information (usually zero)
+     */
+    public final long getAdi() {
+        return adi;
+    }
 }
diff --git a/java/src/com/zerotierone/sdk/Node.java b/java/src/com/zerotierone/sdk/Node.java
index 649f84a8..318f0701 100644
--- a/java/src/com/zerotierone/sdk/Node.java
+++ b/java/src/com/zerotierone/sdk/Node.java
@@ -32,6 +32,9 @@ import java.lang.Long;
 import java.net.InetAddress;
 import java.util.ArrayList;
 
+/**
+ * A ZeroTier One node
+ */
 public class Node {
 	static {
 		System.loadLibrary("ZeroTierOneJNI");
@@ -54,6 +57,20 @@ public class Node {
     private final VirtualNetworkFrameListener frameListener;
     private final VirtualNetworkConfigListener configListener;
     
+    /**
+     * Create a new ZeroTier One node
+     *
+     * <p>Note that this can take a few seconds the first time it's called, as it
+     * will generate an identity.</p>
+     *
+     * @param now Current clock in milliseconds
+     * @param getListener User written instance of the {@link DataStoreGetListener} interface called to get objects from persistent storage.  This instance must be unique per Node object.
+     * @param putListener User written intstance of the {@link DataStorePutListener} interface called to put objects in persistent storage.  This instance must be unique per Node object.
+     * @param sender
+     * @param eventListener User written instance of the {@link EventListener} interface to receive status updates and non-fatal error notices.  This instance must be unique per Node object.
+     * @param frameListener 
+     * @param configListener User written instance of the {@link VirtualNetworkConfigListener} interface to be called when virtual LANs are created, deleted, or their config parameters change.  This instance must be unique per Node object.
+     */
 	public Node(long now,
                 DataStoreGetListener getListener,
                 DataStorePutListener putListener,
@@ -78,6 +95,11 @@ public class Node {
         }
 	}
 
+    /**
+      * Close this Node.
+      * 
+      * <p>The Node object can no longer be used once this method is called.</p>
+      */
     public void close() {
         if(nodeId != -1) {
             node_delete(nodeId);
@@ -90,6 +112,19 @@ public class Node {
         close();
     }
 
+    /**
+     * Process a frame from a virtual network port
+     *
+     * @param now Current clock in milliseconds
+     * @param nwid ZeroTier 64-bit virtual network ID
+     * @param sourceMac Source MAC address (least significant 48 bits)
+     * @param destMac Destination MAC address (least significant 48 bits)
+     * @param etherType 16-bit Ethernet frame type
+     * @param vlanId 10-bit VLAN ID or 0 if none
+     * @param frameData Frame payload data
+     * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode processVirtualNetworkFrame(
         long now,
         long nwid,
@@ -104,6 +139,16 @@ public class Node {
             frameData, nextBackgroundTaskDeadline);
     }
 
+    /**
+     * Process a packet received from the physical wire
+     *
+     * @param now Current clock in milliseconds
+     * @param remoteAddress Origin of packet
+     * @param linkDesperation Link desperation metric for link or protocol over which packet arrived
+     * @param packetData Packet data
+     * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode processWirePacket(
         long now,
         InetAddress remoteAddress,
@@ -115,24 +160,96 @@ public class Node {
             nextBackgroundTaskDeadline);
     }
 
+    /**
+     * Perform periodic background operations
+     *
+     * @param now Current clock in milliseconds
+     * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks()
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode processBackgroundTasks(long now, long[] nextBackgroundTaskDeadline) {
         return processBackgroundTasks(nodeId, now, nextBackgroundTaskDeadline);
     }
 
+    /**
+     * Join a network
+     *
+     * <p>This may generate calls to the port config callback before it returns,
+     * or these may be deffered if a netconf is not available yet.</p>
+     *
+     * <p>If we are already a member of the network, nothing is done and OK is
+     * returned.</p>
+     *
+     * @param nwid 64-bit ZeroTier network ID
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode join(long nwid) {
         return join(nodeId, nwid);
     }
 
+    /**
+     * Leave a network
+     *
+     * <p>If a port has been configured for this network this will generate a call
+     * to the port config callback with a NULL second parameter to indicate that
+     * the port is now deleted.</p>
+     *
+     * @param nwid 64-bit network ID
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode leave(long nwid) {
         return leave(nodeId, nwid);
     }
 
+    /**
+     * Subscribe to an Ethernet multicast group
+     *
+     * <p>For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the
+     * broadcast address) but with an ADI equal to each IPv4 address in host
+     * byte order. This converts ARP from a non-scalable broadcast protocol to
+     * a scalable multicast protocol with perfect address specificity.</p>
+     *
+     * <p>If this is not done, ARP will not work reliably.</p>
+     *
+     * <p>Multiple calls to subscribe to the same multicast address will have no
+     * effect. It is perfectly safe to do this.</p>
+     *
+     * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p>
+     *
+     * @param nwid 64-bit network ID
+     * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode multicastSubscribe(
 		long nwid,
 		long multicastGroup) {
 		return multicastSubscribe(nodeId, nwid, multicastGroup, 0);
 	}
 
+    /**
+     * Subscribe to an Ethernet multicast group
+     *
+     * <p>ADI stands for additional distinguishing information. This defaults to zero
+     * and is rarely used. Right now its only use is to enable IPv4 ARP to scale,
+     * and this must be done.</p>
+     *
+     * <p>For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the
+     * broadcast address) but with an ADI equal to each IPv4 address in host
+     * byte order. This converts ARP from a non-scalable broadcast protocol to
+     * a scalable multicast protocol with perfect address specificity.</p>
+     *
+     * <p>If this is not done, ARP will not work reliably.</p>
+     *
+     * <p>Multiple calls to subscribe to the same multicast address will have no
+     * effect. It is perfectly safe to do this.</p>
+     *
+     * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p>
+     *
+     * @param nwid 64-bit network ID
+     * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
+     * @param multicastAdi Multicast ADI (least significant 32 bits only, default: 0)
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode multicastSubscribe(
         long nwid,
         long multicastGroup,
@@ -140,12 +257,42 @@ public class Node {
         return multicastSubscribe(nodeId, nwid, multicastGroup, multicastAdi);
     }
 
+
+    /**
+     * Unsubscribe from an Ethernet multicast group (or all groups)
+     *
+     * <p>If multicastGroup is zero (0), this will unsubscribe from all groups. If
+     * you are not subscribed to a group this has no effect.</p>
+     *
+     * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p>
+     *
+     * @param nwid 64-bit network ID
+     * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
 	public ResultCode multicastUnsubscribe(
 		long nwid,
 		long multicastGroup) {
 		return multicastUnsubscribe(nodeId, nwid, multicastGroup, 0);
 	}
 
+    /**
+     * Unsubscribe from an Ethernet multicast group (or all groups)
+     *
+     * <p>If multicastGroup is zero (0), this will unsubscribe from all groups. If
+     * you are not subscribed to a group this has no effect.</p>
+     *
+     * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p>
+     *
+     * <p>ADI stands for additional distinguishing information. This defaults to zero
+     * and is rarely used. Right now its only use is to enable IPv4 ARP to scale,
+     * and this must be done.</p>
+     *
+     * @param nwid 64-bit network ID
+     * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits)
+     * @param multicastAdi Multicast ADI (least significant 32 bits only, default: 0)
+     * @return OK (0) or error code if a fatal error condition has occurred
+     */
     public ResultCode multicastUnsubscribe(
         long nwid,
         long multicastGroup,
@@ -153,33 +300,64 @@ public class Node {
         return multicastUnsubscribe(nodeId, nwid, multicastGroup, multicastAdi);
     }
 
+    /**
+     * Get this node's 40-bit ZeroTier address
+     *
+     * @return ZeroTier address (least significant 40 bits of 64-bit int)
+     */
     public long address() {
         return address(nodeId);
     }
 
+    /**
+     * Get the status of this node
+     *
+     * @return @{link NodeStatus} struct with the current node status.
+     */
     public NodeStatus status() {
         return status(nodeId);
     }
 
+    /**
+     * Get a list of known peer nodes
+     *
+     * @return List of known peers or NULL on failure
+     */
     public ArrayList<Peer> peers() {
         return peers(nodeId);
     }
 
+    /**
+     * Get the status of a virtual network
+     *
+     * @param nwid 64-bit network ID
+     * @return {@link VirtualNetworkConfig} or NULL if we are not a member of this network
+     */
     public VirtualNetworkConfig networkConfig(long nwid) {
         return networkConfig(nodeId, nwid);
     }
 
+    /**
+     * Enumerate and get status of all networks
+     *
+     * @return List of networks or NULL on failure
+     */
     public ArrayList<VirtualNetworkConfig> networks() {
         return networks(nodeId);
     }
 
+    /**
+     * Get ZeroTier One version
+     *
+     * @return {@link Version} object with ZeroTierOne version information.
+     */
     public Version getVersion() {
         return version();
     }
 
-    /**
-     * function declarations for JNI
-     */
+    //
+    // function declarations for JNI
+    //
     private native ResultCode node_init(long now);
 
     private native void node_delete(long nodeId);
diff --git a/java/src/com/zerotierone/sdk/NodeStatus.java b/java/src/com/zerotierone/sdk/NodeStatus.java
index fdf5284e..163e3056 100644
--- a/java/src/com/zerotierone/sdk/NodeStatus.java
+++ b/java/src/com/zerotierone/sdk/NodeStatus.java
@@ -27,7 +27,7 @@
 
 package com.zerotierone.sdk;
 
-public class NodeStatus {
+public final class NodeStatus {
 	private long address;
 	private String publicIdentity;
 	private String secretIdentity;
@@ -35,18 +35,34 @@ public class NodeStatus {
 
 	private NodeStatus() {}
 
+	/**
+	 * 40-bit ZeroTier address of this node
+	 */
 	public final long getAddres() {
 		return address;
 	}
 
+	/**
+	 * Public identity in string-serialized form (safe to send to others)
+	 *
+	 * <p>This identity will remain valid as long as the node exists.</p>
+	 */
 	public final String getPublicIdentity() {
 		return publicIdentity;
 	}
 
+	/**
+	 * Full identity including secret key in string-serialized form
+	 *
+	 * <p>This identity will remain valid as long as the node exists.</p>
+	 */
 	public final String getSecretIdentity() {
 		return secretIdentity;
 	}
 
+	/**
+	 * True if some kind of connectivity appears available
+	 */
 	public final boolean isOnline() {
 		return online;
 	}
diff --git a/java/src/com/zerotierone/sdk/PacketSender.java b/java/src/com/zerotierone/sdk/PacketSender.java
index 572e1807..0c1cd83e 100644
--- a/java/src/com/zerotierone/sdk/PacketSender.java
+++ b/java/src/com/zerotierone/sdk/PacketSender.java
@@ -26,12 +26,24 @@
  */
 package com.zerotierone.sdk;
 
-import java.nio.ByteBuffer;
+import java.net.InetAddress;
 
 
 public interface PacketSender {
+    /**
+     * Function to send a ZeroTier packet out over the wire
+     *
+     * <p>The function must return zero on success and may return any error code
+     * on failure. Note that success does not (of course) guarantee packet
+     * delivery. It only means that the packet appears to have been sent.</p>
+     *
+     * @param addr {@link InetAddress} to send to
+     * @param linkDesperation
+     * @param packetData data to send
+     * @return 0 on success, any error code on failure.
+     */
     public int onSendPacketRequested(
-            String addr,
-            int linkDesparation,
+            InetAddress addr,
+            int linkDesperation,
             byte[] packetData);
 }
diff --git a/java/src/com/zerotierone/sdk/Peer.java b/java/src/com/zerotierone/sdk/Peer.java
index cd2268b4..60b9ff4b 100644
--- a/java/src/com/zerotierone/sdk/Peer.java
+++ b/java/src/com/zerotierone/sdk/Peer.java
@@ -29,7 +29,10 @@ package com.zerotierone.sdk;
 
 import java.util.ArrayList;
 
-public class Peer {
+/**
+ * Peer status result
+ */
+public final class Peer {
     private long address;
     private long lastUnicastFrame;
     private long lastMulticastFrame;
@@ -42,38 +45,65 @@ public class Peer {
 
     private Peer() {}
 
+    /**
+     * ZeroTier address (40 bits)
+     */
     public final long address() {
         return address;
     }
 
+    /**
+     * Time we last received a unicast frame from this peer
+     */
     public final long lastUnicastFrame() {
         return lastUnicastFrame;
     }
 
+    /**
+     * Time we last received a multicast rame from this peer
+     */
     public final long lastMulticastFrame() {
         return lastMulticastFrame;
     }
 
+    /**
+     * Remote major version or -1 if not known
+     */
     public final int versionMajor() {
         return versionMajor;
     }
 
+    /**
+     * Remote minor version or -1 if not known
+     */
     public final int versionMinor() {
         return versionMinor;
     }
 
+    /**
+     * Remote revision or -1 if not known
+     */
     public final int versionRev() {
         return versionRev;
     }
 
+    /**
+     * Last measured latency in milliseconds or zero if unknown
+     */
     public final int latency() {
         return latency;
     }
 
+    /**
+     * What trust hierarchy role does this device have?
+     */
     public final PeerRole role() {
         return role;
     }
 
+    /**
+     * Known network paths to peer
+     */
     public final ArrayList<PhysicalPeerPath> paths() {
         return paths;
     }
diff --git a/java/src/com/zerotierone/sdk/PeerPhysicalPath.java b/java/src/com/zerotierone/sdk/PeerPhysicalPath.java
index d7b2fad1..17b0ff8b 100644
--- a/java/src/com/zerotierone/sdk/PeerPhysicalPath.java
+++ b/java/src/com/zerotierone/sdk/PeerPhysicalPath.java
@@ -29,7 +29,10 @@ package com.zerotierone.sdk;
 
 import java.net.InetAddress;
 
-public class PeerPhysicalPath {
+/**
+ * Physical network path to a peer
+ */
+public final class PeerPhysicalPath {
     private InetAddress address;
     private long lastSend;
     private long lastReceive;
@@ -39,26 +42,44 @@ public class PeerPhysicalPath {
 
     private PeerPhysicalPath() {}
 
+    /**
+     * Address of endpoint
+     */
     public final InetAddress address() {
         return address;
     }
 
+    /**
+     * Time of last send in milliseconds or 0 for never
+     */
     public final long lastSend() {
         return lastSend;
     }
 
+    /**
+     * Time of last receive in milliseconds or 0 for never
+     */
     public final long lastReceive() {
         return lastReceive;
     }
 
+    /**
+     * Is path fixed? (i.e. not learned, static)
+     */
     public final boolean isFixed() {
         return fixed;
     }
 
+    /**
+     * Is path active?
+     */
     public final boolean isActive() {
         return active;
     }
 
+    /**
+     * Is path preferred?
+     */
     public final boolean isPreferred() {
         return preferred;
     }
diff --git a/java/src/com/zerotierone/sdk/PeerRole.java b/java/src/com/zerotierone/sdk/PeerRole.java
index 979b1a98..7f507f6d 100644
--- a/java/src/com/zerotierone/sdk/PeerRole.java
+++ b/java/src/com/zerotierone/sdk/PeerRole.java
@@ -28,7 +28,18 @@
 package com.zerotierone.sdk;
 
 public enum PeerRole {
+    /**
+     * An ordinary node
+     */
     PEER_ROLE_LEAF,
+
+    /**
+     * Locally federated hub
+     */
     PEER_ROLE_HUB,
+
+    /**
+     * planetary supernode
+     */
     PEER_ROLE_SUPERNODE
 }
\ No newline at end of file
diff --git a/java/src/com/zerotierone/sdk/ResultCode.java b/java/src/com/zerotierone/sdk/ResultCode.java
index 7597c0f2..bb73f68c 100644
--- a/java/src/com/zerotierone/sdk/ResultCode.java
+++ b/java/src/com/zerotierone/sdk/ResultCode.java
@@ -27,12 +27,41 @@
 
 package com.zerotierone.sdk;
 
+/**
+ * Function return code: OK (0) or error results
+ *
+ * <p>Use {@link ResultCode#isFatal) to check for a fatal error. If a fatal error
+ * occurs, the node should be considered to not be working correctly. These
+ * indicate serious problems like an inaccessible data store or a compile
+ * problem.</p>
+ */
 public enum ResultCode {
-
+    /**
+     * Operation completed normally
+     */
 	RESULT_OK(0),
+
+    // Fatal errors (> 0, < 1000)
+    /**
+     * Ran out of memory
+     */
 	RESULT_FATAL_ERROR_OUT_OF_MEMORY(1),
+
+    /**
+     * Data store is not writable or has failed
+     */
 	RESULT_FATAL_ERROR_DATA_STORE_FAILED(2),
+
+    /**
+     * Internal error (e.g. unexpected exception indicating bug or build problem)
+     */
 	RESULT_FATAL_ERROR_INTERNAL(3),
+
+    // non-fatal errors
+
+    /**
+     * Network ID not valid
+     */
 	RESULT_ERROR_NETWORK_NOT_FOUND(1000);
 	
 	private final int id;
diff --git a/java/src/com/zerotierone/sdk/Version.java b/java/src/com/zerotierone/sdk/Version.java
index abdaab9e..14e9f152 100644
--- a/java/src/com/zerotierone/sdk/Version.java
+++ b/java/src/com/zerotierone/sdk/Version.java
@@ -27,8 +27,8 @@
 
 package com.zerotierone.sdk;
 
-public class Version {
-    public Version() {}
+public final class Version {
+    private Version() {}
     
 	public int major = 0;
 	public int minor = 0;
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java
index 5e06b55f..037fd802 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java
@@ -31,7 +31,7 @@ import java.lang.String;
 import java.util.ArrayList;
 import java.net.InetAddress;
 
-public class VirtualNetworkConfig {
+public final class VirtualNetworkConfig {
     public static final int MAX_MULTICAST_SUBSCRIPTIONS = 4096;
     public static final int ZT1_MAX_ZT_ASSIGNED_ADDRESSES = 16;
 
@@ -44,7 +44,7 @@ public class VirtualNetworkConfig {
     private boolean dhcp;
     private boolean bridge;
     private boolean broadcastEnabled;
-    private boolean portError;
+    private int portError;
     private boolean enabled;
     private long netconfRevision;
     private ArrayList<MulticastGroup> multicastSubscriptions;
@@ -54,57 +54,116 @@ public class VirtualNetworkConfig {
 
     }
 
+    /**
+     * 64-bit ZeroTier network ID
+     */
     public final long networkId() {
         return nwid;
     }
+
+    /**
+     * Ethernet MAC (40 bits) that should be assigned to port
+     */
     public final long macAddress() {
         return mac;
     }
 
+    /**
+     * Network name (from network configuration master)
+     */
     public final String name() {
         return name;
     }
 
+    /**
+     * Network configuration request status
+     */
     public final VirtualNetworkStatus networkStatus() {
         return status;
     }
 
+    /**
+     * Network type
+     */
     public final VirtualNetworkType networkType() {
         return type;
     }
 
+    /**
+     * Maximum interface MTU
+     */
     public final int mtu() {
         return mtu;
     }
 
+    /**
+     * If the network this port belongs to indicates DHCP availability
+     *
+     * <p>This is a suggestion. The underlying implementation is free to ignore it
+     * for security or other reasons. This is simply a netconf parameter that
+     * means 'DHCP is available on this network.'</p>
+     */
     public final boolean isDhcpAvailable() {
         return dhcp;
     }
 
+    /**
+     * If this port is allowed to bridge to other networks
+     *
+     * <p>This is informational. If this is false, bridged packets will simply
+     * be dropped and bridging won't work.</p>
+     */
     public final boolean isBridgeEnabled() {
         return bridge;
     }
 
+    /**
+     * If true, this network supports and allows broadcast (ff:ff:ff:ff:ff:ff) traffic
+     */
     public final boolean broadcastEnabled() {
         return broadcastEnabled;
     }
 
-    public final boolean portError() {
+    /**
+     * If the network is in PORT_ERROR state, this is the error most recently returned by the port config callback
+     */
+    public final int portError() {
         return portError;
     }
 
+    /**
+     * Is this network enabled? If not, all frames to/from are dropped.
+     */
     public final boolean isEnabled() {
         return enabled;
     }
 
+    /**
+     * Network config revision as reported by netconf master
+     *
+     * <p>If this is zero, it means we're still waiting for our netconf.</p>
+     */
     public final long netconfRevision() {
         return netconfRevision;
     }
 
+    /**
+     * Multicast group subscriptions
+     */
     public final ArrayList<MulticastGroup> multicastSubscriptions() {
         return multicastSubscriptions;
     }
 
+    /**
+     * ZeroTier-assigned addresses (in {@link java.net.InetAddress} objects)
+     *
+     * For IP, the port number of the sockaddr_XX structure contains the number
+     * of bits in the address netmask. Only the IP address and port are used.
+     * Other fields like interface number can be ignored.
+     *
+     * This is only used for ZeroTier-managed address assignments sent by the
+     * virtual network's configuration master.
+     */
     public final ArrayList<InetAddress> assignedAddresses() {
         return assignedAddresses;
     }
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java
index 9378b6c9..2a26d79d 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java
@@ -30,6 +30,29 @@ package com.zerotierone.sdk;
 
 
 public interface VirtualNetworkConfigListener {
+    /**
+     * Callback called to update virtual network port configuration
+     *
+     * <p>This can be called at any time to update the configuration of a virtual
+     * network port. The parameter after the network ID specifies whether this
+     * port is being brought up, updated, brought down, or permanently deleted.
+     *
+     * This in turn should be used by the underlying implementation to create
+     * and configure tap devices at the OS (or virtual network stack) layer.</P>
+     *
+     * This should not call {@link Node#multicastSubscribe} or other network-modifying
+     * methods, as this could cause a deadlock in multithreaded or interrupt
+     * driven environments.
+     *
+     * This must return 0 on success. It can return any OS-dependent error code
+     * on failure, and this results in the network being placed into the
+     * PORT_ERROR state.
+     *
+     * @param nwid network id
+     * @param op {@link VirtualNetworkConfigOperation} enum describing the configuration operation
+     * @param config {@link VirtualNetworkConfig} object with the new configuration
+     * @return 0 on success
+     */
     public int onNetworkConfigurationUpdated(
             long nwid,
             VirtualNetworkConfigOperation op,
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java
index 2bf6ce09..989961b3 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java
@@ -27,8 +27,23 @@
 package com.zerotierone.sdk;
 
 public enum VirtualNetworkConfigOperation {
+    /**
+     * Network is coming up (either for the first time or after service restart)
+     */
     VIRTUAL_NETWORK_CONFIG_OPERATION_UP,
+
+    /**
+     * Network configuration has been updated
+     */
     VIRTUAL_NETWORK_CONFIG_OPERATION_CONFIG_UPDATE,
+
+    /**
+     * Network is going down (not permanently)
+     */
     VIRTUAL_NETWORK_CONFIG_OPERATION_DOWN,
+
+    /**
+     * Network is going down permanently (leave/delete)
+     */
     VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY
 }
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java b/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java
index a38cd722..0b85cab1 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java
@@ -30,6 +30,16 @@ package com.zerotierone.sdk;
 import java.nio.ByteBuffer;
 
 public interface VirtualNetworkFrameListener {
+    /**
+     * Function to send a frame out to a virtual network port
+     * 
+     * @param nwid ZeroTier One network ID
+     * @param srcMac source MAC address
+     * @param destMac destination MAC address
+     * @param ethertype
+     * @param vlanId
+     * @param frameData data to send
+     */
     void onVirtualNetworkFrame(
                 long nwid,
                 long srcMac,
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java b/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java
index 1102d2ea..78df06b9 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java
@@ -27,10 +27,33 @@
 package com.zerotierone.sdk;
 
 public enum VirtualNetworkStatus {
+    /**
+     * Waiting for network configuration (also means revision == 0)
+     */
     NETWORK_STATUS_REQUESTING_CONFIGURATION,
+
+    /**
+     * Configuration received and we are authorized
+     */
     NETWORK_STATUS_OK,
+
+    /**
+     * Netconf master told us 'nope'
+     */
     NETWORK_STATUS_ACCESS_DENIED,
+
+    /**
+     * Netconf master exists, but this virtual network does not
+     */
     NETWORK_STATUS_NOT_FOUND,
+
+    /**
+     * Initialization of network failed or other internal error
+     */
     NETWORK_STATUS_PORT_ERROR,
+
+    /**
+     * ZeroTier One version too old
+     */
     NETWORK_STATUS_CLIENT_TOO_OLD
 }
diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkType.java b/java/src/com/zerotierone/sdk/VirtualNetworkType.java
index b4a8ce2f..adc2eaff 100644
--- a/java/src/com/zerotierone/sdk/VirtualNetworkType.java
+++ b/java/src/com/zerotierone/sdk/VirtualNetworkType.java
@@ -27,6 +27,13 @@
 package com.zerotierone.sdk;
 
 public enum VirtualNetworkType {
+    /**
+     * Private networks are authorized via certificates of membership
+     */
     NETWORK_TYPE_PRIVATE,
+
+    /**
+     * Public networks have no access control -- they'll always be AUTHORIZED
+     */
     NETWORK_TYPE_PUBLIC
 }
-- 
cgit v1.2.3