001package ca.uhn.fhir.rest.client.api;
002
003import java.util.List;
004
005/*
006 * #%L
007 * HAPI FHIR - Core Library
008 * %%
009 * Copyright (C) 2014 - 2017 University Health Network
010 * %%
011 * Licensed under the Apache License, Version 2.0 (the "License");
012 * you may not use this file except in compliance with the License.
013 * You may obtain a copy of the License at
014 * 
015 * http://www.apache.org/licenses/LICENSE-2.0
016 * 
017 * Unless required by applicable law or agreed to in writing, software
018 * distributed under the License is distributed on an "AS IS" BASIS,
019 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020 * See the License for the specific language governing permissions and
021 * limitations under the License.
022 * #L%
023 */
024
025import org.hl7.fhir.instance.model.api.IBaseResource;
026
027import ca.uhn.fhir.context.FhirContext;
028import ca.uhn.fhir.rest.api.EncodingEnum;
029import ca.uhn.fhir.rest.api.SummaryEnum;
030
031public interface IRestfulClient {
032
033        /**
034         * Retrieve the contents at the given URL and parse them as a resource. This
035         * method could be used as a low level implementation of a read/vread/search
036         * operation.
037         * 
038         * @param theResourceType
039         *           The resource type to parse
040         * @param theUrl
041         *           The URL to load
042         * @return The parsed resource
043         */
044        <T extends IBaseResource> T fetchResourceFromUrl(Class<T> theResourceType, String theUrl);
045
046        /**
047         * Returns the encoding that will be used on requests. Default is <code>null</code>, which means the client will not
048         * explicitly request an encoding. (This is standard behaviour according to the FHIR specification)
049         */
050        EncodingEnum getEncoding();
051
052        /**
053         * Returns the FHIR context associated with this client
054         */
055        FhirContext getFhirContext();
056
057        /**
058         * Do not call this method in client code. It is a part of the internal HAPI API and
059         * is subject to change!
060         */
061        IHttpClient getHttpClient();
062
063        /**
064         * Returns the client interceptors that have been registered with this client
065         */
066        List<IClientInterceptor> getInterceptors();
067
068        /**
069         * Base URL for the server, with no trailing "/"
070         */
071        String getServerBase();
072
073        /**
074         * Register a new interceptor for this client. An interceptor can be used to add additional
075         * logging, or add security headers, or pre-process responses, etc.
076         */
077        void registerInterceptor(IClientInterceptor theInterceptor);
078
079        /**
080         * Specifies that the client should use the given encoding to do its
081         * queries. This means that the client will append the "_format" param
082         * to GET methods (read/search/etc), and will add an appropriate header for
083         * write methods.
084         * 
085         * @param theEncoding
086         *           The encoding to use in the request, or <code>null</code> not specify
087         *           an encoding (which generally implies the use of XML). The default is <code>null</code>.
088         */
089        void setEncoding(EncodingEnum theEncoding);
090
091        /**
092         * Specifies that the client should request that the server respond with "pretty printing"
093         * enabled. Note that this is a non-standard parameter, not all servers will
094         * support it.
095         * 
096         * @param thePrettyPrint
097         *           The pretty print flag to use in the request (default is <code>false</code>)
098         */
099        void setPrettyPrint(Boolean thePrettyPrint);
100
101        /**
102         * If not set to <code>null</code>, specifies a value for the <code>_summary</code> parameter
103         * to be applied globally on this client.
104         */
105        void setSummary(SummaryEnum theSummary);
106
107        /**
108         * Remove an intercaptor that was previously registered using {@link IRestfulClient#registerInterceptor(IClientInterceptor)}
109         */
110        void unregisterInterceptor(IClientInterceptor theInterceptor);
111
112}