Interface FramingHandler

All Known Implementing Classes:

LengthPrefixedFramingHandler

public interface FramingHandler

Strategy interface for message framing and deframing in network protocols.

Message framing is essential for reliable message delivery over stream-based protocols like TCP, which provide a continuous byte stream without inherent message boundaries. This interface defines the contract for framing strategies that encode message boundaries into the byte stream.

Framing Process

Sender:                                    Receiver:
┌──────────────┐                          ┌──────────────┐
│   Message    │                          │   Message    │
│   Payload    │                          │   Payload    │
└──────────────┘                          └──────────────┘
       │                                         ▲
       ▼ frameMessage()                          │ deframeMessage()
┌────┬──────────────┐    Network    ┌────┬──────────────┐
│Hdr │   Payload    │  ─────────▶  │Hdr │   Payload    │
└────┴──────────────┘               └────┴──────────────┘

Usage Example

FramingHandler framing = new LengthPrefixedFramingHandler();

// Frame a message for sending
MemorySegment payload = ...;
MemorySegment frame = allocator.allocate(payload.byteSize() + framing.getHeaderSize());
int frameLength = framing.frameMessage(payload, (int) payload.byteSize(), frame);

// Deframe a received message
MemorySegment received = ...;
MemorySegment output = allocator.allocate(framing.getMaxPayloadSize());
int payloadLength = framing.deframeMessage(received, bytesReceived, output);
if (payloadLength >= 0) {
    // Complete message received
    processPayload(output.asSlice(0, payloadLength));
} else {
    // Incomplete frame, need more data
    waitForMoreData();
}

Thread Safety

Implementations must be thread-safe. The framing and deframing operations should be stateless, allowing the same handler instance to be used concurrently by multiple threads. Any configuration (such as max message size) should be immutable after construction.

Zero-Copy Design

This interface is designed for zero-copy operation using MemorySegment. Implementations should avoid unnecessary data copying by writing directly to the destination segment.

See Also:

• LengthPrefixedFramingHandler
• FramingException

Method Summary

Modifier and Type	Method	Description
int	deframeMessage(MemorySegment source, int sourceLength, MemorySegment destination)	Deframes a message by extracting the payload from a framed message.
int	frameMessage(MemorySegment source, int sourceLength, MemorySegment destination)	Frames a message by adding protocol-specific headers to the payload.
int	getHeaderSize()	Returns the size of the framing header in bytes.
int	getMaxPayloadSize()	Returns the maximum payload size that can be framed.

Method Details

frameMessage

int frameMessage(MemorySegment source,
 int sourceLength,
 MemorySegment destination)

Frames a message by adding protocol-specific headers to the payload.

This method writes the framing header followed by the payload data to the destination segment. The destination must have sufficient capacity to hold the entire frame (header + payload).

Required destination capacity: sourceLength + getHeaderSize()

Parameters:

source - the source segment containing the message payload

sourceLength - the number of bytes to read from the source (payload length)

destination - the destination segment to write the framed message to

Returns:

the total frame length (header + payload), which equals sourceLength + getHeaderSize()

Throws:

FramingException - if the payload exceeds getMaxPayloadSize()

IndexOutOfBoundsException - if destination has insufficient capacity

NullPointerException - if source or destination is null

deframeMessage

int deframeMessage(MemorySegment source,
 int sourceLength,
 MemorySegment destination)

Deframes a message by extracting the payload from a framed message.

This method reads the framing header to determine the payload length, validates the frame, and copies the payload to the destination segment. If the source contains an incomplete frame (fewer bytes than indicated by the header), this method returns -1.

Return Values

• >= 0: The payload length; the complete payload has been written to destination
• -1: Incomplete frame; more data is needed to complete deframing

Note: When returning -1, the destination segment contents are undefined and should not be used.

Parameters:

source - the source segment containing the framed message (header + payload)

sourceLength - the number of bytes available in the source

destination - the destination segment to write the extracted payload to

Returns:

the payload length if deframing succeeded, or -1 if the frame is incomplete

Throws:

FramingException - if the frame header indicates an invalid or oversized payload

IndexOutOfBoundsException - if destination has insufficient capacity for the payload

NullPointerException - if source or destination is null

getHeaderSize

int getHeaderSize()

Returns the size of the framing header in bytes.

This is the overhead added to each message by the framing protocol. For length-prefixed framing, this is typically 4 bytes (32-bit length field).

Returns:

the header size in bytes

getMaxPayloadSize

int getMaxPayloadSize()

Returns the maximum payload size that can be framed.

Attempts to frame messages larger than this size will result in a FramingException. This limit is typically configured at construction time and may be constrained by protocol requirements or memory considerations.

Returns:

the maximum payload size in bytes