Spring Javadocs (#323)

* Spring Javadocs

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

* Rebase fix

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

Author: slinkydeveloper

pom.xml

@@ -158,6 +158,9 @@
                 <version>3.2.0</version>
                 <configuration>
                     <detectLinks/>
+                    <links>
+                        <link>https://docs.spring.io/spring-framework/docs/current/javadoc-api/</link>
+                    </links>
                 </configuration>
                 <executions>
                     <execution>

spring/src/main/java/io/cloudevents/spring/http/CloudEventHttpUtils.java

@@ -15,20 +15,21 @@
  */
 package io.cloudevents.spring.http;
 
-import java.util.function.Consumer;
-import java.util.function.Supplier;
-
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventContext;
+import io.cloudevents.SpecVersion;
 import io.cloudevents.core.CloudEventUtils;
 import io.cloudevents.core.builder.CloudEventBuilder;
 import io.cloudevents.core.message.MessageReader;
 import io.cloudevents.http.HttpMessageFactory;
 import io.cloudevents.http.impl.HttpMessageWriter;
-
+import io.cloudevents.rw.CloudEventRWException;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.ResponseEntity;
 
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+
 /**
  * Miscellaneous utility methods to assist with Cloud Events in the context of Spring Web
  * frameworks. Primarily intended for the internal use within Spring-based frameworks or
@@ -42,54 +43,58 @@ public class CloudEventHttpUtils {
 	private CloudEventHttpUtils() {
 	}
 
-	/**
-	 * Create a {@link MessageReader} to assist in conversion of an HTTP request to a
-	 * {@link CloudEvent}.
-	 * @param headers the HTTP request headers
-	 * @param body the HTTP request body as a byte array
-	 * @return a {@link MessageReader} representing the {@link CloudEvent}
-	 */
-	public static MessageReader toReader(HttpHeaders headers, Supplier<byte[]> body) {
-		return HttpMessageFactory.createReaderFromMultimap(headers, body.get());
-	}
+    /**
+     * Create a {@link MessageReader} to convert an HTTP request to a {@link CloudEvent}.
+     *
+     * @param headers the HTTP request headers
+     * @param body    the HTTP request body as a byte array
+     * @return a {@link MessageReader} representing the {@link CloudEvent}
+     * @throws CloudEventRWException if something goes wrong while resolving the {@link SpecVersion} or if the message has unknown encoding
+     */
+    public static MessageReader toReader(HttpHeaders headers, Supplier<byte[]> body) throws CloudEventRWException {
+        return HttpMessageFactory.createReaderFromMultimap(headers, body.get());
+    }
 
 	/**
 	 * Create an {@link HttpMessageWriter} that can hand off a {@link CloudEvent} to an
 	 * HTTP response. Mainly useful in a blocking (not async) setting because the response
 	 * body has to be consumed directly.
+     *
 	 * @param headers the response headers (will be mutated)
 	 * @param sendBody a consumer for the response body that puts the bytes on the wire
 	 */
 	public static HttpMessageWriter toWriter(HttpHeaders headers, Consumer<byte[]> sendBody) {
 		return HttpMessageFactory.createWriter(headers::set, sendBody);
-	}
+    }
 
-	/**
-	 * Helper method for extracting {@link HttpHeaders} from a {@link CloudEvent}. Can,
-	 * for instance, be used in a <code>&#64;RequestMapping</code> to return a
-	 * {@link ResponseEntity} that has headers copied from a {@link CloudEvent}.
-	 * @param event the input {@link CloudEvent}
-	 * @return the response headers represented by the event
-	 */
-	public static HttpHeaders toHttp(CloudEventContext event) {
-		HttpHeaders headers = new HttpHeaders();
-		CloudEventUtils.toReader(CloudEventBuilder.fromContext(event).build()).read(toWriter(headers, bytes -> {
-		}));
-		return headers;
-	}
+    /**
+     * Helper method for extracting {@link HttpHeaders} from a {@link CloudEvent}. Can,
+     * for instance, be used in a {@link org.springframework.web.bind.annotation.RequestMapping} to return a
+     * {@link ResponseEntity} that has headers copied from a {@link CloudEvent}.
+     *
+     * @param event the input {@link CloudEvent}
+     * @return the response headers represented by the event
+     * @throws CloudEventRWException if something goes wrong while writing the context to the http headers
+     */
+    public static HttpHeaders toHttp(CloudEventContext event) throws CloudEventRWException {
+        HttpHeaders headers = new HttpHeaders();
+        CloudEventUtils.toReader(CloudEventBuilder.fromContext(event).build()).read(toWriter(headers, bytes -> {
+        }));
+        return headers;
+    }
 
-	/**
-	 * Helper method for converting {@link HttpHeaders} to a {@link CloudEvent}. The input
-	 * headers must represent a valid event in "binary" form, i.e. it must have headers
-	 * "ce-id", "ce-specversion" etc.
-	 * @param headers the input request headers
-	 * @return a {@link CloudEventBuilder} that can be used to create a new
-	 * {@link CloudEvent}
-	 * 
-	 */
-	public static CloudEventBuilder fromHttp(HttpHeaders headers) {
-		return CloudEventBuilder
-				.fromContext(CloudEventUtils.toEvent(CloudEventHttpUtils.toReader(headers, () -> null)));
+    /**
+     * Helper method for converting {@link HttpHeaders} to a {@link CloudEvent}. The input
+     * headers <b>must</b> represent a valid event in "binary" form, i.e. it must have headers
+     * {@code ce-id}, {@code ce-specversion} etc.
+     *
+     * @param headers the input request headers
+     * @return a {@link CloudEventBuilder} that can be used to create a new {@link CloudEvent}
+     * @throws CloudEventRWException if something goes wrong while reading the context from the http headers
+     */
+    public static CloudEventBuilder fromHttp(HttpHeaders headers) throws CloudEventRWException {
+        return CloudEventBuilder
+            .fromContext(CloudEventUtils.toEvent(CloudEventHttpUtils.toReader(headers, () -> null)));
 	}
 
 }

spring/src/main/java/io/cloudevents/spring/messaging/CloudEventContextUtils.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2019-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.cloudevents.spring.messaging;
+
+import io.cloudevents.CloudEvent;
+import io.cloudevents.CloudEventContext;
+import io.cloudevents.SpecVersion;
+import io.cloudevents.core.CloudEventUtils;
+import io.cloudevents.rw.CloudEventRWException;
+import org.springframework.messaging.MessageHeaders;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static io.cloudevents.spring.messaging.CloudEventsHeaders.CE_PREFIX;
+
+/**
+ * Utility class for copying message headers to and from {@link CloudEventContext}.
+ *
+ * @author Dave Syer
+ */
+public class CloudEventContextUtils {
+
+    /**
+     * Helper method for converting {@link MessageHeaders} to a {@link CloudEventContext}.
+     * The input headers <b>must</b> represent a valid event in "binary" form, i.e. it must have headers
+     * {@code ce-id}, {@code ce-specversion} etc.
+     *
+     * @param headers the input message headers
+     * @return a {@link CloudEventContext} that can be used to create a new {@link CloudEvent}
+     * @throws CloudEventRWException if something goes wrong while converting the headers to {@link CloudEventContext}
+     */
+    public static CloudEventContext fromMap(Map<String, Object> headers) throws CloudEventRWException {
+        Object value = headers.get(CloudEventsHeaders.SPEC_VERSION);
+        SpecVersion version = value == null ? SpecVersion.V1 : SpecVersion.parse(value.toString());
+        return CloudEventUtils.toEvent(new MessageBinaryMessageReader(version, headers));
+    }
+
+    /**
+     * Helper method for extracting {@link MessageHeaders} from a {@link CloudEventContext}. The
+     * result will contain headers canonicalized with a {@code ce-} prefix, analogous to the
+     * "binary" message format in Cloud Events.
+     *
+     * @param context the input {@link CloudEventContext}
+     * @return the response headers represented by the event
+     * @throws CloudEventRWException if something goes wrong while converting the {@link CloudEventContext} to headers
+     */
+    public static Map<String, Object> toMap(CloudEventContext context) throws CloudEventRWException {
+        Map<String, Object> headers = new HashMap<>();
+        // Probably this should be done in CloudEventContextReaderAdapter
+        headers.put(CE_PREFIX + "specversion", context.getSpecVersion().toString());
+        MessageBuilderMessageWriter writer = new MessageBuilderMessageWriter(headers);
+        CloudEventUtils.toContextReader(context).readContext(writer);
+        return writer.end().getHeaders();
+    }
+
+}

spring/src/main/java/io/cloudevents/spring/messaging/CloudEventHeaderUtils.java

@@ -15,8 +15,6 @@
  */
 package io.cloudevents.spring.messaging;
 
-import java.nio.charset.Charset;
-
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventContext;
 import io.cloudevents.SpecVersion;
@@ -25,19 +23,19 @@
 import io.cloudevents.core.message.MessageReader;
 import io.cloudevents.core.message.impl.GenericStructuredMessageReader;
 import io.cloudevents.core.message.impl.MessageUtils;
-
 import org.springframework.messaging.Message;
 import org.springframework.messaging.MessageHeaders;
 import org.springframework.messaging.converter.MessageConverter;
 
+import java.nio.charset.Charset;
+
 /**
  * A {@link MessageConverter} that can translate to and from a {@link Message
  * Message<byte[]>} or {@link Message Message<String>} and a {@link CloudEvent}. The
- * {@link CloudEventContext} is canonicalized, with key names given a "ce-" prefix in the
+ * {@link CloudEventContext} is canonicalized, with key names given a {@code ce-} prefix in the
  * {@link MessageHeaders}.
- * 
- * @author Dave Syer
  *
+ * @author Dave Syer
  */
 public class CloudEventMessageConverter implements MessageConverter {
 

spring/src/main/java/io/cloudevents/spring/messaging/CloudEventMessageConverter.java

@@ -15,12 +15,9 @@
  */
 package io.cloudevents.spring.mvc;
 
-import java.io.IOException;
-
 import io.cloudevents.CloudEvent;
 import io.cloudevents.core.CloudEventUtils;
 import io.cloudevents.spring.http.CloudEventHttpUtils;
-
 import org.springframework.http.HttpInputMessage;
 import org.springframework.http.HttpOutputMessage;
 import org.springframework.http.MediaType;
@@ -30,13 +27,14 @@
 import org.springframework.http.converter.HttpMessageNotWritableException;
 import org.springframework.util.StreamUtils;
 
+import java.io.IOException;
+
 /**
  * An {@link HttpMessageConverter} for {@link CloudEvent CloudEvents}. Supports the use of
- * {@link CloudEvent} in a <code>&#64;RequestMapping</code> as either a method parameter
+ * {@link CloudEvent} in a {@link org.springframework.web.bind.annotation.RequestMapping} as either a method parameter
  * or a return value.
- * 
- * @author Dave Syer
  *
+ * @author Dave Syer
  */
 public class CloudEventHttpMessageConverter extends AbstractHttpMessageConverter<CloudEvent> {
 

spring/src/main/java/io/cloudevents/spring/mvc/CloudEventHttpMessageConverter.java

@@ -15,31 +15,29 @@
  */
 package io.cloudevents.spring.webflux;
 
-import java.util.Arrays;
-import java.util.List;
-import java.util.Map;
-
 import io.cloudevents.CloudEvent;
 import io.cloudevents.core.message.MessageReader;
 import io.cloudevents.spring.http.CloudEventHttpUtils;
-import reactor.core.publisher.Flux;
-import reactor.core.publisher.Mono;
-
 import org.springframework.core.ResolvableType;
 import org.springframework.core.io.buffer.DataBufferUtils;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ReactiveHttpInputMessage;
 import org.springframework.http.codec.HttpMessageReader;
 import org.springframework.util.StreamUtils;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
 
 /**
  * A reactive {@link HttpMessageReader} for {@link CloudEvent CloudEvents}, converting
- * from an HTTP request to a cloud event. Supports the use of {@link CloudEvent} as an
+ * from an HTTP request to a CloudEvent. Supports the use of {@link CloudEvent} as an
  * input to a reactive endpoint.
- * 
- * @author Dave Syer
  *
+ * @author Dave Syer
  */
 public class CloudEventHttpMessageReader implements HttpMessageReader<CloudEvent> {
 
@@ -74,4 +72,4 @@ public Mono<CloudEvent> readMono(ResolvableType elementType, ReactiveHttpInputMe
 		return body.map(bytes -> CloudEventHttpUtils.toReader(headers, () -> bytes)).map(MessageReader::toEvent);
 	}
 
-}
+}

spring/src/main/java/io/cloudevents/spring/webflux/CloudEventHttpMessageReader.java

@@ -40,11 +40,10 @@
 
 /**
  * A reactive {@link HttpMessageWriter} for {@link CloudEvent CloudEvents}, converting
- * from a cloud event to an HTTP response. Supports the use of {@link CloudEvent} as an
+ * from a CloudEvent to an HTTP response. Supports the use of {@link CloudEvent} as an
  * output from a reactive endpoint.
  *
  * @author Dave Syer
- *
  */
 public class CloudEventHttpMessageWriter implements HttpMessageWriter<CloudEvent> {