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