Updated Javadoc of most sensiNact examples

core/annotation/src/main/java/org/eclipse/sensinact/core/annotation/verb/UriParam.java

@@ -26,12 +26,13 @@
 public @interface UriParam {
 
     /**
-     * What part of the URI should be passed
-     *
-     * @return
+     * What part of the URI should be passed ( {@link UriSegment#URI} by default)
      */
     UriSegment value() default UriSegment.URI;
 
+    /**
+     * URI segment that can be provided as whiteboard method argument
+     */
     public enum UriSegment {
         /** The whole URI */
         URI,

examples/action/src/main/java/org/eclipse/sensinact/prototype/action/_01_SimpleActionResource.java

@@ -20,21 +20,21 @@
 import org.osgi.service.component.annotations.Component;
 
 /**
- * Service properties define the provider that this resource is for
+ * This sample component handles the ACT verb of the "action" resource of the
+ * "example" service of the "actionResource" provider
  */
-@WhiteboardResource
-@ProviderName("pull_based")
-@Component(service = _01_SimpleActionResource.class)
+@WhiteboardResource // Adds the property to be detected by sensiNact
+@ProviderName("actionResource") // Service property to define the provider that this resource is for
+@Component(service = _01_SimpleActionResource.class) // The component must provide a service to be detected
 public class _01_SimpleActionResource {
 
     /**
-     * A GET method for a service and resource
-     *
-     * @return
+     * An ACT method for service "example" and resource "action". This action takes
+     * no argument and returns a list of long integers.
      */
-    @ACT(model = "testModel", service = "example", resource = "default")
+    @ACT(model = "testModel", service = "example", resource = "action")
     public List<Long> doAction() {
         // Run the action and return the result
-        return null;
+        return List.of(42L);
     }
 }

examples/action/src/main/java/org/eclipse/sensinact/prototype/action/_02_MultiActionResource.java

@@ -20,22 +20,44 @@
 import org.osgi.service.component.annotations.Component;
 
 /**
- * Multiple providers from a single service, different methods for each resource
+ * This sample component handles the ACT verb for multiple resources of multiple
+ * providers, with one method per resource
  */
-@WhiteboardResource
-@ProviderName({ "foo", "bar", "foobar" })
-@Component(service = _02_MultiActionResource.class)
+@WhiteboardResource // Adds the property to be detected by sensiNact
+@ProviderName({ "foo", "bar", "foobar" }) // Names of the providers those resources are provided by
+@Component(service = _02_MultiActionResource.class) // The component must provide a service to be detected
 public class _02_MultiActionResource {
 
+    /**
+     * An ACT handler for service "example" and resource "fizz". This action takes
+     * takes no argument from the caller, but accepts the name of the provider of
+     * the called resource as URI parameter (see {@link UriParam}) from sensiNact.
+     *
+     * @param provider Provider name
+     */
     @ACT(model = "testModel", service = "example", resource = "fizz")
-    public void setFizz(@UriParam(UriSegment.PROVIDER) String provider) {
+    public void actFizz(@UriParam(UriSegment.PROVIDER) String provider) {
     }
 
+    /**
+     * An ACT handler for service "example" and resource "buzz". This action takes
+     * takes no argument from the caller, but accepts the name of the provider of
+     * the called resource as URI parameter (see {@link UriParam}) from sensiNact.
+     *
+     * @param provider Provider name
+     */
     @ACT(model = "testModel", service = "example", resource = "buzz")
-    public void setBuzz(@UriParam(UriSegment.PROVIDER) String provider) {
+    public void actBuzz(@UriParam(UriSegment.PROVIDER) String provider) {
     }
 
+    /**
+     * An ACT handler for service "example" and resource "fizzbuzz". This action
+     * takes no argument from the caller, but accepts the name of the provider of
+     * the called resource as URI parameter (see {@link UriParam}) from sensiNact.
+     *
+     * @param provider Provider name
+     */
     @ACT(model = "testModel", service = "example", resource = "fizzbuzz")
-    public void setFizzBuzz(@UriParam(UriSegment.PROVIDER) String provider) {
+    public void actFizzBuzz(@UriParam(UriSegment.PROVIDER) String provider) {
     }
 }

examples/action/src/main/java/org/eclipse/sensinact/prototype/action/_03_MultiActionResource.java

@@ -20,18 +20,28 @@
 import org.osgi.service.component.annotations.Component;
 
 /**
- * Multiple providers from a single service, a single method for all resources
+ * This sample component handles the ACT verb for multiple resources of multiple
+ * providers, sharing a single method for all resources
  */
-@WhiteboardResource
-@ProviderName({ "foo", "bar", "foobar" })
-@Component(service = _03_MultiActionResource.class)
+@WhiteboardResource // Adds the property to be detected by sensiNact
+@ProviderName({ "foo", "bar", "foobar" }) // Names of the providers those resources are provided by
+@Component(service = _03_MultiActionResource.class) // The component must provide a service to be detected
 public class _03_MultiActionResource {
 
+    /**
+     * An ACT handler for multiple resources, from different services. The action
+     * handler takes no argument from the caller, but accepts different URI
+     * parameters (see {@link UriParam}) from sensiNact.
+     *
+     * @param provider Provider name
+     * @param service  Service name
+     * @param resource Resource name
+     */
     @ACT(model = "testModel", service = "example", resource = "fizz")
     @ACT(model = "testModel", service = "example", resource = "buzz")
     @ACT(model = "testModel", service = "example2", resource = "fizzbuzz")
-    public void setValue(@UriParam(UriSegment.PROVIDER) String provider, @UriParam(UriSegment.SERVICE) String service,
-            @UriParam(UriSegment.RESOURCE) String resource) {
-        // Get the actual value from the sensor
+    public void actResource(@UriParam(UriSegment.PROVIDER) String provider,
+            @UriParam(UriSegment.SERVICE) String service, @UriParam(UriSegment.RESOURCE) String resource) {
+        // Do work based on resource information
     }
 }

examples/action/src/main/java/org/eclipse/sensinact/prototype/action/_04_ParameterActionResource.java

@@ -12,30 +12,34 @@
 **********************************************************************/
 package org.eclipse.sensinact.prototype.action;
 
+import java.time.Duration;
 import java.time.Instant;
-import java.util.List;
 
 import org.eclipse.sensinact.core.annotation.propertytype.ProviderName;
 import org.eclipse.sensinact.core.annotation.propertytype.WhiteboardResource;
 import org.eclipse.sensinact.core.annotation.verb.ACT;
 import org.osgi.service.component.annotations.Component;
 
 /**
- * Service properties define the provider that this resource is for
+ * This sample component handles the ACT verb of the "delta" resource of the
+ * "example" service of the "actionResource" provider. The sample handler
+ * accepts caller arguments.
  */
-@WhiteboardResource
-@ProviderName("pull_based")
-@Component(service = _04_ParameterActionResource.class)
+@WhiteboardResource // Adds the property to be detected by sensiNact
+@ProviderName("actionResource") // Name of the provider the resource is provided by
+@Component(service = _04_ParameterActionResource.class) // The component must provide a service to be detected
 public class _04_ParameterActionResource {
 
     /**
-     * A GET method for a service and resource
+     * An ACT method for service "example" and resource "delta". This action takes
+     * two arguments from the caller and returns a value.
      *
-     * @return
+     * @param fromTime A parameter given by the caller
+     * @param toTime   A parameter given by the caller
      */
-    @ACT(model = "testModel", service = "example", resource = "default")
-    public List<Long> doAction(Instant fromTime, Instant toTime) {
+    @ACT(model = "testModel", service = "example", resource = "delta")
+    public Long doAction(Instant fromTime, Instant toTime) {
         // Run the action and return the result
-        return null;
+        return Duration.between(fromTime, toTime).getSeconds();
     }
 }

examples/generic/src/main/java/org/eclipse/sensinact/prototype/generic/GenericPushComponent.java

@@ -19,34 +19,49 @@
 import org.osgi.service.component.annotations.Reference;
 import org.osgi.service.typedevent.TypedEventBus;
 
+/**
+ * This components show to push an update event to sensiNact using a
+ * {@link GenericDto} object.
+ */
 @Component
 public class GenericPushComponent {
 
+    /**
+     * Service to send the update event through the typed event bus
+     */
     @Reference
     private TypedEventBus bus;
 
+    /**
+     * Service to send the update event through the update DTO handler
+     */
     @Reference
     private PrototypePush sensiNact;
 
     /**
      * Message coming in from the sensor, just like a custom model
      */
     public void onMessage(String message) {
-        // Create the DTO
+        // Create the DTO based on sensor data
         GenericDto dto = toDTO(message);
 
-        // Send the dto data to sensiNact core somehow?
-
-        // e.g. Typed Events
+        // Send the DTO to sensiNact core, either via:
+        // ... Typed Events
         bus.deliver(EventTopicNames.GENERIC_UPDATE_EVENTS, dto);
 
-        // e.g. Direct to core
+        // ... Direct to core using the DTO handler
         sensiNact.pushUpdate(dto);
     }
 
+    /**
+     * Internal method to convert sensor data into an update DTO
+     *
+     * @param message Sensor data
+     * @return A resource value/metadata update DTO
+     */
     GenericDto toDTO(String message) {
         GenericDto dto = new GenericDto();
-        // Populate the DTO
+        // Populate the DTO: model, provider, service, resource, value and timestamp
         return dto;
     }
 

examples/notification/src/main/java/notification/_01_SimpleNotification.java

@@ -18,16 +18,22 @@
 import org.osgi.service.typedevent.propertytypes.EventTopics;
 
 /**
- * Notified for all data events
+ * This component is registered as typed event handler that listens to all data
+ * events. This type of listener is notified of all events from the sensiNact
+ * core and is not associated to a session.
  */
-@Component
-@EventTopics("DATA/*")
+@Component // The TypedEventHandler interface will automatically be registered as a service
+@EventTopics("DATA/*") // Filter on typed event topics
 public class _01_SimpleNotification implements TypedEventHandler<ResourceDataNotification> {
 
+    /**
+     * Method called when a typed event with a matching topic is received
+     *
+     * @param topic Event topic
+     * @param event Received data event
+     */
     @Override
     public void notify(String topic, ResourceDataNotification event) {
         // TODO Auto-generated method stub
-
     }
-
 }

examples/notification/src/main/java/notification/_02_ClientNotification.java

@@ -18,10 +18,12 @@
 import org.eclipse.sensinact.core.session.SensiNactSession;
 import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Deactivate;
 import org.osgi.service.component.annotations.Reference;
 
 /**
- * Notified for all data events visible to the client
+ * This component uses the session notification process to be notified of all
+ * data events visible by the client.
  */
 @Component
 public class _02_ClientNotification {
@@ -30,15 +32,39 @@ public class _02_ClientNotification {
     @Reference
     SensiNactSession session;
 
+    /**
+     * ID of the listener we registered
+     */
+    private String listenerId;
+
+    /**
+     * Component is activated: register the listener
+     */
     @Activate
     void start() {
         // We ask for * but only events visible to the user will be seen
-        session.addListener(List.of("*"), this::notify, null, null, null);
+        // Note that we only register a handler for data notifications
+        listenerId = session.addListener(List.of("*"), this::notify, null, null, null);
+    }
+
+    /**
+     * Component is deactivated: don't forget to unregister the listener
+     */
+    @Deactivate
+    void stop() {
+        if (listenerId != null) {
+            session.removeListener(listenerId);
+            listenerId = null;
+        }
     }
 
+    /**
+     * Called when a visible data notification is received
+     *
+     * @param topic Topic of the notification typed event
+     * @param event The data event
+     */
     private void notify(String topic, ResourceDataNotification event) {
         // TODO Auto-generated method stub
-
     }
-
 }

examples/pull-based/pom.xml

@@ -38,6 +38,11 @@ SPDX-License-Identifier: EPL-2.0
       <artifactId>annotation</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.eclipse.sensinact.gateway.core</groupId>
+      <artifactId>api</artifactId>
+      <version>${project.version}</version>
+    </dependency>
   </dependencies>
 
   <build>

examples/pull-based/src/main/java/org/eclipse/sensinact/prototype/pull/_01_SimplePullBasedResource.java

@@ -12,27 +12,44 @@
 **********************************************************************/
 package org.eclipse.sensinact.prototype.pull;
 
+import java.time.temporal.ChronoUnit;
+
 import org.eclipse.sensinact.core.annotation.propertytype.ProviderName;
 import org.eclipse.sensinact.core.annotation.propertytype.WhiteboardResource;
 import org.eclipse.sensinact.core.annotation.verb.GET;
+import org.eclipse.sensinact.core.command.GetLevel;
 import org.osgi.service.component.annotations.Component;
 
 /**
- * Service properties define the provider that this pull based resource is for
+ * This component provides a custom handler to get the current value of a
+ * resource.
+ *
+ * Note that such handler is called if:
+ * <ul>
+ * <li>... the resource doesn't have a value yet</li>
+ * <li>... if the value request is a strong GET (see
+ * {@link GetLevel#STRONG})</li>
+ * <li>... if the value request is a normal (default) GET (see
+ * {@link GetLevel#NORMAL}) and if the data cache period has expired</li>
+ * </ul>
+ *
+ * The handler is never called if the value request is a weak GET (see
+ * {@link GetLevel#WEAK}).
  */
-@WhiteboardResource
-@ProviderName("pull_based")
-@Component(service = _01_SimplePullBasedResource.class)
+@WhiteboardResource // Adds the property to be detected by sensiNact
+@ProviderName("pull-based") // Service property to define the provider that this resource is for
+@Component(service = _01_SimplePullBasedResource.class) // The component must provide a service to be detected
 public class _01_SimplePullBasedResource {
 
     /**
-     * A GET method for a service and resource
+     * A GET method for resource "getter" of service "example".
      *
-     * @return
+     * The annotation also indicates how long the cached value is considered valid
+     * (500&nbsp;ms by default).
      */
-    @GET(service = "example", resource = "default")
+    @GET(service = "example", resource = "getter", cacheDuration = 5, cacheDurationUnit = ChronoUnit.MINUTES)
     public Double getValue() {
         // Get the value from the sensor
-        return null;
+        return 42.0;
     }
 }