Introduced support for Binary attribute types. (#353)

* Introduced support for Binary attribute types.

Added test data example
Added unit-test for JSON Format

Signed-off-by: Day, Jeremy(jday) <[email protected]>

* documentation tweak

Signed-off-by: Day, Jeremy(jday) <[email protected]>

* - Addressed review comment.
- Removed the withContextAttribute(string, Integer).
   - This should be a seperate PR, was mixed-in by accident.

Signed-off-by: Day, Jeremy(jday) <[email protected]>

* Address review comments

Signed-off-by: Day, Jeremy(jday) <[email protected]>

Author: JemDay

api/src/main/java/io/cloudevents/CloudEventExtension.java

@@ -39,7 +39,7 @@ public interface CloudEventExtension {
      * Get the attribute of extension named {@code key}.
      *
      * @param key the name of the extension attribute
-     * @return the extension value in one of the valid types String/Number/Boolean
+     * @return the extension value in one of the valid types String/Number/Boolean/URI/OffsetDateTime/byte[]
      * @throws IllegalArgumentException if the key is unknown to this extension
      */
     @Nullable

api/src/main/java/io/cloudevents/rw/CloudEventContextWriter.java

@@ -22,6 +22,7 @@
 import javax.annotation.ParametersAreNonnullByDefault;
 import java.net.URI;
 import java.time.OffsetDateTime;
+import java.util.Base64;
 
 /**
  * Interface to write the context attributes/extensions from a {@link io.cloudevents.rw.CloudEventContextReader} to a new representation.
@@ -73,7 +74,7 @@ default CloudEventContextWriter withContextAttribute(String name, OffsetDateTime
     }
 
     /**
-     * Set attribute with type {@link URI}.
+     * Set attribute with type {@link Number}.
      * This setter should not be invoked for specversion, because the writer should
      * already know the specversion or because it doesn't need it to correctly write the value.
      *
@@ -102,4 +103,18 @@ default CloudEventContextWriter withContextAttribute(String name, Boolean value)
         return withContextAttribute(name, value.toString());
     }
 
+    /**
+     * Set attribute with a binary type.
+     * This setter should not be invoked for specversion, because the writer should
+     * already know the specversion or because it doesn't need it to correctly write the value.
+     *
+     * @param name  name of the attribute
+     * @param value value of the attribute
+     * @return self
+     * @throws CloudEventRWException if anything goes wrong while writing this extension.
+     * @throws IllegalArgumentException if you're trying to set the specversion attribute.
+     */
+    default CloudEventContextWriter withContextAttribute(String name, byte[] value) throws CloudEventRWException {
+        return withContextAttribute(name, Base64.getEncoder().encodeToString(value));
+    }
 }

core/src/main/java/io/cloudevents/core/builder/CloudEventBuilder.java

@@ -186,6 +186,15 @@ public interface CloudEventBuilder extends CloudEventWriter<CloudEvent> {
      */
     CloudEventBuilder withExtension(@Nonnull String key, @Nonnull OffsetDateTime value);
 
+    /**
+     * Set an extension with provided key and binary value
+     *
+     * @param key   key of the extension attribute
+     * @param value value of the extension attribute
+     * @return self
+     */
+    CloudEventBuilder withExtension(@Nonnull String key, @Nonnull byte[] value);
+
     /**
      * Add to the builder all the extension key/values of the provided extension
      *

core/src/main/java/io/cloudevents/core/impl/BaseCloudEvent.java

@@ -77,6 +77,8 @@ protected void readExtensions(CloudEventContextWriter writer) throws CloudEventR
                 writer.withContextAttribute(entry.getKey(), (URI) entry.getValue());
             } else if (entry.getValue() instanceof OffsetDateTime) {
                 writer.withContextAttribute(entry.getKey(), (OffsetDateTime) entry.getValue());
+            } else if (entry.getValue() instanceof byte[]) {
+                writer.withContextAttribute(entry.getKey(), (byte[]) entry.getValue());
             } else {
                 // This should never happen because we build that map only through our builders
                 throw new IllegalStateException("Illegal value inside extensions map: " + entry);

core/src/main/java/io/cloudevents/core/impl/BaseCloudEventBuilder.java

@@ -23,6 +23,7 @@
 import io.cloudevents.CloudEventExtension;
 import io.cloudevents.core.builder.CloudEventBuilder;
 import io.cloudevents.core.data.BytesCloudEventData;
+import io.cloudevents.rw.CloudEventContextWriter;
 import io.cloudevents.rw.CloudEventRWException;
 
 import javax.annotation.Nonnull;
@@ -140,6 +141,15 @@ public SELF withExtension(@Nonnull String key, @Nonnull OffsetDateTime value) {
         return self;
     }
 
+    @Override
+    public CloudEventBuilder withExtension(@Nonnull String key, @Nonnull byte[] value) {
+        if (!isValidExtensionName(key)) {
+            throw CloudEventRWException.newInvalidExtensionName(key);
+        }
+        this.extensions.put(key, value);
+        return self;
+    }
+
     @Override
     public SELF withoutExtension(@Nonnull String key) {
         this.extensions.remove(key);

core/src/test/java/io/cloudevents/core/impl/BaseCloudEventBuilderTest.java

@@ -1,8 +1,7 @@
 package io.cloudevents.core.impl;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.*;
 
 import org.junit.jupiter.api.Test;
 
@@ -72,4 +71,25 @@ public void testInvalidExtensionName() {
 
         assertTrue(actualMessage.contains(expectedMessage));
     }
+
+    @Test
+    public void testBinaryExtension() {
+
+        final String EXT_NAME = "verifyme";
+
+        CloudEvent given = CloudEventBuilder.v1(Data.V1_MIN)
+            .withExtension(EXT_NAME, Data.BINARY_VALUE)
+            .build();
+
+        // Sanity
+        assertNotNull(given);
+
+        // Did the extension stick
+        assertTrue(given.getExtensionNames().contains(EXT_NAME));
+        assertNotNull(given.getExtension(EXT_NAME));
+
+        // Does the extension have the right value
+        assertEquals(Data.BINARY_VALUE, given.getExtension(EXT_NAME));
+
+    }
 }

core/src/test/java/io/cloudevents/core/test/Data.java

@@ -41,6 +41,7 @@ public class Data {
     public static byte[] DATA_JSON_SERIALIZED = "{}".getBytes();
     public static byte[] DATA_XML_SERIALIZED = "<stuff></stuff>".getBytes();
     public static byte[] DATA_TEXT_SERIALIZED = "Hello World Lorena!".getBytes();
+    public static byte[] BINARY_VALUE = { (byte) 0xE0, (byte) 0xFF, (byte) 0x00, (byte) 0x44, (byte) 0xAA }; // Base64: 4P8ARKo=
 
     public static final CloudEvent V1_MIN = CloudEventBuilder.v1()
         .withId(ID)
@@ -108,6 +109,13 @@ public class Data {
         .withTime(TIME)
         .build();
 
+    public static final CloudEvent V1_WITH_BINARY_EXT = CloudEventBuilder.v1()
+        .withId(ID)
+        .withType(TYPE)
+        .withSource(SOURCE)
+        .withExtension("binary", BINARY_VALUE)
+        .build();
+
     public static final CloudEvent V03_MIN = CloudEventBuilder.v03(V1_MIN).build();
     public static final CloudEvent V03_WITH_JSON_DATA = CloudEventBuilder.v03(V1_WITH_JSON_DATA).build();
     public static final CloudEvent V03_WITH_JSON_DATA_WITH_EXT = CloudEventBuilder.v03(V1_WITH_JSON_DATA_WITH_EXT).build();
@@ -137,6 +145,18 @@ public static Stream<CloudEvent> v1Events() {
         );
     }
 
+    /**
+     * Due to the nature of CE there are scenarios where an event might be serialized
+     * in such a fashion that it can not be deserialized while retaining the orginal
+     * type information, this varies from format-2-format
+     */
+
+    public static Stream<CloudEvent> v1NonRoundTripEvents() {
+        return Stream.of(
+            Data.V1_WITH_BINARY_EXT
+        );
+    }
+
     public static Stream<CloudEvent> v03Events() {
         return Stream.of(
             Data.V03_MIN,

formats/json-jackson/src/test/java/io/cloudevents/jackson/JsonFormatTest.java

@@ -132,7 +132,8 @@ public static Stream<Arguments> serializeTestArgumentsDefault() {
             Arguments.of(V1_WITH_JSON_DATA_WITH_FRACTIONAL_TIME, "v1/json_data_with_fractional_time.json"),
             Arguments.of(V1_WITH_JSON_DATA_WITH_EXT, "v1/json_data_with_ext.json"),
             Arguments.of(V1_WITH_XML_DATA, "v1/base64_xml_data.json"),
-            Arguments.of(V1_WITH_TEXT_DATA, "v1/base64_text_data.json")
+            Arguments.of(V1_WITH_TEXT_DATA, "v1/base64_text_data.json"),
+            Arguments.of(V1_WITH_BINARY_EXT, "v1/binary_attr.json")
         );
     }
 

formats/json-jackson/src/test/resources/v1/binary_attr.json

@@ -0,0 +1,7 @@
+{
+    "specversion": "1.0",
+    "id": "1",
+    "type": "mock.test",
+    "source": "http://localhost/source",
+    "binary" : "4P8ARKo="
+}