Introduce embedded parameters for REST operations

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/EmbeddableOperationParams.java

@@ -0,0 +1,33 @@
+/*-
+ * #%L
+ * HAPI FHIR - Core Library
+ * %%
+ * Copyright (C) 2014 - 2025 Smile CDR, Inc.
+ * %%
+ * 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
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * #L%
+ */
+package ca.uhn.fhir.rest.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates a class will contain {@link OperationParam} parameters and similar annotations that will be processed
+ * in place of separate method parameters so annotated in an operation provider.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {ElementType.TYPE})
+public @interface EmbeddableOperationParams {}

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/EmbeddedOperationParams.java

@@ -0,0 +1,34 @@
+/*-
+ * #%L
+ * HAPI FHIR - Core Library
+ * %%
+ * Copyright (C) 2014 - 2025 Smile CDR, Inc.
+ * %%
+ * 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
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * #L%
+ */
+package ca.uhn.fhir.rest.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that a method parameter is for a class annotated with {@link EmbeddableOperationParams} which will in turn
+ * contain a constructor whose parameters will be annotated with {@link OperationParam} and similar annotations.
+ * a
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {ElementType.PARAMETER})
+public @interface EmbeddedOperationParams {}

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/Header.java

@@ -0,0 +1,13 @@
+package ca.uhn.fhir.rest.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+// LUKETODO:  javadoc
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.PARAMETER})
+public @interface Header {
+	String value();
+}

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/IdParam.java

@@ -25,7 +25,7 @@
 import java.lang.annotation.Target;
 
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.PARAMETER)
+@Target({ElementType.PARAMETER, ElementType.FIELD})
 public @interface IdParam {
 
 	/**

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/OperationParam.java

@@ -73,6 +73,20 @@
 	 */
 	Class<? extends IBase> type() default IBase.class;
 
+	/**
+	 * The source type of the parameters if we're expecting to do a type conversion, such as String to ZonedDateTime.
+	 * Void indicates that we don't want to do a type conversion.
+	 *
+	 * @return the source type of the parameter
+	 */
+	Class<?> sourceType() default Void.class;
+
+	/**
+	 * @return The range type associated with any type conversion.  For instance, if we expect a start and end date.
+	 * NOT_APPLICABLE is the default and indicates range conversion is not applicable.
+	 */
+	OperationParameterRangeType rangeType() default OperationParameterRangeType.NOT_APPLICABLE;
+
 	/**
 	 * Optionally specifies the type of the parameter as a string, such as <code>Coding</code> or
 	 * <code>base64Binary</code>. This can be useful if you want to use a generic interface type

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/annotation/OperationParameterRangeType.java

@@ -0,0 +1,30 @@
+/*-
+ * #%L
+ * HAPI FHIR - Core Library
+ * %%
+ * Copyright (C) 2014 - 2025 Smile CDR, Inc.
+ * %%
+ * 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
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * #L%
+ */
+package ca.uhn.fhir.rest.annotation;
+
+/**
+ * Used to indicate whether an {@link OperationParam} should be considered as part of a range of values, and if
+ * so whether it's the start or end of the range.
+ */
+public enum OperationParameterRangeType {
+	START,
+	END,
+	NOT_APPLICABLE
+}

hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/param/ParameterUtil.java

@@ -31,6 +31,7 @@
 import ca.uhn.fhir.rest.api.QualifiedParamList;
 import ca.uhn.fhir.util.ReflectionUtil;
 import ca.uhn.fhir.util.UrlUtil;
+import jakarta.annotation.Nullable;
 import org.hl7.fhir.instance.model.api.IIdType;
 import org.hl7.fhir.instance.model.api.IPrimitiveType;
 
@@ -120,21 +121,22 @@ public static Integer findIdParameterIndex(Method theMethod, FhirContext theCont
 			if (IIdType.class.equals(paramType)) {
 				return index;
 			}
-			boolean isRi = theContext.getVersion().getVersion().isRi();
-			boolean usesHapiId = IdDt.class.equals(paramType);
-			if (isRi == usesHapiId) {
-				throw new ConfigurationException(Msg.code(1936)
-						+ "Method uses the wrong Id datatype (IdDt / IdType) for the given context FHIR version: "
-						+ theMethod.toString());
-			}
+			validateIdType(theMethod, theContext, paramType);
 		}
 		return index;
 	}
 
-	// public static Integer findSinceParameterIndex(Method theMethod) {
-	// return findParamIndex(theMethod, Since.class);
-	// }
+	public static void validateIdType(Method theMethod, FhirContext theContext, Class<?> paramType) {
+		boolean isRi = theContext.getVersion().getVersion().isRi();
+		boolean usesHapiId = IdDt.class.equals(paramType);
+		if (isRi == usesHapiId) {
+			throw new ConfigurationException(Msg.code(1936)
+					+ "Method uses the wrong Id datatype (IdDt / IdType) for the given context FHIR version: "
+					+ theMethod.toString());
+		}
+	}
 
+	@Nullable
 	public static Integer findParamAnnotationIndex(Method theMethod, Class<?> toFind) {
 		int paramIndex = 0;
 		for (Annotation[] annotations : theMethod.getParameterAnnotations()) {
@@ -149,6 +151,7 @@ public static Integer findParamAnnotationIndex(Method theMethod, Class<?> toFind
 		return null;
 	}
 
+	@Nullable
 	public static Object fromInteger(Class<?> theType, IntegerDt theArgument) {
 		if (theArgument == null) {
 			return null;

hapi-fhir-base/src/main/java/ca/uhn/fhir/util/ParametersUtil.java

@@ -636,4 +636,8 @@ public static List<String> extractExamples(Annotation[] theParameterAnnotations)
 		}
 		return retVal;
 	}
+
+	public static boolean isOneOfEligibleTypes(Class<?> theTypeToCheck, Class<?>... theEligibleTypes) {
+		return Arrays.stream(theEligibleTypes).anyMatch(eligibleType -> eligibleType == theTypeToCheck);
+	}
 }

hapi-fhir-base/src/main/java/ca/uhn/fhir/util/ReflectionUtil.java

@@ -25,11 +25,13 @@
 import jakarta.annotation.Nonnull;
 import org.apache.commons.lang3.Validate;
 
+import java.lang.annotation.Annotation;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
+import java.lang.reflect.Parameter;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import java.lang.reflect.TypeVariable;
@@ -40,6 +42,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 public class ReflectionUtil {
 
@@ -165,6 +168,28 @@ public static Class<?> getGenericCollectionTypeOfMethodParameter(Method theMetho
 		return getGenericCollectionTypeOf(collectionType.getActualTypeArguments()[0]);
 	}
 
+	public static Class<?> getGenericCollectionTypeOfConstructorParameter(
+			Constructor<?> theConstructor, Parameter theConstructorParameter) {
+		final int theParamIndex = getIndexOfElement(theConstructor.getParameters(), theConstructorParameter);
+		final Type genericParameterType = theConstructor.getGenericParameterTypes()[theParamIndex];
+
+		if (Class.class.equals(genericParameterType) || Class.class.equals(genericParameterType.getClass())) {
+			return null;
+		}
+
+		final ParameterizedType collectionType = (ParameterizedType) genericParameterType;
+		return getGenericCollectionTypeOf(collectionType.getActualTypeArguments()[0]);
+	}
+
+	private static <T> int getIndexOfElement(T[] array, T element) {
+		for (int i = 0; i < array.length; i++) {
+			if (array[i].equals(element)) {
+				return i;
+			}
+		}
+		return -1; // Return -1 if the element is not found
+	}
+
 	public static Class<?> getGenericCollectionTypeOfMethodReturnType(Method theMethod) {
 		Type genericReturnType = theMethod.getGenericReturnType();
 		if (!(genericReturnType instanceof ParameterizedType)) {
@@ -290,4 +315,23 @@ public static boolean typeExists(String theName) {
 			return false;
 		}
 	}
+
+	public static List<Class<?>> getMethodParamsWithClassesWithFieldsWithAnnotation(
+			Method theMethod, Class<? extends Annotation> theAnnotationClass) {
+		return Arrays.stream(theMethod.getParameterTypes())
+				.filter(paramType -> hasAnyFieldsWithAnnotation(paramType, theAnnotationClass))
+				.collect(Collectors.toList());
+	}
+
+	public static boolean hasAnyMethodParamsWithClassesWithFieldsWithAnnotation(
+			Method theMethod, Class<? extends Annotation> theAnnotationClass) {
+		return Arrays.stream(theMethod.getParameterTypes())
+				.anyMatch(paramType -> hasAnyFieldsWithAnnotation(paramType, theAnnotationClass));
+	}
+
+	private static boolean hasAnyFieldsWithAnnotation(
+			Class<?> paramType, Class<? extends Annotation> theAnnotationClass) {
+		return Arrays.stream(paramType.getDeclaredFields())
+				.anyMatch(field -> field.isAnnotationPresent(theAnnotationClass));
+	}
 }

hapi-fhir-base/src/test/java/ca/uhn/fhir/util/ReflectionUtilTest.java

@@ -4,6 +4,8 @@
 import ca.uhn.fhir.i18n.Msg;
 import org.junit.jupiter.api.Test;
 
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.List;
@@ -65,4 +67,39 @@ public void testDescribeMethod() throws NoSuchMethodException {
 		assertEquals("startsWith returns(boolean) params(java.lang.String, int)", description);
 	}
 
+	@Retention(RetentionPolicy.RUNTIME)
+	@interface TestAnnotation {}
+
+	static class TestClass1 {
+		@TestAnnotation
+		private String field1;
+	}
+
+	static class TestClass2 {
+		private String field2;
+	}
+
+	static class TestClass3 {
+		@TestAnnotation
+		private String field3;
+	}
+
+	static class TestClass4 {
+		private TestClass1 param1;
+		private TestClass2 param2;
+		private TestClass3 param3;
+
+		void setParams(TestClass1 param1, TestClass2 param2, TestClass3 param3) {
+		}
+	}
+
+	@Test
+	public void testGetMethodParamsWithClassesWithFieldsWithAnnotation() throws NoSuchMethodException {
+		Method method = TestClass4.class.getDeclaredMethod("setParams", TestClass1.class, TestClass2.class, TestClass3.class);
+		List<Class<?>> result = ReflectionUtil.getMethodParamsWithClassesWithFieldsWithAnnotation(method, TestAnnotation.class);
+
+		assertEquals(2, result.size());
+		assertTrue(result.contains(TestClass1.class));
+		assertTrue(result.contains(TestClass3.class));
+	}
 }

hapi-fhir-jpaserver-test-dstu2/src/test/java/ca/uhn/fhir/jpa/provider/ResourceProviderDstu2ValueSetTest.java

@@ -24,8 +24,6 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.fail;
-import static org.junit.jupiter.api.Assertions.fail;
-
 
 public class ResourceProviderDstu2ValueSetTest extends BaseResourceProviderDstu2Test {
 

hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/server/RestfulServer.java

@@ -450,13 +450,19 @@ private void findResourceMethods(Object theProvider) {
 		Class<?> clazz = theProvider.getClass();
 		Class<?> supertype = clazz.getSuperclass();
 		while (!Object.class.equals(supertype)) {
+			//			ourLog.info("1234: findResourceMethods: findResourceMethodsOnInterfaces for provider class: {}",
+			// theProvider.getClass());
 			count += findResourceMethodsOnInterfaces(theProvider, supertype.getInterfaces());
+			//			ourLog.info("1234: findResourceMethods: findResourceMethods for provider class: {}",
+			// theProvider.getClass());
 			count += findResourceMethods(theProvider, supertype);
 			supertype = supertype.getSuperclass();
 		}
 
 		try {
+			//			ourLog.info("1234: findResourceMethodsOnInterfaces for provider class: {}", theProvider.getClass());
 			count += findResourceMethodsOnInterfaces(theProvider, clazz.getInterfaces());
+			//			ourLog.info("1234: findResourceMethods for provider class: {}", theProvider.getClass());
 			count += findResourceMethods(theProvider, clazz);
 		} catch (ConfigurationException e) {
 			throw new ConfigurationException(
@@ -472,7 +478,13 @@ private void findResourceMethods(Object theProvider) {
 	private int findResourceMethodsOnInterfaces(Object theProvider, Class<?>[] interfaces) {
 		int count = 0;
 		for (Class<?> anInterface : interfaces) {
+			//			final List<Class<?>> innerInterfaces = Arrays.stream(anInterface.getInterfaces()).map(innerinterface ->
+			// innerinterface.getClass()).collect(Collectors.toUnmodifiableList());
+			//			ourLog.info("1234: findResourceMethodsOnInterfaces for provider class: {} and interface: {}",
+			// theProvider.getClass(), innerInterfaces);
 			count += findResourceMethodsOnInterfaces(theProvider, anInterface.getInterfaces());
+			//			ourLog.info("1234: findResourceMethodsOnInterfaces for provider class: {} and interface: {}",
+			// theProvider.getClass(), anInterface.getClass());
 			count += findResourceMethods(theProvider, anInterface);
 		}
 		return count;