You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@edgent.apache.org by dj...@apache.org on 2016/05/11 20:52:54 UTC
[2/3] incubator-quarks git commit: Start documenting provider commands
Start documenting provider commands
Project: http://git-wip-us.apache.org/repos/asf/incubator-quarks/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-quarks/commit/4a754374
Tree: http://git-wip-us.apache.org/repos/asf/incubator-quarks/tree/4a754374
Diff: http://git-wip-us.apache.org/repos/asf/incubator-quarks/diff/4a754374
Branch: refs/heads/master
Commit: 4a7543743b10c6a10106fc4bdc690248d9b196c5
Parents: 4381426
Author: Dan Debrunner <dj...@debrunners.com>
Authored: Tue May 10 17:22:15 2016 -0700
Committer: Dan Debrunner <dj...@debrunners.com>
Committed: Tue May 10 17:22:15 2016 -0700
----------------------------------------------------------------------
.../java/quarks/providers/iot/IotProvider.java | 4 --
.../java/quarks/providers/iot/package-info.java | 46 +++++++++++++++++++-
.../runtime/jsoncontrol/package-info.java | 14 +++---
3 files changed, 53 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/4a754374/providers/iot/src/main/java/quarks/providers/iot/IotProvider.java
----------------------------------------------------------------------
diff --git a/providers/iot/src/main/java/quarks/providers/iot/IotProvider.java b/providers/iot/src/main/java/quarks/providers/iot/IotProvider.java
index dea4e1a..e0c2723 100644
--- a/providers/iot/src/main/java/quarks/providers/iot/IotProvider.java
+++ b/providers/iot/src/main/java/quarks/providers/iot/IotProvider.java
@@ -63,10 +63,6 @@ import quarks.topology.services.ApplicationService;
* </UL>
* System applications provide this functionality:
* <UL>
- * <LI>
- * </LI>
- * </UL>
- * <UL>
* <LI>Single connection to the message hub using an {@code IotDevice}
* using {@link IotDevicePubSub}.
* Applications using this provider that want to connect
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/4a754374/providers/iot/src/main/java/quarks/providers/iot/package-info.java
----------------------------------------------------------------------
diff --git a/providers/iot/src/main/java/quarks/providers/iot/package-info.java b/providers/iot/src/main/java/quarks/providers/iot/package-info.java
index 5044636..befe330 100644
--- a/providers/iot/src/main/java/quarks/providers/iot/package-info.java
+++ b/providers/iot/src/main/java/quarks/providers/iot/package-info.java
@@ -20,6 +20,50 @@ under the License.
/**
* Iot provider that allows multiple applications to
* share an {@code IotDevice}.
+ *
+ * <H3>IoT device</H3>
+ *
+ * <H3>Application registration</H3>
+ * The provider includes an {@link quarks.topology.services.ApplicationService ApplicationService} that allows applications
+ * to be registered by name. Once registered an application can be started (and stopped) remotely
+ * through the control service using a device command.
+ *
+ * <H3>Supported device commands</H3>
+ * This provider supports a number of system level device commands to control the applications
+ * running within it.
+ * <H4>Control service</H4>
+ * Device commands with the command identifier '{@link quarks.connectors.iot.Commands#CONTROL_SERVICE quarksControl}'
+ * are sent to the provider's control service, an instance of {@link quarks.runtime.jsoncontrol.JsonControlService JsonControlService}.
+ * This allows invocation of an operation against a control mbean registered with the
+ * control service, either by an application or the provider itself.
+ * <BR>
+ * The command's data (JSON) uniquely identifies a control MBean through its type and
+ * alias, and indicates the operation to call on the MBean and the arguments to
+ * pass the control MBean.
+ * <BR>
+ * Thus any control operation can be remotely invoked through a {@code quarksControl} device command,
+ * including arbitrary control mbeans registered by applications.
+ *
+ * <H4>Provider operations</H4>
+ * <TABLE border="1">
+ * <tr>
+ * <th>Operation</th><th>Command identifier</th>
+ * <th>Type</th><th>Alias</th><th>Method</th><th>Arguments</th>
+ * <th>Control MBean</th>
+ * </tr>
+ * <tr>
+ * <th rowspan="2">Submit (start) a registered application</th>
+ * <td>{@code quarksControl}</td><td>{@code appService}</td>
+ * <td>{@code quarks}</td><td>{@link quarks.topology.mbeans.ApplicationServiceMXBean#submit(String, String) submit}</td>
+ * <td><em>{@code [applicationName, config]}</em></td>
+ * <td>{@link quarks.topology.mbeans.ApplicationServiceMXBean ApplicationServiceMXBean}</td>
+ * </tr>
+ * </tr>
+ * <th>Sample command data</th>
+ * <td colspan=5>{@code {"type":"appService","alias":"quarks","op":"submit","args":["Heartbeat",{}]}}</td>
+ * </tr>
+ * <tr></tr>
+ * </TABLE>
+ *
*/
package quarks.providers.iot;
-
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/4a754374/runtime/jsoncontrol/src/main/java/quarks/runtime/jsoncontrol/package-info.java
----------------------------------------------------------------------
diff --git a/runtime/jsoncontrol/src/main/java/quarks/runtime/jsoncontrol/package-info.java b/runtime/jsoncontrol/src/main/java/quarks/runtime/jsoncontrol/package-info.java
index 9eaa4af..9c10250 100644
--- a/runtime/jsoncontrol/src/main/java/quarks/runtime/jsoncontrol/package-info.java
+++ b/runtime/jsoncontrol/src/main/java/quarks/runtime/jsoncontrol/package-info.java
@@ -24,14 +24,16 @@ under the License.
* <H3>Operations</H3>
* A JSON object passed to {@link quarks.runtime.jsoncontrol.JsonControlService#controlRequest(com.google.gson.JsonObject) controlRequest} with these name/value pairs is
* handled as an operation resulting in a method call to a
- * void method on a control service MBean interface.
+ * void method on a control service MBean interface.
* <UL>
- * <LI>{@code type=}<em>type</em></LI>
- * <LI>{@code alias=}<em>alias</em></LI>
- * <LI>{@code op=}<em>name</em></LI>
- * <LI>{@code arguments=}<em>optional list of arguments</em></LI>
+ * <LI>{@code type=}<em>type</em> - MBean type.</LI>
+ * <LI>{@code alias=}<em>alias - Alias of the MBean.</em></LI>
+ * <LI>{@code op=}<em>name</em> - Name of the operation to invoke, this is the method name on the MBean.</LI>
+ * <LI>{@code arguments=}<em>optional list of arguments</em> - Arguments passed to the operation (method).</LI>
* </UL>
- *
+ * The MBean must be uniquely identified through
+ * its <em>type</em> and <em>alias</em> and previously registered using
+ * {@link quarks.execution.services.ControlService#registerControl(String, String, String, Class, Object) registerControl()}.
*/
package quarks.runtime.jsoncontrol;
\ No newline at end of file