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