0.70.0

* Responder list refactored for true async.
* Added AsyncActionResults and changed how action results are handled.
* Added DSBoolRange
* DSIEnum now extends DSIMetadata
* Fix NPE in DS1Requester

Author: a-hansen

build.gradle

@@ -5,7 +5,7 @@ subprojects {
     apply plugin: 'maven'
 
     group 'org.iot-dsa'
-    version '0.69.0'
+    version '0.70.0'
 
     targetCompatibility = JavaVersion.VERSION_1_8
     sourceCompatibility = JavaVersion.VERSION_1_8

dslink-v2-api/src/main/java/org/iot/dsa/dslink/Action.java

@@ -1,14 +1,13 @@
 package org.iot.dsa.dslink;
 
 import org.iot.dsa.node.DSMap;
-import org.iot.dsa.security.DSPermission;
 
 /**
  * Defines an invokable node in the DSA model.
  *
  * @author Aaron Hansen
  */
-public interface Action {
+public interface Action extends Node {
 
     /**
      * Only needed for a VALUES type actions, and optional even then.
@@ -41,17 +40,17 @@ public default void getParameterMetadata(int idx, DSMap bucket) {
     }
 
     /**
-     * Minimum permission level required to invoke, returns WRITE by default.
+     * What the action returns, returns VOID by default.
      */
-    public default DSPermission getPermission() {
-        return DSPermission.WRITE;
+    public default ResultsType getResultsType() {
+        return ResultsType.VOID;
     }
 
     /**
-     * What the action returns, returns VOID by default.
+     * Whether or not the action the action requires write permission.  Returns false by default.
      */
-    public default ResultsType getResultsType() {
-        return ResultsType.VOID;
+    public default boolean isReadOnly() {
+        return false;
     }
 
     /**

dslink-v2-api/src/main/java/org/iot/dsa/dslink/ActionRequest.java

@@ -5,42 +5,36 @@
 import org.iot.dsa.security.DSPermission;
 
 /**
- * Encapsulates the details of an action invocation and provides the mechanism for updating an open
- * stream.
+ * Encapsulates the details of an action invocation and provides the mechanism for async
+ * updates.
  *
  * @author Aaron Hansen
  */
 public interface ActionRequest {
 
     /**
-     * For use with streams and open tables, will have no effect if the stream is already closed.
+     * For use with streams and AsyncActionResults, will have no effect if already closed.
      */
     public void close();
 
     /**
-     * Close and send an error. For use with streams and open tables, will have no effect if the
-     * stream is already closed.
+     * Close and send an error. For use with streams and AsyncActionResults, will have no effect
+     * if already closed.
      */
     public void close(Exception reason);
 
     /**
-     * This needs to be called when there are more results after ActionsResults.next()
-     * returns false.
+     * A convenience for getting a single parameter out of the parameters map.
      */
-    public void enqueueResults();
+    public default DSElement getParameter(String key) {
+        return getParameters().get(key);
+    }
 
     /**
      * The parameters supplied by the invoker, or null.
      */
     public DSMap getParameters();
 
-    /**
-     * A convenience for getting a single parameter out of the parameters map.
-     */
-    public default DSElement getParameter(String key) {
-        return getParameters().get(key);
-    }
-
     /**
      * The permission level of the invoker.
      */
@@ -51,4 +45,13 @@ public default DSElement getParameter(String key) {
      */
     public boolean isOpen();
 
+    /**
+     * This is for streams and AsyncActionResults.  Call this after returning false
+     * ActionResults.next() and there are more results.  AsyncActionResults implementors also
+     * need to call this to send the initial columns.
+     *
+     * @see AsyncActionResults
+     */
+    public void sendResults();
+
 }

dslink-v2-api/src/main/java/org/iot/dsa/dslink/ActionResults.java

@@ -6,14 +6,10 @@
 
 /**
  * The results of an action request.  This is implemented as a cursor for all result types.
- * The implementation can return false from next() and resume later.  After returning
- * false from next(), the implementation must call ActionRequest.close() or
- * ActionRequest.enqueueResults().
- * <p>
- * If the result type is VALUES, next() will only be called once.  The implementation does not
- * need to call any other methods on ActionRequest.
+ * For async results, implement AsyncActionResults instead.
  *
  * @author Aaron Hansen
+ * @see AsyncActionResults
  */
 public interface ActionResults {
 
@@ -23,14 +19,13 @@ public interface ActionResults {
     public int getColumnCount();
 
     /**
-     * Only needed if the column count is greater than 0.  Throws an IllegalStateException by
-     * default.
+     * Only needed if the column count is greater than 0.
      */
     public void getColumnMetadata(int idx, DSMap bucket);
 
     /**
-     * The implementation should add the values of the current result set to the given bucket.  The
-     * bucket may be reused across calls, the implementation should not cache references to it.
+     * The implementation should add the values of the current row to the given bucket.  The
+     * bucket can be reused across calls, the implementation should not cache references to it.
      */
     public void getResults(DSList bucket);
 
@@ -41,9 +36,11 @@ public interface ActionResults {
 
     /**
      * Initially, this cursor must be positioned before the first set of results. Return true to
-     * advance the next set of results.  The implementation is responsible for calling
-     * DIActionRequest.enqueueResults() or DIActionRequest.close().  This will only
-     * be called once for a result type of VALUES.
+     * advance the next set of results.  If the implementation is a stream or AsyncActionResults,
+     * this can return false and later have more rows, the implementor is responsible for calling
+     * ActionRequest.sendResults() or ActionRequest.close().  If not a stream or async, the request
+     * will be closed once this returns false.  This will only be called once for a results
+     * type of VALUES.
      */
     public boolean next();
 

dslink-v2-api/src/main/java/org/iot/dsa/dslink/AsyncActionResults.java

@@ -0,0 +1,15 @@
+package org.iot.dsa.dslink;
+
+/**
+ * This is a marker interface that indicates ActionResults are async.
+ * <p>
+ * Implementors are required to call ActionRequest.sendResults() for sending
+ * the initial column definitions, as well as after returning false from next().
+ * <p>
+ * Implementors are also required to call ActionRequest.close().
+ *
+ * @author Aaron Hansen
+ */
+public interface AsyncActionResults extends ActionResults {
+
+}

dslink-v2-api/src/main/java/org/iot/dsa/dslink/DSIResponder.java

@@ -4,7 +4,7 @@
 import org.iot.dsa.dslink.responder.InboundListRequest;
 import org.iot.dsa.dslink.responder.InboundSetRequest;
 import org.iot.dsa.dslink.responder.InboundSubscribeRequest;
-import org.iot.dsa.dslink.responder.OutboundListResponse;
+import org.iot.dsa.dslink.responder.ListCloseHandler;
 import org.iot.dsa.dslink.responder.SubscriptionCloseHandler;
 
 /**
@@ -42,7 +42,7 @@ public interface DSIResponder {
      * @param request The details of the request and the mechanism for providing updates.
      * @return The initial response and close mechanism.
      */
-    public OutboundListResponse onList(InboundListRequest request);
+    public ListCloseHandler onList(InboundListRequest request);
 
     /**
      * The implementation should do no processing of it on the calling thread. Simply throw a

dslink-v2-api/src/main/java/org/iot/dsa/dslink/Node.java

@@ -0,0 +1,26 @@
+package org.iot.dsa.dslink;
+
+import org.iot.dsa.node.DSMap;
+
+/**
+ * Used in DSIResponder list responses.
+ *
+ * @author Aaron Hansen
+ */
+public interface Node {
+
+    /**
+     * Add all metadata for the object.  Does nothing by default.
+     */
+    public default void getMetadata(DSMap bucket) {
+    }
+
+    /**
+     * Whether or not the object requires admin level permission.  Returns false
+     * by default.
+     */
+    public default boolean isAdmin() {
+        return false;
+    }
+
+}

dslink-v2-api/src/main/java/org/iot/dsa/dslink/Value.java

@@ -0,0 +1,24 @@
+package org.iot.dsa.dslink;
+
+import org.iot.dsa.node.DSIValue;
+
+/**
+ * Used in DSIResponder list responses.
+ *
+ * @author Aaron Hansen
+ */
+public interface Value extends Node {
+
+    /**
+     * Whether or not the value can be written.
+     */
+    public boolean isReadOnly();
+
+    /**
+     * Does not have to be the current value, used to determine the type
+     * of the value.
+     * @return
+     */
+    public DSIValue toValue();
+
+}