Module io.netty5.common

Package io.netty5.util

Interface Resource<T extends Resource<T>>

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

Buffer, CompositeBuffer, DnsRawRecord, FullHttpMessage<R>, FullHttpRequest, FullHttpResponse, Http2DataFrame, Http2GoAwayFrame, Http2UnknownFrame, HttpContent<R>, LastHttpContent<R>

All Known Implementing Classes:

AdaptableBuffer, BinaryWebSocketFrame, BufferAddressedEnvelope, BufferHolder, BufferRef, BufferStub, CloseWebSocketFrame, ContinuationWebSocketFrame, DatagramPacket, DefaultBufferAddressedEnvelope, DefaultDnsRawRecord, DefaultFullHttpRequest, DefaultFullHttpResponse, DefaultHttp2DataFrame, DefaultHttp2GoAwayFrame, DefaultHttp2UnknownFrame, DefaultHttpContent, DefaultLastHttpContent, EmptyLastHttpContent, HttpServerUpgradeHandler.UpgradeEvent, PemPrivateKey, PemX509Certificate, PingWebSocketFrame, PongWebSocketFrame, ResourceSupport, SegmentedDatagramPacket, TextWebSocketFrame, WebSocketFrame

public interface Resource<T extends Resource<T>>
extends AutoCloseable

A resource that has a life-time, and can be closed. Resources are initially accessible, but closing them makes them inaccessible.

Method Summary

Modifier and Type	Method	Description
void	close()	Close the resource, making it inaccessible.
static void	dispose(Object obj)	Attempt to dispose of whatever the given object is.
boolean	isAccessible()	Check if this object is accessible.
static boolean	isAccessible(Object obj, boolean expectedDefault)	Check if an object is accessible.
Send<T>	send()	Send this object instance to another Thread, transferring the ownership to the recipient.
default T	touch(Object hint)	Record the current access location for debugging purposes.
static void	touch(Object obj, Object hint)	Record the current access location for debugging purposes.

Method Detail

send

Send<T> send()

Send this object instance to another Thread, transferring the ownership to the recipient.

The object must be in a state where it can be sent, which includes at least being accessible.

When sent, this instance will immediately become inaccessible, as if by closing it. All attempts at accessing an object that has been sent, even if that object has not yet been received, should cause an exception to be thrown.

Calling close() on an object that has been sent will have no effect, so this method is safe to call within a try-with-resources statement.

close

void close()

Close the resource, making it inaccessible.

Note, this method is not thread-safe unless otherwise specified.

Specified by:

close in interface AutoCloseable

Throws:

IllegalStateException - If this Resource has already been closed.

isAccessible

boolean isAccessible()

Check if this object is accessible.

Returns:

true if this object is still valid and can be accessed, otherwise false if, for instance, this object has been dropped/deallocated, or been sent elsewhere.

touch

default T touch(Object hint)

Record the current access location for debugging purposes. This information may be included if the resource throws a life-cycle related exception, or if it leaks. If this resource has already been closed, then this method has no effect.

Parameters:

hint - An optional hint about this access and its context. May be null.

Returns:

This resource instance.

dispose

static void dispose(Object obj)

Attempt to dispose of whatever the given object is.

If the object is AutoCloseable, such as anything that implements Resource, then it will be closed. If the object is ReferenceCounted, then it will be released once.

Any exceptions caused by this will be left to bubble up, and checked exceptions will be wrapped in a RuntimeException.

Parameters:

obj - The object to dispose of.

isAccessible

static boolean isAccessible(Object obj,
                            boolean expectedDefault)

Check if an object is accessible. This returns true if the object is a resource that is accessible, or if the object is reference counted and has a positive reference count.

If the object is neither of these types, then the expected default value is returned.

Parameters:

obj - The object to check.

expectedDefault - The value to return if the object is neither a resource, nor reference counted.

Returns:

If the object is accessible.

touch

static void touch(Object obj,
                  Object hint)

Record the current access location for debugging purposes. This information may be included if the resource throws a life-cycle related exception, or if it leaks. If this resource has already been closed, then this method has no effect.

If the given object is not a resource, or not reference counted, then this method has no effect.

Parameters:

obj - The object to annotate.

hint - An optional hint about this access and its context. May be null.