From 742669f757e6cca77b6dccf6d5c157d7b8b29b52 Mon Sep 17 00:00:00 2001
From: Simon Bernard <sbernard@sierrawireless.com>
Date: Thu, 17 Oct 2019 18:18:29 +0200
Subject: [PATCH] #751: Add some documentation about listener execution.

---
 .../server/observation/ObservationListener.java | 17 +++++++++++++++++
 .../leshan/server/queue/PresenceListener.java   |  4 +++-
 .../registration/RegistrationListener.java      |  3 +++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/leshan-server-core/src/main/java/org/eclipse/leshan/server/observation/ObservationListener.java b/leshan-server-core/src/main/java/org/eclipse/leshan/server/observation/ObservationListener.java
index 39f77b3406..c7f75cb4bc 100644
--- a/leshan-server-core/src/main/java/org/eclipse/leshan/server/observation/ObservationListener.java
+++ b/leshan-server-core/src/main/java/org/eclipse/leshan/server/observation/ObservationListener.java
@@ -19,10 +19,27 @@
 import org.eclipse.leshan.core.response.ObserveResponse;
 import org.eclipse.leshan.server.registration.Registration;
 
+/**
+ * Monitor observation lifetime.
+ * <p>
+ * Those methods are called by the protocol stage thread pool, this means that execution MUST be done in a short delay,
+ * if you need to do long time processing use a dedicated thread pool.
+ */
 public interface ObservationListener {
 
+    /**
+     * Called when a new observation is created.
+     * 
+     * @param observation the new observation.
+     * @param registration the related registration
+     */
     void newObservation(Observation observation, Registration registration);
 
+    /**
+     * Called when an observation is cancelled.
+     * 
+     * @param observation the cancelled observation.
+     */
     void cancelled(Observation observation);
 
     /**
diff --git a/leshan-server-core/src/main/java/org/eclipse/leshan/server/queue/PresenceListener.java b/leshan-server-core/src/main/java/org/eclipse/leshan/server/queue/PresenceListener.java
index c319850af8..d62df42b7c 100644
--- a/leshan-server-core/src/main/java/org/eclipse/leshan/server/queue/PresenceListener.java
+++ b/leshan-server-core/src/main/java/org/eclipse/leshan/server/queue/PresenceListener.java
@@ -19,7 +19,9 @@
 
 /**
  * A listener aware of the status of LWM2M Client using queue mode binding.
- *
+ * <p>
+ * Those methods are called by the protocol stage thread pool, this means that execution MUST be done in a short delay,
+ * if you need to do long time processing use a dedicated thread pool.
  */
 public interface PresenceListener {
 
diff --git a/leshan-server-core/src/main/java/org/eclipse/leshan/server/registration/RegistrationListener.java b/leshan-server-core/src/main/java/org/eclipse/leshan/server/registration/RegistrationListener.java
index 00a033bd9a..f8fa2cc94b 100644
--- a/leshan-server-core/src/main/java/org/eclipse/leshan/server/registration/RegistrationListener.java
+++ b/leshan-server-core/src/main/java/org/eclipse/leshan/server/registration/RegistrationListener.java
@@ -21,6 +21,9 @@
 
 /**
  * Listen for client registration events.
+ * <p>
+ * Those methods are called by the protocol stage thread pool, this means that execution MUST be done in a short delay,
+ * if you need to do long time processing use a dedicated thread pool.
  */
 public interface RegistrationListener {