#743: Add documentation + fast fail when null is used for callback

leshan-core-cf/src/main/java/org/eclipse/leshan/core/californium/AsyncRequestObserver.java

@@ -21,8 +21,30 @@
 import org.eclipse.leshan.core.response.LwM2mResponse;
 import org.eclipse.leshan.core.response.ResponseCallback;
 
+/**
+ * A dedicated {@link CoapAsyncRequestObserver} for LWM2M.
+ * <p>
+ * A {@link LwM2mResponse} is created from the CoAP Response received. This behavior is not implemented and should be
+ * provided by overriding {@link #buildResponse(Response)}.
+ * 
+ * @param <T> the type of the {@link LwM2mResponse} to build from the CoAP response
+ */
 public abstract class AsyncRequestObserver<T extends LwM2mResponse> extends CoapAsyncRequestObserver {
 
+    /**
+     * A Californium message observer for a CoAP request helping to get results asynchronously dedicated for LWM2M
+     * requests.
+     * <p>
+     * The Californium API does not ensure that message callback are exclusive. E.g. In some race condition, you can get
+     * a onReponse call and a onCancel one. The CoapAsyncRequestObserver ensure that you will receive only one event.
+     * Meaning, you get either 1 response or 1 error.
+     * 
+     * @param coapRequest The CoAP request to observe.
+     * @param responseCallback This is called when a response is received. This MUST NOT be null.
+     * @param errorCallback This is called when an error happens. This MUST NOT be null.
+     * @param timeoutInMs A response timeout(in millisecond) which is raised if neither a response or error happens (see
+     *        https://github.com/eclipse/leshan/wiki/Request-Timeout).
+     */
     public AsyncRequestObserver(Request coapRequest, final ResponseCallback<T> responseCallback,
             final ErrorCallback errorCallback, long timeoutInMs) {
         super(coapRequest, null, errorCallback, timeoutInMs);
@@ -43,5 +65,11 @@ public void onResponse(Response coapResponse) {
         };
     }
 
+    /**
+     * Build the {@link LwM2mResponse} from the CoAP {@link Response}.
+     * 
+     * @param coapResponse The CoAP response received.
+     * @return the corresponding {@link LwM2mResponse}.
+     */
     protected abstract T buildResponse(Response coapResponse);
 }

leshan-core-cf/src/main/java/org/eclipse/leshan/core/californium/CoapAsyncRequestObserver.java

@@ -34,6 +34,15 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * A Californium message observer for a CoAP request.
+ * <p>
+ * Either a response or an error is raised. Results are available via callbacks.
+ * <p>
+ * This class also provides response timeout facility.
+ * 
+ * @see https://github.com/eclipse/leshan/wiki/Request-Timeout for more details.
+ */
 public class CoapAsyncRequestObserver extends AbstractRequestObserver {
 
     private static final Logger LOG = LoggerFactory.getLogger(CoapAsyncRequestObserver.class);
@@ -54,6 +63,19 @@ public class CoapAsyncRequestObserver extends AbstractRequestObserver {
 
     private final AtomicBoolean responseTimedOut = new AtomicBoolean(false);
 
+    /**
+     * A Californium message observer for a CoAP request helping to get results asynchronously.
+     * <p>
+     * The Californium API does not ensure that message callback are exclusive. E.g. In some race condition, you can get
+     * a onReponse call and a onCancel one. The CoapAsyncRequestObserver ensure that you will receive only one event.
+     * Meaning, you get either 1 response or 1 error.
+     * 
+     * @param coapRequest The CoAP request to observe.
+     * @param responseCallback This is called when a response is received. This MUST NOT be null.
+     * @param errorCallback This is called when an error happens. This MUST NOT be null.
+     * @param timeoutInMs A response timeout(in millisecond) which is raised if neither a response or error happens (see
+     *        https://github.com/eclipse/leshan/wiki/Request-Timeout).
+     */
     public CoapAsyncRequestObserver(Request coapRequest, CoapResponseCallback responseCallback,
             ErrorCallback errorCallback, long timeoutInMs) {
         super(coapRequest);

leshan-core-cf/src/main/java/org/eclipse/leshan/core/californium/CoapSyncRequestObserver.java

@@ -29,6 +29,15 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * A Californium message observer for a CoAP request.
+ * <p>
+ * Results are available via synchronous {@link #waitForCoapResponse()} method.
+ * <p>
+ * This class also provides response timeout facility.
+ * 
+ * @see https://github.com/eclipse/leshan/wiki/Request-Timeout for more details.
+ */
 public class CoapSyncRequestObserver extends AbstractRequestObserver {
 
     private static final Logger LOG = LoggerFactory.getLogger(CoapSyncRequestObserver.class);
@@ -39,9 +48,14 @@ public class CoapSyncRequestObserver extends AbstractRequestObserver {
     private AtomicReference<RuntimeException> exception = new AtomicReference<>();
     private long timeout;
 
-    public CoapSyncRequestObserver(Request coapRequest, long timeout) {
+    /**
+     * @param coapRequest The CoAP request to observe.
+     * @param timeoutInMs A response timeout(in millisecond) which is raised if neither a response or error happens (see
+     *        https://github.com/eclipse/leshan/wiki/Request-Timeout).
+     */
+    public CoapSyncRequestObserver(Request coapRequest, long timeoutInMs) {
         super(coapRequest);
-        this.timeout = timeout;
+        this.timeout = timeoutInMs;
     }
 
     @Override
@@ -80,6 +94,17 @@ public void onSendError(Throwable error) {
         latch.countDown();
     }
 
+    /**
+     * Wait for the CoAP response.
+     * 
+     * @return the CoAP response. The response can be <code>null</code> if the timeout expires (see
+     *         https://github.com/eclipse/leshan/wiki/Request-Timeout).
+     * 
+     * @throws InterruptedException if the thread was interrupted.
+     * @throws RequestRejectedException if the request is rejected by foreign peer.
+     * @throws RequestCanceledException if the request is cancelled.
+     * @throws SendFailedException if the request can not be sent. E.g. error at CoAP or DTLS/UDP layer.
+     */
     public Response waitForCoapResponse() throws InterruptedException {
         try {
             boolean timeElapsed = false;

leshan-core-cf/src/main/java/org/eclipse/leshan/core/californium/SyncRequestObserver.java

@@ -17,14 +17,37 @@
 
 import org.eclipse.californium.core.coap.Request;
 import org.eclipse.californium.core.coap.Response;
+import org.eclipse.leshan.core.request.exception.InvalidResponseException;
+import org.eclipse.leshan.core.request.exception.RequestRejectedException;
+import org.eclipse.leshan.core.request.exception.SendFailedException;
 import org.eclipse.leshan.core.response.LwM2mResponse;
 
+/**
+ * A dedicated {@link SyncRequestObserver} for LWM2M.
+ * <p>
+ * A {@link LwM2mResponse} is created from the CoAP Response received. This behavior is not implemented and should be
+ * provided by overriding {@link #buildResponse(Response)}.
+ * 
+ * @param <T> the type of the {@link LwM2mResponse} to build from the CoAP response
+ */
 public abstract class SyncRequestObserver<T extends LwM2mResponse> extends CoapSyncRequestObserver {
 
     public SyncRequestObserver(Request coapRequest, long timeout) {
         super(coapRequest, timeout);
     }
 
+    /**
+     * Wait for the LWM2M response.
+     * 
+     * @return the LWM2M response. The response can be <code>null</code> if the timeout expires (see
+     *         https://github.com/eclipse/leshan/wiki/Request-Timeout).
+     * 
+     * @throws InterruptedException if the thread was interrupted.
+     * @throws RequestRejectedException if the request is rejected by foreign peer.
+     * @throws RequestCanceledException if the request is cancelled.
+     * @throws SendFailedException if the request can not be sent. E.g. error at CoAP or DTLS/UDP layer.
+     * @throws InvalidResponseException if the response received is malformed.
+     */
     public T waitForResponse() throws InterruptedException {
         Response coapResponse = waitForCoapResponse();
         if (coapResponse != null) {