Allow SearchParameterMap to be used by IRepository

hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/IRepository.java

@@ -22,6 +22,7 @@
 import ca.uhn.fhir.context.FhirContext;
 import ca.uhn.fhir.i18n.Msg;
 import ca.uhn.fhir.model.api.IQueryParameterType;
+import ca.uhn.fhir.repository.impl.MultiMapRepositoryRestQueryBuilder;
 import ca.uhn.fhir.rest.api.MethodOutcome;
 import ca.uhn.fhir.rest.server.exceptions.AuthenticationException;
 import ca.uhn.fhir.rest.server.exceptions.ForbiddenOperationException;
@@ -82,6 +83,15 @@
  * level of support for interactions should be.
  * </p>
  *
+ * <p>
+ *     Note to implementors: this interface exposes several search() methods.
+ *     Several are deprecated and present for source-compatibility with previous versions
+ *     of this interface used by the clinical reasoning project.
+ *     We provide two main apis with different payloads for the query parameters: a Multimap method,
+ *     and an abstract builder callback.  Implementations must implement at least one of these two.
+ *     We provide default implementations of each in terms of the other.
+ * </p>
+ *
  * @see <a href="https://www.hl7.org/fhir/http.html">FHIR REST API</a>
  */
 @Beta
@@ -262,7 +272,9 @@ default <B extends IBaseBundle, T extends IBaseResource> B search(
 	 * @param resourceType the class of the Resource type to search
 	 * @param searchParameters the searchParameters for this search
 	 * @return a Bundle with the results of the search
+	 * @deprecated since 8.4 use Multimap instead
 	 */
+	@Deprecated(since = "8.4.0")
 	default <B extends IBaseBundle, T extends IBaseResource> B search(
 			Class<B> bundleType, Class<T> resourceType, Map<String, List<IQueryParameterType>> searchParameters) {
 		return this.search(bundleType, resourceType, searchParameters, Collections.emptyMap());
@@ -275,18 +287,48 @@ default <B extends IBaseBundle, T extends IBaseResource> B search(
 	 *
 	 * @param <B> a Bundle type
 	 * @param <T> a Resource type
-	 * @param bundleType the class of the Bundle type to return
-	 * @param resourceType the class of the Resource type to search
-	 * @param searchParameters the searchParameters for this search
-	 * @param headers headers for this request, typically key-value pairs of HTTP headers
+	 * @param theBundleType the class of the Bundle type to return
+	 * @param theResourceType the class of the Resource type to search
+	 * @param theSearchParameters the searchParameters for this search
+	 * @param theHeaders headers for this request, typically key-value pairs of HTTP headers
 	 * @return a Bundle with the results of the search
 	 */
-	<B extends IBaseBundle, T extends IBaseResource> B search(
-			Class<B> bundleType,
-			Class<T> resourceType,
-			Multimap<String, List<IQueryParameterType>> searchParameters,
-			Map<String, String> headers);
+	default <B extends IBaseBundle, T extends IBaseResource> B search(
+			Class<B> theBundleType,
+			Class<T> theResourceType,
+			Multimap<String, List<IQueryParameterType>> theSearchParameters,
+			Map<String, String> theHeaders) {
+		// we have a cycle of default implementations between this and the search builder version.
+		// Implementors MUST implement one or the other or both.
+		return this.search(theBundleType, theResourceType, sb -> sb.addAll(theSearchParameters), theHeaders);
+	}
 
+	/**
+	 * Searches this repository
+	 *
+	 * @see <a href="https://www.hl7.org/fhir/http.html#search">FHIR search</a>
+	 *
+	 * @param <B> a Bundle type
+	 * @param <T> a Resource type
+	 * @param theBundleType the class of the Bundle type to return
+	 * @param theResourceType the class of the Resource type to search
+	 * @param theQueryContributor the searchParameters for this search
+	 * @param theHeaders headers for this request, typically key-value pairs of HTTP headers
+	 * @return a Bundle with the results of the search
+	 */
+	default <B extends IBaseBundle, T extends IBaseResource> B search(
+			Class<B> theBundleType,
+			Class<T> theResourceType,
+			IRepositoryRestQueryContributor theQueryContributor,
+			Map<String, String> theHeaders) {
+		// we have a cycle of default implementations between this and the multi-map version.
+		// Implementors MUST implement one or the other for now.
+		return this.search(
+				theBundleType,
+				theResourceType,
+				MultiMapRepositoryRestQueryBuilder.contributorToMultimap(theQueryContributor),
+				theHeaders);
+	}
 	/**
 	 * Searches this repository
 	 *
@@ -299,7 +341,9 @@ <B extends IBaseBundle, T extends IBaseResource> B search(
 	 * @param searchParameters the searchParameters for this search
 	 * @param headers headers for this request, typically key-value pairs of HTTP headers
 	 * @return a Bundle with the results of the search
+	 * @deprecated since 8.4 use Multimap instead
 	 */
+	@Deprecated(since = "8.4.0")
 	default <B extends IBaseBundle, T extends IBaseResource> B search(
 			Class<B> bundleType,
 			Class<T> resourceType,
@@ -737,4 +781,12 @@ default <B extends IBaseBundle, P extends IBaseParameters, I extends IIdType> B
 	private static <T> T throwNotImplementedOperationException(String theMessage) {
 		throw new NotImplementedOperationException(Msg.code(2542) + theMessage);
 	}
+
+	/**
+	 * Callback interface for search() methods that use a builder to construct the query.
+	 */
+	@FunctionalInterface
+	interface IRepositoryRestQueryContributor {
+		void contributeToQuery(IRepositoryRestQueryBuilder theBuilder);
+	}
 }

hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/IRepositoryRestQueryBuilder.java

@@ -0,0 +1,41 @@
+package ca.uhn.fhir.repository;
+
+import ca.uhn.fhir.model.api.IQueryParameterType;
+import ca.uhn.fhir.rest.param.NumberParam;
+import com.google.common.collect.Multimap;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Abstract interface for building a repository rest query.
+ */
+public interface IRepositoryRestQueryBuilder {
+
+	/**
+	 * The main method for implementations to add a parameter to the query.
+	 * @param theParamName the search parameter name, without modifiers.  E.g. "name", or "_sort"
+	 * @param theParameters a list of parameters - this is the comma-separated list after the "=" in a rest query.
+	 * @return this for chaining
+	 */
+	IRepositoryRestQueryBuilder addOrList(String theParamName, List<IQueryParameterType> theParameters);
+
+	default IRepositoryRestQueryBuilder addOrList(String theParamName, IQueryParameterType... theParameterValues) {
+		return addOrList(theParamName, List.of(theParameterValues));
+	}
+
+	default IRepositoryRestQueryBuilder addNumericParameter(String theParamName, int theValue) {
+		return addOrList(theParamName, new NumberParam(theValue));
+	}
+
+	default IRepositoryRestQueryBuilder addAll(Multimap<String, List<IQueryParameterType>> theSearchParameters) {
+		theSearchParameters.entries().forEach(e -> this.addOrList(e.getKey(), e.getValue()));
+		return this;
+	}
+
+	default IRepositoryRestQueryBuilder addAll(Map<String, List<IQueryParameterType>> theSearchParameters) {
+		theSearchParameters.forEach(this::addOrList);
+		return this;
+	}
+
+}

hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/impl/MultiMapRepositoryRestQueryBuilder.java

@@ -0,0 +1,61 @@
+package ca.uhn.fhir.repository.impl;
+
+import ca.uhn.fhir.model.api.IQueryParameterType;
+import ca.uhn.fhir.repository.IRepository;
+import ca.uhn.fhir.repository.IRepositoryRestQueryBuilder;
+import com.google.common.collect.ArrayListMultimap;
+import com.google.common.collect.Multimap;
+
+import java.util.List;
+
+/**
+ * This class provides a rest-query builder over a plain Multimap.
+ * It is used to convert {@link IRepository.IRepositoryRestQueryContributor} implementations
+ * that are not Multimap-based so they can be used by IRepository implementations that are.
+ */
+public class MultiMapRepositoryRestQueryBuilder implements IRepositoryRestQueryBuilder {
+	/**
+	 * Our search parameters.
+	 * We use a list multimap to maintain insertion order, and because most of IQueryParameterType don't
+	 * provide a meaningful equals/hashCode implementation.
+	 */
+	private final Multimap<String, List<IQueryParameterType>> mySearchParameters = ArrayListMultimap.create();
+
+	@Override
+	public IRepositoryRestQueryBuilder addOrList(String theParamName, List<IQueryParameterType> theParameters) {
+		validateHomogeneousList(theParamName, theParameters);
+		mySearchParameters.put(theParamName, theParameters);
+		return this;
+	}
+
+	private void validateHomogeneousList(String theName, List<IQueryParameterType> theValues) {
+		if (theValues.isEmpty()) {
+			return;
+		}
+		IQueryParameterType firstValue = theValues.get(0);
+		for (IQueryParameterType nextValue : theValues) {
+			if (!nextValue.getClass().equals(firstValue.getClass())) {
+				throw new IllegalArgumentException("All parameters in a or-list must be of the same type. Found "
+						+ firstValue.getClass().getSimpleName() + " and "
+						+ nextValue.getClass().getSimpleName() + " in parameter '" + theName + "'");
+			}
+		}
+	}
+
+	public Multimap<String, List<IQueryParameterType>> toMultiMap() {
+		return mySearchParameters;
+	}
+
+	/**
+	 * Converts a {@link IRepository.IRepositoryRestQueryContributor} to a Multimap.
+	 *
+	 * @param theSearchQueryBuilder the contributor to convert
+	 * @return a Multimap containing the search parameters contributed by the contributor
+	 */
+	public static Multimap<String, List<IQueryParameterType>> contributorToMultimap(
+			IRepository.IRepositoryRestQueryContributor theSearchQueryBuilder) {
+		MultiMapRepositoryRestQueryBuilder builder = new MultiMapRepositoryRestQueryBuilder();
+		theSearchQueryBuilder.contributeToQuery(builder);
+		return builder.toMultiMap();
+	}
+}

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/api/SortSpec.java

@@ -20,7 +20,11 @@
 package ca.uhn.fhir.rest.api;
 
 import ca.uhn.fhir.i18n.Msg;
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+import org.apache.commons.lang3.builder.ToStringBuilder;
 
+import java.io.Serial;
 import java.io.Serializable;
 
 /**
@@ -29,6 +33,7 @@
  */
 public class SortSpec implements Serializable {
 
+	@Serial
 	private static final long serialVersionUID = 2866833099879713467L;
 
 	private SortSpec myChain;
@@ -138,4 +143,52 @@ public SortSpec setOrder(SortOrderEnum theOrder) {
 		myOrder = theOrder;
 		return this;
 	}
+
+	@Override
+	public boolean equals(Object theO) {
+		if (this == theO) return true;
+
+		if (!(theO instanceof SortSpec sortSpec)) return false;
+
+		return new EqualsBuilder()
+				.append(myChain, sortSpec.myChain)
+				.append(myParamName, sortSpec.myParamName)
+				.append(myOrder, sortSpec.myOrder)
+				.isEquals();
+	}
+
+	@Override
+	public int hashCode() {
+		return new HashCodeBuilder(17, 37)
+				.append(myChain)
+				.append(myParamName)
+				.append(myOrder)
+				.toHashCode();
+	}
+
+	@Override
+	public String toString() {
+		return new ToStringBuilder(this)
+				.append("myParamName", myParamName)
+				.append("myOrder", myOrder)
+				.append("myChain", myChain)
+				.toString();
+	}
+
+	/**
+	 * Convert strings like "-date" into a SortSpec object.
+	 * Note: this does not account for DSTU2-style sort modifiers like "date:desc" or "date:asc"
+	 * since those are on the parameter name, not the value.
+	 *
+	 * @param theParamValue a string like "-date" or "date"
+	 * @return a parsed SortSpec object
+	 */
+	public static SortSpec fromR3OrLaterParameterValue(String theParamValue) {
+		SortOrderEnum direction = SortOrderEnum.ASC;
+		if (theParamValue.startsWith("-")) {
+			direction = SortOrderEnum.DESC;
+			theParamValue = theParamValue.substring(1);
+		}
+		return new SortSpec(theParamValue, direction);
+	}
 }

hapi-fhir-base/src/test/java/ca/uhn/fhir/repository/impl/MultiMapRepositoryRestQueryBuilderTest.java

@@ -0,0 +1,52 @@
+package ca.uhn.fhir.repository.impl;
+
+import ca.uhn.fhir.model.api.IQueryParameterType;
+import ca.uhn.fhir.rest.param.TokenParam;
+import com.google.common.collect.ArrayListMultimap;
+import com.google.common.collect.LinkedHashMultimap;
+import com.google.common.collect.Multimap;
+import com.google.common.collect.Multimaps;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class MultiMapRepositoryRestQueryBuilderTest {
+	MultiMapRepositoryRestQueryBuilder myBuilder = new MultiMapRepositoryRestQueryBuilder();
+
+	@Test
+	void testAddAllMultimap() {
+	    // given
+		Multimap<String, List<IQueryParameterType>> map = ArrayListMultimap.create();
+		map.put("param1", List.of(new TokenParam("value1"), new TokenParam("value2")));
+		map.put("param1", List.of(new TokenParam("value3")));
+		map.put("param2", List.of(new TokenParam("value4")));
+
+	    // when
+		myBuilder.addAll(map);
+
+	    // then
+		assertEquals(map, myBuilder.toMultiMap());
+	}
+
+
+	@Test
+	void testAddAllMap() {
+		// given
+		Map<String, List<IQueryParameterType>> map = new HashMap<>();
+		map.put("param1", List.of(new TokenParam("value1"), new TokenParam("value2")));
+		map.put("param2", List.of(new TokenParam("value4")));
+
+		// when
+		myBuilder.addAll(map);
+
+		// then
+		// use a set for comparison.
+		var actualAsSetMultiMap = LinkedHashMultimap.create(myBuilder.toMultiMap());
+		assertEquals(Multimaps.forMap(map), actualAsSetMultiMap);
+	}
+
+}