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