001/*
002 * #%L
003 * HAPI FHIR - Core Library
004 * %%
005 * Copyright (C) 2014 - 2024 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.ConfigurationException;
023import ca.uhn.fhir.rest.api.RequestTypeEnum;
024
025import java.util.List;
026import java.util.Map;
027
028public interface IRestfulClientFactory {
029
030        /**
031         * Default value for {@link #getConnectTimeout()}
032         */
033        public static final int DEFAULT_CONNECT_TIMEOUT = 10000;
034
035        /**
036         * Default value for {@link #getConnectionRequestTimeout()}
037         */
038        public static final int DEFAULT_CONNECTION_REQUEST_TIMEOUT = 10000;
039
040        /**
041         * Default value for {@link #getServerValidationModeEnum()}
042         */
043        public static final ServerValidationModeEnum DEFAULT_SERVER_VALIDATION_MODE = ServerValidationModeEnum.ONCE;
044
045        /**
046         * Default value for {@link #getSocketTimeout()}
047         */
048        public static final int DEFAULT_SOCKET_TIMEOUT = 10000;
049
050        /**
051         * Default value for {@link #getPoolMaxTotal() ()}
052         */
053        public static final int DEFAULT_POOL_MAX = 20;
054
055        /**
056         * Default value for {@link #getPoolMaxPerRoute() }
057         */
058        public static final int DEFAULT_POOL_MAX_PER_ROUTE = DEFAULT_POOL_MAX;
059
060        /**
061         * Gets the connection request timeout, in milliseconds. This is the amount of time that the HTTPClient connection
062         * pool may wait for an available connection before failing. This setting typically does not need to be adjusted.
063         * <p>
064         * The default value for this setting is defined by {@link #DEFAULT_CONNECTION_REQUEST_TIMEOUT}
065         * </p>
066         */
067        int getConnectionRequestTimeout();
068
069        /**
070         * Gets the connect timeout, in milliseconds. This is the amount of time that the initial connection attempt network
071         * operation may block without failing.
072         * <p>
073         * The default value for this setting is defined by {@link #DEFAULT_CONNECT_TIMEOUT}
074         * </p>
075         */
076        int getConnectTimeout();
077
078        /**
079         * Returns the HTTP client instance. This method will not return null.
080         * @param theUrl
081         *            The complete FHIR url to which the http request will be sent
082         * @param theIfNoneExistParams
083         *            The params for header "If-None-Exist" as a hashmap
084         * @param theIfNoneExistString
085         *            The param for header "If-None-Exist" as a string
086         * @param theRequestType
087         *            the type of HTTP request (GET, DELETE, ..)
088         * @param theHeaders
089         *            the headers to be sent together with the http request
090         * @return the HTTP client instance
091         */
092        IHttpClient getHttpClient(
093                        StringBuilder theUrl,
094                        Map<String, List<String>> theIfNoneExistParams,
095                        String theIfNoneExistString,
096                        RequestTypeEnum theRequestType,
097                        List<Header> theHeaders);
098
099        /**
100         * @deprecated Use {@link #getServerValidationMode()} instead (this method is a synonym for that method, but this method is poorly named and will be removed at some point)
101         */
102        @Deprecated
103        ServerValidationModeEnum getServerValidationModeEnum();
104
105        /**
106         * Gets the server validation mode for any clients created from this factory. Server
107         * validation involves the client requesting the server's conformance statement
108         * to determine whether the server is appropriate for the given client.
109         * <p>
110         * The default value for this setting is defined by {@link #DEFAULT_SERVER_VALIDATION_MODE}
111         * </p>
112         *
113         * @since 1.0
114         */
115        ServerValidationModeEnum getServerValidationMode();
116
117        /**
118         * Gets the socket timeout, in milliseconds. This is the SO_TIMEOUT time, which is the amount of time that a
119         * read/write network operation may block without failing.
120         * <p>
121         * The default value for this setting is defined by {@link #DEFAULT_SOCKET_TIMEOUT}
122         * </p>
123         */
124        int getSocketTimeout();
125
126        /**
127         * Gets the maximum number of connections allowed in the pool.
128         * <p>
129         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX}
130         * </p>
131         */
132        int getPoolMaxTotal();
133
134        /**
135         * Gets the maximum number of connections per route allowed in the pool.
136         * <p>
137         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX_PER_ROUTE}
138         * </p>
139         */
140        int getPoolMaxPerRoute();
141
142        /**
143         * Instantiates a new client instance
144         *
145         * @param theClientType
146         *            The client type, which is an interface type to be instantiated
147         * @param theServerBase
148         *            The URL of the base for the restful FHIR server to connect to
149         * @return A newly created client
150         * @throws ConfigurationException
151         *             If the interface type is not an interface
152         */
153        <T extends IRestfulClient> T newClient(Class<T> theClientType, String theServerBase);
154
155        /**
156         * Instantiates a new generic client instance
157         *
158         * @param theServerBase
159         *            The URL of the base for the restful FHIR server to connect to
160         * @return A newly created client
161         */
162        IGenericClient newGenericClient(String theServerBase);
163
164        /**
165         * Sets the connection request timeout, in milliseconds. This is the amount of time that the HTTPClient connection
166         * pool may wait for an available connection before failing. This setting typically does not need to be adjusted.
167         * <p>
168         * The default value for this setting is defined by {@link #DEFAULT_CONNECTION_REQUEST_TIMEOUT}
169         * </p>
170         */
171        void setConnectionRequestTimeout(int theConnectionRequestTimeout);
172
173        /**
174         * Sets the connect timeout, in milliseconds. This is the amount of time that the initial connection attempt network
175         * operation may block without failing.
176         * <p>
177         * The default value for this setting is defined by {@link #DEFAULT_CONNECT_TIMEOUT}
178         * </p>
179         */
180        void setConnectTimeout(int theConnectTimeout);
181
182        /**
183         * Sets the Apache HTTP client instance to be used by any new restful clients created by this factory. If set to
184         * <code>null</code>, a new HTTP client with default settings will be created.
185         *
186         * @param theHttpClient
187         *            An HTTP client instance to use, or <code>null</code>
188         */
189        <T> void setHttpClient(T theHttpClient);
190
191        /**
192         * Sets the HTTP proxy to use for outgoing connections
193         *
194         * @param theHost
195         *            The host (or null to disable proxying, as is the default)
196         * @param thePort
197         *            The port (or null to disable proxying, as is the default)
198         */
199        void setProxy(String theHost, Integer thePort);
200
201        /**
202         * Sets the credentials to use to authenticate with the HTTP proxy,
203         * if one is defined. Set to null to use no authentication with the proxy.
204         * @param theUsername The username
205         * @param thePassword The password
206         */
207        void setProxyCredentials(String theUsername, String thePassword);
208
209        /**
210         * @deprecated Use {@link #setServerValidationMode(ServerValidationModeEnum)} instead. This method was incorrectly named.
211         */
212        @Deprecated
213        void setServerValidationModeEnum(ServerValidationModeEnum theServerValidationMode);
214
215        /**
216         * Sets the server validation mode for any clients created from this factory. Server
217         * validation involves the client requesting the server's conformance statement
218         * to determine whether the server is appropriate for the given client.
219         * <p>
220         * This check is primarily to validate that the server supports an appropriate
221         * version of FHIR
222         * </p>
223         * <p>
224         * The default value for this setting is defined by {@link #DEFAULT_SERVER_VALIDATION_MODE}
225         * </p>
226         *
227         * @since 1.0
228         */
229        void setServerValidationMode(ServerValidationModeEnum theServerValidationMode);
230
231        /**
232         * Sets the socket timeout, in milliseconds. This is the SO_TIMEOUT time, which is the amount of time that a
233         * read/write network operation may block without failing.
234         * <p>
235         * The default value for this setting is defined by {@link #DEFAULT_SOCKET_TIMEOUT}
236         * </p>
237         */
238        void setSocketTimeout(int theSocketTimeout);
239
240        /**
241         * Sets the maximum number of connections allowed in the pool.
242         * <p>
243         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX}
244         * </p>
245         */
246        void setPoolMaxTotal(int thePoolMaxTotal);
247
248        /**
249         * Sets the maximum number of connections per route allowed in the pool.
250         * <p>
251         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX_PER_ROUTE}
252         * </p>
253         */
254        void setPoolMaxPerRoute(int thePoolMaxPerRoute);
255
256        void validateServerBase(String theServerBase, IHttpClient theHttpClient, IRestfulClient theClient);
257
258        /**
259         * This method is internal to HAPI - It may change in future versions, use with caution.
260         */
261        void validateServerBaseIfConfiguredToDoSo(
262                        String theServerBase, IHttpClient theHttpClient, IRestfulClient theClient);
263}