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