OpenJDK 27 · jdk.internal.net.http.http3.frames.FramesDecoder

API Note

When the frame decoder returns a partial frame, the same frame will be returned until its payload has been fully read. The caller is supposed to call readPayloadBytes() until poll() returns a different frame. At this point there will be no remaining payload bytes to read for the previous frame.
The sequence of calls:

framesDecoder.submit(buffer);
while ((frame = framesDecoder.poll()) != null) {
    if (frame instanceof PartialFrame partial) {
        var nextPayloadBytes = framesDecoder.readPayloadBytes();
        if (nextPayloadBytes == null || nextPayloadBytes.isEmpty()) {
             // no more data is available at this moment
             break;
        }
        // nextPayloadBytes are the next bytes for the payload
        // of the partial frame
        deliverBytes(partial, nextPayloadBytes);
    } else ...
        // got a full frame...
}

makes it possible to incrementally deliver payload bytes for a frame - since poll() will always return the same partial frame until all its payload has been read.

Field Summary

Modifier and Type	Field and Description
private final Supplier<String>	dbgTag
private final Logger	debug
pack-priv boolean	eof
private final BuffersReader.ListBuffersReader	framesReader
private final LongPredicate	isAllowed
private final ReentrantLock	lock
pack-priv PartialFrame	partialFrame

Constructor Summary

Access	Constructor and Description
public	FramesDecoder(String a debug tag for logging dbgTag) A new `FramesDecoder` that accepts all frames.
public	FramesDecoder(String a debug tag for logging dbgTag, LongPredicate isAllowed) A new `FramesDecoder` that accepts only frames authorized by the given `isAllowed` predicate.
public	FramesDecoder(Supplier<String> a debug tag for logging dbgTag, LongPredicate isAllowed) A new `FramesDecoder` that accepts only frames authorized by the given `isAllowed` predicate.

Method Summary

Modifier and Type	Method and Description
private static boolean	allAllowed(long frameType)
public boolean	Returns: true if all buffers have been read clean() Returns true if all buffers have been read.
public void	clear() Clears any unconsumed buffers.
pack-priv String	dbgTag()
public boolean	Returns: true if EOF has been reached and all buffers have been read eof() Returns true if EOF has been reached and all buffers have been read.
protected boolean	Returns: true if the frame is allowed isAllowed(long the frame type frameType) Can be overridden by subclasses to avoid parsing a frame fully if the frame is not allowed on this stream, or according to the stream state.
public static boolean	Returns: whether a frame of this type is allowed on a control stream. isAllowedOnClientControlStream(long a frame type frameType) A predicate that returns true for all frames types allowed on the client->server control stream.
public static boolean	Returns: whether a frame of this type is allowed on a control stream. isAllowedOnControlStream(long a frame type frameType) A predicate that returns true for all frames types allowed on the server->client control stream.
public static boolean	Returns: whether a frame of this type is allowed on a request/response stream. isAllowedOnPromiseStream(long a frame type frameType) A predicate that returns true for all frames types allowed on a push promise stream.
public static boolean	Returns: whether a frame of this type is allowed on a request/response stream. isAllowedOnRequestStream(long a frame type frameType) A predicate that returns true for all frames types allowed on a request/response stream.
public Http3Frame	Returns: an `Http3Frame`, possibly partial, or `null` if not enough bytes have been receive to decode (at least partially) a frame poll() Returns an `Http3Frame`, possibly partial, or `null` if not enough bytes have been receive to decode (at least partially) a frame.
public List<ByteBuffer>	Returns: the next payload bytes for the current partial frame, or `null` if no partial frame readPayloadBytes() Returns the next payload bytes for the current partial frame, or `null` if no partial frame.
public void	submit(ByteBuffer a new buffer from the stream buffer) Submit a new buffer to this frames decoder

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

dbgTag	back to summary
private final Supplier<String> dbgTag

debug	back to summary
private final Logger debug

eof	back to summary
pack-priv boolean eof

framesReader	back to summary
private final BuffersReader.ListBuffersReader framesReader

isAllowed	back to summary
private final LongPredicate isAllowed

lock	back to summary
private final ReentrantLock lock

partialFrame	back to summary
pack-priv PartialFrame partialFrame

Constructor Detail

FramesDecoder back to summary

FramesDecoder	back to summary
public FramesDecoder(String dbgTag) A new `FramesDecoder` that accepts all frames. Parameters dbgTag:String a debug tag for logging

public FramesDecoder(String dbgTag)

A new FramesDecoder that accepts all frames.

Parameters

dbgTag:String: a debug tag for logging

FramesDecoder back to summary

FramesDecoder	back to summary
public FramesDecoder(String dbgTag, LongPredicate isAllowed) A new `FramesDecoder` that accepts only frames authorized by the given `isAllowed` predicate. If a frame is not allowed, a `MalformedFrame` is returned. Parameters dbgTag:String a debug tag for logging

public FramesDecoder(String dbgTag, LongPredicate isAllowed)

A new FramesDecoder that accepts only frames authorized by the given isAllowed predicate. If a frame is not allowed, a MalformedFrame is returned.

Parameters

dbgTag:String: a debug tag for logging

FramesDecoder back to summary

FramesDecoder	back to summary
public FramesDecoder(Supplier<String> dbgTag, LongPredicate isAllowed) A new `FramesDecoder` that accepts only frames authorized by the given `isAllowed` predicate. If a frame is not allowed, a `MalformedFrame` is returned. Parameters dbgTag:Supplier<String> a debug tag for logging

public FramesDecoder(Supplier<String> dbgTag, LongPredicate isAllowed)

A new FramesDecoder that accepts only frames authorized by the given isAllowed predicate. If a frame is not allowed, a MalformedFrame is returned.

Parameters

dbgTag:Supplier<String>: a debug tag for logging

Method Detail

allAllowed	back to summary
private static boolean allAllowed(long frameType)

clean	back to summary
public boolean clean() Returns true if all buffers have been read. Returns:boolean true if all buffers have been read

clean

back to summary

public boolean clean()

Returns true if all buffers have been read.

Returns:boolean: true if all buffers have been read

clear	back to summary
public void clear() Clears any unconsumed buffers.

dbgTag	back to summary
pack-priv String dbgTag()

eof	back to summary
public boolean eof() Returns true if EOF has been reached and all buffers have been read. Returns:boolean true if EOF has been reached and all buffers have been read

eof

back to summary

public boolean eof()

Returns true if EOF has been reached and all buffers have been read.

Returns:boolean: true if EOF has been reached and all buffers have been read

isAllowed	back to summary
protected boolean isAllowed(long frameType) Can be overridden by subclasses to avoid parsing a frame fully if the frame is not allowed on this stream, or according to the stream state. Implementation Specification This method delegates to the predicate given at construction time. If no predicate was given this method returns true. Parameters frameType:long the frame type Returns:boolean true if the frame is allowed

isAllowed

back to summary

protected boolean isAllowed(long frameType)

Can be overridden by subclasses to avoid parsing a frame fully if the frame is not allowed on this stream, or according to the stream state.

Implementation Specification

This method delegates to the predicate given at construction time. If no predicate was given this method returns true.

Parameters

frameType:long: the frame type

Returns:boolean

true if the frame is allowed

isAllowedOnClientControlStream	back to summary
public static boolean isAllowedOnClientControlStream(long frameType) A predicate that returns true for all frames types allowed on the client->server control stream. Parameters frameType:long a frame type Returns:boolean whether a frame of this type is allowed on a control stream.

isAllowedOnClientControlStream

back to summary

public static boolean isAllowedOnClientControlStream(long frameType)

A predicate that returns true for all frames types allowed on the client->server control stream.

Parameters

frameType:long: a frame type

Returns:boolean

whether a frame of this type is allowed on a control stream.

isAllowedOnControlStream	back to summary
public static boolean isAllowedOnControlStream(long frameType) A predicate that returns true for all frames types allowed on the server->client control stream. Parameters frameType:long a frame type Returns:boolean whether a frame of this type is allowed on a control stream.

isAllowedOnControlStream

back to summary

public static boolean isAllowedOnControlStream(long frameType)

A predicate that returns true for all frames types allowed on the server->client control stream.

Parameters

frameType:long: a frame type

Returns:boolean

whether a frame of this type is allowed on a control stream.

isAllowedOnPromiseStream	back to summary
public static boolean isAllowedOnPromiseStream(long frameType) A predicate that returns true for all frames types allowed on a push promise stream. Parameters frameType:long a frame type Returns:boolean whether a frame of this type is allowed on a request/response stream.

isAllowedOnPromiseStream

back to summary

public static boolean isAllowedOnPromiseStream(long frameType)

A predicate that returns true for all frames types allowed on a push promise stream.

Parameters

frameType:long: a frame type

Returns:boolean

whether a frame of this type is allowed on a request/response stream.

isAllowedOnRequestStream	back to summary
public static boolean isAllowedOnRequestStream(long frameType) A predicate that returns true for all frames types allowed on a request/response stream. Parameters frameType:long a frame type Returns:boolean whether a frame of this type is allowed on a request/response stream.

isAllowedOnRequestStream

back to summary

public static boolean isAllowedOnRequestStream(long frameType)

A predicate that returns true for all frames types allowed on a request/response stream.

Parameters

frameType:long: a frame type

Returns:boolean

whether a frame of this type is allowed on a request/response stream.

poll back to summary

poll	back to summary
public Http3Frame poll() Returns an `Http3Frame`, possibly partial, or `null` if not enough bytes have been receive to decode (at least partially) a frame. If a frame is illegal or not allowed, a `MalformedFrame` is returned. The caller is supposed to clear all data and proceed to close the connection in that case. Returns:Http3Frame an `Http3Frame`, possibly partial, or `null` if not enough bytes have been receive to decode (at least partially) a frame

public Http3Frame poll()

Returns an Http3Frame, possibly partial, or null if not enough bytes have been receive to decode (at least partially) a frame. If a frame is illegal or not allowed, a MalformedFrame is returned. The caller is supposed to clear all data and proceed to close the connection in that case.

Returns:Http3Frame: an Http3Frame, possibly partial, or null if not enough bytes have been receive to decode (at least partially) a frame

readPayloadBytes back to summary

readPayloadBytes	back to summary
public List<ByteBuffer> readPayloadBytes() Returns the next payload bytes for the current partial frame, or `null` if no partial frame. If EOF has been reached (`EOF` was submitted, and all buffers have been read, the returned list will contain `EOF` Returns:List<ByteBuffer> the next payload bytes for the current partial frame, or `null` if no partial frame

public List<ByteBuffer> readPayloadBytes()

Returns the next payload bytes for the current partial frame, or null if no partial frame. If EOF has been reached (EOF was submitted, and all buffers have been read, the returned list will contain EOF

Returns:List<ByteBuffer>: the next payload bytes for the current partial frame, or null if no partial frame

submit	back to summary
public void submit(ByteBuffer buffer) Submit a new buffer to this frames decoder Parameters buffer:ByteBuffer a new buffer from the stream

submit

back to summary

public void submit(ByteBuffer buffer)

Submit a new buffer to this frames decoder

Parameters

buffer:ByteBuffer: a new buffer from the stream

public Class FramesDecoder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail