Add a repository loader for :exp-kalm-filesystem: repositories (#7150)

Author: michaelabuckley

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/8_4_0/7150-add-kalm-filesystem-repository.yaml

@@ -0,0 +1,4 @@
+---
+type: add
+issue: 7150
+title: "Add a repository loader for fhir-repository:exp-kalm-filesystem:/path/to/directory repositories used by the KALM IDE."

hapi-fhir-repositories/pom.xml

@@ -48,7 +48,13 @@
 			<version>${project.version}</version>
 			<scope>test</scope>
 		</dependency>
-
+		<!-- Used to compile the KalmFilesystemRepository. Delete this once KalmFilesystemRepositoryLoader is downstreamed to cqf or the IgRepository upstreamed here -->
+		  <dependency>
+				<groupId>org.opencds.cqf.fhir</groupId>
+				<artifactId>cqf-fhir-utility</artifactId>
+				<version>3.23.0</version>
+				<scope>provided</scope>
+		  </dependency>
 	</dependencies>
 
 	<build>

hapi-fhir-repositories/src/main/java/ca/uhn/fhir/repository/impl/kalm/KalmFilesystemRepositoryLoader.java

@@ -0,0 +1,81 @@
+/*-
+ * #%L
+ * Smile CDR - CDR
+ * %%
+ * Copyright (C) 2016 - 2025 Smile CDR, Inc.
+ * %%
+ * All rights reserved.
+ * #L%
+ */
+package ca.uhn.fhir.repository.impl.kalm;
+
+import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.i18n.Msg;
+import ca.uhn.fhir.repository.IRepository;
+import ca.uhn.fhir.repository.IRepositoryLoader;
+import ca.uhn.fhir.repository.impl.BaseSchemeBasedFhirRepositoryLoader;
+import jakarta.annotation.Nonnull;
+import org.apache.commons.lang3.Validate;
+
+import java.io.File;
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.nio.file.Path;
+import java.util.Optional;
+
+/**
+ * ServiceLoader for the fhir-repository: url scheme.
+ * Placeholder until this can move to cqf-fhir-utility or hapi-fhir-repositories.
+ * @see ca.uhn.fhir.repository.Repositories#repositoryForUrl
+ * TODO Either push this down to cqf-fhir-utility or upstream the IgRepository here to hapi-fhir-repositories.
+ */
+public class KalmFilesystemRepositoryLoader extends BaseSchemeBasedFhirRepositoryLoader implements IRepositoryLoader {
+	public static final String URL_SUB_SCHEME = "exp-kalm-filesystem";
+
+	public KalmFilesystemRepositoryLoader() {
+		super(URL_SUB_SCHEME);
+	}
+
+	@Nonnull
+	@Override
+	public IRepository loadRepository(@Nonnull IRepositoryRequest theRepositoryRequest) {
+		// Validate
+		Optional<FhirContext> maybeContext = theRepositoryRequest.getFhirContext();
+		Validate.isTrue(maybeContext.isPresent(), "The :%s: FHIR repository requires a FhirContext.", URL_SUB_SCHEME);
+
+		// we expect the details to be a file path for now.
+		Path configPath = getConfigPath(theRepositoryRequest.getDetails());
+
+		return makeKalmRepository(maybeContext.get(), configPath);
+	}
+
+	static Path getConfigPath(String theDetails) {
+		Path configPath = Path.of(theDetails);
+		File directory = configPath.toFile();
+
+		if (!(directory.exists() && directory.isDirectory())) {
+			throw new IllegalArgumentException(
+					Msg.code(2754) + "The provided path does not exist or is not a directory: " + directory);
+		}
+		return configPath;
+	}
+
+	static IRepository makeKalmRepository(FhirContext theFhirContext, Path thePath) {
+		try {
+			// we use reflection in case cqf-utilities is not on the classpath.  We don't want to force it as a
+			// dependency.
+			Class<?> repositoryClass = KalmFilesystemRepositoryLoader.class
+					.getClassLoader()
+					.loadClass("ca.uhn.fhir.repository.impl.kalm.PatchedKalmFileSystemRepository");
+			Constructor<?> constructor = repositoryClass.getConstructor(FhirContext.class, Path.class);
+			return (IRepository) constructor.newInstance(theFhirContext, thePath);
+		} catch (ClassNotFoundException e) {
+			throw new IllegalStateException(Msg.code(2752) + "Can't find IgRepository from cqf-utilities.jar", e);
+		} catch (NoSuchMethodException
+				| InvocationTargetException
+				| InstantiationException
+				| IllegalAccessException e) {
+			throw new IllegalStateException(Msg.code(2753) + "Error building IgRepository.", e);
+		}
+	}
+}

hapi-fhir-repositories/src/main/java/ca/uhn/fhir/repository/impl/kalm/PatchedKalmFileSystemRepository.java

@@ -0,0 +1,34 @@
+/*-
+ * #%L
+ * Smile CDR - CDR
+ * %%
+ * Copyright (C) 2016 - 2025 Smile CDR, Inc.
+ * %%
+ * All rights reserved.
+ * #L%
+ */
+package ca.uhn.fhir.repository.impl.kalm;
+
+import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.repository.impl.NaiveRepositoryTransactionProcessor;
+import org.hl7.fhir.instance.model.api.IBaseBundle;
+import org.opencds.cqf.fhir.utility.repository.ig.IgRepository;
+
+import java.nio.file.Path;
+import java.util.Map;
+
+/**
+ * A patched version of the IgRepository that adds support for transaction bundle processing.
+ * The current 3.23 version from cqf-fhir-utility has a nop implementation of transaction().
+ * TODO Delete this once the cfq implementation adds transaction support
+ */
+public class PatchedKalmFileSystemRepository extends IgRepository {
+	public PatchedKalmFileSystemRepository(FhirContext theFhirContext, Path theRoot) {
+		super(theFhirContext, theRoot);
+	}
+
+	@Override
+	public <B extends IBaseBundle> B transaction(B theTransactionBundle, Map<String, String> theHeaders) {
+		return new NaiveRepositoryTransactionProcessor(this).processTransaction(theTransactionBundle);
+	}
+}

hapi-fhir-repositories/src/main/java/ca/uhn/fhir/repository/impl/kalm/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Loader support for the IgRepository from the Clinical Reasoning group.
+ * This is a placeholder until this can move to cqf-fhir-utility or the code is up-streamed here to hapi-fhir-repositories.
+ */
+package ca.uhn.fhir.repository.impl.kalm;

hapi-fhir-repositories/src/main/resources/META-INF/services/ca.uhn.fhir.repository.IRepositoryLoader

@@ -1 +1,2 @@
 ca.uhn.fhir.repository.impl.memory.InMemoryFhirRepositoryLoader
+ca.uhn.fhir.repository.impl.kalm.KalmFilesystemRepositoryLoader

hapi-fhir-repositories/src/test/java/ca/uhn/fhir/repository/impl/kalm/KalmFilesystemRepositoryLoaderTest.java

@@ -0,0 +1,76 @@
+package ca.uhn.fhir.repository.impl.kalm;
+
+import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.context.FhirVersionEnum;
+import ca.uhn.fhir.repository.impl.UrlRepositoryFactory;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.Answers;
+import org.mockito.Mock;
+import org.mockito.Mockito;
+import org.mockito.junit.jupiter.MockitoSettings;
+
+import java.io.IOException;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+@MockitoSettings
+class KalmFilesystemRepositoryLoaderTest {
+	@Mock(stubOnly = true, answer = Answers.RETURNS_DEEP_STUBS)
+	FhirContext myFhirContext;
+	@TempDir
+	Path myTempDir;
+
+
+	@Test
+	void testRepositoryCreation() {
+	    // given
+		KalmFilesystemRepositoryLoader loader = new KalmFilesystemRepositoryLoader();
+		Mockito.when(myFhirContext.getVersion().getVersion()).thenReturn(FhirVersionEnum.R4);
+
+	    // when
+		var repo = loader.loadRepository(UrlRepositoryFactory.buildRequest("fhir-repository:exp-kalm-filesystem:" + myTempDir, myFhirContext));
+
+	    // then
+	    assertThat(repo).isInstanceOf(PatchedKalmFileSystemRepository.class);
+	}
+
+	@Test
+	void testPathExists() {
+	    // given
+
+	    // when
+		Path configPath = KalmFilesystemRepositoryLoader.getConfigPath(myTempDir.toAbsolutePath().toString());
+
+	    // then
+	    assertThat(configPath).isNotNull();
+	}
+
+	@Test
+	void testPathNotExists_error() {
+		// given
+		String nonexistent = myTempDir.resolve("nonexistent").toAbsolutePath().toString();
+
+		// when
+		assertThatThrownBy(()->KalmFilesystemRepositoryLoader.getConfigPath(nonexistent))
+				.isInstanceOf(IllegalArgumentException.class)
+				.hasMessage("HAPI-2754: The provided path does not exist or is not a directory: " + nonexistent);
+	}
+
+	@Test
+	void testPathNotDirectory_error() throws IOException {
+		// given
+		Path filename = myTempDir.resolve("file").toAbsolutePath();
+		filename.toFile().createNewFile(); // create a file instead of a directory
+		String filenameString = filename.toString();
+
+		// when
+		assertThatThrownBy(()->KalmFilesystemRepositoryLoader.getConfigPath(filenameString))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("HAPI-2754: The provided path does not exist or is not a directory: " + filename);
+	}
+
+
+}