Refactor to Facilitate Decoupling from Concrete Implementations of EventFormat (#539)

- Introduce ContentType enum
- Resolve formats by using the ContentType enum

Signed-off-by: Randi Sheaffer-Klass <97033958+skepticoitusInteruptus@users.noreply.github.com>

core/src/main/java/io/cloudevents/core/format/ContentType.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2018-Present The CloudEvents Authors
+ * <p>
+ * 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
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.core.format;
+
+import io.cloudevents.CloudEvent;
+import io.cloudevents.CloudEventData;
+import io.cloudevents.rw.CloudEventDataMapper;
+
+import javax.annotation.ParametersAreNonnullByDefault;
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * <p>A construct that aggregates a two-part identifier of file formats and format contents transmitted on the Internet.
+ *
+ * <p>The two parts of a {@code ContentType} are its <em>type</em> and a <em>subtype</em>; separated by a forward slash ({@code /}).
+ *
+ * <p>The constants enumerated by {@code ContentType} correspond <em>only</em> to the specialized formats supported by the Java™ SDK for CloudEvents.
+ *
+ * @see io.cloudevents.core.format.EventFormat
+ */
+@ParametersAreNonnullByDefault
+public enum ContentType {
+
+    /**
+     * Content type associated with the JSON event format
+     */
+    JSON("application/cloudevents+json"),
+    /**
+     * The content type for transports sending cloudevents in the protocol buffer format.
+     */
+    PROTO("application/cloudevents+protobuf"),
+    /**
+     * The content type for transports sending cloudevents in XML format.
+     */
+    XML("application/cloudevents+xml");
+
+    private String value;
+
+    private ContentType(String value) { this.value = value; }
+
+    /**
+     * Return a string consisting of the slash-delimited ({@code /}) two-part identifier for this {@code enum} constant.
+     */
+    public String value() { return value; }
+
+    /**
+     * Return a string consisting of the slash-delimited ({@code /}) two-part identifier for this {@code enum} constant.
+     */
+    @Override
+    public String toString() { return value(); }
+
+}

core/src/main/java/io/cloudevents/core/provider/EventFormatProvider.java

@@ -25,6 +25,7 @@ import java.util.stream.StreamSupport;
 
 import javax.annotation.ParametersAreNonnullByDefault;
 
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventFormat;
 import io.cloudevents.lang.Nullable;
 
@@ -98,4 +99,14 @@ public final class EventFormatProvider {
 		return this.formats.get(contentType);
 	}
 
+	/**
+	 * Resolve an event format starting from the content type.
+	 *
+	 * @param contentType the content type to resolve the event format
+	 * @return null if no format was found for the provided content type
+	 */
+	@Nullable
+	public EventFormat resolveFormat(ContentType contentType) {
+		return this.formats.get(contentType.value());
+	}
 }

docs/json-jackson.md

@@ -28,9 +28,9 @@ adding the dependency to your project:
 
 ```java
 import io.cloudevents.CloudEvent;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventFormatProvider;
 import io.cloudevents.core.builder.CloudEventBuilder;
-import io.cloudevents.jackson.JsonFormat;
 
 CloudEvent event = CloudEventBuilder.v1()
     .withId("hello")
@@ -40,7 +40,7 @@ CloudEvent event = CloudEventBuilder.v1()
 
 byte[]serialized = EventFormatProvider
     .getInstance()
-    .resolveFormat(JsonFormat.CONTENT_TYPE)
+    .resolveFormat(ContentType.JSON)
     .serialize(event);
 ```
 

docs/protobuf.md

@@ -30,9 +30,9 @@ No further configuration is required is use the module.
 
 ```java
 import io.cloudevents.CloudEvent;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventFormatProvider;
 import io.cloudevents.core.builder.CloudEventBuilder;
-import io.cloudevents.protobuf.ProtobufFormat;
 
 CloudEvent event = CloudEventBuilder.v1()
     .withId("hello")
@@ -42,7 +42,7 @@ CloudEvent event = CloudEventBuilder.v1()
 
 byte[]serialized = EventFormatProvider
     .getInstance()
-    .resolveFormat(ProtobufFormat.CONTENT_TYPE)
+    .resolveFormat(ContentType.PROTO)
     .serialize(event);
 ```
 

docs/xml.md

@@ -29,9 +29,9 @@ adding the dependency to your project:
 
 ```java
 import io.cloudevents.CloudEvent;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventFormatProvider;
 import io.cloudevents.core.builder.CloudEventBuilder;
-import io.cloudevents.xml.XMLFormat;
 
 CloudEvent event = CloudEventBuilder.v1()
     .withId("hello")
@@ -41,7 +41,7 @@ CloudEvent event = CloudEventBuilder.v1()
 
 byte[] serialized = EventFormatProvider
     .getInstance()
-    .resolveFormat(XMLFormat.CONTENT_TYPE)
+    .resolveFormat(ContentType.XML)
     .serialize(event);
 ```
 

formats/json-jackson/src/main/java/io/cloudevents/jackson/JsonFormat.java

@@ -22,6 +22,7 @@ import com.fasterxml.jackson.databind.module.SimpleModule;
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventData;
 import io.cloudevents.core.builder.CloudEventBuilder;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventDeserializationException;
 import io.cloudevents.core.format.EventFormat;
 import io.cloudevents.core.format.EventSerializationException;

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

@@ -24,6 +24,7 @@ import com.fasterxml.jackson.databind.node.JsonNodeFactory;
 import io.cloudevents.CloudEvent;
 import io.cloudevents.SpecVersion;
 import io.cloudevents.core.builder.CloudEventBuilder;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventDeserializationException;
 import io.cloudevents.core.provider.EventFormatProvider;
 import io.cloudevents.rw.CloudEventRWException;
@@ -40,6 +41,7 @@ import java.nio.file.Paths;
 import java.util.Objects;
 import java.util.stream.Stream;
 
+import static io.cloudevents.core.format.ContentType.*;
 import static io.cloudevents.core.test.Data.*;
 import static org.assertj.core.api.Assertions.*;
 
@@ -185,7 +187,10 @@ class JsonFormatTest {
             //https://www.rfc-editor.org/rfc/rfc2045#section-5.1
             // any us-ascii char can be part of parameters (except CTRLs and tspecials)
             Arguments.of("text/json; char-set = $!#$%&'*+.^_`|"),
-            Arguments.of((Object) null)
+            Arguments.of((Object) null),
+            Arguments.of(JSON + ""),
+            Arguments.of(JSON.value()),
+            Arguments.of(JSON.toString())
         );
     }
 
@@ -307,7 +312,7 @@ class JsonFormatTest {
     }
 
     private JsonFormat getFormat() {
-        return (JsonFormat) EventFormatProvider.getInstance().resolveFormat(JsonFormat.CONTENT_TYPE);
+        return (JsonFormat) EventFormatProvider.getInstance().resolveFormat(JSON);
     }
 
     private static byte[] loadFile(String input) {

formats/protobuf/src/main/java/io/cloudevents/protobuf/ProtobufFormat.java

@@ -20,6 +20,7 @@ import com.google.protobuf.InvalidProtocolBufferException;
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventData;
 import io.cloudevents.core.builder.CloudEventBuilder;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventDeserializationException;
 import io.cloudevents.core.format.EventFormat;
 import io.cloudevents.core.format.EventSerializationException;

formats/xml/src/main/java/io/cloudevents/xml/XMLFormat.java

@@ -19,6 +19,7 @@ package io.cloudevents.xml;
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventData;
 import io.cloudevents.core.builder.CloudEventBuilder;
+import io.cloudevents.core.format.ContentType;
 import io.cloudevents.core.format.EventDeserializationException;
 import io.cloudevents.core.format.EventFormat;
 import io.cloudevents.core.format.EventSerializationException;