HttpConversationManager is the main entry point class of the library through which HTTP-based conversations start. You can create an instance of this type for each endpoint that requires the use of the same configuration. Alternatively, you can make one instance available VM-wide by setting the instance as the default using setDefault(HttpConversationManager); obtain it using getDefault().
HttpConversationManager manager = new HttpConversationManager(context);
Use the fluent API established by the various setters to specify and configure the manager: its name, the number of maximum restarts, flow executor and listener, and others. Add request and response filters to the filter chain using the corresponding API methods, for example addFilter(IRequestFilter). Specific configurations, including host name verification and proxy usage, are obtained by the connection configuration listeners. The implementations of the IConnectionConfigurationListener interface are provided by the client of this library and set by the corresponding setters – setHostnameVerifierListener(IConnectionConfigurationListener<HostnameVerifier> listener) and setProxyProviderListener(IConnectionConfigurationListener<Proxy> listener), which are executed just before the actual HTTP/HTTPS connection is built.
For a typical high-level use case, you could use instances of IManagerConfigurator to configure a conversation manager. Instances of the configurator are usually supplied by additional libraries that support special use cases (for example: SAML2, OAuth2, and so on) that are described later. You usually add request/response filters and set various listeners to Configurator implementations.
X.509 and SSL/TLS support
addKeyManager(X509KeyManager) methods. You can
use the last two methods to add independent trust and key managers which
are then exchanged for an SSLSocketFactory through
the configured ISSLSocketFactoryListener. The main
purpose of this pattern is to specify trust and key managers
independently of factory creation. The default SSL socket factory
listener initializes a single SSLContext using the
- Redirection handling with white-list Redirects occurring during an HTTP conversation are handled manually, which means that the following of redirects is turned off on the underlying HttpURLConnection using HttpURLConnection.setInstanceFollowRedirects(boolean). Furthermore, this manager is capable of consulting a white-list to determine if the given redirect is allowed or not. In case a non-null instance of RedirectWhitelist is set using setRedirectWhitelist(RedirectWhitelist) and the redirect URL is found to be invalid then the conversation fails with an InvalidRedirectUrlException, which is a subclass of IOException. To detect this, look for this type of exception in the IConversationFlowListener.onCommunicationError(IOException) method. By default, the conversation manager unconditionally allows all redirects.
Thread management and thread safety
This class is not thread-safe and should be initialized before
performing any conversations. However, multiple threads can safely
create a new conversation using create(URL). The
actual conversations are executed using the configured executor set with
setExecutor(Executor), which determines where and
how to execute the entire conversation flow. To execute many short-lived
conversations by threads taken from a cached pool, use:
manager.setExecutor(Executors.newCachedThreadPool());The SynchronousExecutor in the com.sap.smp.client.httpc.utils package executes commands in the same thread from which it is invoked, and is useful when creating a synchronous HttpConversationManager.
- Observers The conversation manager supports the definition of observers from the addObserver(IObserver) method. Subinterfaces of IObserver that are defined within the com.sap.smp.client.httpc.observers package have built-in support in the conversation manager. You can also add user-defined observers, but you must invoke them using corresponding request and response filters/listeners. You can query the collection of registered observers using the IBaseEvent.getObserversByType(Class) method, making the collection available for all filters and listeners in their event parameters.
You can set response detectors that recognize textual contents. A
default response detector is included with the manager and can
optionally be used in each conversation.
- ITextBasedResponseDetector is implemented and a Charset is returned for a call to the performDetection() method. This allows response filters and response listeners to read the response using a reader instead of just an InputStream in cases where the charset of the content type in the response is not specified.
- JsonContentResponseDetector recognizes JSON content by looking for the 'application/json' content type and returning the UTF-8 charset if found. The other detector provided by the library is XmlContentResponseDetector, which detects the encoding of XML-based responses.
- CompositeTextBasedResponseDetector can execute a series of detectors.
Copying a Manager
A conversation manager acts as a preconfigured connectionfactory that can create new conversations using various filters and listeners. Use the copy() method to create a new manager from an existing one including its entire configuration.
IHttpConversation conversation = manager.create(new URL("http://www.example.com"));You need not include request parameters in the URL as you can specify them later using the IHttpConversation.addParameter(String, String) method.