Javadocs to http mods (cloudevents#320)

Signed-off-by: Francesco Guardiani <[email protected]>

Author: slinkydeveloper

http/restful-ws/src/main/java/io/cloudevents/http/restful/ws/CloudEventsProvider.java

@@ -24,7 +24,6 @@
 import io.cloudevents.http.restful.ws.impl.RestfulWSClientMessageWriter;
 import io.cloudevents.http.restful.ws.impl.RestfulWSMessageFactory;
 import io.cloudevents.http.restful.ws.impl.RestfulWSMessageWriter;
-import io.cloudevents.http.restful.ws.impl.Utils;
 import io.cloudevents.rw.CloudEventWriter;
 
 import javax.ws.rs.Consumes;
@@ -47,7 +46,7 @@
 import java.util.Optional;
 
 /**
- * This provider implements {@link CloudEvent} encoding and decoding for Jax-Rs Resources and {@link javax.ws.rs.client.Client}
+ * This provider implements {@link CloudEvent} encoding and decoding for Jax-Rs Resources and with {@link javax.ws.rs.client.Client}.
  */
 @Provider
 @Consumes(MediaType.WILDCARD)
@@ -133,7 +132,7 @@ private <V extends MessageWriter<V, Void> & CloudEventWriter<Void>> void writeSt
 
     @Override
     public void filter(ClientRequestContext requestContext) throws IOException {
-        if (Utils.isCloudEventEntity(requestContext.getEntity())) {
+        if (isCloudEventEntity(requestContext.getEntity())) {
             EventFormat format = EventFormatProvider.getInstance().resolveFormat(requestContext.getMediaType().toString());
 
             if (format != null) {
@@ -150,4 +149,9 @@ public void filter(ClientRequestContext requestContext) throws IOException {
             }
         }
     }
+
+    private static boolean isCloudEventEntity(Object obj) {
+        return obj != null && CloudEvent.class.isAssignableFrom(obj.getClass());
+    }
+
 }

http/restful-ws/src/main/java/io/cloudevents/http/restful/ws/StructuredEncoding.java

@@ -30,8 +30,9 @@
 @Retention(RetentionPolicy.RUNTIME)
 public @interface StructuredEncoding {
     /**
-     * Specify the content type of the structured mode
-     * (used to resolve the {@link io.cloudevents.core.format.EventFormat} through the {@link io.cloudevents.core.provider.EventFormatProvider})
+     * Specify the content type of the structured mode.
+     * This values will be used to resolve the {@link io.cloudevents.core.format.EventFormat} through
+     * the {@link io.cloudevents.core.provider.EventFormatProvider}.
      */
     String value();
 }

http/restful-ws/src/main/java/io/cloudevents/http/restful/ws/impl/Utils.java

@@ -11,7 +11,10 @@
 import io.cloudevents.lang.Nullable;
 import io.cloudevents.rw.CloudEventRWException;
 import io.cloudevents.rw.CloudEventWriter;
-import io.vertx.core.*;
+import io.vertx.core.AsyncResult;
+import io.vertx.core.Future;
+import io.vertx.core.Handler;
+import io.vertx.core.MultiMap;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.http.HttpHeaders;
 import io.vertx.core.http.HttpServerRequest;
@@ -23,7 +26,7 @@
 
 /**
  * This class provides a collection of methods to create {@link io.cloudevents.core.message.MessageReader}
- * and {@link io.cloudevents.core.message.MessageWriter} for Vert.x HTTP Server and Web Client.
+ * and {@link io.cloudevents.core.message.MessageWriter} for Vert.x {@link io.vertx.core.http.HttpServer} and {@link io.vertx.ext.web.client.WebClient}.
  */
 @ParametersAreNonnullByDefault
 public final class VertxMessageFactory {
@@ -36,7 +39,8 @@ private VertxMessageFactory() {
      *
      * @param headers Http headers
      * @param body    nullable buffer of the body
-     * @return a Message implementation with potentially an unknown encoding
+     * @return a {@link MessageReader} implementation
+     * @throws CloudEventRWException if the encoding is unknown or something went wrong while parsing the headers
      */
     public static MessageReader createReader(MultiMap headers, @Nullable Buffer body) throws CloudEventRWException {
         return MessageUtils.parseStructuredOrBinaryMessage(
@@ -55,41 +59,33 @@ public static MessageReader createReader(MultiMap headers, @Nullable Buffer body
     }
 
     /**
-     * Build a {@link MessageReader} starting from an {@link HttpServerRequest}
+     * Build a {@link MessageReader} starting from an {@link HttpServerRequest}.
      *
-     * @param request
-     * @return
+     * @param request the input request
+     * @return a succeeded {@link Future} with the {@link MessageReader},
+     * otherwise a failed {@link Future} if something went wrong while reading the body or while creating the {@link MessageReader}
      */
     public static Future<MessageReader> createReader(HttpServerRequest request) {
-        Promise<MessageReader> prom = Promise.promise();
-
-        request.exceptionHandler(prom::tryFail);
-        request.bodyHandler(b -> {
-            try {
-                prom.complete(createReader(request.headers(), b));
-            } catch (final Exception e) {
-                prom.fail(e);
-            }
-        });
-        return prom.future();
+        return request
+            .body()
+            .map(b -> createReader(request.headers(), b));
     }
 
     /**
-     * @param request
-     * @param handler
      * @see #createReader(HttpServerRequest)
      */
     public static void createReader(HttpServerRequest request, Handler<AsyncResult<MessageReader>> handler) {
         createReader(request).onComplete(handler);
     }
 
     /**
-     * Build a {@link MessageReader} starting from an {@link io.vertx.ext.web.client.HttpResponse}
+     * Build a {@link MessageReader} starting from an {@link HttpResponse}.
      *
-     * @param response
-     * @return
+     * @param response the input web client response
+     * @return a {@link MessageReader} implementation
+     * @throws CloudEventRWException if the encoding is unknown or something went wrong while parsing the headers
      */
-    public static MessageReader createReader(HttpResponse<Buffer> response) {
+    public static MessageReader createReader(HttpResponse<Buffer> response) throws CloudEventRWException {
         return createReader(response.headers(), response.body());
     }
 

http/vertx/src/main/java/io/cloudevents/http/vertx/VertxMessageFactory.java

@@ -160,6 +160,8 @@
                     <detectLinks/>
                     <links>
                         <link>https://docs.spring.io/spring-framework/docs/current/javadoc-api/</link>
+                        <link>https://vertx.io/docs/apidocs/</link>
+                        <link>https://jakarta.ee/specifications/platform/8/apidocs/</link>
                     </links>
                 </configuration>
                 <executions>