org.microbean.jersey.netty

Class AbstractContainerRequestHandlingResponseWriter<T>

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

org.microbean.jersey.netty.AbstractContainerRequestHandlingResponseWriter<T>

Type Parameters:

T - the type of message that will be written by instances of this class; see createOutputStream(long, ContainerResponse)

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler, ContainerResponseWriter

Direct Known Subclasses:

Http2ContainerRequestHandlingResponseWriter, HttpContainerRequestHandlingResponseWriter

public abstract class AbstractContainerRequestHandlingResponseWriter<T>
extends ChannelInboundHandlerAdapter
implements ContainerResponseWriter

An abstract ChannelInboundHandlerAdapter that is also a ContainerResponseWriter that processes incoming ContainerRequest events, such as those dispatched by an AbstractContainerRequestDecoder, by supplying them to the ApplicationHandler.handle(ContainerRequest) method.

Instances of this class are in charge of properly invoking ApplicationHandler.handle(ContainerRequest), thus adapting Jersey to Netty's constraints and vice versa.

Author:

Laird Nelson

See Also:

channelRead(ChannelHandlerContext, Object), createOutputStream(long, ContainerResponse), ChannelInboundHandlerAdapter, ApplicationHandler.handle(ContainerRequest), ContainerResponseWriter

Nested Class Summary

Nested classes/interfaces inherited from interface org.glassfish.jersey.server.spi.ContainerResponseWriter

ContainerResponseWriter.TimeoutHandler

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

ChannelHandler.Sharable

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractContainerRequestHandlingResponseWriter(ApplicationHandler applicationHandler) Creates a new AbstractContainerRequestHandlingResponseWriter.
protected	AbstractContainerRequestHandlingResponseWriter(ApplicationHandler applicationHandler, int flushThreshold, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator byteBufCreator) Creates a new AbstractContainerRequestHandlingResponseWriter.
protected	AbstractContainerRequestHandlingResponseWriter(Supplier<? extends ApplicationHandler> applicationHandlerSupplier) Creates a new AbstractContainerRequestHandlingResponseWriter.
protected	AbstractContainerRequestHandlingResponseWriter(Supplier<? extends ApplicationHandler> applicationHandlerSupplier, int flushThreshold, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator byteBufCreator) Creates a new AbstractContainerRequestHandlingResponseWriter.

Method Summary

Modifier and Type	Method and Description
void	channelActive(ChannelHandlerContext channelHandlerContext) Overrides ChannelInboundHandlerAdapter.channelActive(ChannelHandlerContext) to ensure that a channel read is performed one way or another.
void	channelRead(ChannelHandlerContext channelHandlerContext, Object message) If the supplied message is a ContainerRequest then this method will install itself as that request's ContainerResponseWriter and will invoke ApplicationHandler.handle(ContainerRequest).
void	channelReadComplete(ChannelHandlerContext channelHandlerContext) Overrides the ChannelInboundHandlerAdapter.channelReadComplete(ChannelHandlerContext) method to call channelHandlerContext.flush() before calling the superclass implementation.
void	commit() Invoked by Jersey when a ContainerRequest has been fully handled successfully.
protected static void	copyHeaders(Map<? extends String,? extends List<String>> headersSource, UnaryOperator<String> keyTransformer, BiConsumer<? super String,? super List<String>> headersTarget) A utility function that copies entries from a source Map by passing each entry to the supplied BiConsumer, transforming the keys beforehand using the supplied UnaryOperator and that is intended in this framework to be used to copy HTTP or HTTP/2 headers to and from the proper places.
protected abstract AbstractChannelOutboundInvokingOutputStream<? extends T>	createOutputStream(long contentLength, ContainerResponse containerResponse) Creates and returns a new AbstractChannelOutboundInvokingOutputStream, or returns null if it is determined that no AbstractChannelOutboundInvokingOutputStream is required given the supplied contentLength parameter value.
boolean	enableResponseBuffering() Returns true when invoked to indicate that buffering of entity content is supported and can be configured to be on or off.
void	failure(Throwable failureCause) Handles any failure case encountered by the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method.
protected AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator	getByteBufCreator() Returns a AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator that may be used to create the AbstractChannelOutboundInvokingOutputStream implementation that must be returned by an implementation of the createOutputStream(long, ContainerResponse) method.
protected ChannelHandlerContext	getChannelHandlerContext() Returns the ChannelHandlerContext in effect, or null if there is no such ChannelHandlerContext.
protected int	getFlushThreshold() Returns the minimum number of bytes that an AbstractChannelOutboundInvokingOutputStream returned by the createOutputStream(long, ContainerResponse) method must write before an automatic flush may take place.
void	setSuspendTimeout(long timeout, TimeUnit timeUnit)
boolean	suspend(long timeout, TimeUnit timeUnit, ContainerResponseWriter.TimeoutHandler timeoutHandler)
protected abstract void	writeFailureMessage(Throwable failureCause) Writes an appropriate message, possibly using the ChannelHandlerContext to do so.
OutputStream	writeResponseStatusAndHeaders(long contentLength, ContainerResponse containerResponse) Writes the status and headers portion of the response present in the supplied ContainerResponse by calling the writeStatusAndHeaders(long, ContainerResponse) method, and, if the supplied contentLength is not 0L and that method returns true indicating that output will be forthcoming, returns the result of invoking createOutputStream(long, ContainerResponse).
protected abstract boolean	writeStatusAndHeaders(long contentLength, ContainerResponse containerResponse) Writes the status and headers portion of the response present in the supplied ContainerResponse and returns true if further output is forthcoming.

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelInactive, channelRegistered, channelUnregistered, channelWritabilityChanged, exceptionCaught, userEventTriggered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, handlerAdded, handlerRemoved, isSharable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.netty.channel.ChannelHandler

handlerAdded, handlerRemoved

Constructor Detail

AbstractContainerRequestHandlingResponseWriter

protected AbstractContainerRequestHandlingResponseWriter(ApplicationHandler applicationHandler)

Creates a new AbstractContainerRequestHandlingResponseWriter.

Parameters:

applicationHandler - an ApplicationHandler representing a Jakarta RESTful Web Services application whose ApplicationHandler.handle(ContainerRequest) method will serve as the bridge between Netty and Jersey; may be null somewhat pathologically but normally is not

See Also:

AbstractContainerRequestHandlingResponseWriter(Supplier, int, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator), ApplicationHandler, ApplicationHandler.handle(ContainerRequest), channelRead(ChannelHandlerContext, Object)

AbstractContainerRequestHandlingResponseWriter

protected AbstractContainerRequestHandlingResponseWriter(ApplicationHandler applicationHandler,
                                                         int flushThreshold,
                                                         AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator byteBufCreator)

Creates a new AbstractContainerRequestHandlingResponseWriter.

Parameters:

applicationHandler - an ApplicationHandler representing a Jakarta RESTful Web Services application whose ApplicationHandler.handle(ContainerRequest) method will serve as the bridge between Netty and Jersey; may be null somewhat pathologically but normally is not

flushThreshold - the minimum number of bytes that an AbstractByteBufBackedChannelOutboundInvokingOutputStream returned by the createOutputStream(long, ContainerResponse) method must write before an automatic flush may take place; if less than 0 0 will be used instead; if Integer#MAX_VALUE then it is suggested that no automatic flushing will occur

byteBufCreator - a AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator that may be used (but does not have to be used) by the implementation of the createOutputStream(long, ContainerResponse) method; may be null

See Also:

AbstractContainerRequestHandlingResponseWriter(Supplier, int, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator), ApplicationHandler, ApplicationHandler.handle(ContainerRequest), channelRead(ChannelHandlerContext, Object), getFlushThreshold(), getByteBufCreator(), createOutputStream(long, ContainerResponse)

AbstractContainerRequestHandlingResponseWriter

protected AbstractContainerRequestHandlingResponseWriter(Supplier<? extends ApplicationHandler> applicationHandlerSupplier)

Creates a new AbstractContainerRequestHandlingResponseWriter.

Parameters:

applicationHandlerSupplier - a Supplier of an ApplicationHandler representing a Jakarta RESTful Web Services application whose ApplicationHandler.handle(ContainerRequest) method will serve as the bridge between Netty and Jersey; may be null somewhat pathologically but normally is not

See Also:

AbstractContainerRequestHandlingResponseWriter(Supplier, int, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator), ApplicationHandler, ApplicationHandler.handle(ContainerRequest), channelRead(ChannelHandlerContext, Object)

AbstractContainerRequestHandlingResponseWriter

protected AbstractContainerRequestHandlingResponseWriter(Supplier<? extends ApplicationHandler> applicationHandlerSupplier,
                                                         int flushThreshold,
                                                         AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator byteBufCreator)

Creates a new AbstractContainerRequestHandlingResponseWriter.

Parameters:

applicationHandlerSupplier - a Supplier of an ApplicationHandler representing a Jakarta RESTful Web Services application whose ApplicationHandler.handle(ContainerRequest) method will serve as the bridge between Netty and Jersey; may be null somewhat pathologically but normally is not

flushThreshold - the minimum number of bytes that an AbstractByteBufBackedChannelOutboundInvokingOutputStream returned by the createOutputStream(long, ContainerResponse) method must write before an automatic flush may take place; if less than 0 0 will be used instead; if Integer#MAX_VALUE then it is suggested that no automatic flushing will occur

byteBufCreator - a AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator that may be used (but does not have to be used) by the implementation of the createOutputStream(long, ContainerResponse) method; may be null

See Also:

ApplicationHandler, ApplicationHandler.handle(ContainerRequest), channelRead(ChannelHandlerContext, Object), getFlushThreshold(), getByteBufCreator(), createOutputStream(long, ContainerResponse)

Method Detail

channelActive

public final void channelActive(ChannelHandlerContext channelHandlerContext)
                         throws Exception

Overrides ChannelInboundHandlerAdapter.channelActive(ChannelHandlerContext) to ensure that a channel read is performed one way or another.

If autoread is active, then the superclass' version of this method is executed with no changes. If autoread is inactive, then a call is made to ChannelHandlerContext.read().

Specified by:

channelActive in interface ChannelInboundHandler

Overrides:

channelActive in class ChannelInboundHandlerAdapter

Parameters:

channelHandlerContext - the ChannelHandlerContext in effect; must not be null

Throws:

NullPointerException - if channelHandlerContext is null

Exception - if an error occurs

See Also:

ChannelConfig.isAutoRead(), Channel.read(), ChannelHandlerContext.read(), channelRead(ChannelHandlerContext, Object)

channelRead

public final void channelRead(ChannelHandlerContext channelHandlerContext,
                              Object message)
                       throws Exception

If the supplied message is a ContainerRequest then this method will install itself as that request's ContainerResponseWriter and will invoke ApplicationHandler.handle(ContainerRequest).

In all other cases this method will simply call ChannelInboundHandlerAdapter.channelRead(ChannelHandlerContext, Object) with the supplied message.

Specified by:

channelRead in interface ChannelInboundHandler

Overrides:

channelRead in class ChannelInboundHandlerAdapter

Parameters:

channelHandlerContext - the ChannelHandlerContext in effect; must not be null

message - the incoming message, or event; may be null

Throws:

NullPointerException - if channelHandlerContext is null, or if the Supplier of ApplicationHandler instances supplied at construction time returns null

Exception - if message is not an instance of ContainerRequest and ChannelInboundHandlerAdapter.channelRead(ChannelHandlerContext, Object) throws an Exception

See Also:

ApplicationHandler.handle(ContainerRequest), ContainerResponseWriter, ContainerRequest.setWriter(ContainerResponseWriter)

channelReadComplete

public final void channelReadComplete(ChannelHandlerContext channelHandlerContext)
                               throws Exception

Overrides the ChannelInboundHandlerAdapter.channelReadComplete(ChannelHandlerContext) method to call channelHandlerContext.flush() before calling the superclass implementation.

Specified by:

channelReadComplete in interface ChannelInboundHandler

Overrides:

channelReadComplete in class ChannelInboundHandlerAdapter

Parameters:

channelHandlerContext - the ChannelHandlerContext in effect; must not be null

Throws:

NullPointerException - if channelHandlerContext is null

Exception - if ChannelInboundHandlerAdapter.channelReadComplete(ChannelHandlerContext) throws an Exception

getChannelHandlerContext

protected final ChannelHandlerContext getChannelHandlerContext()

Returns the ChannelHandlerContext in effect, or null if there is no such ChannelHandlerContext.

This method may return null.

Returns:

the ChannelHandlerContext in effect, or null if there is no such ChannelHandlerContext

enableResponseBuffering

public final boolean enableResponseBuffering()

Returns true when invoked to indicate that buffering of entity content is supported and can be configured to be on or off.

Note that the return value of this method is a default value indicating that the concept of response buffering is enabled. The actual configuration of response buffering is a property of the application. Specifically, an application's response buffering policy can be configured: if the application's configuration sets the jersey.config.contentLength.buffer property to a positive int, then buffering will occur, and if the application's configuration sets the jersey.config.contentLength.buffer property to a negative int, then buffering will not occur. If the application's configuration does nothing in this regard, response buffering will be enabled with a default buffer size of 8192.

(If, instead, this method had been written to return false, then no matter what configuration settings an application might specify in the realm of response buffering settings, response buffering of any kind would never be possible.)

Specified by:

enableResponseBuffering in interface ContainerResponseWriter

Returns:

true when invoked; never false

See Also:

ContainerResponseWriter.enableResponseBuffering(), ServerRuntime.java, ContainerResponse.java, OutboundMessageContext.java

writeResponseStatusAndHeaders

public final OutputStream writeResponseStatusAndHeaders(long contentLength,
                                                        ContainerResponse containerResponse)

Writes the status and headers portion of the response present in the supplied ContainerResponse by calling the writeStatusAndHeaders(long, ContainerResponse) method, and, if the supplied contentLength is not 0L and that method returns true indicating that output will be forthcoming, returns the result of invoking createOutputStream(long, ContainerResponse).

In all other cases, this method returns null.

Specified by:

writeResponseStatusAndHeaders in interface ContainerResponseWriter

Parameters:

contentLength - the content length as determined by the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method; a value less than zero indicates an unknown content length

containerResponse - the ContainerResponse containing status and headers information; must not be null

Returns:

the OutputStream returned by the createOutputStream(long, ContainerResponse) method, or null

Throws:

NullPointerException - if containerResponse is null

See Also:

writeStatusAndHeaders(long, ContainerResponse), createOutputStream(long, ContainerResponse), ApplicationHandler.handle(ContainerRequest)

writeStatusAndHeaders

protected abstract boolean writeStatusAndHeaders(long contentLength,
                                                 ContainerResponse containerResponse)

Writes the status and headers portion of the response present in the supplied ContainerResponse and returns true if further output is forthcoming.

Implementations of this method must not call the writeResponseStatusAndHeaders(long, ContainerResponse) method or an infinite loop may result.

Implementations of this method must not call the createOutputStream(long, ContainerResponse) method or undefined behavior may result.

Parameters:

contentLength - the content length as determined by the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method; a value less than zero indicates an unknown content length

containerResponse - the ContainerResponse containing status and headers information; must not be null

Returns:

true if the createOutputStream(long, ContainerResponse) method should be invoked, i.e. if further output is forthcoming

Throws:

NullPointerException - if containerResponse is null

See Also:

ApplicationHandler.handle(ContainerRequest), createOutputStream(long, ContainerResponse)

createOutputStream

protected abstract AbstractChannelOutboundInvokingOutputStream<? extends T> createOutputStream(long contentLength,
                                                                                               ContainerResponse containerResponse)

Creates and returns a new AbstractChannelOutboundInvokingOutputStream, or returns null if it is determined that no AbstractChannelOutboundInvokingOutputStream is required given the supplied contentLength parameter value.

Implementations of this method may return null.

Parameters:

contentLength - the content length as determined by the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method; a value less than zero indicates an unknown content length; must not be equal to 0L

containerResponse - the ContainerResponse containing status and headers information; must not be null; may be (and often is) ignored by implementations

Returns:

a new AbstractChannelOutboundInvokingOutputStream implementation, or null

Throws:

NullPointerException - if containerResponse is null

IllegalArgumentException - if contentLength is equal to 0L

getFlushThreshold

protected final int getFlushThreshold()

Returns the minimum number of bytes that an AbstractChannelOutboundInvokingOutputStream returned by the createOutputStream(long, ContainerResponse) method must write before an automatic flush may take place.

Note: Implementations of the createOutputStream(long, ContainerResponse) method may choose to ignore the return value of this method. It is supplied for convenience only for use by implementors of the createOutputStream(long, ContainerResponse) method.

Returns:

the minimum number of bytes that an AbstractChannelOutboundInvokingOutputStream returned by the createOutputStream(long, ContainerResponse) method must write before an automatic flush may take place; always 0L or a positive int; if 0 it is suggested that automatic flushing occur after every write; if Integer#MAX_VALUE it is suggested that no automatic flushing should occur

See Also:

createOutputStream(long, ContainerResponse), AbstractContainerRequestHandlingResponseWriter(ApplicationHandler, int, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator), AbstractByteBufBackedChannelOutboundInvokingOutputStream.AbstractByteBufBackedChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean, ByteBufCreator)

getByteBufCreator

protected final AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator getByteBufCreator()

Returns a AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator that may be used to create the AbstractChannelOutboundInvokingOutputStream implementation that must be returned by an implementation of the createOutputStream(long, ContainerResponse) method.

This method may return null.

Note: Implementations of the createOutputStream(long, ContainerResponse) method may choose to ignore the return value of this method. It is supplied for convenience only for use by implementors of the createOutputStream(long, ContainerResponse) method.

Returns:

a AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator, or null

See Also:

createOutputStream(long, ContainerResponse), AbstractContainerRequestHandlingResponseWriter(ApplicationHandler, int, AbstractByteBufBackedChannelOutboundInvokingOutputStream.ByteBufCreator), AbstractByteBufBackedChannelOutboundInvokingOutputStream.AbstractByteBufBackedChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean, ByteBufCreator)

commit

public void commit()

Invoked by Jersey when a ContainerRequest has been fully handled successfully.

Either commit() or failure(Throwable) will be called by Jersey as the logically final operation in the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method, but not both.

This implementation does nothing.

Specified by:

commit in interface ContainerResponseWriter

See Also:

ContainerResponseWriter.commit(), failure(Throwable)

suspend

public final boolean suspend(long timeout,
                             TimeUnit timeUnit,
                             ContainerResponseWriter.TimeoutHandler timeoutHandler)

Specified by:

suspend in interface ContainerResponseWriter

setSuspendTimeout

public final void setSuspendTimeout(long timeout,
                                    TimeUnit timeUnit)

Specified by:

setSuspendTimeout in interface ContainerResponseWriter

failure

public final void failure(Throwable failureCause)

Handles any failure case encountered by the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method.

Either commit() or failure(Throwable) will be called by Jersey as the logically final operation in the logic encapsulated by the ApplicationHandler.handle(ContainerRequest) method, but not both.

This method calls the writeFailureMessage(Throwable) method and takes great care to ensure that any Throwables encountered along the way are properly recorded and suppressed.

This implementation never returns. A ContainerException is always thrown by this method.

Specified by:

failure in interface ContainerResponseWriter

Parameters:

failureCause - the Throwable encountered by the ApplicationHandler.handle(ContainerRequest) method; may be null

Throws:

ContainerException - when this method is invoked; it will have the supplied failureCause as its cause

See Also:

commit(), ContainerResponseWriter.failure(Throwable)

writeFailureMessage

protected abstract void writeFailureMessage(Throwable failureCause)

Writes an appropriate message, possibly using the ChannelHandlerContext to do so.

Implementations of this method must not call the failure(Throwable) method or an infinite loop may result.

Parameters:

failureCause - the Throwable responsible for this method's invocation; may be null in pathological cases

copyHeaders

protected static final void copyHeaders(Map<? extends String,? extends List<String>> headersSource,
                                        UnaryOperator<String> keyTransformer,
                                        BiConsumer<? super String,? super List<String>> headersTarget)

A utility function that copies entries from a source Map by passing each entry to the supplied BiConsumer, transforming the keys beforehand using the supplied UnaryOperator and that is intended in this framework to be used to copy HTTP or HTTP/2 headers to and from the proper places.

Parameters:

headersSource - the source of the headers to copy; may be null in which case no action will be taken

keyTransformer - a UnaryOperator that transforms a header name; if null then the return value of UnaryOperator.identity() will be used instead

headersTarget - where the headers will be copied to; may be null in which case no action will be taken