001package ca.uhn.fhir.rest.client;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2017 University Health Network
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 java.util.List;
024import java.util.Map;
025
026import org.hl7.fhir.instance.model.api.IBaseConformance;
027import org.hl7.fhir.instance.model.api.IBaseResource;
028
029import ca.uhn.fhir.model.api.Bundle;
030import ca.uhn.fhir.model.api.IQueryParameterType;
031import ca.uhn.fhir.model.api.IResource;
032import ca.uhn.fhir.model.primitive.DateTimeDt;
033import ca.uhn.fhir.model.primitive.IdDt;
034import ca.uhn.fhir.model.primitive.UriDt;
035import ca.uhn.fhir.rest.api.MethodOutcome;
036import ca.uhn.fhir.rest.client.api.IRestfulClient;
037import ca.uhn.fhir.rest.client.exceptions.FhirClientConnectionException;
038import ca.uhn.fhir.rest.client.exceptions.FhirClientInappropriateForServerException;
039import ca.uhn.fhir.rest.client.interceptor.LoggingInterceptor;
040import ca.uhn.fhir.rest.gclient.*;
041
042public interface IGenericClient extends IRestfulClient {
043
044        /**
045         * Retrieves and returns the server conformance statement
046         * 
047         * @deprecated Use {@link #fetchConformance()} instead
048         */
049        @Deprecated
050        IBaseConformance conformance();
051
052        /**
053         * Fluent method for the "create" operation, which creates a new resource instance on the server
054         */
055        ICreate create();
056        
057        /**
058         * Implementation of the "type create" method.
059         * 
060         * @param theResource
061         *            The resource to create
062         * @return An outcome
063         * @deprecated Use {@link #create() fluent method instead}. This method will be removed.
064         * 
065         */
066        @Deprecated
067        MethodOutcome create(IBaseResource theResource);
068
069        /**
070         * Fluent method for the "delete" operation, which performs a logical delete on a server resource
071         */
072        IDelete delete();
073
074        /**
075         * Implementation of the "delete instance" method.
076         * 
077         * @param theType
078         *            The type of resource to delete
079         * @param theId
080         *            the ID of the resource to delete
081         * @return An outcome
082         * @deprecated Use {@link #delete()} instead
083         */
084        @Deprecated
085        MethodOutcome delete(Class<? extends IBaseResource> theType, IdDt theId);
086
087        /**
088         * Implementation of the "delete instance" method.
089         * 
090         * @param theType
091         *            The type of resource to delete
092         * @param theId
093         *            the ID of the resource to delete
094         * @return An outcome
095         * @deprecated Use {@link #delete()} instead
096         */
097        @Deprecated
098        MethodOutcome delete(Class<? extends IBaseResource> theType, String theId);
099
100        /**
101         * Retrieves the server's conformance statement
102         */
103        IFetchConformanceUntyped fetchConformance();
104
105        /**
106         * Force the client to fetch the server's conformance statement and validate that it is appropriate for this client.
107         * 
108         * @throws FhirClientConnectionException
109         *             if the conformance statement cannot be read, or if the client
110         * @throws FhirClientInappropriateForServerException
111         *             If the conformance statement indicates that the server is inappropriate for this client (e.g. it implements the wrong version of FHIR)
112         */
113        void forceConformanceCheck() throws FhirClientConnectionException;
114
115        /**
116         * Fluent method for the "get tags" operation
117         */
118        IGetTags getTags();
119
120        /**
121         * Implementation of the "history" method
122         */
123        IHistory history();
124
125        /**
126         * Implementation of the "history instance" method.
127         * 
128         * @param theType
129         *            The type of resource to return the history for, or <code>null</code> to search for history across all resources
130         * @param theId
131         *            The ID of the resource to return the history for, or <code>null</code> to search for all resource instances. Note that if this param is not null, <code>theType</code> must also not
132         *            be null
133         * @param theSince
134         *            If not null, request that the server only return resources updated since this time
135         * @param theLimit
136         *            If not null, request that the server return no more than this number of resources. Note that the server may return less even if more are available, but should not return more
137         *            according to the FHIR specification.
138         * @return A bundle containing returned resources
139         * @deprecated As of 0.9, use the fluent {@link #history()} method instead
140         */
141        @Deprecated
142        <T extends IBaseResource> Bundle history(Class<T> theType, IdDt theId, DateTimeDt theSince, Integer theLimit);
143
144        /**
145         * Implementation of the "history instance" method.
146         * 
147         * @param theType
148         *            The type of resource to return the history for, or <code>null</code> to search for history across all resources
149         * @param theId
150         *            The ID of the resource to return the history for, or <code>null</code> to search for all resource instances. Note that if this param is not null, <code>theType</code> must also not
151         *            be null
152         * @param theSince
153         *            If not null, request that the server only return resources updated since this time
154         * @param theLimit
155         *            If not null, request that the server return no more than this number of resources. Note that the server may return less even if more are available, but should not return more
156         *            according to the FHIR specification.
157         * @return A bundle containing returned resources
158         * @deprecated As of 0.9, use the fluent {@link #history()} method instead
159         */
160        @Deprecated
161        <T extends IBaseResource> Bundle history(Class<T> theType, String theId, DateTimeDt theSince, Integer theLimit);
162
163        /**
164         * Loads the previous/next bundle of resources from a paged set, using the link specified in the "link type=next" tag within the atom bundle.
165         * 
166         * @see Bundle#getLinkNext()
167         */
168        IGetPage loadPage();
169
170        // /**
171        // * Implementation of the "instance read" method. This method will only ever do a "read" for the latest version of a
172        // * given resource instance, even if the ID passed in contains a version. If you wish to request a specific version
173        // * of a resource (the "vread" operation), use {@link #vread(Class, IdDt)} instead.
174        // * <p>
175        // * Note that if an absolute resource ID is passed in (i.e. a URL containing a protocol and host as well as the
176        // * resource type and ID) the server base for the client will be ignored, and the URL passed in will be queried.
177        // * </p>
178        // *
179        // * @param theType
180        // * The type of resource to load
181        // * @param theId
182        // * The ID to load, including the resource ID and the resource version ID. Valid values include
183        // * "Patient/123/_history/222", or "http://example.com/fhir/Patient/123/_history/222"
184        // * @return The resource
185        // */
186        // <T extends IBaseResource> T read(Class<T> theType, IdDt theId);
187
188        /**
189         * Fluent method for the "meta" operations, which can be used to get, add and remove tags and other
190         * Meta elements from a resource or across the server.
191         * 
192         * @since 1.1
193         */
194        IMeta meta();
195
196        /**
197         * Implementation of the FHIR "extended operations" action
198         */
199        IOperation operation();
200
201        /**
202         * Fluent method for "read" and "vread" methods.
203         */
204        IRead read();
205
206        /**
207         * Implementation of the "instance read" method.
208         * 
209         * @param theType
210         *            The type of resource to load
211         * @param theId
212         *            The ID to load
213         * @return The resource
214         */
215        <T extends IBaseResource> T read(Class<T> theType, String theId);
216
217        /**
218         * Perform the "read" operation (retrieve the latest version of a resource instance by ID) using an absolute URL.
219         * 
220         * @param theType
221         *            The resource type that is being retrieved
222         * @param theUrl
223         *            The absolute URL, e.g. "http://example.com/fhir/Patient/123"
224         * @return The returned resource from the server
225         */
226        <T extends IBaseResource> T read(Class<T> theType, UriDt theUrl);
227
228        /**
229         * Perform the "read" operation (retrieve the latest version of a resource instance by ID) using an absolute URL.
230         * 
231         * @param theUrl
232         *            The absolute URL, e.g. "http://example.com/fhir/Patient/123"
233         * @return The returned resource from the server
234         */
235        IBaseResource read(UriDt theUrl);
236
237        /**
238         * Register a new interceptor for this client. An interceptor can be used to add additional logging, or add security headers, or pre-process responses, etc.
239         */
240        @Override
241        void registerInterceptor(IClientInterceptor theInterceptor);
242
243        /**
244         * Fluent method for the "patch" operation, which performs a logical patch on a server resource
245         */
246        IPatch patch();
247
248        /**
249         * Search for resources matching a given set of criteria. Searching is a very powerful
250         * feature in FHIR with many features for specifying exactly what should be seaerched for 
251         * and how it should be returned. See the <a href="http://www.hl7.org/fhir/search.html">specification on search</a>
252         * for more information.
253         */
254        IUntypedQuery search();
255
256        /**
257         * Implementation of the "instance search" method.
258         * 
259         * @param theType
260         *            The type of resource to load
261         * @param theParams
262         */
263        <T extends IBaseResource> Bundle search(Class<T> theType, Map<String, List<IQueryParameterType>> theParams);
264
265        /**
266         * Perform the "search" operation using an absolute URL.
267         * 
268         * @param theType
269         *            The primary resource type that is being retrieved
270         * @param theUrl
271         *            The absolute URL, e.g. "http://example.com/fhir/Patient/123"
272         * @return The returned bundle from the server
273         */
274        <T extends IBaseResource> Bundle search(Class<T> theType, UriDt theUrl);
275
276        Bundle search(UriDt theUrl);
277
278        /**
279         * If set to <code>true</code>, the client will log all requests and all responses. This is probably not a good production setting since it will result in a lot of extra logging, but it can be
280         * useful for troubleshooting.
281         * 
282         * @param theLogRequestAndResponse
283         *            Should requests and responses be logged
284         * @deprecated Use {@link LoggingInterceptor} as a client interceptor registered to your
285         * client instead, as this provides much more fine-grained control over what is logged. This
286         * method will be removed at some point (deprecated in HAPI 1.6 - 2016-06-16) 
287         */
288        @Deprecated
289        void setLogRequestAndResponse(boolean theLogRequestAndResponse);
290
291        /**
292         * Send a transaction (collection of resources) to the server to be executed as a single unit
293         */
294        ITransaction transaction();
295
296        /**
297         * Implementation of the "transaction" method.
298         * 
299         * @param theResources
300         *            The resources to create/update in a single transaction
301         * @return A list of resource stubs (<b>these will not be fully populated</b>) containing IDs and other {@link IResource#getResourceMetadata() metadata}
302         * @deprecated Use {@link #transaction()}
303         * 
304         */
305        @Deprecated
306        List<IBaseResource> transaction(List<IBaseResource> theResources);
307
308        /**
309         * Remove an intercaptor that was previously registered using {@link IRestfulClient#registerInterceptor(IClientInterceptor)}
310         */
311        @Override
312        void unregisterInterceptor(IClientInterceptor theInterceptor);
313
314        /**
315         * Fluent method for the "update" operation, which performs a logical delete on a server resource
316         */
317        IUpdate update();
318
319        /**
320         * Implementation of the "instance update" method.
321         * 
322         * @param theId
323         *            The ID to update
324         * @param theResource
325         *            The new resource body
326         * @return An outcome containing the results and possibly the new version ID
327         */
328        MethodOutcome update(IdDt theId, IBaseResource theResource);
329
330        /**
331         * Implementation of the "instance update" method.
332         * 
333         * @param theId
334         *            The ID to update
335         * @param theResource
336         *            The new resource body
337         * @return An outcome containing the results and possibly the new version ID
338         */
339        MethodOutcome update(String theId, IBaseResource theResource);
340
341        /**
342         * Validate a resource
343         */
344        IValidate validate();
345
346        /**
347         * Implementation of the "type validate" method.
348         * 
349         * @param theResource
350         *            The resource to validate
351         * @return An outcome containing any validation issues
352         */
353        MethodOutcome validate(IBaseResource theResource);
354
355        /**
356         * Implementation of the "instance vread" method. Note that this method expects <code>theId</code> to contain a resource ID as well as a version ID, and will fail if it does not.
357         * <p>
358         * Note that if an absolute resource ID is passed in (i.e. a URL containing a protocol and host as well as the resource type and ID) the server base for the client will be ignored, and the URL
359         * passed in will be queried.
360         * </p>
361         * 
362         * @param theType
363         *            The type of resource to load
364         * @param theId
365         *            The ID to load, including the resource ID and the resource version ID. Valid values include "Patient/123/_history/222", or "http://example.com/fhir/Patient/123/_history/222"
366         * @return The resource
367         */
368        <T extends IBaseResource> T vread(Class<T> theType, IdDt theId);
369
370        /**
371         * Implementation of the "instance vread" method.
372         * 
373         * @param theType
374         *            The type of resource to load
375         * @param theId
376         *            The ID to load
377         * @param theVersionId
378         *            The version ID
379         * @return The resource
380         * @deprecated Deprecated in 0.7 - IdDt can contain an ID and a version, so this class doesn't make a lot of sense
381         */
382        @Deprecated
383        <T extends IBaseResource> T vread(Class<T> theType, IdDt theId, IdDt theVersionId);
384
385        /**
386         * Implementation of the "instance vread" method.
387         * 
388         * @param theType
389         *            The type of resource to load
390         * @param theId
391         *            The ID to load
392         * @param theVersionId
393         *            The version ID
394         * @return The resource
395         */
396        <T extends IBaseResource> T vread(Class<T> theType, String theId, String theVersionId);
397
398
399        
400}