You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@edgent.apache.org by dl...@apache.org on 2017/02/26 20:44:13 UTC
[06/13] incubator-edgent git commit: updates / cleanup
updates / cleanup
- add the ability to avoid use of IotDevice from a gateway context
Project: http://git-wip-us.apache.org/repos/asf/incubator-edgent/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-edgent/commit/26c198b6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-edgent/tree/26c198b6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-edgent/diff/26c198b6
Branch: refs/heads/master
Commit: 26c198b615eb887acbd0549e8d032469330e3ce4
Parents: 48bbb10
Author: Dale LaBossiere <dl...@us.ibm.com>
Authored: Fri Feb 3 16:16:34 2017 -0500
Committer: Dale LaBossiere <dl...@us.ibm.com>
Committed: Fri Feb 24 21:53:41 2017 -0500
----------------------------------------------------------------------
.../apache/edgent/connectors/iot/IotDevice.java | 8 +-
.../edgent/connectors/iot/IotGateway.java | 137 ++++++++++++++++---
.../edgent/connectors/iot/package-info.java | 22 ++-
3 files changed, 138 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-edgent/blob/26c198b6/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotDevice.java
----------------------------------------------------------------------
diff --git a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotDevice.java b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotDevice.java
index 046bc95..16d81f4 100644
--- a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotDevice.java
+++ b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotDevice.java
@@ -28,7 +28,7 @@ import org.apache.edgent.topology.TopologyElement;
import com.google.gson.JsonObject;
/**
- * Generic Internet of Things device connector.
+ * A generic IoT device IoT hub connector.
* <p>
* IotDevice characteristics:
* <ul>
@@ -41,9 +41,9 @@ import com.google.gson.JsonObject;
* for the same logical device, false otherwise.</li>
* <li>{@code IotDevice.hashCode()} returns the same value for all IotDevice instances
* for the same logical device.</li>
- * <li>{@code IotDevice} may be used as a {@link org.apache.edgent.topology.TWindow TWindow} partition key.</li>
* </ul>
*
+ * @see <a href="{@docRoot}/org/apache/edgent/connectors/iot/package-summary.html">Edgent generic IoT device model</a>
* @see IotGateway
*/
public interface IotDevice extends TopologyElement {
@@ -56,14 +56,14 @@ public interface IotDevice extends TopologyElement {
/**
* Get the device's opaque device type identifier.
* TODO remove the "default" - avoids compilation errors while discussing this.
- * @return
+ * @return the device's type
*/
public default String getDeviceType() { return "a-device-type-id"; }
/**
* Get the device's unique opaque device identifier.
* TODO remove the "default" - avoids compilation errors while discussing this.
- * @return
+ * @return the device's id
*/
public default String getDeviceId() { return "a-device-id"; }
http://git-wip-us.apache.org/repos/asf/incubator-edgent/blob/26c198b6/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotGateway.java
----------------------------------------------------------------------
diff --git a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotGateway.java b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotGateway.java
index d714d74..4988ba1 100644
--- a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotGateway.java
+++ b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/IotGateway.java
@@ -19,48 +19,117 @@ under the License.
package org.apache.edgent.connectors.iot;
-import java.util.Collection;
import java.util.Map;
+import java.util.Set;
+import org.apache.edgent.function.Function;
+import org.apache.edgent.function.UnaryOperator;
+import org.apache.edgent.topology.TSink;
import org.apache.edgent.topology.TStream;
import com.google.gson.JsonObject;
/**
- * A generic IoT Gateway device connector.
+ * A generic IoT gateway device IoT hub connector.
* <p>
- * An IoT Gateway device is a conduit for a collection of IoT devices
+ * An IoT gateway device is a conduit for a collection of IoT devices
* that lack direct connection to the enterprise IoT hub.
* <p>
- * The IoT Gateway device is an {@link IotDevice}. Events can be published
- * that are from the gateway device and commands can be received that are targeted for it
- * using the IotGateway's {@code events()} and {@code commands()}.
+ * An IoT gateway device is an IoT device. Events can be published
+ * that are from the gateway's deviceId and commands can be received that are targeted for it
+ * using the gateway's {@link IotDevice#events(TStream, String, int) events()}
+ * and {@link IotDevice#commands(String...) commands()}.
* <p>
- * Use {@link #getIotDevice(Map)} to get an IotDevice for a connected device.
+ * Use {@link #getIotDevice(Map)} to get an {@code IotDevice} for a gateway connected device
+ * or {@link #getIotDeviceId(Map)} to get a deviceId for it.
* The name/value pairs in the map are IotGateway implementation defined values.
* Refer to the IotGateway implementation for details.
- * Events can be published that are from that device and commands can be
- * received for that are targeted for that device using the connected device's IotDevice
- * {@code events()} and {@code commands()).
+ * <p>
+ * Events can be published that are from a deviceId and commands can be
+ * received for that are targeted for it using
+ * {@link #eventsForDevice(String, TStream, String, JsonObject, int) eventsForDevice()}
+ * and {@link #commandsForDevice(Set, String...) commandsForDevice()}.
*
+ * @see <a href="{@docRoot}/org/apache/edgent/connectors/iot/package-summary.html">Edgent generic IoT device model</a>
* @see IotDevice
*/
public interface IotGateway extends IotDevice {
/**
* Get an {@link IotDevice} for a connected device.
+ * No external validation of the attribute values is performed.
+ *
+ * @param deviceIdAttrs IotGateway implementation specific attributes
+ * that identify a device.
+ * @return IotDevice
+ */
+ IotDevice getIotDevice(Map<String,String> deviceIdAttrs);
+
+ /**
+ * Get a {@code deviceId} for a device.
+ * Logically equivalent to {@code getIotDevice(deviceIdAttrs).getDeviceId()}.
+ * No external validation of the attribute values is performed.
+ *
* @param deviceIdAttrs IotGateway implementation specific attributes
- * that identify a connected device.
- * @return
+ * that identify a device.
+ * @return deviceId
*/
- public IotDevice getIotDevice(Map<String,String> deviceIdAttrs);
+ String getIotDeviceId(Map<String,String> deviceIdAttrs);
/**
* Get an {@link IotDevice} for a connected device.
* @param deviceId a value from {@link IotDevice#getDeviceId()}.
- * @return
+ * @return IotDevice
+ */
+ IotDevice getIotDevice(String deviceId);
+
+ /**
+ * Publish a stream's tuples as device events.
+ * Each tuple is published as a device event with the supplied functions
+ * providing the device identifier, event identifier, payload and QoS.
+ * The values can be generated based upon the tuple.
+ * <p>
+ * Events for a particular device can also be published via its
+ * {@link IotDevice#events(TStream, Function, UnaryOperator, Function) IotDevice.events()}.
+ *
+ * @param deviceId
+ * function to supply the device-id that the event is associated with.
+ * @param stream
+ * Stream to be published.
+ * @param eventId
+ * function to supply the event identifier.
+ * @param payload
+ * function to supply the event's payload.
+ * @param qos
+ * function to supply the event's delivery Quality of Service.
+ * @return TSink sink element representing termination of this stream.
*/
- public IotDevice getIotDevice(String deviceId);
+ TSink<JsonObject> eventsForDevice(Function<JsonObject,String> deviceId,
+ TStream<JsonObject> stream, Function<JsonObject, String> eventId,
+ UnaryOperator<JsonObject> payload, Function<JsonObject, Integer> qos) ;
+
+ /**
+ * Publish a stream's tuples as device events.
+ * Each tuple is published as a device event with the supplied
+ * device identifier, event identifier, payload and QoS.
+ * <p>
+ * Events for a particular device can also be published via its
+ * {@link IotDevice#events(TStream, String, int) IotDevice.event()}.
+ *
+ * @param deviceId
+ * Device-id that the event is associated with.
+ * @param stream
+ * Stream to be published.
+ * @param eventId
+ * Event identifier.
+ * @param payload
+ * Event's payload.
+ * @param qos
+ * Event's delivery Quality of Service.
+ * @return TSink sink element representing termination of this stream.
+ */
+ TSink<JsonObject> eventsForDevice(String deviceId,
+ TStream<JsonObject> stream, String eventId, JsonObject payload, int qos) ;
/**
* Create a stream of device commands as JSON objects.
@@ -78,17 +147,45 @@ public interface IotGateway extends IotDevice {
* </UL>
* </LI>
* </UL>
- * <P>
- * This is logically equivalent to a union of a collection of individual IotDevice specific
+ *
+ * Logically equivalent to a union of a collection of individual IotDevice specific
* command streams but enables an IotGateway implementation to implement it more efficiently.
*
- * @param devices
- * Only return commands for the specified connected devices
+ * @param deviceIds
+ * Filter to include commands for the specified deviceIds
+ * If the set is empty no filtering occurs. The commands for any device are included.
* @param commands Command identifiers to include. If no command identifiers are provided then the
* stream will contain all device commands for the specified devices.
* @return Stream containing device commands.
*/
- TStream<JsonObject> commands(Collection<IotDevice> devices, String... commands);
+ TStream<JsonObject> commandsForDevice(Set<String> deviceIds, String... commands);
+
+ /**
+ * Create a stream of device commands as JSON objects.
+ * Each command sent to the specified device matching {@code commands} will
+ * result in a tuple on the stream. The JSON object has these keys:
+ * <UL>
+ * <LI>{@link IotDevice#CMD_DEVICE device} - Command's target device's opaque id String.
+ * <LI>{@link IotDevice#CMD_ID command} - Command identifier as a String</LI>
+ * <LI>{@link IotDevice#CMD_TS tsms} - Timestamp of the command in milliseconds since the 1970/1/1 epoch.</LI>
+ * <LI>{@link IotDevice#CMD_FORMAT format} - Format of the command as a String</LI>
+ * <LI>{@link IotDevice#CMD_PAYLOAD payload} - Payload of the command
+ * <UL>
+ * <LI>If {@code format} is {@code json} then {@code payload} is JSON</LI>
+ * <LI>Otherwise {@code payload} is String</LI>
+ * </UL>
+ * </LI>
+ * </UL>
+ * <P>
+ * Equivalent to {@code commandsForDevice(Collections.singleton(deviceId)), ...}.
+ *
+ * @param deviceId
+ * Filter to include commands for the specified deviceId
+ * @param commands Command identifiers to include. If no command identifiers are provided then the
+ * stream will contain all device commands for the specified device.
+ * @return Stream containing device commands.
+ */
+ TStream<JsonObject> commandsForDevice(String deviceId, String... commands);
/**
* Create a stream of device commands as JSON objects.
http://git-wip-us.apache.org/repos/asf/incubator-edgent/blob/26c198b6/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java
----------------------------------------------------------------------
diff --git a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java
index 0e85756..374f5fa 100644
--- a/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java
+++ b/connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java
@@ -20,13 +20,25 @@ under the License.
/**
* Edgent IoT device and IoT Gateway device connector API to an IoT message hub.
* <P>
- * An IoT device can publish device events and receive device commands from an IoT hub.
- * An IoT Gateway device is an IoT device that also acts as a conduit for
- * its "connected" IoT devices. The connected devices lack direct connectivity to the
- * IoT hub. Their events are published and their commands are received via the gateway.
+ * An IoT environment consists of an enterprise IoT message hub and devices and other clients
+ * connected to it.
+ * Each IoT device has an identity in the hub. The form of a device's identity is the domain
+ * of an IoT hub implementation.
+ * How a device becomes registered to an IoT hub and generally what device management capabilities
+ * exist and how a device is managed is beyond the scope of the
+ * "analytic pipelines" focused Edgent APIs.
* </P>
* <P>
- * More specifically, the generic device model consists of:
+ * An IoT device can publish device events to and receive device commands from an IoT hub.
+ * An IoT gateway device is an IoT device that is also conduit for a collection of IoT devices
+ * that lack direct connection to the enterprise IoT hub.
+ * A gateway can publish events on behalf of its connected devices and
+ * receive commands from the hub targeted to them.
+ * An Edgent IoT hub connector bridges the gap between this generic model and and
+ * particular IoT hub implementation's underlying protocols.
+ * </P>
+ * <P>
+ * More specifically, the generic IoT device model consists of:
* <UL>
* <LI>
* <B>Device events</B> - A device {@link org.apache.edgent.connectors.iot.IotDevice#events(org.apache.edgent.topology.TStream, String, int) publishes} <em>events</em> as messages to a message hub to allow