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 <[email protected]> Authored: Fri Feb 3 16:16:34 2017 -0500 Committer: Dale LaBossiere <[email protected]> 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
