001package org.hl7.fhir.instance.client;
002
003/*
004Copyright (c) 2011+, HL7, Inc
005All rights reserved.
006
007Redistribution and use in source and binary forms, with or without modification, 
008are permitted provided that the following conditions are met:
009
010 * Redistributions of source code must retain the above copyright notice, this 
011   list of conditions and the following disclaimer.
012 * Redistributions in binary form must reproduce the above copyright notice, 
013   this list of conditions and the following disclaimer in the documentation 
014   and/or other materials provided with the distribution.
015 * Neither the name of HL7 nor the names of its contributors may be used to 
016   endorse or promote products derived from this software without specific 
017   prior written permission.
018
019THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
020ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
021WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
022IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
023INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
024NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
025PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
026WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
027ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
028POSSIBILITY OF SUCH DAMAGE.
029
030*/
031
032import java.net.URISyntaxException;
033import java.util.Calendar;
034import java.util.Date;
035import java.util.Map;
036
037import org.hl7.fhir.instance.model.Bundle;
038import org.hl7.fhir.instance.model.Conformance;
039import org.hl7.fhir.instance.model.OperationOutcome;
040import org.hl7.fhir.instance.model.Parameters;
041import org.hl7.fhir.instance.model.Resource;
042import org.hl7.fhir.instance.model.ValueSet;
043
044
045/**
046 * FHIR RESTful Client Interface.
047 * 
048 * @author Claude Nanjo
049 * @author Grahame Grieve
050 *
051 */
052public interface IFHIRClient {
053
054        public interface VersionInfo {
055                public String getClientJavaLibVersion();
056                public String getFhirJavaLibVersion();
057                public String getFhirJavaLibRevision();
058                public String getFhirServerVersion();
059                public String getFhirServerSoftware();
060  }
061
062        /**
063         * Get the Java verion of client and reference implementation, the 
064         * client FHIR version, the server FHIR version, and the server 
065         * software version. The server information will be blank if no 
066         * service URL is provided
067         * 
068         * @return the version information  
069         */
070        public VersionInfo getVersions();
071        
072        
073        /**
074         * Call method to initialize FHIR client. This method must be invoked
075         * with a valid base server URL prior to using the client.
076         * 
077         * Invalid base server URLs will result in a URISyntaxException being thrown.
078         * 
079         * @param baseServiceUrl Base service URL for FHIR Service.
080         * @return 
081         * @throws URISyntaxException
082         */
083        public IFHIRClient initialize(String baseServiceUrl)  throws URISyntaxException;
084        
085        /**
086         * 
087         * Call method to initialize FHIR client. This method must be invoked
088         * with a valid base server URL prior to using the client.
089         * 
090         * Invalid base server URLs will result in a URISyntaxException being thrown.
091         * 
092         * @param baseServiceUrl The base service URL
093         * @param resultCount Maximum size of the result set 
094         * @throws URISyntaxException
095         */
096        public void initialize(String baseServiceUrl, int recordCount)  throws URISyntaxException;
097        
098        /**
099         * Override the default resource format of 'application/fhir+xml'. This format is
100         * used to set Accept and Content-Type headers for client requests.
101         * 
102         * @param resourceFormat
103         */
104        public void setPreferredResourceFormat(ResourceFormat resourceFormat);
105        
106        /**
107         * Returns the resource format in effect.
108         * 
109         * @return
110         */
111        public String getPreferredResourceFormat();
112        
113        /**
114         * Override the default feed format of 'application/atom+xml'. This format is
115         * used to set Accept and Content-Type headers for client requests.
116         * 
117         * @param resourceFormat
118         */
119        public void setPreferredFeedFormat(FeedFormat feedFormat);
120        
121        /**
122         * Returns the feed format in effect.
123         * 
124         * @return
125         */
126        public String getPreferredFeedFormat();
127        
128        /**
129         * Returns the maximum record count specified for list operations
130         * such as search and history.
131         * 
132         * @return
133         */
134        public int getMaximumRecordCount();
135        
136        /**
137         * Sets the maximum record count for list operations such as history
138         * and search.
139         *
140         * @param recordCount
141         */
142        public void setMaximumRecordCount(int recordCount);
143        
144        /**
145         * Method returns a conformance statement for the system queried.
146         * @return
147         */
148        public Conformance getConformanceStatement();
149        
150        /**
151         * Method returns a conformance statement for the system queried.
152         * 
153         * @param useOptionsVerb If 'true', use OPTION rather than GET.
154         * 
155         * @return
156         */
157        public Conformance getConformanceStatement(boolean useOptionsVerb);
158        
159  /**
160   * Method returns a conformance statement for the system queried.
161   * @return
162   */
163  public Conformance getConformanceStatementQuick();
164  
165  /**
166   * Method returns a conformance statement for the system queried.
167   * 
168   * @param useOptionsVerb If 'true', use OPTION rather than GET.
169   * 
170   * @return
171   */
172  public Conformance getConformanceStatementQuick(boolean useOptionsVerb);
173  
174        /**
175         * Read the current state of a resource.
176         * 
177         * @param resource
178         * @param id
179         * @return
180         */
181        public <T extends Resource> T read(Class<T> resource, String id);
182
183        /**
184         * Read the state of a specific version of the resource
185         * 
186         * @param resource
187         * @param id
188         * @param versionid
189         * @return
190         */
191        public <T extends Resource> T vread(Class<T> resource, String id, String versionid);
192        
193        /**
194         * Update an existing resource by its id or create it if it is a new resource, not present on the server
195         * 
196         * @param resourceClass
197         * @param resource
198         * @param id
199         * @return
200         */
201        public <T extends Resource> T update(Class<T> resourceClass, T resource, String id);
202        
203        /**
204         * Delete the resource with the given ID.
205         * 
206         * @param resourceClass
207         * @param id
208         * @return
209         */
210        public <T extends Resource> boolean delete(Class<T> resourceClass, String id); 
211
212        /**
213         * Create a new resource with a server assigned id. Return the newly created
214         * resource with the id the server assigned.
215         * 
216         * @param resourceClass
217         * @param resource
218         * @return
219         */
220        public <T extends Resource> OperationOutcome create(Class<T> resourceClass, T resource);
221        
222        /**
223         * Retrieve the update history for a resource with given id since last update time. 
224         * Last update may be null TODO - ensure this is the case.
225         * 
226         * @param lastUpdate
227         * @param resourceClass
228         * @param id
229         * @return
230         */
231        public <T extends Resource> Bundle history(Calendar lastUpdate, Class<T> resourceClass, String id);
232        public <T extends Resource> Bundle history(Date lastUpdate, Class<T> resourceClass, String id);
233        
234        /**
235         * Retrieve the entire update history for a resource with the given id.
236         * Last update may be null TODO - ensure this is the case.
237         * 
238         * @param lastUpdate
239         * @param resourceClass
240         * @param id
241         * @return
242         */
243        public <T extends Resource> Bundle history(Class<T> resource, String id);
244        
245        /**
246         * Retrieve the update history for a resource type since the specified calendar date.
247         * Last update may be null TODO - ensure this is the case.
248         * 
249         * @param lastUpdate
250         * @param resourceClass
251         * @param id
252         * @return
253         */
254        public <T extends Resource> Bundle history(Calendar lastUpdate, Class<T> resourceClass);
255        public <T extends Resource> Bundle history(Date lastUpdate, Class<T> resourceClass);
256        public <T extends Resource> Bundle history(Class<T> resourceClass);
257        
258        /**
259         * Retrieve the update history for all resource types since the specified calendar date.
260         * Last update may be null 
261         * 
262         * Note: 
263         * 
264         * @param lastUpdate
265         * @param resourceClass
266         * @param id
267         * @return
268         */
269        public <T extends Resource> Bundle history(Calendar lastUpdate);
270        public <T extends Resource> Bundle history(Date lastUpdate);
271        
272        /**
273         * Retrieve the update history for all resource types since the start of server records.
274         * 
275         * Note: 
276         * 
277         * @param lastUpdate
278         * @param resourceClass
279         * @param id
280         * @return
281         */
282        public <T extends Resource> Bundle history();
283
284        /**
285         * Validate resource payload.
286         * 
287         * @param resourceClass
288         * @param resource
289         * @param id
290         * @return
291         */
292        public <T extends Resource> OperationOutcome validate(Class<T> resourceClass, T resource, String id);
293        
294        /**
295         * Return all results matching search query parameters for the given resource class.
296         * 
297         * @param resourceClass
298         * @param params
299         * @return
300         */
301        public <T extends Resource> Bundle search(Class<T> resourceClass, Map<String, String> params);
302        
303  /**
304   * Return all results matching search query parameters for the given resource class.
305   * This includes a resource as one of the parameters, and performs a post
306   * 
307   * @param resourceClass
308   * @param params
309   * @return
310   */
311  public <T extends Resource> Bundle searchPost(Class<T> resourceClass, T resource, Map<String, String> params);
312        
313        /**
314         * Update or create a set of resources
315         * 
316         * @param batch
317         * @return
318         */
319        public Bundle transaction(Bundle batch);
320        
321
322//      /**
323//       * Get a list of all tags on server 
324//       * 
325//       * GET [base]/_tags
326//       */
327//      public List<Coding> getAllTags();
328//      
329//      /**
330//       * Get a list of all tags used for the nominated resource type 
331//       * 
332//       * GET [base]/[type]/_tags
333//       */
334//      public <T extends Resource> List<Coding> getAllTagsForResourceType(Class<T> resourceClass);
335//      
336//      /**
337//       * Get a list of all tags affixed to the nominated resource. This duplicates the HTTP header entries 
338//       * 
339//       * GET [base]/[type]/[id]/_tags
340//       */
341//      public <T extends Resource> List<Coding> getTagsForReference(Class<T> resource, String id);
342//      
343//      /**
344//       * Get a list of all tags affixed to the nominated version of the resource. This duplicates the HTTP header entries
345//       * 
346//       * GET [base]/[type]/[id]/_history/[vid]/_tags
347//       */
348//      public <T extends Resource> List<Coding> getTagsForResourceVersion(Class<T> resource, String id, String versionId);
349//      
350//      /**
351//       * Remove all tags in the provided list from the list of tags for the nominated resource
352//       * 
353//       * DELETE [base]/[type]/[id]/_tags
354//       */
355//      //public <T extends Resource> boolean deleteTagsForReference(Class<T> resourceClass, String id);
356//      
357//      /**
358//       * Remove tags in the provided list from the list of tags for the nominated version of the resource
359//       * 
360//       * DELETE [base]/[type]/[id]/_history/[vid]/_tags
361//       */
362//      public <T extends Resource> List<Coding> deleteTags(List<Coding> tags, Class<T> resourceClass, String id, String version);
363//      
364//      /**
365//       * Affix tags in the list to the nominated resource
366//       * 
367//       * POST [base]/[type]/[id]/_tags
368//       * @return
369//       */
370//      public <T extends Resource> List<Coding> createTags(List<Coding> tags, Class<T> resourceClass, String id);
371//      
372//      /**
373//       * Affix tags in the list to the nominated version of the resource
374//       * 
375//       * POST [base]/[type]/[id]/_history/[vid]/_tags
376//       * 
377//       * @return
378//       */
379//      public <T extends Resource> List<Coding> createTags(List<Coding> tags, Class<T> resourceClass, String id, String version);
380//
381        /**
382         * Use this to follow a link found in a feed (e.g. paging in a search)
383         * 
384         * @param link - the URL provided by the server
385         * @return the feed the server returns
386         */
387        public Bundle fetchFeed(String url);
388
389
390        /**
391         *  invoke the expand operation and pass the value set for expansion
392         * 
393         * @param source
394         * @return
395         * @throws Exception 
396         */
397  public ValueSet expandValueset(ValueSet source) throws Exception;
398
399
400  /**
401   * Invoke an operation at the type level
402   * 
403   * @param resourceClass - the type on which to perform the operation
404   * @param name - the name of the operation to invoke
405   * @param params - parameters to pass to the operation. If the parameters are all simple, a GET will be performed
406   * @return
407   */
408        public <T extends Resource> Parameters operateType(Class<T> resourceClass, String name, Parameters params);
409
410
411        /**
412         * for debugging- the server address that the client is using
413         * 
414         * @return
415         */
416  public String getAddress();
417}