Commit 26760cb8 authored by Martin Grzenia's avatar Martin Grzenia
Browse files

Add classes for a new device registration process



* Add DeviceInstance and DeviceType that replace the previously used
  Device data structure.
* Deprecate org.siliconeconomy.iotbroker.model.device.Device.

Co-authored-by: David Ronnenberg's avatarDavid Ronnenberg <david.ronnenberg@iml.fraunhofer.de>
parent 05679155
......@@ -3,6 +3,14 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [5.4.0] - 2022-02-22
### Added
- Data structures to be used with a new, more sophisticated device registration process.
This process revolves around device instances and device types.
### Changed
- Deprecate `org.siliconeconomy.iotbroker.model.device.Device` in favor of `org.siliconeconomy.iotbroker.model.device.DeviceInstance` and `org.siliconeconomy.iotbroker.model.device.DeviceType`.
## [5.3.0] - 2022-02-15
### Added
- Add support for global queries in a partitioned CouchDB repository.
......
......@@ -11,7 +11,7 @@
<groupId>org.siliconeconomy.iotbroker</groupId>
<artifactId>sdk</artifactId>
<version>5.3.0</version>
<version>5.4.0</version>
<licenses>
<license>
......
......@@ -20,12 +20,14 @@
* is done merely to avoid checks for {@code null}.
*
* @author M. Grzenia
* @deprecated Use {@link DeviceInstance} instead.
*/
@RequiredArgsConstructor
@Getter
@With
@EqualsAndHashCode
@ToString
@Deprecated
public class Device {
/**
......
/*
* Copyright 2021 Open Logistics Foundation
*
* Licensed under the Open Logistics License 1.0.
* For details on the licensing terms, see the LICENSE file.
*/
package org.siliconeconomy.iotbroker.model.device;
import lombok.*;
import org.checkerframework.checker.nullness.qual.NonNull;
import java.time.Instant;
/**
* A representation of a device that is known to the IoT Broker.
* <p>
* A device is defined by the following properties:
* <ul>
* <li>It is uniquely identifiable via its {@link #source} and {@link #tenant}. Multiple devices
* with the same source and tenant are therefore not allowed.</li>
* <li>It is always associated with a specific {@link DeviceType}.</li>
* </ul>
* In addition to the properties listed above, this class contains information that is important in
* the context of the IoT Broker (e.g. the registration time or whether the device is enabled) and
* information describing details about the device itself (e.g. the device's firmware version).
* <p>
* For fields containing optional information, most, if not all, are required not to be
* {@code null}. This is done merely to avoid checks for {@code null}.
*
* @author M. Grzenia
* @author D. Ronnenberg
*/
@RequiredArgsConstructor
@Getter
@With
@EqualsAndHashCode
@ToString
public class DeviceInstance {
/**
* A unique identifier for this {@link DeviceInstance} instance.
* <p>
* This field is not to be confused with the {@link #tenant} field.
* While the id is used to uniquely identify a device instance across <em>all</em> device
* instances, regardless of any other device instance properties, the tenant can only be
* used to uniquely identify a device instance in the context of the {@link #source} it is
* associated with.
* <p>
* Some APIs may support using this attribute as an alternative shortcut for accessing device
* instances.
*/
@NonNull
private final String id;
/**
* The source that the device is associated with. (E.g. as a source of data.)
*/
@NonNull
private final String source;
/**
* A unique identifier for the device. (E.g. the device ID. Only unique in the context of the
* device's source.)
*/
@NonNull
private final String tenant;
/**
* The identifier of the {@link DeviceType} the device is associated with.
*/
@NonNull
private final String deviceTypIdentifier;
/**
* The date and time at which the device was registered.
*/
@NonNull
private final Instant registrationTime;
/**
* The date and time when the device was last seen.
* <p>
* If there has been no communication with the device so far, the value is
* {@link Instant#EPOCH}.
*/
@NonNull
private final Instant lastSeen;
/**
* Whether the device is enabled or not.
* <p>
* For disabled devices, incoming data will not be processed by their associated adapter.
*/
private final boolean enabled;
/**
* A description for the device.
* <p>
* Optional: May be an empty string.
*/
@NonNull
private final String description;
/**
* The device's hardware revision.
* <p>
* Optional: May be an empty string.
*/
@NonNull
private final String hardwareRevision;
/**
* The device's firmware version.
* Optional: May be an empty string.
*/
@NonNull
private final String firmwareVersion;
}
/*
* Copyright 2021 Open Logistics Foundation
*
* Licensed under the Open Logistics License 1.0.
* For details on the licensing terms, see the LICENSE file.
*/
package org.siliconeconomy.iotbroker.model.device;
import lombok.*;
import org.checkerframework.checker.nullness.qual.NonNull;
import java.util.Set;
/**
* A device type contains information concerning multiple devices of the same type.
* <p>
* A device type can be considered as a <em>logical</em> group of devices that are similar with
* respect to one or more distinctive characteristics. Examples of such characteristics can be:
* <ul>
* <li>The name of the device model.</li>
* <li>A revision or version of the device's hardware or software.</li>
* <li>Other device properties.</li>
* </ul>
* These characteristics, or even a combination of them, can be used to describe a particular type
* of device. For example, if the revision of a device's hardware changes, the device could be
* considered a different type than it was at a previous revision.
* <p>
* In any case, a device type is uniquely identifiable via its {@link #source} and
* {@link #identifier}. Multiple device types with the same source and identifier are therefore not
* allowed.
*
* @author M. Grzenia
* @author D. Ronnenberg
* @see DeviceInstance
*/
@RequiredArgsConstructor
@Getter
@With
@EqualsAndHashCode
@ToString
public class DeviceType {
/**
* A unique identifier for this {@link DeviceType} instance.
* <p>
* This field is not to be confused with the {@link #identifier} field.
* While the id is used to uniquely identify a device type across <em>all</em> device
* types, regardless of any other device type properties, the identifier can only be
* used to uniquely identify a device type in the context of the {@link #source} it is
* associated with.
* <p>
* Some APIs may support using this attribute as an alternative shortcut for accessing device
* types.
*/
@NonNull
private final String id;
/**
* The source that the device type is associated with. (E.g. as a source of data.)
*/
@NonNull
private final String source;
/**
* A unique identifier for the device type. (Only unique in the context of the device type's
* source.)
*/
@NonNull
private final String identifier;
/**
* A list of adapters (more specifically adapter identifiers) via which devices of this type are
* provided within the IoT Broker.
*/
@NonNull
private final Set<String> providedBy;
/**
* A description for the device type.
* <p>
* Optional: May be an empty string.
*/
@NonNull
private final String description;
/**
* Whether the entire device type is enabled or not.
* <p>
* For devices that are associated with a disabled device type, incoming data will not be
* processed by the associated adapters.
*/
private final boolean enabled;
/**
* Whether new, as yet unknown {@link DeviceInstance}s associated with this device type should
* be automatically registered with the IoT Broker.
*/
private final boolean autoRegisterDeviceInstances;
/**
* Whether newly registered {@link DeviceInstance}s associated with this device type should be
* enabled automatically.
*/
private final boolean autoEnableDeviceInstances;
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment