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