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