Developer

Conversation Manager

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().

Instantiation

Instantiate a conversation manager instance by passing in the android application context:
HttpConversationManager manager = new HttpConversationManager(context); 

Configuration

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.

This example shows a configurator that implements the configure() method of the IManagerConfigurator interface. It uses the isConfiguredBy() method to determine whether the manager instance is already configured. If it is, you can then either return the configurator silently, or throw an exception. If the instance is not already configured, the configurator calls various methods on the manager to prepare it for the specified use case. Finally, the sample uses the configuredBy() method to mark the manager instance to be configured.
Use response filters to process the response when it is received. RecieveEvent instance response filters can access and alter particular properties of the response. More importantly, these filters can access and alter the stream or the reader of the response body. A stream or reader obtained this way cannot be marked, reset, or closed without throwing an exception. Like request filters, a response filter passes control to the rest of the chain. Returning the specific RESTART_SIGNAL object restarts the entire flow, unless the maximum number of restarts has been reached, in which case, the flow is canceled.
  • X.509 and SSL/TLS support Achieved through setSSLSocketFactoryListener(ISSLSocketFactoryListener), addTrustManager(X509TrustManager) and 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 SSL protocol.
  • 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.
  • Response detection 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.

Conversation Creation

Once you have an instance of the conversation manager, the code below creates a new HTTP conversation using the configuration, that is set in the manager. The specified URL must point to either an HTTP or an HTTPS endpoint:
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.