Merge pull request #7 from openapi-tools/add-curies-support

Add curies support as a continuation of Jim Hooker PR #6. Solving issue #4.

Author: langecode

README.md

@@ -11,7 +11,7 @@ the normal Jackson JSON handling.
 Module is considered production ready.
 
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.openapitools.jackson.dataformat/jackson-dataformat-hal/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.openapitools.jackson.dataformat/jackson-dataformat-hal/)
-[![Javadoc](https://javadoc-emblem.rhcloud.com/doc/io.openapitools.jackson.dataformat/jackson-dataformat-hal/badge.svg)](https://www.javadoc.io/doc/io.openapitools.jackson.dataformat/jackson-dataformat-hal)
+[![Javadoc](http://javadoc.io/badge/io.openapitools.jackson.dataformat/jackson-dataformat-hal.svg)](https://www.javadoc.io/doc/io.openapitools.jackson.dataformat/jackson-dataformat-hal)
 [![Build status](https://travis-ci.org/openapi-tools/jackson-dataformat-hal.svg?branch=master)](https://travis-ci.org/openapi-tools/jackson-dataformat-hal)
 [![Coverage Status](https://codecov.io/gh/openapi-tools/jackson-dataformat-hal/coverage.svg?branch=master)](https://codecov.io/gh/openapi-tools/jackson-dataformat-hal)
 
@@ -71,6 +71,114 @@ The JSON resulting from the above small POJO model would look like the following
 
 All fields which are not annotated will be handled by the normal Jackson JSON data-binding.
 
+## Including Curies
+
+```java
+@Resource
+@Curie(curie = "curie", href = "http://example.com/doc/{rel}")
+class Model {
+    String modelProperty;
+
+    @Link
+    HALLink self;
+
+    @Link("rel:associated")
+    HALLink relation;
+
+    @Link(value = "curieLink", curie = "curie")
+    HALLink curieLink;
+
+}
+```
+
+```java
+@Resource
+@Curies({
+    @Curie(href = "http://docs.my.site/{rel}", curie = "curie1"),
+    @Curie(href = "http://docs.other.site/{rel}", curie = "curie2")})
+
+class Model {
+    String modelProperty;
+
+    @Link
+    HALLink self;
+
+    @Link("rel:associated")
+    HALLink relation;
+
+    @Link(value = "curieLink11", curie = "curie1")
+    HALLink curieLink11;
+
+    @Link(value = "curieLink21", curie = "curie2")
+    HALLink curieLink21;
+
+    @Link(value = "curieLink22", curie = "curie2")
+    HALLink curieLink22;
+
+    @Link(value = "curieLink23", curie = "curie2")
+    HALLink curieLink23;
+
+}
+```
+The resulting JSON would be:
+
+```json
+{
+    "_links": {
+        "curies": [{
+            "name": "curie1",
+            "href": "http://docs.my.site/{rel}",
+            "templated": "true"
+        },{
+            "name": "curie2",
+            "href": "http://docs.other.site/{rel}",
+            "templated": "true"
+        }],
+        "self": { "href": "https://..."},
+        "rel:associated": { "href": "https://..."},
+        "curie1:link11": { "href": "https://...", "templated" : "..."},
+        "curie2:link21": { "href": "https://...", "templated" : "..."},
+        "curie2:link22": { "href": "https://...", "templated" : "..."}
+    },
+    "_embedded": {
+        "associated": {
+            "_links": {
+                "self": { "href": "https://..." }
+            },
+            "associatedProperty": "..."
+        }
+    },
+    "modelProperty": "..."
+}
+```
+
+The above is equivalent to:
+
+```json
+{
+    "_links": {
+        "self": { "href": "https://..."},
+        "rel:associated": { "href": "https://..."},
+        "http://docs.my.site/link11": { "href": "https://...", "templated" : "..."},
+        "http://docs.other.site/link21": { "href": "https://...", "templated" : "..."},
+        "http://docs.other.site/link22": { "href": "https://...", "templated" : "..."}
+    },
+    "_embedded": {
+        "associated": {
+            "_links": {
+                "self": { "href": "https://..." }
+            },
+            "associatedProperty": "..."
+        }
+    },
+    "modelProperty": "..."
+}
+```
+
+Both will be supported for deserialization. Also if curie prefixes in the incoming document
+is chosen to be different from the prefixes in the POJO annotations deserialization will be
+supported.
+
 ## Serializing POJOs as HAL JSON
 
 Serialization is similar to the normal JSON serialization using the `HALMapper` instead of the

pom.xml

@@ -94,8 +94,8 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.5.1</version>
                 <configuration>
-                    <source>1.7</source>
-                    <target>1.7</target>
+                    <source>1.8</source>
+                    <target>1.8</target>
                     <compilerArgs>
                         <arg>-Xlint</arg>
                     </compilerArgs>

src/main/java/io/openapitools/jackson/dataformat/hal/HALLink.java

@@ -152,7 +152,7 @@ public static class Builder {
          */
         public Builder(String href) {
             this.href = href;
-            templated = true;
+            templated = getTemplated(href);
         }
 
         /**
@@ -212,5 +212,14 @@ public Builder seen(Instant temporal) {
         public HALLink build() {
             return new HALLink(this);
         }
+
+        /**
+         * URI template https://tools.ietf.org/html/rfc6570
+         *  
+         *  very simple implementation of templates
+         */
+        private Boolean getTemplated(String href) {            
+            return href.contains("{");
+        }
     }
 }

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Curie.java

@@ -0,0 +1,31 @@
+package io.openapitools.jackson.dataformat.hal.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation specifying a CURIE for use with links. As defined by W3C in
+ * <a href="https://www.w3.org/TR/2010/NOTE-curie-20101216/">CURIE Syntax 1.0</a>. Note that in
+ * the context of HAL the only substitution done to the template URI of a curie is the
+ * <code>{rel}</code> place holder.
+ */
+@Target({ElementType.TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Curie {
+
+    /**
+     * CURIE href template e.g. "http://docs.my.site/{rel}"
+     * @return href a reference to the elaborated documentation for a given resource
+     */
+    String href() default "";
+
+    /**
+     * CURIE name used to reference the CURIE in {@link Link} annotations
+     * e.g. "mysite"
+     * @return the name of the curie
+     */
+    String prefix() default "";
+
+}

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Curies.java

@@ -0,0 +1,21 @@
+package io.openapitools.jackson.dataformat.hal.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation specifying an array of curies to be used in defining link relations.
+ */
+@Target({ElementType.TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Curies {
+
+    /**
+     * Annotation grouping a list of {@link Curies} for convenience/readability
+     * @return an array of curies
+     */
+    Curie[] value() default {};
+
+}

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Link.java

@@ -16,4 +16,10 @@
      * @return name of the relation represented by the link.
      */
     String value() default "";
+
+    /**
+     * CURIE prefix - if not set then no CURIE will be associated.
+     * @return name of the CURIE intended to be used with this link.
+     */
+    String curie() default "";
 }

src/main/java/io/openapitools/jackson/dataformat/hal/deser/CurieMap.java

@@ -0,0 +1,65 @@
+package io.openapitools.jackson.dataformat.hal.deser;
+
+import io.openapitools.jackson.dataformat.hal.annotation.Curie;
+import java.net.URI;
+import java.util.Arrays;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.StringTokenizer;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Defining map of a curies in the context of HAL. That is, this will only substitute
+ * a curie reference into the <code>{rel}</code> placeholder of a templated URI.
+ *
+ * @see <a href="https://www.w3.org/TR/2010/NOTE-curie-20101216/">CURIE Syntax 1.0</a>
+ */
+public class CurieMap {
+
+    private final ConcurrentHashMap<String, String> mappings = new ConcurrentHashMap<>();
+
+
+    public CurieMap(Mapping... mappings) {
+        Objects.requireNonNull(mappings, "Non-null array must be provided");
+        Arrays.stream(mappings).forEach(m -> this.mappings.put(m.prefix, m.template));
+    }
+
+    /**
+     * Resolve the given curie using this mapping. Return empty if no relevant mapping could be found.
+     *
+     * @param curie Curie to resolve using this map in the standard form <code>prefix:rel</code>
+     * @return Resolved URI if map contained mapping for the given prefix - empty otherwise
+     */
+    public Optional<URI> resolve(String curie) {
+        StringTokenizer st = new StringTokenizer(curie, ":");
+        if (st.countTokens() != 2) {
+            return Optional.empty();
+        }
+
+        String template = mappings.get(st.nextToken());
+        if (template == null) {
+            return Optional.empty();
+        } else {
+            URI resolvedURI = URI.create(template.replace("{rel}", st.nextToken()));
+            return Optional.of(resolvedURI);
+        }
+    }
+
+    /**
+     * A single mapping definition in the map.
+     */
+    public static class Mapping {
+        private final String prefix;
+        private final String template;
+
+        public Mapping(String prefix, String template) {
+            this.prefix = prefix;
+            this.template = template;
+        }
+
+        public Mapping(Curie curie) {
+            this.prefix = curie.prefix();
+            this.template = curie.href();
+        }
+    }
+}

src/main/java/io/openapitools/jackson/dataformat/hal/deser/HALBeanDeserializer.java

@@ -8,13 +8,20 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.deser.BeanDeserializerBase;
 import com.fasterxml.jackson.databind.deser.std.DelegatingDeserializer;
+import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.io.IOException;
+import java.net.URI;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.StreamSupport;
 
 /**
- * Deserializer to handle incomming application/hal+json.
+ * Deserializer to handle incoming application/hal+json. The de-serializer is responsible for intercepting
+ * the reserved properties (<code>_links</code> and <code>_embedded</code>) and mapping the properties of these
+ * objects in the incoming json to the uniquely assigned properties of the POJO class.
  */
 public class HALBeanDeserializer extends DelegatingDeserializer {
 
@@ -23,21 +30,26 @@ public HALBeanDeserializer(BeanDeserializerBase delegate) {
     }
 
     @Override
-    public Object deserialize(JsonParser p, DeserializationContext ctxt) throws IOException, JsonProcessingException {
-        TreeNode tn = p.getCodec().readTree(p);  
+    public Object deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
+        TreeNode tn = p.getCodec().readTree(p);
         if (tn.isObject()) {
             ObjectNode root = (ObjectNode) tn;
             for (ReservedProperty rp : ReservedProperty.values()) {
                 ObjectNode on = (ObjectNode) tn.get(rp.getPropertyName());
                 if (on != null) {
-                    Iterator<Map.Entry<String,JsonNode>> it = on.fields();
+                    CurieMap curieMap = createCurieMap(rp, on);
+                    on.remove("curies");
+
+                    Iterator<Map.Entry<String, JsonNode>> it = on.fields();
                     while (it.hasNext()) {
-                        Map.Entry<String,JsonNode> jn = it.next();
-                        root.set(rp.alternateName(jn.getKey()), jn.getValue());
+                        Map.Entry<String, JsonNode> jn = it.next();
+                        String propertyName = curieMap.resolve(jn.getKey()).map(URI::toString).orElse(jn.getKey());
+                        root.set(rp.alternateName(propertyName), jn.getValue());
                     }
-                    root.remove(rp.getPropertyName());                
+
+                    root.remove(rp.getPropertyName());
                 }
-                
+
             }
         }
 
@@ -46,9 +58,25 @@ public Object deserialize(JsonParser p, DeserializationContext ctxt) throws IOEx
         return _delegatee.deserialize(modifiedParser, ctxt);
     }
 
+    private CurieMap createCurieMap(ReservedProperty rp, ObjectNode on) {
+        if (ReservedProperty.LINKS.equals(rp) && on.has("curies")) {
+            ArrayNode curies = (ArrayNode) on.get("curies");
+            List<CurieMap.Mapping> mappings = StreamSupport.stream(curies.spliterator(), false)
+                    .map(n -> createMapping((ObjectNode) n))
+                    .collect(Collectors.toList());
+            return new CurieMap(mappings.toArray(new CurieMap.Mapping[0]));
+        } else {
+            return new CurieMap();
+        }
+    }
+
+    private CurieMap.Mapping createMapping(ObjectNode node) {
+        return new CurieMap.Mapping(node.get("name").textValue(), node.get("href").textValue());
+    }
+
     @Override
     protected JsonDeserializer<?> newDelegatingInstance(JsonDeserializer<?> newDelegatee) {
         return new HALBeanDeserializer((BeanDeserializerBase) newDelegatee);
     }
-    
+
 }