Package org.omegazero.http.util

Interface HTTPServerStream

All Superinterfaces:

AutoCloseable, Closeable, HTTPMessageStream

All Known Implementing Classes:

AbstractHTTPServerStream

public interface HTTPServerStream
extends HTTPMessageStream

A HTTPServerStream represents a single HTTP request transaction from the perspective of the server, including the incoming HTTPRequest and its associated incoming data, and is used to send a corresponding response.

Since:

1.4.1

See Also:

• HTTPServer.onNewRequest(SpecificThrowingConsumer)

Method Summary

Modifier and Type	Method	Description
default void	endResponse(HTTPMessageTrailers trailers)	Ends the response with optional trailers, if supported.
HTTPServer	getServer()	Returns the HTTPServer that created this HTTPServerStream.
void	onRequestData(Consumer<HTTPRequestData> onRequestData)	Sets a callback that is called when this HTTPServerStream receives data for the request.
void	onRequestEnded(Consumer<HTTPMessageTrailers> onRequestEnded)	Sets a callback that is called when this HTTPServerStream has finished receiving the request and data, including optional trailers.
void	respond(int status, byte[] data, String... headers)	Responds to this HTTPServerStream with a new HTTP response with the given status, data and headers, if no response was already sent.
void	respond(HTTPResponseData response)	Responds to this HTTPServerStream with the given full response, if no response was already sent.
boolean	sendResponseData(byte[] data, boolean lastPacket)	Streams response data after a call to startResponse(HTTPResponse).
void	startResponse(HTTPResponse response)	Starts a response with the given response header.
default HTTPServerStream	startServerPush(HTTPRequest request)	Starts a server push stream with the given push request.

Methods inherited from interface org.omegazero.http.util.HTTPMessageStream

close, close, getRequest, isClosed, onError, onWritable, setReceiveData

Method Details

getServer

HTTPServer getServer()

Returns the HTTPServer that created this HTTPServerStream.

Returns:

The HTTPServer

onRequestData

void onRequestData(Consumer<HTTPRequestData> onRequestData)

Sets a callback that is called when this HTTPServerStream receives data for the request.

If HTTPMessageData.isLastPacket() is true for a HTTPRequestData object passed to the callback, it is followed by a onRequestEnded callback.

Parameters:

onRequestData - The callback

onRequestEnded

void onRequestEnded(Consumer<HTTPMessageTrailers> onRequestEnded)

Sets a callback that is called when this HTTPServerStream has finished receiving the request and data, including optional trailers.

If this callback is called, it ends this HTTPServerStream and no further callbacks will be called.

Parameters:

onRequestEnded - The callback

startServerPush

default HTTPServerStream startServerPush(HTTPRequest request)

Starts a server push stream with the given push request.

This method must be called before startResponse(HTTPResponse). If server push is enabled, but no stream could be created because of limits set by the implementation or peer, null is returned.

The returned new HTTPServerStream is used to send the pushed response the same way a regular response is sent. No callbacks will be called on this HTTPServerStream.

Parameters:

request - The push request

Returns:

The new HTTPServerStream used to send the response, or null if no new stream could be created

Throws:

UnsupportedOperationException - If server push is not supported or not enabled (HTTPServer.isServerPushEnabled() returns false)

startResponse

void startResponse(HTTPResponse response)

Starts a response with the given response header.

Unlike the respond methods, this does not end the response stream, but allows data to be streamed in multiple calls to sendResponseData(byte[], boolean).

This method may be called multiple times, for example to send a 102 Processing response before the actual response.

Parameters:

response - The response header

Throws:

IllegalStateException - If this method is called before the onRequestEnded callback (optional)

sendResponseData

boolean sendResponseData(byte[] data,
 boolean lastPacket)

Streams response data after a call to startResponse(HTTPResponse).

If lastPacket is true, the call closes this HTTPServerStream.

Parameters:

data - The data

lastPacket - true if this is the last piece of data being sent

Returns:

true if the underlying connection is writable, false if the write buffer is full and data will have to be queued

Throws:

IllegalStateException - If this method is called before the onRequestEnded callback (optional)

See Also:

• HTTPMessageStream.onWritable(Runnable)

endResponse

default void endResponse(HTTPMessageTrailers trailers)

Ends the response with optional trailers, if supported. This method implicitly closes this HTTPServerStream.

Parameters:

trailers - If not null, the trailers to send

respond

void respond(HTTPResponseData response)

Responds to this HTTPServerStream with the given full response, if no response was already sent. This method implicitly closes this HTTPServerStream.

See HTTPResponder.respond(HTTPRequest, HTTPResponseData) for additional information.

Parameters:

response - The response

See Also:

• respond(int, byte[], String...)
• startResponse(HTTPResponse)

respond

void respond(int status,
 byte[] data,
 String... headers)

Responds to this HTTPServerStream with a new HTTP response with the given status, data and headers, if no response was already sent. This method implicitly closes this HTTPServerStream.

See HTTPResponder.respond(HTTPRequest, int, byte[], String...) for additional information.

Parameters:

status - The status code of the response

data - The data to send in the response

headers - Headers to send in the response

See Also:

• respond(HTTPResponseData)
• startResponse(HTTPResponse)