com.facebook.stetho.inspector.network

Interface NetworkEventReporter

All Known Implementing Classes:

NetworkEventReporterImpl

public interface NetworkEventReporter

Interface that callers must invoke in order to supply data to the Network tab in the WebKit Inspector.

 requestWillBeSent +---> responseHeadersReceived +---> interpretResponseStream
                   |           |                 |
                   |           `---> dataSent    |
                   |                             |
                   `-----------------------------`--------> httpExchangeFailed
 

Note that interpretResponseStream(java.lang.String, java.lang.String, java.lang.String, java.io.InputStream, com.facebook.stetho.inspector.network.ResponseHandler) combined with DefaultResponseHandler will automatically invoke dataReceived(java.lang.String, int, int), responseReadFailed(java.lang.String, java.lang.String) and responseReadFinished(java.lang.String). If you use your own custom ResponseHandler you must be sure to invoke these methods manually.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	NetworkEventReporter.InspectorHeaders
static interface	NetworkEventReporter.InspectorRequest Represents the request that will be sent over HTTP.
static interface	NetworkEventReporter.InspectorResponse

Method Summary

Modifier and Type	Method and Description
void	dataReceived(java.lang.String requestId, int dataLength, int encodedDataLength) Indicates that raw data was received from the network.
void	dataSent(java.lang.String requestId, int dataLength, int encodedDataLength) Indicates that raw data was sent over the network.
void	httpExchangeFailed(java.lang.String requestId, java.lang.String errorText) Indicates that communication with the server has failed.
java.io.InputStream	interpretResponseStream(java.lang.String requestId, java.lang.String contentType, java.lang.String contentEncoding, java.io.InputStream inputStream, ResponseHandler responseHandler) Intercept the stream as given by the underlying HTTP library that contains the body of the response.
boolean	isEnabled() Returns true if there is at least one peer listening for network events; false otherwise.
void	requestWillBeSent(NetworkEventReporter.InspectorRequest request) Indicates that a request is about to be sent, but has not yet been delivered over the wire.
void	responseHeadersReceived(NetworkEventReporter.InspectorResponse response) Indicates that a response message was just received from the network, but the body has not yet been read.
void	responseReadFailed(java.lang.String requestId, java.lang.String errorText) Indicates that there was a failure while reading from response stream.
void	responseReadFinished(java.lang.String requestId) Indicates that the response stream has been fully exhausted and the request is now complete.

Method Detail

isEnabled

boolean isEnabled()

Returns true if there is at least one peer listening for network events; false otherwise. This value is provided as an optimization to avoid expensive work when the WebKit Inspector is not being used. It is otherwise safe to invoke methods defined in this interface when the value is false.

requestWillBeSent

void requestWillBeSent(NetworkEventReporter.InspectorRequest request)

Indicates that a request is about to be sent, but has not yet been delivered over the wire.

Parameters:

request - Request descriptor.

responseHeadersReceived

void responseHeadersReceived(NetworkEventReporter.InspectorResponse response)

Indicates that a response message was just received from the network, but the body has not yet been read.

Parameters:

response - Response descriptor.

httpExchangeFailed

void httpExchangeFailed(java.lang.String requestId,
                        java.lang.String errorText)

Indicates that communication with the server has failed. You are expected to call this for any exception before you call interpretResponseStream(java.lang.String, java.lang.String, java.lang.String, java.io.InputStream, com.facebook.stetho.inspector.network.ResponseHandler). After interpretResponseStream(java.lang.String, java.lang.String, java.lang.String, java.io.InputStream, com.facebook.stetho.inspector.network.ResponseHandler) is called we will reporting any IOException during reading from the InputStream.

Parameters:

requestId - Unique identifier for the request as per NetworkEventReporter.InspectorRequest.id()

errorText - Text to report for the error; using Throwable.toString() is recommended.

interpretResponseStream

java.io.InputStream interpretResponseStream(java.lang.String requestId,
                                            java.lang.String contentType,
                                            java.lang.String contentEncoding,
                                            java.io.InputStream inputStream,
                                            ResponseHandler responseHandler)

Intercept the stream as given by the underlying HTTP library that contains the body of the response. In order to have the response show up in inspector (and to have the request be completed successfully) you need to call this AND read until exhaustion/EOF of the returned stream.

We will internally signal a failure if there is an IOException received while reading from the stream.

Do not invoke httpExchangeFailed(String, String) after calling this method.

Parameters:

requestId - Unique identifier for the request as per NetworkEventReporter.InspectorRequest.id()

contentType - The Content-Type header value that was specified in NetworkEventReporter.InspectorResponse. This header is used to determine the appropriate storage format for the body. For instance, image/* is necessary to cause images to appear in the Inspector UI.

contentEncoding - The Content-Encoding header value that was specified in NetworkEventReporter.InspectorResponse. This header is used to determine what type of decompression is to be applied when delivering the raw response stream to the debugging interface. If null, no decompression will be used.

inputStream - Response stream if applicable ("HEAD" for instance does not have a body). null otherwise.

responseHandler - Callback to forward stream events back to the relevant event reporter methods. Recommend using DefaultResponseHandler for most callers.

Returns:

InputStream that has been intercepted if WebkitInspector is active and enabled otherwise it will return inputStream

responseReadFailed

void responseReadFailed(java.lang.String requestId,
                        java.lang.String errorText)

Indicates that there was a failure while reading from response stream. If you use interpretResponseStream(java.lang.String, java.lang.String, java.lang.String, java.io.InputStream, com.facebook.stetho.inspector.network.ResponseHandler) with DefaultResponseHandler (as is recommended), this method will be invoked automatically for you.

Parameters:

requestId - Unique identifier for the request as per NetworkEventReporter.InspectorRequest.id()

errorText - Text to report for the error; using Throwable.toString() is recommended.

responseReadFinished

void responseReadFinished(java.lang.String requestId)

Indicates that the response stream has been fully exhausted and the request is now complete. If you use interpretResponseStream(java.lang.String, java.lang.String, java.lang.String, java.io.InputStream, com.facebook.stetho.inspector.network.ResponseHandler) with DefaultResponseHandler (as is recommended), this method will be invoked automatically for you.

Parameters:

requestId - Unique identifier for the request as per NetworkEventReporter.InspectorRequest.id()

dataSent

void dataSent(java.lang.String requestId,
              int dataLength,
              int encodedDataLength)

Indicates that raw data was sent over the network. It is permissible to invoke this method just once after the full size of the request is known.

Invoking this method is optional and merely provides additional timing metrics and actual payload sizes to the Inspector UI.

Parameters:

requestId - Unique identifier for the request as per NetworkEventReporter.InspectorRequest.id()

dataLength - Uncompressed data segment length

encodedDataLength - Compressed data segment length

dataReceived

void dataReceived(java.lang.String requestId,
                  int dataLength,
                  int encodedDataLength)

Indicates that raw data was received from the network.

See Also:

dataSent(java.lang.String, int, int)