Top Description Inners Fields Constructors Methods
org.eclipse.jetty.client.transport

public abstract Class HttpReceiver

extends Object
Class Inheritance
Known Direct Subclasses
org.eclipse.jetty.client.transport.internal.HttpReceiverOverHTTP
Imports
java.net.URI, java.util.List, java.util.concurrent.atomic.AtomicReference, org.eclipse.jetty.client.ContentDecoder, .HttpClient, .ProtocolHandler, .Response, .Result, org.eclipse.jetty.http.HttpField, .HttpFields, .HttpHeader, .HttpMethod, .HttpStatus, .QuotedCSV, org.eclipse.jetty.io.Content, .RetainableByteBuffer, org.eclipse.jetty.io.content.ContentSourceTransformer, org.eclipse.jetty.util.ExceptionUtil, .Promise, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.thread.AutoLock, .SerializedInvoker, org.slf4j.Logger, .LoggerFactory

HttpReceiver provides the abstract code to implement the various steps of the receive of HTTP responses.

HttpReceiver maintains a state machine that is updated when the steps of receiving a response are executed.

Subclasses must handle the transport-specific details, for example how to read from the raw socket and how to parse the bytes read from the socket. Then they have to call the methods defined in this class in the following order:

  1. responseBegin(HttpExchange), when the HTTP response data containing the HTTP status code is available
  2. responseHeader(HttpExchange, HttpField), when an HTTP field is available
  3. responseHeaders(HttpExchange), when all HTTP headers are available
  4. responseSuccess(HttpExchange, Runnable), when the response is successful
At any time, subclasses may invoke responseFailure(Throwable, Promise) to indicate that the response has failed (for example, because of I/O exceptions). At any time, user threads may abort the response which will cause responseFailure(Throwable, Promise) to be invoked.

The state machine maintained by this class ensures that the response steps are not executed by an I/O thread if the response has already been failed.

See Also
HttpSender

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
HttpReceiver.ContentSource

This Content.Source implementation guarantees that all read(boolean) calls happening from a demand(Runnable) callback must be serialized.

private static class
private static interface
private static enum
HttpReceiver.ResponseState

The request states HttpReceiver goes through when receiving a response.

Field Summary

Modifier and TypeField and Description
private final HttpChannel
private HttpReceiver.NotifiableContentSource
private Throwable
private final SerializedInvoker
private static final Logger
private HttpReceiver.ResponseState

Constructor Summary

AccessConstructor and Description
protected

Method Summary

Modifier and TypeMethod and Description
public void
abort(HttpExchange exchange, Throwable failure, Promise<Boolean> promise)

private void
protected void
dispose()

Disposes the state of this HttpReceiver.

protected abstract void
failAndClose(Throwable
the failure.
failure
)

Fails the receiver and closes the underlying stream.

protected HttpChannel
protected HttpDestination
protected HttpExchange
protected boolean
public boolean
protected abstract void
onInterim()

Prepare for the next step after an interim response was read.

protected abstract Content.Chunk

Returns:

the chunk of data that was read, or null if nothing was read.
read
(boolean
true to register for fill interest when no data was read.
fillInterestIfNeeded
)

Reads a chunk of data.

protected void
reset()

Resets the state of this HttpReceiver.

protected void
responseBegin(HttpExchange
the HTTP exchange
exchange
)

Method to be invoked when the response status code is available.

protected void
responseContentAvailable()

Method to be invoked when response content is available to be read.

protected void
responseFailure(Throwable
the response failure
failure
,
Promise<Boolean> promise)

Method to be invoked when the response is failed.

protected void
responseHeader(HttpExchange
the HTTP exchange
exchange
,
HttpField
the response HTTP field
field
)

Method to be invoked when a response HTTP header is available.

protected void
responseHeaders(HttpExchange
the HTTP exchange
exchange
)

Method to be invoked after all response HTTP headers are available.

protected void
responseSuccess(HttpExchange
the HTTP exchange
exchange
,
Runnable
an optional task to invoke afterwards
afterSuccessTask
)

Method to be invoked when the response is successful.

protected void
private void
private void
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

channelback to summary
private final HttpChannel channel
contentSourceback to summary
private HttpReceiver.NotifiableContentSource contentSource
failureback to summary
private Throwable failure
invokerback to summary
private final SerializedInvoker invoker
LOGback to summary
private static final Logger LOG
responseStateback to summary
private HttpReceiver.ResponseState responseState

Constructor Detail

HttpReceiverback to summary
protected HttpReceiver(HttpChannel channel)

Method Detail

abortback to summary
public void abort(HttpExchange exchange, Throwable failure, Promise<Boolean> promise)
cleanupback to summary
private void cleanup()
disposeback to summary
protected void dispose()

Disposes the state of this HttpReceiver.

Subclasses should override (but remember to call super) to dispose their own state.

Either this method or reset() is called.

failAndCloseback to summary
protected abstract void failAndClose(Throwable failure)

Fails the receiver and closes the underlying stream.

Parameters
failure:Throwable

the failure.

getHttpChannelback to summary
protected HttpChannel getHttpChannel()
getHttpDestinationback to summary
protected HttpDestination getHttpDestination()
getHttpExchangeback to summary
protected HttpExchange getHttpExchange()
hasContentback to summary
protected boolean hasContent()
isFailedback to summary
public boolean isFailed()
onInterimback to summary
protected abstract void onInterim()

Prepare for the next step after an interim response was read.

readback to summary
protected abstract Content.Chunk read(boolean fillInterestIfNeeded)

Reads a chunk of data.

If no data was read, null is returned and if fillInterestIfNeeded is true then fill interest is registered.

The returned chunk of data may be the last one or an error exactly like Content.Source#read() specifies.

Parameters
fillInterestIfNeeded:boolean

true to register for fill interest when no data was read.

Returns:Content.Chunk

the chunk of data that was read, or null if nothing was read.

resetback to summary
protected void reset()

Resets the state of this HttpReceiver.

Subclasses should override (but remember to call super) to reset their own state.

Either this method or dispose() is called.

responseBeginback to summary
protected void responseBegin(HttpExchange exchange)

Method to be invoked when the response status code is available.

Subclasses must have set the response status code on the Response object of the HttpExchange prior invoking this method.

This method takes case of notifying Response.BeginListeners.

Parameters
exchange:HttpExchange

the HTTP exchange

responseContentAvailableback to summary
protected void responseContentAvailable()

Method to be invoked when response content is available to be read.

This method takes care of ensuring the Content.Source passed to Response.ContentSourceListener#onContentSource(Response, Content.Source) calls the demand callback.

responseFailureback to summary
protected void responseFailure(Throwable failure, Promise<Boolean> promise)

Method to be invoked when the response is failed.

This method takes care of notifying Response.FailureListeners.

Parameters
failure:Throwable

the response failure

responseHeaderback to summary
protected void responseHeader(HttpExchange exchange, HttpField field)

Method to be invoked when a response HTTP header is available.

Subclasses must not have added the header to the Response object of the HttpExchange prior invoking this method.

This method takes case of notifying Response.HeaderListeners and storing cookies.

Parameters
exchange:HttpExchange

the HTTP exchange

field:HttpField

the response HTTP field

responseHeadersback to summary
protected void responseHeaders(HttpExchange exchange)

Method to be invoked after all response HTTP headers are available.

This method takes care of notifying Response.HeadersListeners.

Parameters
exchange:HttpExchange

the HTTP exchange

responseSuccessback to summary
protected void responseSuccess(HttpExchange exchange, Runnable afterSuccessTask)

Method to be invoked when the response is successful.

This method takes care of notifying Response.SuccessListeners and possibly Response.CompleteListeners (if the exchange is completed).

Parameters
exchange:HttpExchange

the HTTP exchange

afterSuccessTask:Runnable

an optional task to invoke afterwards

storeCookieback to summary
protected void storeCookie(URI uri, HttpField field)
terminateResponseback to summary
private void terminateResponse(HttpExchange exchange)
terminateResponseback to summary
private void terminateResponse(HttpExchange exchange, Result result)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
org.eclipse.jetty.client.transport back to summary

private Class HttpReceiver.ContentSource

extends Object
implements NotifiableContentSource
Class Inheritance
  • java.lang.Object
  • org.eclipse.jetty.client.transport.HttpReceiver.ContentSource
All Implemented Interfaces
org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.io.Content.Source

This Content.Source implementation guarantees that all read(boolean) calls happening from a demand(Runnable) callback must be serialized.

Field Summary

Modifier and TypeField and Description
private Content.Chunk
private final AtomicReference<Runnable>
private final AutoLock
private static final Logger
private final Runnable

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
private Content.Chunk
public void
demand(Runnable
the demand callback to invoke where there is a content chunk available
demandCallback
)

Implements org.eclipse.jetty.io.Content.Source.demand.

Demands to invoke the given demand callback parameter when a chunk of content is available.

public boolean
public void
fail(Throwable
the cause of the failure
failure
)

Implements org.eclipse.jetty.io.Content.Source.fail.

Fails this content source with a last failure chunk, failing and discarding accumulated content chunks that were not yet read.

private void
invokeDemandCallback(boolean invoke)

public void
private void
public Content.Chunk
read()

Implements org.eclipse.jetty.io.Content.Source.read.

Reads a chunk of content.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

currentChunkback to summary
private Content.Chunk currentChunk
demandCallbackRefback to summary
private final AtomicReference<Runnable> demandCallbackRef
lockback to summary
private final AutoLock lock
LOGback to summary
private static final Logger LOG
processDemandback to summary
private final Runnable processDemand

Constructor Detail

ContentSourceback to summary
private ContentSource()

Method Detail

chunkback to summary
private Content.Chunk chunk()
demandback to summary
public void demand(Runnable demandCallback)

Implements org.eclipse.jetty.io.Content.Source.demand.

Doc from org.eclipse.jetty.io.Content.Source.demand.

Demands to invoke the given demand callback parameter when a chunk of content is available.

See how to use this method idiomatically.

Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Runnable callback and a call to this method. Invocations of the passed Runnable are serialized and a callback for demand call is not invoked until any previous demand callback has returned. Thus the Runnable should not block waiting for a callback of a future demand call.

The demand callback may be invoked spuriously: a subsequent call to read() may return null.

Calling this method establishes a pending demand, which is fulfilled when the demand callback is invoked.

Calling this method when there is already a pending demand results in an IllegalStateException to be thrown.

If the invocation of the demand callback throws an exception, then fail(Throwable) is called.

Parameters
demandCallback:Runnable

the demand callback to invoke where there is a content chunk available

Annotations
@Override
errorback to summary
public boolean error(Throwable failure)

Implements org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource.error.

Annotations
@Override
failback to summary
public void fail(Throwable failure)

Implements org.eclipse.jetty.io.Content.Source.fail.

Doc from org.eclipse.jetty.io.Content.Source.fail.

Fails this content source with a last failure chunk, failing and discarding accumulated content chunks that were not yet read.

The failure may be notified to the content reader at a later time, when the content reader reads a content chunk, via a Chunk instance with a non null Chunk#getFailure().

If read() has returned a last chunk, this is a no operation.

Typical failure: the content being aborted by user code, or idle timeouts.

If this method has already been called, then it is a no operation.

Parameters
failure:Throwable

the cause of the failure

Annotations
@Override
invokeDemandCallbackback to summary
private void invokeDemandCallback(boolean invoke)
onDataAvailableback to summary
public void onDataAvailable()

Implements org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource.onDataAvailable.

Annotations
@Override
processDemandback to summary
private void processDemand()
readback to summary
public Content.Chunk read()

Implements org.eclipse.jetty.io.Content.Source.read.

Doc from org.eclipse.jetty.io.Content.Source.read.

Reads a chunk of content.

See how to use this method idiomatically.

The returned chunk could be:

  • null, to signal that there isn't a chunk of content available
  • an Chunk instance with non null Chunk#getFailure(), to signal that there was a failure trying to produce a chunk of content, or that the content production has been failed externally
  • a Chunk instance, containing the chunk of content.

Once a read returns an Chunk instance with non-null Chunk#getFailure() then if the failure is last further reads will continue to return the same failure chunk instance, otherwise further read() operations may return different non-failure chunks.

Once a read returns a last chunk, further reads will continue to return a last chunk (although the instance may be different).

The content reader code must ultimately arrange for a call to Chunk#release() on the returned Chunk.

Additionally, prior to the ultimate call to Chunk#release(), the reader code may make additional calls to Chunk#retain(), that must ultimately be matched by a correspondent number of calls to Chunk#release().

Concurrent reads from different threads are not recommended, as they are inherently in a race condition.

Reads performed outside the invocation context of a demand callback are allowed. However, reads performed with a pending demand are inherently in a race condition (the thread that reads with the thread that invokes the demand callback).

Returns:Content.Chunk

a chunk of content, possibly a failure instance, or null

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
org.eclipse.jetty.client.transport back to summary

private Class HttpReceiver.DecodingContentSource

extends ContentSourceTransformer
implements NotifiableContentSource
Class Inheritance
All Implemented Interfaces
org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.io.Content.Source

Field Summary

Modifier and TypeField and Description
private volatile Content.Chunk
private final ContentDecoder
private final Response
private static final Logger

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public void
public boolean
protected HttpReceiver.NotifiableContentSource
public void
protected Content.Chunk
transform(Content.Chunk
a chunk read from the wrapped Content.Source
inputChunk
)

Implements abstract org.eclipse.jetty.io.content.ContentSourceTransformer.transform.

Transforms the input chunk parameter into an output chunk.

Inherited from org.eclipse.jetty.io.content.ContentSourceTransformer:
demandfailread

Field Detail

_chunkback to summary
private volatile Content.Chunk _chunk
_decoderback to summary
private final ContentDecoder _decoder
_responseback to summary
private final Response _response
LOGback to summary
private static final Logger LOG

Constructor Detail

DecodingContentSourceback to summary
private DecodingContentSource(HttpReceiver.NotifiableContentSource rawSource, SerializedInvoker invoker, ContentDecoder decoder, Response response)

Method Detail

destroyback to summary
public void destroy()

Overrides default org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource.destroy.

Annotations
@Override
errorback to summary
public boolean error(Throwable failure)

Implements org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource.error.

Annotations
@Override
getContentSourceback to summary
protected HttpReceiver.NotifiableContentSource getContentSource()

Overrides org.eclipse.jetty.io.content.ContentSourceTransformer.getContentSource.

Annotations
@Override
onDataAvailableback to summary
public void onDataAvailable()

Implements org.eclipse.jetty.client.transport.HttpReceiver.NotifiableContentSource.onDataAvailable.

Annotations
@Override
transformback to summary
protected Content.Chunk transform(Content.Chunk inputChunk)

Implements abstract org.eclipse.jetty.io.content.ContentSourceTransformer.transform.

Doc from org.eclipse.jetty.io.content.ContentSourceTransformer.transform.

Transforms the input chunk parameter into an output chunk.

When this method produces a non-null, non-last chunk, it is subsequently invoked with a null input chunk to try to produce more output chunks from the previous input chunk. For example, a single compressed input chunk may be transformed into multiple uncompressed output chunks.

The input chunk is released as soon as this method returns, so implementations that must hold onto the input chunk must arrange to call Content.Chunk#retain() and its correspondent Content.Chunk#release().

Implementations should return an Content.Chunk with non-null Content.Chunk#getFailure() in case of transformation errors.

Exceptions thrown by this method are equivalent to returning an error chunk.

Implementations of this method may return:

  • null, if more input chunks are necessary to produce an output chunk
  • the inputChunk itself, typically in case of non-null Content.Chunk#getFailure(), or when no transformation is required
  • a new Content.Chunk derived from inputChunk.
Parameters
inputChunk:Content.Chunk

a chunk read from the wrapped Content.Source

Returns:Content.Chunk

a transformed chunk or null

Annotations
@Override
org.eclipse.jetty.client.transport back to summary

private Interface HttpReceiver.NotifiableContentSource

extends Source, Destroyable
Known Direct Implementers
org.eclipse.jetty.client.transport.HttpReceiver.DecodingContentSource, org.eclipse.jetty.client.transport.HttpReceiver.ContentSource

Method Summary

Modifier and TypeMethod and Description
public default void
public boolean
error(Throwable failure)

public void
Inherited from org.eclipse.jetty.io.Content.Source:
asByteArrayAsyncasByteBufferasByteBufferasByteBufferAsyncasByteBufferAsyncasInputStreamasPublisherasRetainableByteBufferasStringasStringasStringasStringAsyncconsumeAllconsumeAlldemandfailfailgetLengthreadrewind

Method Detail

destroyback to summary
public default void destroy()

Implements org.eclipse.jetty.util.component.Destroyable.destroy.

Annotations
@Override
errorback to summary
public boolean error(Throwable failure)
onDataAvailableback to summary
public void onDataAvailable()
org.eclipse.jetty.client.transport back to summary

private final Enum HttpReceiver.ResponseState

extends Enum<HttpReceiver.ResponseState>
Class Inheritance

The request states HttpReceiver goes through when receiving a response.

Field Summary

Modifier and TypeField and Description
public static final HttpReceiver.ResponseState
BEGIN

The response status code has been received

public static final HttpReceiver.ResponseState
CONTENT

The response content is being received

public static final HttpReceiver.ResponseState
FAILURE

The response is failed

public static final HttpReceiver.ResponseState
HEADER

The response headers are being received

public static final HttpReceiver.ResponseState
HEADERS

All the response headers have been received

public static final HttpReceiver.ResponseState
IDLE

The response is not yet received, the initial state

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static HttpReceiver.ResponseState
public static HttpReceiver.ResponseState[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

BEGINback to summary
public static final HttpReceiver.ResponseState BEGIN

The response status code has been received

CONTENTback to summary
public static final HttpReceiver.ResponseState CONTENT

The response content is being received

FAILUREback to summary
public static final HttpReceiver.ResponseState FAILURE

The response is failed

HEADERback to summary
public static final HttpReceiver.ResponseState HEADER

The response headers are being received

HEADERSback to summary
public static final HttpReceiver.ResponseState HEADERS

All the response headers have been received

IDLEback to summary
public static final HttpReceiver.ResponseState IDLE

The response is not yet received, the initial state

Constructor Detail

ResponseStateback to summary
private ResponseState()

Method Detail

valueOfback to summary
public static HttpReceiver.ResponseState valueOf(String name)
valuesback to summary
public static HttpReceiver.ResponseState[] values()