Allow links on a particular rel to be displayed as an array even if there is only one link

[vivin]

Currently, Jackson2HalModule.HalLinkListSerializer will serialize a rel with only one link, into an object. If the rel has more than one link, it will serialize it into an array.

I know that rels have nothing to do with cardinality. However, for consistency's sake I would like to force certain a rel to always represent its links as being in an array. I ran into this issue in a case where I return a "collection" representation that contains links to individual resources. If I only have one element in the collection, the link is serialized as:

"ex:persons/person-resource": {
    "href": "..."
}

However, if I have multiple items, I will see:

"ex:persons/person-resource": [
    { "href": "..." },
    { "href": "..." }
]

From the perspective of an API user, this is remarkably inconsistent and confusing. I would rather that the representation not change based on the cardinality of elements. It is fine if the representation is always going to contain a link to a single element under some rel. In that case, it is alright that the link is serialized into a object (IMHO, it's a bit of a weakness because you don't see the same issue in HAL+XML where you can put a <link> element inside a <links> whether there is one or more <link>, but that's another issue). However in the case of a representation that is returning a collection of elements, I think it would be valuable from a consistency and usability perspective to always return the link as an array.

It would be nice if this was configurable when building the link somehow. A way, perhaps, to let the serializer know that the links should be serialized as an array instead of an object, regardless of cardinality.

Also, the HAL specification says:

Note: If you're unsure whether the link should be singular, assume it will be multiple. If you pick singular and find you need to change it, you will need to create a new link relation or face breaking existing clients.

Currently, there is no way to force a link to be multiple in Spring HATEOAS. I hope you guys will consider this feature request. I can also try and solve this problem myself and make a pull request.

If this is not feasible, or if I am misinterpreting the HAL specification, please let me know!

[schvanhugten]

I think the problem is in Jackson2HalModule:OptionalListJackson2Serializer:355 to 366 (version 0.16).

if (list.isEmpty()) {
    return;
}

if (list.size() == 1) {
    serializeContents(list.iterator(), jgen, provider);
    return;
}

jgen.writeStartArray();
serializeContents(list.iterator(), jgen, provider);
jgen.writeEndArray();

You always want to write an array, so at least the if (list.size() == 1) { has to go. I did some work on a CustomHalLinkListSerializer that effectively does this. Code below for inspiration.

public void serialize(List<Link> value, JsonGenerator jgen, SerializerProvider provider) throws IOException, JsonGenerationException {
        // sort links according to their relation
        Map<String, Object[]> sortedLinks = new LinkedHashMap<String, Object[]>();

        for (Link link : value) {

                String rel = link.getRel();
                Object[] existingLink = sortedLinks.get(rel);

                if (existingLink == null) {
                    sortedLinks.put(rel, new Object[] { link });
                } else {
                    // Resize array
                    sortedLinks.put(rel, ArrayUtils.add(existingLink, link));
                }
        }

        TypeFactory typeFactory = provider.getConfig().getTypeFactory();
        JavaType keyType = typeFactory.uncheckedSimpleType(String.class);
        JavaType valueType = typeFactory.constructArrayType(Object.class);
        JavaType mapType = typeFactory.constructMapType(HashMap.class, keyType, valueType);

        MapSerializer serializer = MapSerializer.construct(new String[] {}, mapType, true, null,
                        provider.findKeySerializer(keyType, null), provider.findValueSerializer(valueType, null), null);

        serializer.serialize(sortedLinks, jgen, provider);
    }

[vivin]

Yup! I have a fix on this pull-request.

[vivin]

Hello everyone,

I have a workaround for this issue, and I think you can use the same concepts for issue #324 as well. It's a little ugly and involves duplicating logic from Spring HATEOAS, but it works (at least for me). I'll post the code here, but when I get time, I'll set up a small demo project that showcases this workaround. I think this is a good stop-gap measure until my pull request is accepted or if Spring HATEOAS implements its own solution for this problem.

I got the idea after I read up on Jackson's MixIn Annotations. Using these, you can attach Jackson annotations to fields on classes, whose source you do not control.

The main problem with the current implementation is that the serializer for links always serializes a rel with a single link directly into a JSON object, and a rel with multiple links into an array of objects. There is no way to control the representation. With MixIn annotations, you can override the serializer for the links field in ResourceSupport and specify your own serializer. However, it's not as simple as that because there is some additional stuff you have to do, because the serializer requires access to some Spring Beans, and furthermore, Spring HATEOAS' custom module also controls the lifecycle of the serializers. So even if you set a MixIn annotation, the module does not know about it. I'll go through my workaround step by step. On a high level, the workaround involves creating some custom-serializers, maintaining the lifecycle of those serializers and their dependencies, and reconfiguring Spring HATEOAS' Jackson object-mapper to recognize our custom stuff:

Step 1: Create the mixin class:

public abstract class HalLinkListMixin {
    @JsonProperty("_links") @JsonSerialize(using = HalLinkListSerializer.class)
    public abstract List<Link> getLinks();
}

This mixin class will associate the HalLinkListSerializer serializer with the links property. This is a class that we will eventually create.

Step 2: Create a container class that holds the rels whose link representations should always be an array of link objects:

public class HalMultipleLinkRels {
    private final Set<String> rels;

    public HalMultipleLinkRels(String... rels) {
        this.rels = new HashSet<String>(Arrays.asList(rels));
    }

    public Set<String> getRels() {
        return Collections.unmodifiableSet(rels);
    }
}

Step 3: Create our new serializer that will override Spring HATEOAS's link-list serializer:

This class unfortunately duplicates logic, but it's not too bad. The key difference is that instead of using OptionalListJackson2Serializer, we use our own serializer (ListJackson2Serializer) that will force a rel's link representation as an array, if that rel exists in our container of rel overrides (HalMultipleLinkRels):

public class HalLinkListSerializer extends ContainerSerializer<List<Link>> implements ContextualSerializer {

    private final BeanProperty property;

    private CurieProvider curieProvider;

    private HalMultipleLinkRels halMultipleLinkRels;

    public HalLinkListSerializer() {
        this(null, null, new HalMultipleLinkRels());
    }

    public HalLinkListSerializer(CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
        this(null, curieProvider, halMultipleLinkRels);
    }

    public HalLinkListSerializer(BeanProperty property, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
        super(List.class, false);
        this.property = property;
        this.curieProvider = curieProvider;
        this.halMultipleLinkRels = halMultipleLinkRels;
    }

    @Override
    public void serialize(List<Link> value, JsonGenerator jgen, SerializerProvider provider) throws IOException, JsonGenerationException {

        // sort links according to their relation
        Map<String, List<Object>> sortedLinks = new LinkedHashMap<>();
        List<Link> links = new ArrayList<>();

        boolean prefixingRequired = curieProvider != null;
        boolean curiedLinkPresent = false;

        for (Link link : value) {

            String rel = prefixingRequired ? curieProvider.getNamespacedRelFrom(link) : link.getRel();

            if (!link.getRel().equals(rel)) {
                curiedLinkPresent = true;
            }

            if (sortedLinks.get(rel) == null) {
                sortedLinks.put(rel, new ArrayList<>());
            }

            links.add(link);
            sortedLinks.get(rel).add(link);
        }

        if (prefixingRequired && curiedLinkPresent) {

            ArrayList<Object> curies = new ArrayList<>();
            curies.add(curieProvider.getCurieInformation(new Links(links)));

            sortedLinks.put("curies", curies);
        }

        TypeFactory typeFactory = provider.getConfig().getTypeFactory();
        JavaType keyType = typeFactory.uncheckedSimpleType(String.class);
        JavaType valueType = typeFactory.constructCollectionType(ArrayList.class, Object.class);
        JavaType mapType = typeFactory.constructMapType(HashMap.class, keyType, valueType);

        MapSerializer serializer = MapSerializer.construct(new String[]{}, mapType, true, null,
            provider.findKeySerializer(keyType, null), new ListJackson2Serializer(property, halMultipleLinkRels), null);

        serializer.serialize(sortedLinks, jgen, provider);
    }

    @Override
    public JavaType getContentType() {
        return null;
    }

    @Override
    public JsonSerializer<?> getContentSerializer() {
        return null;
    }

    @Override
    public boolean hasSingleElement(List<Link> value) {
        return value.size() == 1;
    }

    @Override
    protected ContainerSerializer<?> _withValueTypeSerializer(TypeSerializer vts) {
        return null;
    }

    @Override
    public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) throws JsonMappingException {
        return new HalLinkListSerializer(property, curieProvider, halMultipleLinkRels);
    }

    private static class ListJackson2Serializer extends ContainerSerializer<Object> implements ContextualSerializer {

        private final BeanProperty property;
        private final Map<Class<?>, JsonSerializer<Object>> serializers = new HashMap<>();
        private final HalMultipleLinkRels halMultipleLinkRels;

        public ListJackson2Serializer() {
            this(null, null);
        }

        public ListJackson2Serializer(BeanProperty property, HalMultipleLinkRels halMultipleLinkRels) {
            super(List.class, false);

            this.property = property;
            this.halMultipleLinkRels = halMultipleLinkRels;
        }

        @Override
        public void serialize(Object value, JsonGenerator jgen, SerializerProvider provider) throws IOException, JsonGenerationException {

            List<?> list = (List<?>) value;

            if (list.isEmpty()) {
                return;
            }

            if (list.size() == 1) {
                Object element = list.get(0);
                if (element instanceof Link) {
                    Link link = (Link) element;
                    if (halMultipleLinkRels.getRels().contains(link.getRel())) {
                        jgen.writeStartArray();
                        serializeContents(list.iterator(), jgen, provider);
                        jgen.writeEndArray();

                        return;
                    }
                }

                serializeContents(list.iterator(), jgen, provider);
                return;
            }

            jgen.writeStartArray();
            serializeContents(list.iterator(), jgen, provider);
            jgen.writeEndArray();
        }

        @Override
        public JavaType getContentType() {
            return null;
        }

        @Override
        public JsonSerializer<?> getContentSerializer() {
            return null;
        }

        @Override
        public boolean hasSingleElement(Object value) {
            return false;
        }

        @Override
        protected ContainerSerializer<?> _withValueTypeSerializer(TypeSerializer vts) {
            throw new UnsupportedOperationException("not implemented");
        }

        @Override
        public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) throws JsonMappingException {
            return new ListJackson2Serializer(property, halMultipleLinkRels);
        }

        private void serializeContents(Iterator<?> value, JsonGenerator jgen, SerializerProvider provider) throws IOException, JsonGenerationException {

            while (value.hasNext()) {
                Object elem = value.next();
                if (elem == null) {
                    provider.defaultSerializeNull(jgen);
                } else {
                    getOrLookupSerializerFor(elem.getClass(), provider).serialize(elem, jgen, provider);
                }
            }
        }

        private JsonSerializer<Object> getOrLookupSerializerFor(Class<?> type, SerializerProvider provider) throws JsonMappingException {

            JsonSerializer<Object> serializer = serializers.get(type);

            if (serializer == null) {
                serializer = provider.findValueSerializer(type, property);
                serializers.put(type, serializer);
            }

            return serializer;
        }
    }
}

Step 4: Deal with serializer lifecycle and dependency issues:

We have annotated the links property with @JsonSerializer(using = HalLinkListSerializer.class). Jackson will just new up the serializer that it finds in the annotation. This is fine if our serializer does not have any dependencies. But we do have dependencies on CurieProvider and HalMultipleLinkRels. These need to be initialized and provided to the serializer. You especially run into this issue when your serializer needs access to Spring beans. You cannot autowire them in, since Jackson news up the serializer, which bypasses Spring completely. The way to get around this is to create a class that implements HandlerInstantiator, which controls the lifecycle of the serializers. Spring HATEOAS does exactly this with Jackson2HalModule.HalHandlerInstantiator. The handler-instantiator creates instances of the serializers with the dependencies that they need, and maintains these serializer instances. So when Jackson sees the annotation, instead of creating a new instance, it requests the appropriate instance from the handler-instantiator. The problem is that Spring HATEOAS' handler-instantiator has no idea about our custom serializers. So how do we get around that? We have to create our own instantiator that maintains our custom serializers. This instantiator also maintains a private, internal instance of Jackson2HalModule.HalHandlerInstantiator and delegates to that, if Jackson requests a serializer-instance that our custom-instantiator does not know about. This way, I let Spring HATEOAS' instantiator handle the lifecycle and dependencies of the serializers that it knows about and also avoid duplicating logic:

public class HalHandlerInstantiator extends HandlerInstantiator {

    private final Jackson2HalModule.HalHandlerInstantiator halHandlerInstantiator;
    private final Map<Class<?>, JsonSerializer<?>> serializerMap = new HashMap<>();

    public HalHandlerInstantiator(RelProvider relProvider, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
        this(relProvider, curieProvider, halMultipleLinkRels, true);
    }

    public HalHandlerInstantiator(RelProvider relProvider, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels, boolean enforceEmbeddedCollections) {
        halHandlerInstantiator = new Jackson2HalModule.HalHandlerInstantiator(relProvider, curieProvider, enforceEmbeddedCollections);

        serializerMap.put(HalLinkListSerializer.class, new HalLinkListSerializer(curieProvider, halMultipleLinkRels));
    }

    @Override
    public JsonDeserializer<?> deserializerInstance(DeserializationConfig config, Annotated annotated, Class<?> deserClass) {
        return halHandlerInstantiator.deserializerInstance(config, annotated, deserClass);
    }

    @Override
    public KeyDeserializer keyDeserializerInstance(DeserializationConfig config, Annotated annotated, Class<?> keyDeserClass) {
        return halHandlerInstantiator.keyDeserializerInstance(config, annotated, keyDeserClass);
    }

    @Override
    public JsonSerializer<?> serializerInstance(SerializationConfig config, Annotated annotated, Class<?> serClass) {
        if(serializerMap.containsKey(serClass)) {
            return serializerMap.get(serClass);
        } else {
            return halHandlerInstantiator.serializerInstance(config, annotated, serClass);
        }
    }

    @Override
    public TypeResolverBuilder<?> typeResolverBuilderInstance(MapperConfig<?> config, Annotated annotated, Class<?> builderClass) {
        return halHandlerInstantiator.typeResolverBuilderInstance(config, annotated, builderClass);
    }

    @Override
    public TypeIdResolver typeIdResolverInstance(MapperConfig<?> config, Annotated annotated, Class<?> resolverClass) {
        return halHandlerInstantiator.typeIdResolverInstance(config, annotated, resolverClass);
    }
}

Note: The neat thing about this instantiator is that if you have any custom serializers that require access to CurieProvider, RelProvider or any Spring Bean, you can throw them in here. You just have to make sure that you pass in the appropriate dependencies to the instantiator's constructor.

Step 5: Put it all together:

We have to reconfigure Spring HATEOAS' Jackson object-mapper to use our custom classes. You can do this in your application-configuration class. The code below is an example based on some actual code from a Spring Boot application that I maintain. I reconfigured the mapper inside a method that returns my HttpMessageConverters instance, since I'm already reconfiguring the Spring HATEOS' Jackson obkect-mapper to recognize application/*+json and application/json (I am using semantic media-types and content-negotation-based versioning). Notice that I'm getting all the dependencies I need and then passing them into the instantiator, which in turn provides those dependencies to the serializers that need them. This is also where I use the mix-in class to override the link list serializer for ResourceSupport. The code below has comments that explain what I am doing:

@Configuration
public class ApplicationConfiguration {

    private static final String HAL_OBJECT_MAPPER_BEAN_NAME = "_halObjectMapper";
    private static final String DELEGATING_REL_PROVIDER_BEAN_NAME = "_relProvider";

    @Autowired
    private BeanFactory beanFactory;

    private static CurieProvider getCurieProvider(BeanFactory factory) {
        try {
            return factory.getBean(CurieProvider.class);
        } catch (NoSuchBeanDefinitionException e) {
            return null;
        }
    }

    ...

    @Bean
    public HttpMessageConverters customConverters() {
        CurieProvider curieProvider = getCurieProvider(beanFactory);
        RelProvider relProvider = beanFactory.getBean(DELEGATING_REL_PROVIDER_BEAN_NAME, RelProvider.class);
        ObjectMapper halObjectMapper = beanFactory.getBean(HAL_OBJECT_MAPPER_BEAN_NAME, ObjectMapper.class);

        //Create a new instance of Spring HATEOAS' Jackson2HalModule
        SimpleModule module = new Jackson2HalModule();

        //Override the serializer for the link list in ResourceSupport using our mixin class
        module.setMixInAnnotation(ResourceSupport.class, HalLinkListMixin.class);

        //Register our module with the HAL object mapper
        halObjectMapper.registerModule(module);

        //Set the mapper's handler instantiator to our custom instantiator
        halObjectMapper.setHandlerInstantiator(new HalHandlerInstantiator(relProvider, curieProvider, halMultipleLinkRels()));

        //The code below this line is just specific to my case.
        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
        converter.setSupportedMediaTypes(Arrays.asList(
                new MediaType("application", "json", Charset.defaultCharset()),
                new MediaType("application", "*+json", Charset.defaultCharset()),
                new MediaType("application", "hal+json")
        ));
        converter.setObjectMapper(halObjectMapper);

        return new HttpMessageConverters(converter);
    }

    //Populate our container class with the list of rels whose link representations must always be an
    //array of objects
    private HalMultipleLinkRels halMultipleLinkRels() {
        return new HalMultipleLinkRels(
            "order",
            "person",
            "blah"             
        );
    }
}

Note: For your case, you can probably just have a method annotated with @Bean that returns an instance of ObjectMapper. Everything would be exactly the same as the above, except for the message-converter code.

I hope this was helpful. This works for me, but I don't know if this is the best/most-elegant way of doing this, or if I am completely hosing Spring HATEOAS' regular behavior. Based on my tests, I haven't seen any strange behavior. Perhaps @olivergierke can comment if this is a valid workaround.

[odrotbohm]

HalEmbeddedBuilder takes a boolean in the constructor to enable the preference of collection rels. Before starting to document what needs to be changed would you mind coming up with a test case that shows what you're doing, what that's rendered like, what you don't like about it and what you'd like to see instead? You could e.g. use that:

Person person = new Person("Dave", "Matthews");

EmbeddedWrappers wrappers = new EmbeddedWrappers(true);
EmbeddedWrapper embeddedPerson = wrappers.wrap(person);

System.out.println(mapper.writeValueAsString(new Resources<EmbeddedWrapper>(Arrays.asList(embeddedPerson))));

yields

{
  "_embedded" : {
    "persons" : [ {
      "firstname" : "Dave",
      "lastname" : "Matthews"
    } ]
  }
}