001package ca.uhn.fhir.rest.client.api;
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
023
024import org.apache.http.client.HttpClient;
025import org.hl7.fhir.instance.model.api.IBaseResource;
026
027import ca.uhn.fhir.context.FhirContext;
028import ca.uhn.fhir.rest.api.SummaryEnum;
029import ca.uhn.fhir.rest.client.IClientInterceptor;
030import ca.uhn.fhir.rest.server.EncodingEnum;
031
032public interface IRestfulClient {
033
034        /**
035         * Retrieve the contents at the given URL and parse them as a resource. This
036         * method could be used as a low level implementation of a read/vread/search
037         * operation.
038         * 
039         * @param theResourceType The resource type to parse
040         * @param theUrl The URL to load
041         * @return The parsed resource
042         */
043        <T extends IBaseResource> T fetchResourceFromUrl(Class<T> theResourceType, String theUrl);
044        
045        /**
046         * Returns the FHIR context associated with this client
047         */
048        FhirContext getFhirContext();
049        
050        /**
051         * Do not call this method in client code. It is a part of the internal HAPI API and 
052         * is subject to change!
053         */
054        HttpClient getHttpClient();
055        
056        /**
057         * Base URL for the server, with no trailing "/"
058         */
059        String getServerBase();
060        
061        /**
062         * Register a new interceptor for this client. An interceptor can be used to add additional
063         * logging, or add security headers, or pre-process responses, etc. 
064         */
065        void registerInterceptor(IClientInterceptor theInterceptor);
066
067        /**
068         * Specifies that the client should use the given encoding to do its 
069         * queries. This means that the client will append the "_format" param
070         * to GET methods (read/search/etc), and will add an appropriate header for
071         * write methods. 
072         * 
073         * @param theEncoding The encoding to use in the request, or <code>null</code> not specify
074         * an encoding (which generally implies the use of XML). The default is <code>null</code>.
075         */
076        void setEncoding(EncodingEnum theEncoding);
077        
078        /**
079         * Specifies that the client should request that the server respond with "pretty printing"
080         * enabled. Note that this is a non-standard parameter, not all servers will
081         * support it.
082         * 
083         * @param thePrettyPrint The pretty print flag to use in the request (default is <code>false</code>)
084         */
085        void setPrettyPrint(Boolean thePrettyPrint);
086
087        /**
088         * If not set to <code>null</code>, specifies a value for the <code>_summary</code> parameter
089         * to be applied globally on this client.
090         */
091        void setSummary(SummaryEnum theSummary);
092
093        /**
094         * Remove an intercaptor that was previously registered using {@link IRestfulClient#registerInterceptor(IClientInterceptor)}
095         */
096        void unregisterInterceptor(IClientInterceptor theInterceptor);
097        
098}