IHttpConversation

```
public interface IHttpConversation
```
Represents a single HTTP conversation. An instance of this type can be obtained using HttpConversationManager.create(java.net.URL) and as such it belongs to it's creating manager throughout it's lifecycle. Make sure to become familiar with the concepts layed down by the manager before using this interface.
After having instantiated a new object from this type it's in the preparation state. At this time headers and parameters can be added, setters can be invoked. After having called the start() method the conversation begins and no more modifications are allowed anymore.

The response listener is mandatory. The request listener is optional in case the user does not want to inject additional headers or a body.

If not set explicitly then a conversation by default is configured with the HTTP GET method.

For efficiency reasons, as recommended by HttpURLConnection, by default all conversations are configured to use chunked transfer mode using the default chunk size.

The default Content-Type header for methods allowing a request body is 'text/plain'.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`IHttpConversation`	`addHeader(java.lang.String name, java.lang.String value)` Adds a new request header.
`IHttpConversation`	`addParameter(java.lang.String name, java.lang.String value)` Adds a new request parameter.
`void`	`cancel()` Cancels the conversation after it has been started.
`java.lang.String`	`getName()` Returns the name of this conversation.
`ITextBasedResponseDetector`	`getTextBasedResponseDetector()` Returns the text-based response detector of this conversation.
`boolean`	`isCancelled()` Returns whether this converation has been cancelled, either explicitly using `cancel()` or by one of the request/response filters.
`IHttpConversation`	`setChunkSize(int chunkSize)` Sets the chunk size for the chunked transfer encoding.
`IHttpConversation`	`setContentLength(int length)` Sets the content length which is the total amount of bytes to be sent in the request body.
`IHttpConversation`	`setFlowListener(IConversationFlowListener listener)` Sets the flow listener.
`IHttpConversation`	`setMaximumRestarts(int maximumRestarts)` Sets the maximum number of flow restarts allowed.
`IHttpConversation`	`setMethod(HttpMethod method)` Sets the HTTP method to use.
`IHttpConversation`	`setName(java.lang.String name)` Sets the name of this conversation.
`IHttpConversation`	`setRequestListener(IRequestBodyListener listener)` Convenience method setting a request listener with `setRequestListener(IRequestListener)` which sends only the body and does not make use of the `IRequestHeaderListener.onRequestHeaderSending(ISendEvent)` method.
`IHttpConversation`	`setRequestListener(IRequestListener listener)` Sets the request listener which is going to be invoked when the request is about to be sent.
`IHttpConversation`	`setResponseListener(IResponseListener listener)` Sets the response listener which is going to be invoked when the response has been received.
`IHttpConversation`	`setTextBasedResponseDetector(ITextBasedResponseDetector detector)` Sets the text-based response detector for this conversation.
`IHttpConversation`	`setTimeout(int timeoutInMillis)` Sets a connection timeout to be used for the underlying `HttpURLConnection`s throughout this conversation.
`void`	`start()` Starts the conversation.

- Method Detail
  - setName
```
IHttpConversation setName(java.lang.String name)
```
    Sets the name of this conversation. The name is exposed to pluggable components such as request/response listeners and filters using IContext objects accessible from IBaseEvent s.
    
    Parameters:
    
    name - the name, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - getName
```
java.lang.String getName()
```
    Returns the name of this conversation.
    
    Returns:
    
    the name, may be null
  - addHeader
```
IHttpConversation addHeader(java.lang.String name,
                            java.lang.String value)
```
    Adds a new request header. If there's an existing one with the same name it gets overwritten. If the value is null then the header gets removed.
    Note that the final set of headers sent might be overwritten by the request filters and listeners during the conversation.
    
    Parameters:
    
    name - the header name, must be non-null
    
    value - the value, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - addParameter
```
IHttpConversation addParameter(java.lang.String name,
                               java.lang.String value)
```
    Adds a new request parameter. Takes care of URL encoding the given value. If there's an existing one with the same name it gets overwritten. If the value is null then the parameter gets removed.
    Note that the final set of parameters sent might be overwritten by the request filters and listeners during the conversation.
    
    Parameters:
    
    name - the parameter name, must be non-null
    
    value - the value, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - setMethod
```
IHttpConversation setMethod(HttpMethod method)
```
    Sets the HTTP method to use. Must be one of the supported method types. Setting null resets to the default (which is HTTP GET).
    If the method set is allowed to have a request body and the 'Content-Type' header is not set then it's set to the default.
    
    Parameters:
    
    method - the method, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - setContentLength
```
IHttpConversation setContentLength(int length)
```
    Sets the content length which is the total amount of bytes to be sent in the request body. Sending fewer or more data results in undefined behaviour.
    As content length and chunk size are mutually exclusive concepts, this method clears the chunk size.
    
    Parameters:
    
    length - the number of bytes that are planned to be sent, must be positive
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
    
    java.lang.IllegalArgumentException - in case the argument is zero or negative
  - setChunkSize
```
IHttpConversation setChunkSize(int chunkSize)
```
    Sets the chunk size for the chunked transfer encoding. Setting it to zero resets the default chunk size.
    As content length and chunk size are mutually exclusive concepts, this method clears the content length.
    
    Parameters:
    
    chunkSize - the chunk size in bytes, must be positive or zero (for the default)
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
    
    java.lang.IllegalArgumentException - in case the argument is negative
  - setMaximumRestarts
```
IHttpConversation setMaximumRestarts(int maximumRestarts)
```
    Sets the maximum number of flow restarts allowed. The default value is inherited from the HttpConversationManager. If the response filter chain singals to restart the conversation flow meanwhile the maximum has already been reached then the conversation gets cancelled and the IConversationFlowListener gets notified.
    If the set value is less than or equals to zero then the response filter chain is not allowed to restart the flow at all.
    
    Parameters:
    
    maximumRestarts - the maximum number of restarts
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - setTimeout
```
IHttpConversation setTimeout(int timeoutInMillis)
```
    Sets a connection timeout to be used for the underlying HttpURLConnections throughout this conversation. Setting a negative value disables the timeout as if URLConnection.setConnectTimeout(int) were not called. This results in a default timeout being used.
    
    Parameters:
    
    timeoutInMillis - the timeout in milliseconds or a negative value to revert to default behaviour
    
    Returns:
    
    this, for method chaining * @throws IllegalStateException in case the conversation has already started
  - setTextBasedResponseDetector
```
IHttpConversation setTextBasedResponseDetector(ITextBasedResponseDetector detector)
```
    Sets the text-based response detector for this conversation. The default value is inherited from the HttpConversationManager.
    
    Parameters:
    
    detector - the detector, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - getTextBasedResponseDetector
```
ITextBasedResponseDetector getTextBasedResponseDetector()
```
    Returns the text-based response detector of this conversation.
    
    Returns:
    
    the detector in use, may be null
  - setFlowListener
```
IHttpConversation setFlowListener(IConversationFlowListener listener)
```
    Sets the flow listener. The default value is inherited from the HttpConversationManager.
    
    Parameters:
    
    listener - the listener, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - setRequestListener
```
IHttpConversation setRequestListener(IRequestListener listener)
```
    Sets the request listener which is going to be invoked when the request is about to be sent. If no listener is set then a bare request will be sent without user provided extra headers and without a body.
    
    Parameters:
    
    listener - the listener, can be null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - setRequestListener
```
IHttpConversation setRequestListener(IRequestBodyListener listener)
```
    Convenience method setting a request listener with setRequestListener(IRequestListener) which sends only the body and does not make use of the IRequestHeaderListener.onRequestHeaderSending(ISendEvent) method.
    In 99% of the cases, this method is going to suffice. Its main advantage is that it can be used with Java 8 lambdas.
    
    Parameters:
    
    listener - the listener, can be null
    
    Returns:
    
    this, for method chaining
  - setResponseListener
```
IHttpConversation setResponseListener(IResponseListener listener)
```
    Sets the response listener which is going to be invoked when the response has been received.
    
    Parameters:
    
    listener - the listener, must be non-null
    
    Returns:
    
    this, for method chaining
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation has already started
  - start
```
void start()
```
    Starts the conversation. This submits the task executing the entire conversation flow to the executor configured for the HttpConversationManager which this instance has been created with. Calling this method on an already started conversation has no effect.
    
    Throws:
    
    java.lang.IllegalStateException - in case mandatory parameters are missing, such as request/response listeners, etc..
  - cancel
```
void cancel()
```
    Cancels the conversation after it has been started. Cancelling might occur at any point in the flow, therefore it can cancel either request sending or response processing.
    
    Throws:
    
    java.lang.IllegalStateException - in case the conversation was not yet started
  - isCancelled
```
boolean isCancelled()
```
    Returns whether this converation has been cancelled, either explicitly using cancel() or by one of the request/response filters. Returns false in case the flow hasn't started yet.
    
    Returns:
    
    true if cancelled, false otherwise

Interface IHttpConversation

Method Summary

Method Detail

setName

getName

addHeader

addParameter

setMethod

setContentLength

setChunkSize

setMaximumRestarts

setTimeout

setTextBasedResponseDetector

getTextBasedResponseDetector

setFlowListener

setRequestListener

setRequestListener

setResponseListener

start

cancel

isCancelled