001package ca.uhn.fhir.rest.client;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2016 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 org.apache.http.client.HttpClient;
024
025import ca.uhn.fhir.context.ConfigurationException;
026import ca.uhn.fhir.rest.client.api.IRestfulClient;
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 Apache HTTP client instance. This method will not return null.
080         * 
081         * @see #setHttpClient(HttpClient)
082         */
083        HttpClient getHttpClient();
084
085        /**
086         * @deprecated Use {@link #getServerValidationMode()} instead
087         */
088        @Deprecated
089        ServerValidationModeEnum getServerValidationModeEnum();
090
091        /**
092         * Gets the server validation mode for any clients created from this factory. Server 
093         * validation involves the client requesting the server's conformance statement
094         * to determine whether the server is appropriate for the given client. 
095         * <p>
096         * The default value for this setting is defined by {@link #DEFAULT_SERVER_VALIDATION_MODE}
097         * </p>
098         * 
099         * @since 1.0
100         */
101        ServerValidationModeEnum getServerValidationMode();
102
103        /**
104         * Gets the socket timeout, in milliseconds. This is the SO_TIMEOUT time, which is the amount of time that a
105         * read/write network operation may block without failing.
106         * <p>
107         * The default value for this setting is defined by {@link #DEFAULT_SOCKET_TIMEOUT}
108         * </p>
109         */
110        int getSocketTimeout();
111
112        /**
113         * Gets the maximum number of connections allowed in the pool.
114         * <p>
115         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX}
116         * </p>
117         */
118        int getPoolMaxTotal();
119
120        /**
121         * Gets the maximum number of connections per route allowed in the pool.
122         * <p>
123         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX_PER_ROUTE}
124         * </p>
125         */
126        int getPoolMaxPerRoute();
127        
128        /**
129         * Instantiates a new client instance
130         * 
131         * @param theClientType
132         *            The client type, which is an interface type to be instantiated
133         * @param theServerBase
134         *            The URL of the base for the restful FHIR server to connect to
135         * @return A newly created client
136         * @throws ConfigurationException
137         *             If the interface type is not an interface
138         */
139        <T extends IRestfulClient> T newClient(Class<T> theClientType, String theServerBase);
140
141        /**
142         * Instantiates a new generic client instance
143         * 
144         * @param theServerBase
145         *            The URL of the base for the restful FHIR server to connect to
146         * @return A newly created client
147         */
148        IGenericClient newGenericClient(String theServerBase);
149
150        /**
151         * Sets the connection request timeout, in milliseconds. This is the amount of time that the HTTPClient connection
152         * pool may wait for an available connection before failing. This setting typically does not need to be adjusted.
153         * <p>
154         * The default value for this setting is defined by {@link #DEFAULT_CONNECTION_REQUEST_TIMEOUT}
155         * </p>
156         */
157        void setConnectionRequestTimeout(int theConnectionRequestTimeout);
158
159        /**
160         * Sets the connect timeout, in milliseconds. This is the amount of time that the initial connection attempt network
161         * operation may block without failing.
162         * <p>
163         * The default value for this setting is defined by {@link #DEFAULT_CONNECT_TIMEOUT}
164         * </p>
165         */
166        void setConnectTimeout(int theConnectTimeout);
167
168        /**
169         * Sets the Apache HTTP client instance to be used by any new restful clients created by this factory. If set to
170         * <code>null</code>, a new HTTP client with default settings will be created.
171         * 
172         * @param theHttpClient
173         *            An HTTP client instance to use, or <code>null</code>
174         */
175        void setHttpClient(HttpClient theHttpClient);
176
177        /**
178         * Sets the HTTP proxy to use for outgoing connections
179         * 
180         * @param theHost
181         *            The host (or null to disable proxying, as is the default)
182         * @param thePort
183         *            The port (or null to disable proxying, as is the default)
184         */
185        void setProxy(String theHost, Integer thePort);
186
187        /**
188         * Sets the credentials to use to authenticate with the HTTP proxy,
189         * if one is defined. Set to null to use no authentication with the proxy.
190         * @param theUsername The username
191         * @param thePassword The password
192         */
193        void setProxyCredentials(String theUsername, String thePassword);
194
195        /**
196         * @deprecated Use {@link #setServerValidationMode(ServerValidationModeEnum)} instead. This method was incorrectly named.
197         */
198        @Deprecated
199        void setServerValidationModeEnum(ServerValidationModeEnum theServerValidationMode);
200
201        /**
202         * Sets the server validation mode for any clients created from this factory. Server 
203         * validation involves the client requesting the server's conformance statement
204         * to determine whether the server is appropriate for the given client. 
205         * <p>
206         * The default value for this setting is defined by {@link #DEFAULT_SERVER_VALIDATION_MODE}
207         * </p>
208         * 
209         * @since 1.0
210         */
211        void setServerValidationMode(ServerValidationModeEnum theServerValidationMode);
212
213        /**
214         * Sets the socket timeout, in milliseconds. This is the SO_TIMEOUT time, which is the amount of time that a
215         * read/write network operation may block without failing.
216         * <p>
217         * The default value for this setting is defined by {@link #DEFAULT_SOCKET_TIMEOUT}
218         * </p>
219         */
220        void setSocketTimeout(int theSocketTimeout);
221
222        /**
223         * Sets the maximum number of connections allowed in the pool.
224         * <p>
225         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX}
226         * </p>
227         */
228        void setPoolMaxTotal(int thePoolMaxTotal);
229
230        /**
231         * Sets the maximum number of connections per route allowed in the pool.
232         * <p>
233         * The default value for this setting is defined by {@link #DEFAULT_POOL_MAX_PER_ROUTE}
234         * </p>
235         */
236        void setPoolMaxPerRoute(int thePoolMaxPerRoute);
237}