Creating links with query params that are objects

[johannesgiani]

I want to create a link to a controller method that does not use single @RequestParam annotations for each query parameter. Instead I pass an object containing all query parameters. This works fine despite that the self link I am constructing does not contain the query parameters that I am passing:

  @GetMapping
  public PagedModel<EntityModel<FooDto>> findBy(
      @Valid Query query,
      @PageableDefault(size = 5) Pageable pageable,
      PagedResourcesAssembler<FooDto> assembler) {
    final Link link =
        linkTo(methodOn(Controller.class).findBy(query, pageable, assembler))
            .withSelfRel()
            .expand();
   
    final Page<FooDto> fooList = fooService.findBy(query, pageable);
    return assembler.toModel(fooList, link);
  }

The result I get when requesting http://localhost:8080/foo?param1=bar looks like this:

{
    "_links": {
        "self": {
            "href": "http://localhost:55560/foo"
        }
    },
    "page": {
        "size": 5,
        "totalElements": 0,
        "totalPages": 0,
        "number": 0
    }
}

It does not contain the query parameters in the self link. Any chance to make this work? I cannot find any documentation on query parameters when building links expect this one here: https://docs.spring.io/spring-hateoas/docs/current/reference/html/#server.link-builder.webmvc.methods.request-params which does not help me.

Thanks in advance :)

[dingjiefeng]

I want to create a link to a controller method that does not use single @RequestParam annotations for each query parameter. Instead I pass an object containing all query parameters. This works fine despite that the self link I am constructing does not contain the query parameters that I am passing:

  @GetMapping
  public PagedModel<EntityModel<FooDto>> findBy(
      @Valid Query query,
      @PageableDefault(size = 5) Pageable pageable,
      PagedResourcesAssembler<FooDto> assembler) {
    final Link link =
        linkTo(methodOn(Controller.class).findBy(query, pageable, assembler))
            .withSelfRel()
            .expand();
   
    final Page<FooDto> fooList = fooService.findBy(query, pageable);
    return assembler.toModel(fooList, link);
  }

The result I get when requesting http://localhost:8080/foo?param1=bar looks like this:

{
    "_links": {
        "self": {
            "href": "http://localhost:55560/foo"
        }
    },
    "page": {
        "size": 5,
        "totalElements": 0,
        "totalPages": 0,
        "number": 0
    }
}

It does not contain the query parameters in the self link. Any chance to make this work? I cannot find any documentation on query parameters when building links expect this one here: https://docs.spring.io/spring-hateoas/docs/current/reference/html/#server.link-builder.webmvc.methods.request-params which does not help me.

Thanks in advance :)

Did you solve it, I have the same problem

[mawsfr-adeo]

Hello !

Any update ?

[rivon0507]

Hello, is it solved now?

[bmr-exerp]

Also running into this, would like to know if anyone's found a solution.

[reda-alaoui]

Here is the workaround I have been using since July 2021 .

First, fork the project to include #1312.

Then add the following classes:

import java.beans.ConstructorProperties;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Allows Spring HATEOAS to generate request params for URI and URI templates based on attributes
 * nested in a method parameter of type {@link Record}.
 *
 * <p>The annotated type must be a {@link Record}.
 *
 * <p>{@link ConstructorProperties} can be used to customize the method parameter nested request
 * param names. But {@link ConstructorProperties} is only allowed on the @{@link Record} canonical
 * constructor.
 *
 * <p>The record can only contain attributes of type {@link String}, {@link Number}, {@link Enum},
 * {@link Boolean} or {@link Iterable} of the formers.
 *
 * <p>Usage example:
 *
 * <pre>{@code
 * @RecordRequestParams
 * record Params(String firstParam, String secondParam) {
 *
 *    @ConstructorProperties( {"first_param", "second_param"} )
 *    Params {}
 *
 * }
 *
 * }</pre>
 *
 * <pre>{@code
 * @RequestMapping("/foos")
 * @Controller
 * class MyController {
 *
 *   @GetMapping
 *   public ResponseEntity<?> list(Params params) {
 *     return ResponseEntity.ok(List.of());
 *   }
 * }
 * }</pre>
 *
 * @author Réda Housni Alaoui
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RecordRequestParams {}

import java.beans.ConstructorProperties;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.RecordComponent;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.Optional;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
import org.springframework.beans.BeanUtils;
import org.springframework.core.MethodParameter;
import org.springframework.hateoas.TemplateVariable;
import org.springframework.hateoas.TemplateVariables;
import org.springframework.hateoas.server.mvc.UriComponentsContributor;
import org.springframework.stereotype.Component;
import org.springframework.web.util.UriComponents;
import org.springframework.web.util.UriComponentsBuilder;

/**
 * Allows Spring HATEOAS to generate request params for URI and URI templates based on attributes
 * nested in a method parameter of type {@link Record}.
 *
 * <p>Spring MVC already supports java beans - annotated or not with @{@link
 * org.springframework.web.bind.annotation.ModelAttribute} - thanks to {@link
 * org.springframework.web.method.annotation.ModelAttributeMethodProcessor} .
 *
 * <p>This contributor tries to stay inline as much as possible with {@link
 * org.springframework.web.method.annotation.ModelAttributeMethodProcessor} . This saves us from
 * implementing an additional {@link
 * org.springframework.web.method.support.HandlerMethodArgumentResolver}.
 *
 * <p>For reasons explained in <a
 * href="https://web.archive.org/web/20220829102844/https://github.com/spring-projects/spring-hateoas/issues/496#issuecomment-1229891169">spring-hateoas#496</a>,
 * this contributor does not support any java bean. It only supports {@link Record} . Because of
 * this additional constraints, the record type must be annotated with @{@link RecordRequestParams}
 * to keep existing code working and to explicitly segregate unsupported types.
 *
 * <p>For now, the records can only contain attributes of type {@link String}, {@link Number},
 * {@link Enum}, {@link Boolean} or {@link Iterable} of the formers.
 *
 * <p>{@link ConstructorProperties} can be used to customize request param names. {@link
 * ConstructorProperties} is only allowed on the @{@link Record} canonical constructor.
 *
 * @author Réda Housni Alaoui
 */
@Component
class RecordRequestParamsUriContributor implements UriComponentsContributor {

  @Override
  public boolean supportsParameter(MethodParameter parameter) {
    return parameter.getParameterType().isAnnotationPresent(RecordRequestParams.class);
  }

  @Override
  public void enhance(UriComponentsBuilder builder, MethodParameter parameter, Object record) {
    if (parameter == null || record == null) {
      return;
    }

    Class<?> recordType = parameter.getParameterType();
    if (!recordType.isRecord()) {
      throw new IllegalArgumentException("%s is not a record !".formatted(recordType));
    }

    Constructor<?> canonicalConstructor = fetchCanonicalConstructor(recordType);

    String[] parameterNames = BeanUtils.getParameterNames(canonicalConstructor);
    RecordComponent[] recordComponents = recordType.getRecordComponents();
    for (int constructorParamIndex = 0;
        constructorParamIndex < recordComponents.length;
        constructorParamIndex++) {
      RecordComponent recordComponent = recordComponents[constructorParamIndex];
      Object queryParamValue;
      try {
        queryParamValue = recordComponent.getAccessor().invoke(record);
      } catch (IllegalAccessException | InvocationTargetException e) {
        throw new RuntimeException(e);
      }
      Object[] values = parseQueryParamValues(queryParamValue).orElse(null);
      if (values == null) {
        continue;
      }
      builder.queryParam(parameterNames[constructorParamIndex], values);
    }
  }

  @Override
  public TemplateVariables enhance(
      TemplateVariables templateVariables, UriComponents uriComponents, MethodParameter parameter) {

    Class<?> recordType = parameter.getParameterType();
    Constructor<?> canonicalConstructor = fetchCanonicalConstructor(recordType);
    String[] parameterNames = BeanUtils.getParameterNames(canonicalConstructor);

    TemplateVariable.VariableType variableType;
    if (uriComponents.getQueryParams().isEmpty()) {
      variableType = TemplateVariable.VariableType.REQUEST_PARAM;
    } else {
      variableType = TemplateVariable.VariableType.REQUEST_PARAM_CONTINUED;
    }

    Collection<TemplateVariable> variables =
        Arrays.stream(parameterNames)
            .map(variableName -> new TemplateVariable(variableName, variableType))
            .toList();

    return templateVariables.concat(variables);
  }

  private Constructor<?> fetchCanonicalConstructor(Class<?> recordType) {
    RecordComponent[] recordComponents = recordType.getRecordComponents();
    if (recordComponents == null) {
      throw new IllegalArgumentException("%s is not a record !".formatted(recordType));
    }

    Class[] parameterTypes =
        Arrays.stream(recordComponents).map(RecordComponent::getType).toArray(Class[]::new);

    Constructor<?> canonicalConstructor;
    try {
      canonicalConstructor = recordType.getDeclaredConstructor(parameterTypes);
    } catch (NoSuchMethodException e) {
      throw new RuntimeException(e);
    }

    List<Constructor<?>> annotatedConstructors =
        Arrays.stream(recordType.getDeclaredConstructors())
            .filter(constructor -> constructor.isAnnotationPresent(ConstructorProperties.class))
            .toList();

    if (annotatedConstructors.size() > 1) {
      throw new IllegalArgumentException(
          "%s has multiple constructors annotated with %s. Only the record canonical constructor can be annotated with %s."
              .formatted(recordType, ConstructorProperties.class, ConstructorProperties.class));
    }

    Constructor<?> singleAnnotatedConstructor =
        annotatedConstructors.stream().findFirst().orElse(null);
    if (singleAnnotatedConstructor != null
        && !singleAnnotatedConstructor.equals(canonicalConstructor)) {
      throw new IllegalArgumentException(
          "%s has a non canonical constructor annotated with %s. Only the record canonical constructor can be annotated with %s."
              .formatted(recordType, ConstructorProperties.class, ConstructorProperties.class));
    }

    return canonicalConstructor;
  }

  private Optional<Object[]> parseQueryParamValues(Object rawValue) {
    if (rawValue == null) {
      return Optional.empty();
    }
    return Optional.ofNullable(unfold(rawValue).map(this::sanitize).toArray());
  }

  private Stream<?> unfold(Object rawValue) {
    if (rawValue instanceof Iterable<?>) {
      return StreamSupport.stream(((Iterable<?>) rawValue).spliterator(), false);
    }
    Class<?> rawValueClass = rawValue.getClass();
    if (rawValueClass.isArray()) {
      return Arrays.stream((Object[]) rawValue);
    }
    return Stream.of(rawValue);
  }

  private Object sanitize(Object value) {
    Class<?> valueClass = value.getClass();
    boolean isAuthorized =
        String.class.isAssignableFrom(valueClass)
            || Number.class.isAssignableFrom(valueClass)
            || Boolean.class.isAssignableFrom(valueClass)
            || valueClass.isEnum();
    if (isAuthorized) {
      return value;
    }
    throw new IllegalArgumentException("Value %s has not an allowed type".formatted(value));
  }
}

The automated tests:

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.methodOn;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import com.fasterxml.jackson.jr.ob.JSON;
import jakarta.inject.Inject;
import java.beans.ConstructorProperties;
import java.io.IOException;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.hateoas.Link;
import org.springframework.hateoas.server.mvc.WebMvcLinkBuilderFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.context.WebApplicationContext;

/**
 * @author Réda Housni Alaoui
 */
@SpringBootTest
class RecordRequestParamsTest {

  @Inject private WebMvcLinkBuilderFactory webMvcLinkBuilderFactory;

  @Inject private WebApplicationContext context;

  private MockMvc mockMvc;

  @BeforeEach
  public void before() {
    this.mockMvc = MockMvcBuilders.webAppContextSetup(context).build();
  }

  @Test
  @DisplayName("The http request is correctly processed")
  void test1() throws Exception {
    mockMvc
        .perform(
            get("/RecordRequestParamsTest/list")
                .queryParam("first_param", "1")
                .queryParam("second_param", "2"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.firstParam").value("1"))
        .andExpect(jsonPath("$.secondParam").value("2"));
  }

  @Test
  @DisplayName("The link contains the correct request params")
  void test2() throws Exception {
    assertThat(
            webMvcLinkBuilderFactory
                .linkTo(methodOn(MyController.class).list(new RecordParams("1", "2")))
                .toUri())
        .hasToString("http://localhost/RecordRequestParamsTest/list?first_param=1&second_param=2");
  }

  @Test
  @DisplayName("Null request param value is excluded from the link")
  void test3() throws Exception {
    assertThat(
            webMvcLinkBuilderFactory
                .linkTo(methodOn(MyController.class).list(new RecordParams("1", null)))
                .toUri())
        .hasToString("http://localhost/RecordRequestParamsTest/list?first_param=1");
  }

  @Test
  @DisplayName("URI template describes all request params")
  void test4() throws Exception {
    Link link =
        webMvcLinkBuilderFactory
            .linkTo(methodOn(MyController.class).list(new RecordParams(null, null)))
            .withRel("foo");
    assertThat(link.getHref())
        .isEqualTo("http://localhost/RecordRequestParamsTest/list{?first_param,second_param}");
  }

  @Test
  @DisplayName("Link building fails when the annotated method parameter is a non record")
  void test5() throws Exception {
    ResponseEntity<?> invocation =
        methodOn(MyController.class)
            .listWithNonRecordAnnotatedWithRecordRequestParams(new NonRecordParams(null, null));
    assertThatThrownBy(() -> webMvcLinkBuilderFactory.linkTo(invocation))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("is not a record");
  }

  @Test
  @DisplayName(
      "Link building fails when more than one record constructor is annotated with @ConstructorProperties twice")
  void test6() throws Exception {
    ResponseEntity<?> invocation =
        methodOn(MyController.class)
            .listWithRecordParamsWithTwoConstructorProperties(
                new RecordParamsWithTwoConstructorProperties(null, null));
    assertThatThrownBy(() -> webMvcLinkBuilderFactory.linkTo(invocation))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("Only the record canonical constructor can be annotated");
  }

  @Test
  @DisplayName(
      "Link building fails when a record non canonical constructor is annotated with @ConstructorProperties")
  void test7() throws Exception {
    ResponseEntity<?> invocation =
        methodOn(MyController.class)
            .listWithRecordParamsWithConstructorPropertiesOnNonCanonicalCtor(
                new RecordParamsWithConstructorPropertiesOnNonCanonicalCtor(null, null));
    assertThatThrownBy(() -> webMvcLinkBuilderFactory.linkTo(invocation))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("Only the record canonical constructor can be annotated");
  }

  @Test
  @DisplayName("Link building fails when a record has one attribute of unauthorized type")
  void test8() throws Exception {
    ResponseEntity<?> invocation =
        methodOn(MyController.class)
            .listWithRecordParamsWithForbiddenTypes(new RecordParamsWithForbiddenTypes(new Foo()));
    assertThatThrownBy(() -> webMvcLinkBuilderFactory.linkTo(invocation))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("has not an allowed type");
  }

  @RequestMapping("/RecordRequestParamsTest")
  @Controller
  static class MyController {

    @GetMapping("/list")
    public ResponseEntity<?> list(RecordParams params) throws IOException {
      return ResponseEntity.ok(
          JSON.std
              .composeString()
              .startObject()
              .put("firstParam", params.firstParam())
              .put("secondParam", params.secondParam())
              .end()
              .finish());
    }

    @GetMapping("/listWithNonRecordAnnotatedWithRecordRequestParams")
    public ResponseEntity<?> listWithNonRecordAnnotatedWithRecordRequestParams(
        NonRecordParams params) throws IOException {
      return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
    }

    @GetMapping("listWithRecordParamsWithTwoConstructorProperties")
    public ResponseEntity<?> listWithRecordParamsWithTwoConstructorProperties(
        RecordParamsWithTwoConstructorProperties params) throws IOException {
      return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
    }

    @GetMapping("listWithRecordParamsWithConstructorPropertiesOnNonCanonicalCtor")
    public ResponseEntity<?> listWithRecordParamsWithConstructorPropertiesOnNonCanonicalCtor(
        RecordParamsWithConstructorPropertiesOnNonCanonicalCtor params) throws IOException {
      return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
    }

    @GetMapping("listWithRecordParamsWithForbiddenTypes")
    public ResponseEntity<?> listWithRecordParamsWithForbiddenTypes(
        RecordParamsWithForbiddenTypes params) throws IOException {
      return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
    }
  }

  @RecordRequestParams
  record RecordParams(String firstParam, String secondParam) {

    @ConstructorProperties({"first_param", "second_param"})
    RecordParams {}
  }

  @RecordRequestParams
  static class NonRecordParams {
    private final String firstParam;
    private final String secondParam;

    @ConstructorProperties({"first_param", "second_param"})
    NonRecordParams(String firstParam, String secondParam) {
      this.firstParam = firstParam;
      this.secondParam = secondParam;
    }

    public String firstParam() {
      return firstParam;
    }

    public String secondParam() {
      return secondParam;
    }
  }

  @RecordRequestParams
  record RecordParamsWithTwoConstructorProperties(String firstParam, String secondParam) {

    @ConstructorProperties({"first_param", "second_param"})
    RecordParamsWithTwoConstructorProperties {}

    @ConstructorProperties({"first_param"})
    RecordParamsWithTwoConstructorProperties(String firstParam) {
      this(firstParam, null);
    }
  }

  @RecordRequestParams
  record RecordParamsWithConstructorPropertiesOnNonCanonicalCtor(
      String firstParam, String secondParam) {

    @ConstructorProperties({"first_param"})
    RecordParamsWithConstructorPropertiesOnNonCanonicalCtor(String firstParam) {
      this(firstParam, null);
    }
  }

  @RecordRequestParams
  record RecordParamsWithForbiddenTypes(Foo foo) {}

  record Foo() {}
}