0.69.0

* Action Refactor

Author: a-hansen

build.gradle

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

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

@@ -0,0 +1,110 @@
+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 {
+
+    /**
+     * Only needed for a VALUES type actions, and optional even then.
+     */
+    public default int getColumnCount() {
+        return 0;
+    }
+
+    /**
+     * Add the metadata for the column at the given index to the bucket.  Only called before the
+     * action invocation.  Throws an IllegalStateException by default.
+     */
+    public default void getColumnMetadata(int idx, DSMap bucket) {
+        throw new IllegalStateException("Method not overridden");
+    }
+
+    /**
+     * Return 0 or less if there are no parameters.  Returns 0 by default.
+     */
+    public default int getParameterCount() {
+        return 0;
+    }
+
+    /**
+     * Add the metadata for the parameter at the given index to the bucket.  Throws an
+     * IllegalStateException by default.
+     */
+    public default void getParameterMetadata(int idx, DSMap bucket) {
+        throw new IllegalStateException("Method not overridden");
+    }
+
+    /**
+     * Minimum permission level required to invoke, returns WRITE by default.
+     */
+    public default DSPermission getPermission() {
+        return DSPermission.WRITE;
+    }
+
+    /**
+     * What the action returns, returns VOID by default.
+     */
+    public default ResultsType getResultsType() {
+        return ResultsType.VOID;
+    }
+
+    /**
+     * Defines what the action returns.
+     */
+    public enum ResultsType {
+
+        /**
+         * A stream of rows.  Clients can choose to trim rows for memory management.
+         */
+        STREAM("stream"),
+
+        /**
+         * A finite sized table whose stream is closed when the row cursor is complete.
+         */
+        TABLE("table"),
+
+        /**
+         * A single row of values.
+         */
+        VALUES("values"),
+
+        /**
+         * No return value.
+         */
+        VOID("");
+
+        private String display;
+
+        ResultsType(String display) {
+            this.display = display;
+        }
+
+        public boolean isStream() {
+            return this == STREAM;
+        }
+
+        public boolean isTable() {
+            return this == TABLE;
+        }
+
+        public boolean isValues() {
+            return this == VALUES;
+        }
+
+        public boolean isVoid() {
+            return this == VOID;
+        }
+
+        public String toString() {
+            return display;
+        }
+
+    } //ResultType
+
+}

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

@@ -0,0 +1,54 @@
+package org.iot.dsa.dslink;
+
+import org.iot.dsa.node.DSElement;
+import org.iot.dsa.node.DSMap;
+import org.iot.dsa.security.DSPermission;
+
+/**
+ * Encapsulates the details of an action invocation and provides the mechanism for updating an open
+ * stream.
+ *
+ * @author Aaron Hansen
+ */
+public interface ActionRequest {
+
+    /**
+     * For use with streams and open tables, will have no effect if the stream is 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.
+     */
+    public void close(Exception reason);
+
+    /**
+     * This needs to be called when there are more results after ActionsResults.next()
+     * returns false.
+     */
+    public void enqueueResults();
+
+    /**
+     * 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.
+     */
+    public DSPermission getPermission();
+
+    /**
+     * Whether or not response is still open.
+     */
+    public boolean isOpen();
+
+}

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

@@ -0,0 +1,56 @@
+package org.iot.dsa.dslink;
+
+import org.iot.dsa.dslink.Action.ResultsType;
+import org.iot.dsa.node.DSList;
+import org.iot.dsa.node.DSMap;
+
+/**
+ * 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.
+ *
+ * @author Aaron Hansen
+ */
+public interface ActionResults {
+
+    /**
+     * Unless the result type is void, this should return a value greater than zero.
+     */
+    public int getColumnCount();
+
+    /**
+     * Only needed if the column count is greater than 0.  Throws an IllegalStateException by
+     * default.
+     */
+    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.
+     */
+    public void getResults(DSList bucket);
+
+    /**
+     * Determines how the results should be used.
+     */
+    public ResultsType getResultsType();
+
+    /**
+     * 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.
+     */
+    public boolean next();
+
+    /**
+     * Always called, does nothing by default.
+     */
+    public default void onClose() {
+    }
+
+}

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

@@ -6,7 +6,6 @@
 import org.iot.dsa.dslink.responder.InboundSubscribeRequest;
 import org.iot.dsa.dslink.responder.OutboundListResponse;
 import org.iot.dsa.dslink.responder.SubscriptionCloseHandler;
-import org.iot.dsa.node.action.ActionResult;
 
 /**
  * Interface for nodes in the node tree to manually handle requests.  The first implementation
@@ -33,7 +32,7 @@ public interface DSIResponder {
      * @return The initial response and close notification mechanism, can be null if the if the
      * result type is void.
      */
-    public ActionResult onInvoke(InboundInvokeRequest request);
+    public ActionResults onInvoke(InboundInvokeRequest request);
 
     /**
      * The implementation should quickly create an object for responding to the request, but do no

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

@@ -18,9 +18,7 @@ public class SimpleInvokeHandler extends AbstractInvokeHandler {
     // Instance Fields
     ///////////////////////////////////////////////////////////////////////////
 
-    private boolean closed = false;
     private DSList columns;
-    private RuntimeException error;
     private Mode mode;
     private DSMap tableMeta;
     private ArrayList<DSList> updates;
@@ -79,7 +77,7 @@ public DSList getUpdate(long timeout) {
                 timeout = end - System.currentTimeMillis();
             }
             if (isError()) {
-                throw error;
+                throw getError();
             }
             if (hasUpdates()) {
                 return updates.remove(0);

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

@@ -1,8 +1,8 @@
 package org.iot.dsa.dslink.responder;
 
 import java.util.Iterator;
+import org.iot.dsa.dslink.Action;
 import org.iot.dsa.node.DSMap;
-import org.iot.dsa.node.action.ActionSpec;
 
 /**
  * Can be a node, value or an action.
@@ -14,7 +14,7 @@ public interface ApiObject {
     /**
      * The action, should only be called if isAction() returns true.
      */
-    public ActionSpec getAction();
+    public Action getAction();
 
     /**
      * Return the object representing the child with the given name.
@@ -28,23 +28,13 @@ public interface ApiObject {
 
     public void getMetadata(DSMap bucket);
 
-    /**
-     * The display name.
-     public String getName();
-     */
-
-    /**
-     * Value of the object, should only be called if isValue() returns true.
-     public DSIValue getValue();
-     */
-
     /**
      * True if the object is an action.
      */
     public boolean isAction();
 
     /**
-     * Whether or not this object requires configuration permission to read/write.
+     * Whether or not this object requires admin permission to read/write.
      */
     public boolean isAdmin();
 
@@ -59,7 +49,7 @@ public interface ApiObject {
     public boolean isReadOnly();
 
     /**
-     * True if getValue() can be called.
+     * True if the object is a value.
      */
     public boolean isValue();
 

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

@@ -1,15 +1,15 @@
 package org.iot.dsa.dslink.responder;
 
 import org.iot.dsa.node.DSMap;
-import org.iot.dsa.node.action.ActionInvocation;
+import org.iot.dsa.node.action.DSIActionRequest;
 
 /**
  * See ActionInvocation for the real meat.
  *
  * @author Aaron Hansen
- * @see ActionInvocation
+ * @see DSIActionRequest
  */
-public interface InboundInvokeRequest extends InboundRequest, ActionInvocation {
+public interface InboundInvokeRequest extends InboundRequest, DSIActionRequest {
 
     /**
      * The parameters supplied by the invoker, or null.

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

@@ -5,6 +5,7 @@
 import java.util.List;
 import org.iot.dsa.dslink.responder.ApiObject;
 import org.iot.dsa.node.action.DSAction;
+import org.iot.dsa.node.action.DSIAction;
 import org.iot.dsa.node.action.DSISetAction;
 import org.iot.dsa.util.DSUtil;
 
@@ -148,8 +149,8 @@ public T get() {
     }
 
     @Override
-    public DSAction getAction() {
-        return (DSAction) get();
+    public DSIAction getAction() {
+        return (DSIAction) get();
     }
 
     @Override
@@ -362,7 +363,7 @@ public void modified(DSGroup map) {
     /**
      * The next info in the parent node, or null.
      */
-    public DSInfo next() {
+    public DSInfo<?> next() {
         return next;
     }
 
@@ -432,7 +433,7 @@ public DSInfo<T> setAdmin(boolean admin) {
     }
 
     /**
-     * False by default, set to true to reset the target to it's default when the encapsulated node
+     * False by default, set to true to reset the target to it's default when the parent node
      * is copied.
      */
     public DSInfo<T> setDefaultOnCopy(boolean defaultOnCopy) {
@@ -569,6 +570,12 @@ DSInfo<T> setName(String arg) {
     }
 
     DSInfo<T> setObject(T arg) {
+        if (isDeclared()) {
+            if (!getDefaultObject().getClass().isInstance(arg)) {
+                throw new IllegalArgumentException(arg + " not an instanceof the declared type " +
+                                                           getDefaultObject().getClass().getName());
+            }
+        }
         this.object = arg;
         return this;
     }