001package ca.uhn.fhir.jpa.api.dao;
002
003/*
004 * #%L
005 * HAPI FHIR JPA API
006 * %%
007 * Copyright (C) 2014 - 2021 Smile CDR, Inc.
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import ca.uhn.fhir.context.RuntimeResourceDefinition;
024import ca.uhn.fhir.jpa.api.model.DaoMethodOutcome;
025import ca.uhn.fhir.jpa.api.model.DeleteConflictList;
026import ca.uhn.fhir.jpa.api.model.DeleteMethodOutcome;
027import ca.uhn.fhir.jpa.api.model.ExpungeOptions;
028import ca.uhn.fhir.jpa.api.model.ExpungeOutcome;
029import ca.uhn.fhir.jpa.model.entity.BaseHasResource;
030import ca.uhn.fhir.jpa.model.entity.ResourceTable;
031import ca.uhn.fhir.jpa.model.entity.TagTypeEnum;
032import ca.uhn.fhir.jpa.searchparam.SearchParameterMap;
033import ca.uhn.fhir.model.api.IQueryParameterType;
034import ca.uhn.fhir.rest.api.EncodingEnum;
035import ca.uhn.fhir.rest.api.MethodOutcome;
036import ca.uhn.fhir.rest.api.PatchTypeEnum;
037import ca.uhn.fhir.rest.api.ValidationModeEnum;
038import ca.uhn.fhir.rest.api.server.IBundleProvider;
039import ca.uhn.fhir.rest.api.server.RequestDetails;
040import ca.uhn.fhir.rest.api.server.storage.ResourcePersistentId;
041import ca.uhn.fhir.rest.api.server.storage.TransactionDetails;
042import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
043import ca.uhn.fhir.rest.server.exceptions.ResourceNotFoundException;
044import org.hl7.fhir.instance.model.api.IBaseMetaType;
045import org.hl7.fhir.instance.model.api.IBaseParameters;
046import org.hl7.fhir.instance.model.api.IBaseResource;
047import org.hl7.fhir.instance.model.api.IIdType;
048
049import javax.annotation.Nonnull;
050import javax.annotation.Nullable;
051import javax.servlet.http.HttpServletResponse;
052import java.util.Collection;
053import java.util.Date;
054import java.util.List;
055import java.util.Map;
056import java.util.Set;
057
058/**
059 * Note that this interface is not considered a stable interface. While it is possible to build applications
060 * that use it directly, please be aware that we may modify methods, add methods, or even remove methods from
061 * time to time, even within minor point releases.
062 */
063public interface IFhirResourceDao<T extends IBaseResource> extends IDao {
064
065        /**
066         * Create a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
067         * therefore can not fire any interceptors. Use only for internal system calls
068         */
069        DaoMethodOutcome create(T theResource);
070
071        DaoMethodOutcome create(T theResource, RequestDetails theRequestDetails);
072
073        /**
074         * Create a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
075         * therefore can not fire any interceptors. Use only for internal system calls
076         */
077        DaoMethodOutcome create(T theResource, String theIfNoneExist);
078
079        /**
080         * @param thePerformIndexing Use with caution! If you set this to false, you need to manually perform indexing or your resources
081         *                           won't be indexed and searches won't work.
082         * @param theRequestDetails  TODO
083         */
084        DaoMethodOutcome create(T theResource, String theIfNoneExist, boolean thePerformIndexing, @Nonnull TransactionDetails theTransactionDetails, RequestDetails theRequestDetails);
085
086        DaoMethodOutcome create(T theResource, String theIfNoneExist, RequestDetails theRequestDetails);
087
088        /**
089         * Delete a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
090         * therefore can not fire any interceptors. Use only for internal system calls
091         */
092        DaoMethodOutcome delete(IIdType theResource);
093
094        /**
095         * This method does not throw an exception if there are delete conflicts, but populates them
096         * in the provided list
097         */
098        DaoMethodOutcome delete(IIdType theResource, DeleteConflictList theDeleteConflictsListToPopulate, RequestDetails theRequestDetails, @Nonnull TransactionDetails theTransactionDetails);
099
100        /**
101         * This method throws an exception if there are delete conflicts
102         */
103        DaoMethodOutcome delete(IIdType theResource, RequestDetails theRequestDetails);
104
105        /**
106         * This method does not throw an exception if there are delete conflicts, but populates them
107         * in the provided list
108         */
109        DeleteMethodOutcome deleteByUrl(String theUrl, DeleteConflictList theDeleteConflictsListToPopulate, RequestDetails theRequestDetails);
110
111        /**
112         * This method throws an exception if there are delete conflicts
113         */
114        DeleteMethodOutcome deleteByUrl(String theString, RequestDetails theRequestDetails);
115
116        ExpungeOutcome expunge(ExpungeOptions theExpungeOptions, RequestDetails theRequestDetails);
117
118        ExpungeOutcome expunge(IIdType theIIdType, ExpungeOptions theExpungeOptions, RequestDetails theRequest);
119
120        ExpungeOutcome forceExpungeInExistingTransaction(IIdType theId, ExpungeOptions theExpungeOptions, RequestDetails theRequest);
121
122        Class<T> getResourceType();
123
124        IBundleProvider history(Date theSince, Date theUntil, Integer theOffset, RequestDetails theRequestDetails);
125
126        IBundleProvider history(IIdType theId, Date theSince, Date theUntil, Integer theOffset, RequestDetails theRequestDetails);
127
128        /**
129         * Not supported in DSTU1!
130         *
131         * @param theRequestDetails TODO
132         */
133        <MT extends IBaseMetaType> MT metaAddOperation(IIdType theId1, MT theMetaAdd, RequestDetails theRequestDetails);
134
135        /**
136         * Not supported in DSTU1!
137         *
138         * @param theRequestDetails TODO
139         */
140        <MT extends IBaseMetaType> MT metaDeleteOperation(IIdType theId1, MT theMetaDel, RequestDetails theRequestDetails);
141
142        /**
143         * Not supported in DSTU1!
144         *
145         * @param theRequestDetails TODO
146         */
147        <MT extends IBaseMetaType> MT metaGetOperation(Class<MT> theType, IIdType theId, RequestDetails theRequestDetails);
148
149        /**
150         * Not supported in DSTU1!
151         *
152         * @param theRequestDetails TODO
153         */
154        <MT extends IBaseMetaType> MT metaGetOperation(Class<MT> theType, RequestDetails theRequestDetails);
155
156        DaoMethodOutcome patch(IIdType theId, String theConditionalUrl, PatchTypeEnum thePatchType, String thePatchBody, IBaseParameters theFhirPatchBody, RequestDetails theRequestDetails);
157
158        /**
159         * Read a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
160         * therefore can not fire any interceptors. Use only for internal system calls
161         */
162        T read(IIdType theId);
163
164        /**
165         * Read a resource by its internal PID
166         */
167        T readByPid(ResourcePersistentId thePid);
168
169        /**
170         * Read a resource by its internal PID
171         */
172        default T readByPid(ResourcePersistentId thePid, boolean theDeletedOk) {
173                throw new UnsupportedOperationException();
174        }
175
176        /**
177         * @param theRequestDetails TODO
178         * @throws ResourceNotFoundException If the ID is not known to the server
179         */
180        T read(IIdType theId, RequestDetails theRequestDetails);
181
182        /**
183         * Should deleted resources be returned successfully. This should be false for
184         * a normal FHIR read.
185         */
186        T read(IIdType theId, RequestDetails theRequestDetails, boolean theDeletedOk);
187
188        BaseHasResource readEntity(IIdType theId, RequestDetails theRequest);
189
190        /**
191         * @param theCheckForForcedId If true, this method should fail if the requested ID contains a numeric PID which exists, but is
192         *                            obscured by a "forced ID" so should not exist as far as the outside world is concerned.
193         */
194        BaseHasResource readEntity(IIdType theId, boolean theCheckForForcedId, RequestDetails theRequest);
195
196        /**
197         * Updates index tables associated with the given resource. Does not create a new
198         * version or update the resource's update time.
199         */
200        void reindex(T theResource, ResourceTable theEntity);
201
202        void removeTag(IIdType theId, TagTypeEnum theTagType, String theSystem, String theCode, RequestDetails theRequestDetails);
203
204        void removeTag(IIdType theId, TagTypeEnum theTagType, String theSystem, String theCode);
205
206        IBundleProvider search(SearchParameterMap theParams);
207
208        IBundleProvider search(SearchParameterMap theParams, RequestDetails theRequestDetails);
209
210        IBundleProvider search(SearchParameterMap theParams, RequestDetails theRequestDetails, HttpServletResponse theServletResponse);
211
212        /**
213         * Search for IDs for processing a match URLs, etc.
214         */
215        default Set<ResourcePersistentId> searchForIds(SearchParameterMap theParams, RequestDetails theRequest) {
216                return searchForIds(theParams, theRequest, null);
217        }
218
219        /**
220         * Search for IDs for processing a match URLs, etc.
221         *
222         * @param theConditionalOperationTargetOrNull If we're searching for IDs in order to satisfy a conditional
223         *                                            create/update, this is the resource being searched for
224         * @since 5.5.0
225         */
226        default Set<ResourcePersistentId> searchForIds(SearchParameterMap theParams, RequestDetails theRequest, @Nullable IBaseResource theConditionalOperationTargetOrNull) {
227                return searchForIds(theParams, theRequest);
228        }
229
230
231        /**
232         * Takes a map of incoming raw search parameters and translates/parses them into
233         * appropriate {@link IQueryParameterType} instances of the appropriate type
234         * for the given param
235         *
236         * @throws InvalidRequestException If any of the parameters are not known
237         */
238        void translateRawParameters(Map<String, List<String>> theSource, SearchParameterMap theTarget);
239
240        /**
241         * Update a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
242         * therefore can not fire any interceptors. Use only for internal system calls
243         */
244        DaoMethodOutcome update(T theResource);
245
246        DaoMethodOutcome update(T theResource, RequestDetails theRequestDetails);
247
248        /**
249         * Update a resource - Note that this variant of the method does not take in a {@link RequestDetails} and
250         * therefore can not fire any interceptors. Use only for internal system calls
251         */
252        DaoMethodOutcome update(T theResource, String theMatchUrl);
253
254        /**
255         * @param thePerformIndexing Use with caution! If you set this to false, you need to manually perform indexing or your resources
256         *                           won't be indexed and searches won't work.
257         * @param theRequestDetails  TODO
258         */
259        DaoMethodOutcome update(T theResource, String theMatchUrl, boolean thePerformIndexing, RequestDetails theRequestDetails);
260
261        DaoMethodOutcome update(T theResource, String theMatchUrl, RequestDetails theRequestDetails);
262
263        /**
264         * @param theForceUpdateVersion Create a new version with the same contents as the current version even if the content hasn't changed (this is mostly useful for
265         *                              resources mapping to external content such as external code systems)
266         */
267        DaoMethodOutcome update(T theResource, String theMatchUrl, boolean thePerformIndexing, boolean theForceUpdateVersion, RequestDetails theRequestDetails, @Nonnull TransactionDetails theTransactionDetails);
268
269        /**
270         * Not supported in DSTU1!
271         *
272         * @param theRequestDetails TODO
273         */
274        MethodOutcome validate(T theResource, IIdType theId, String theRawResource, EncodingEnum theEncoding, ValidationModeEnum theMode, String theProfile, RequestDetails theRequestDetails);
275
276        RuntimeResourceDefinition validateCriteriaAndReturnResourceDefinition(String criteria);
277
278        /**
279         * Delete a list of resource Pids
280         *
281         * @param theUrl             the original URL that triggered the delete
282         * @param theResourceIds     the ids of the resources to be deleted
283         * @param theDeleteConflicts out parameter of conflicts preventing deletion
284         * @param theRequest         the request that initiated the request
285         * @return response back to the client
286         */
287        DeleteMethodOutcome deletePidList(String theUrl, Collection<ResourcePersistentId> theResourceIds, DeleteConflictList theDeleteConflicts, RequestDetails theRequest);
288
289        /**
290         * Returns the current version ID for the given resource
291         */
292        default String getCurrentVersionId(IIdType theReferenceElement) {
293                return read(theReferenceElement.toVersionless()).getIdElement().getVersionIdPart();
294        }
295
296}