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}