
001/* 002 * #%L 003 * HAPI FHIR JPA Server 004 * %% 005 * Copyright (C) 2014 - 2025 Smile CDR, Inc. 006 * %% 007 * Licensed under the Apache License, Version 2.0 (the "License"); 008 * you may not use this file except in compliance with the License. 009 * You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, software 014 * distributed under the License is distributed on an "AS IS" BASIS, 015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 016 * See the License for the specific language governing permissions and 017 * limitations under the License. 018 * #L% 019 */ 020package ca.uhn.fhir.jpa.cache; 021 022import ca.uhn.fhir.interceptor.model.RequestPartitionId; 023import ca.uhn.fhir.rest.api.server.RequestDetails; 024import jakarta.annotation.Nonnull; 025 026import java.util.Optional; 027import java.util.function.Supplier; 028 029/** 030 * This service manages a partition-independent cache of resource identifiers. 031 * 032 * @since 8.6.0 033 */ 034public interface IResourceIdentifierCacheSvc { 035 036 /** 037 * Retrieves (and creates if necessary) the PID associated with the 038 * given identifier system URL. 039 * <p> 040 * Thread-safety: This method is designed to be thread-safe, including in cases where 041 * multiple threads are attempting to create a new FHIR ID for the same identifier system. 042 * It will internally retry automatically if multiple threads attempt to create a new 043 * identifier system and will not fail in this case. 044 * </p> 045 * <p> 046 * Transactionality: This method will open a new transaction if one is not already open. 047 * </p> 048 * 049 * @param theRequestDetails The request details associated with the current request 050 * @param theRequestPartitionId The partition ID associated with the current request 051 * @param theSystem The <code>Identifier.system</code> value 052 * @return Returns a PID associated with the given identifier system URL. 053 */ 054 long getOrCreateResourceIdentifierSystem( 055 RequestDetails theRequestDetails, RequestPartitionId theRequestPartitionId, String theSystem); 056 057 /** 058 * Retrieves the FHIR ID associated with the given Patient identifier, creating a new 059 * record using the given Supplier if no existing record is found. This method enforces 060 * uniqueness on the identifier using a database constraint and will therefore only allow 061 * one FHIR ID to be associated with one Identifier. No uniqueness is enforced on the FHIR 062 * ID. 063 * <p> 064 * Thread safety: This method will fail with a constraint error if multiple threads 065 * attempt to assign a FHIR ID for the same system+value combination concurrently. 066 * </p> 067 * <p> 068 * Transactionality: This method will open a new transaction if one is not already open. 069 * </p> 070 * 071 * @param theSystem The <code>Identifier.system</code> value 072 * @param theValue The <code>Identifier.value</code> value 073 * @param theNewIdSupplier If no existing FHIR ID is found, a new entry will be created using this ID supplier 074 * @return The FHIR ID associated with this identifier 075 */ 076 @Nonnull 077 String getFhirIdAssociatedWithUniquePatientIdentifier( 078 RequestDetails theRequestDetails, 079 RequestPartitionId theRequestPartitionId, 080 String theSystem, 081 String theValue, 082 Supplier<String> theNewIdSupplier); 083 084 /** 085 * Retrieves the FHIR ID previously associated with the given Patient identifier, if 086 * one exists, and returns {@link Optional#empty()} otherwise. 087 * <p> 088 * Thread safety: This method is always thread safe, as it reads without writing. 089 * </p> 090 * <p> 091 * Transactionality: This method will open a new transaction if one is not already open. 092 * </p> 093 * 094 * @param theSystem The <code>Identifier.system</code> value 095 * @param theValue The <code>Identifier.value</code> value 096 * @return The FHIR ID associated with this identifier, if one already exists 097 */ 098 @Nonnull 099 Optional<String> getFhirIdAssociatedWithUniquePatientIdentifier( 100 RequestDetails theRequestDetails, 101 RequestPartitionId theRequestPartitionId, 102 String theSystem, 103 String theValue); 104}