Javadocs

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>

Author: slinkydeveloper

amqp/src/main/java/io/cloudevents/amqp/ProtonAmqpMessageFactory.java

@@ -17,21 +17,24 @@
 
 package io.cloudevents.amqp;
 
-
+import io.cloudevents.SpecVersion;
 import io.cloudevents.amqp.impl.AmqpConstants;
 import io.cloudevents.amqp.impl.ProtonAmqpBinaryMessageReader;
 import io.cloudevents.amqp.impl.ProtonAmqpMessageWriter;
 import io.cloudevents.core.message.MessageReader;
 import io.cloudevents.core.message.MessageWriter;
 import io.cloudevents.core.message.impl.GenericStructuredMessageReader;
 import io.cloudevents.core.message.impl.MessageUtils;
+import io.cloudevents.lang.Nullable;
+import io.cloudevents.rw.CloudEventRWException;
 import io.cloudevents.rw.CloudEventWriter;
 import org.apache.qpid.proton.amqp.messaging.ApplicationProperties;
 import org.apache.qpid.proton.message.Message;
 
 import javax.annotation.ParametersAreNonnullByDefault;
+
 /**
- * A factory class providing convenience methods for creating MessageReader and MessageWriter instances based on Qpid Proton.
+ * A factory class providing convenience methods for creating {@link MessageReader} and {@link MessageWriter} instances based on Qpid Proton {@link Message}.
  */
 @ParametersAreNonnullByDefault
 public final class ProtonAmqpMessageFactory {
@@ -41,62 +44,63 @@ private ProtonAmqpMessageFactory() {
     }
 
     /**
-     * Creates a MessageReader to read a proton-based {@link Message}.
+     * Creates a {@link MessageReader} to read a proton-based {@link Message}.
+     * This reader is able to read both binary and structured encoded {@link io.cloudevents.CloudEvent}.
      * <p>
      * This implementation simply calls {@link #createReader(String, ApplicationProperties, byte[])}.
      *
-     * @param message The proton message to read from.
-     *
-     * @return        A message reader that can read the given proton message to a cloud event representation.
+     * @param message The proton {@link Message} to read from.
+     * @return A {@link MessageReader} that can read the given proton {@link Message} to a {@link io.cloudevents.CloudEvent} representation.
+     * @throws CloudEventRWException if something goes wrong while resolving the {@link SpecVersion} or if the message has unknown encoding
+     * @see #createReader(String, ApplicationProperties, byte[])
      */
-    public static MessageReader createReader(final Message message) {
-
+    public static MessageReader createReader(final Message message) throws CloudEventRWException {
         final byte[] payload = AmqpConstants.getPayloadAsByteArray(message.getBody());
         return createReader(message.getContentType(), message.getApplicationProperties(), payload);
     }
 
     /**
-     * Creates a MessageReader using the content-type property and payload of a proton-based message.
-     * <p>
-     * This method simply calls {@link #createReader(String, ApplicationProperties, byte[])}.
+     * Creates a {@link MessageReader} using the {@code content-type} property and payload of a proton-based {@link Message}.
+     * This reader is able to read both binary and structured encoded {@link io.cloudevents.CloudEvent}.
      *
-     * @param contentType The content-type of the message payload.
+     * @param contentType The {@code content-type} of the message payload.
      * @param payload     The message payload in bytes.
-     * @return            A message reader capable of representing a CloudEvent from
-     *                    a message <em>content-type</em> property and <em>application-data</em>.
+     * @return A {@link MessageReader} capable of representing a CloudEvent from
+     * a message {@code content-type} property and {@code application-data}.
+     * @see #createReader(String, ApplicationProperties, byte[])
      */
     public static MessageReader createReader(final String contentType, final byte[] payload) {
         return createReader(contentType, null, payload);
     }
 
     /**
-     * Creates a MessageWriter capable of translating both a structured and binary CloudEvent
-     * to a proton-based AMQP 1.0 representation.
+     * Creates a MessageReader to read using the {@code content-type} property, {@code application-properties} and data payload
+     * of a proton-based {@link Message}. This reader is able to read both binary and structured encoded {@link io.cloudevents.CloudEvent}.
      *
-     * @return A message writer to read structured and binary cloud event from a proton-based message.
+     * @param contentType  The {@code content-type} of the message payload.
+     * @param props        The {@code application-properties} section of the proton-message containing cloud event metadata (attributes and/or extensions).
+     * @param payload      The message payload in bytes or {@code null} if the message does not contain any payload.
+     * @return A {@link MessageReader} capable of representing a {@link io.cloudevents.CloudEvent} from the {@code application-properties},
+     *                     {@code content-type} and payload of a proton message.
+     * @throws CloudEventRWException if something goes wrong while resolving the {@link SpecVersion} or if the message has unknown encoding
      */
-    public static MessageWriter<CloudEventWriter<Message>, Message> createWriter() {
-        return new ProtonAmqpMessageWriter<>();
+    public static MessageReader createReader(final String contentType, final ApplicationProperties props, @Nullable final byte[] payload) throws CloudEventRWException {
+        return MessageUtils.parseStructuredOrBinaryMessage(
+            () -> contentType,
+            format -> new GenericStructuredMessageReader(format, payload),
+            () -> AmqpConstants.getApplicationProperty(props, AmqpConstants.APP_PROPERTY_SPEC_VERSION, String.class),
+            sv -> new ProtonAmqpBinaryMessageReader(sv, props, contentType, payload)
+        );
     }
 
     /**
-     * Creates a MessageReader to read using the content-type property, application-propeties and data payload
-     * of a proton-based message.
+     * Creates a {@link MessageWriter} capable of translating both a structured and binary CloudEvent
+     * to a proton-based AMQP 1.0 {@link Message}.
      *
-     * @param contentType  The content-type of the message payload.
-     * @param props        The application-properties section of the proton-message containing cloud event metadata (attributes and/or extensions).
-     * @param payload      The message payload in bytes or {@code null} if the message does not contain any payload.
-     * @return             A message reader capable of representing a CloudEvent from the application-properties,
-     *                     content-type and payload of a proton message.
+     * @return A {@link MessageWriter} to write a {@link io.cloudevents.CloudEvent} to Proton {@link Message} using structured or binary encoding.
      */
-    public static MessageReader createReader(final String contentType, final ApplicationProperties props, final byte[] payload) {
-
-        return MessageUtils.parseStructuredOrBinaryMessage(
-                () -> contentType,
-                format -> new GenericStructuredMessageReader(format, payload),
-                () -> AmqpConstants.getApplicationProperty(props, AmqpConstants.APP_PROPERTY_SPEC_VERSION, String.class),
-                sv -> new ProtonAmqpBinaryMessageReader(sv, props, contentType, payload));
-
+    public static MessageWriter<CloudEventWriter<Message>, Message> createWriter() {
+        return new ProtonAmqpMessageWriter<>();
     }
 
 }

pom.xml

@@ -158,6 +158,9 @@
                 <version>3.2.0</version>
                 <configuration>
                     <detectLinks/>
+                    <links>
+                        <link>https://qpid.apache.org/releases/qpid-proton-j-0.33.7/api/</link>
+                    </links>
                 </configuration>
                 <executions>
                     <execution>