View Javadoc
1   package ca.uhn.fhir.rest.client.api;
2   
3   /*
4    * #%L
5    * HAPI FHIR - Core Library
6    * %%
7    * Copyright (C) 2014 - 2018 University Health Network
8    * %%
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   * 
13   *      http://www.apache.org/licenses/LICENSE-2.0
14   * 
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
20   * #L%
21   */
22  
23  import java.util.List;
24  import java.util.Map;
25  
26  import ca.uhn.fhir.context.ConfigurationException;
27  import ca.uhn.fhir.rest.api.RequestTypeEnum;
28  
29  public interface IRestfulClientFactory {
30  
31  	/**
32  	 * Default value for {@link #getConnectTimeout()}
33  	 */
34  	public static final int DEFAULT_CONNECT_TIMEOUT = 10000;
35  
36  	/**
37  	 * Default value for {@link #getConnectionRequestTimeout()}
38  	 */
39  	public static final int DEFAULT_CONNECTION_REQUEST_TIMEOUT = 10000;
40  
41  	/**
42  	 * Default value for {@link #getServerValidationModeEnum()}
43  	 */
44  	public static final ServerValidationModeEnum DEFAULT_SERVER_VALIDATION_MODE = ServerValidationModeEnum.ONCE;
45  
46  	/**
47  	 * Default value for {@link #getSocketTimeout()}
48  	 */
49  	public static final int DEFAULT_SOCKET_TIMEOUT = 10000;
50  	
51  	/**
52  	 * Default value for {@link #getPoolMaxTotal() ()}
53  	 */
54  	public static final int DEFAULT_POOL_MAX = 20;
55  	
56  	/**
57  	 * Default value for {@link #getPoolMaxPerRoute() }
58  	 */
59  	public static final int DEFAULT_POOL_MAX_PER_ROUTE = DEFAULT_POOL_MAX;
60  	
61  	/**
62  	 * Gets the connection request timeout, in milliseconds. This is the amount of time that the HTTPClient connection
63  	 * pool may wait for an available connection before failing. This setting typically does not need to be adjusted.
64  	 * <p>
65  	 * The default value for this setting is defined by {@link #DEFAULT_CONNECTION_REQUEST_TIMEOUT}
66  	 * </p>
67  	 */
68  	int getConnectionRequestTimeout();
69  	
70  	/**
71  	 * Gets the connect timeout, in milliseconds. This is the amount of time that the initial connection attempt network
72  	 * operation may block without failing.
73  	 * <p>
74  	 * The default value for this setting is defined by {@link #DEFAULT_CONNECT_TIMEOUT}
75  	 * </p>
76  	 */
77  	int getConnectTimeout();
78  
79  	/**
80  	 * Returns the HTTP client instance. This method will not return null.
81  	 * @param theUrl
82  	 *            The complete FHIR url to which the http request will be sent
83  	 * @param theIfNoneExistParams
84  	 *            The params for header "If-None-Exist" as a hashmap
85  	 * @param theIfNoneExistString
86  	 *            The param for header "If-None-Exist" as a string
87  	 * @param theRequestType
88  	 *            the type of HTTP request (GET, DELETE, ..) 
89  	 * @param theHeaders
90  	 *            the headers to be sent together with the http request
91  	 * @return the HTTP client instance
92  	 */
93  	IHttpClient getHttpClient(StringBuilder theUrl, Map<String, List<String>> theIfNoneExistParams, String theIfNoneExistString, RequestTypeEnum theRequestType, List<Header> theHeaders);
94  
95  	/**
96  	 * @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)
97  	 */
98  	@Deprecated
99  	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 }