Package org.apache.juneau.console.bus

Class BusFrames

java.lang.Object

org.apache.juneau.console.bus.BusFrames

public final class BusFrames
extends Object

The bus wire format, version 1: one JSON object per frame, in a canonical field order shared with the browser codec and pinned by bus-frames-corpus.json.

The SSE transport writes each frame as event: bus, id: <seq>, data: <frame>; the WebSocket transport sends one frame per text message.

Example:

String f = BusFrames.pub("ops.jobs", Json.of(payload), true, 7); // {"v":1,"type":"pub","topic":"ops.jobs","payload":{...},"retained":true,"seq":7} JsonMap up = BusFrames.decode(text); // BusRefusal bus:bad-frame when malformed

Since:

10.0.0

Field Summary

Fields

Modifier and Type	Field	Description
static final String	EVENT	The SSE event name carrying frames.
static final Set<String>	TYPES	The frame types of version 1.
static final int	VERSION	The wire format version.

Method Summary

Modifier and Type	Method	Description
static String	clear(String topic, long seq)	A clear frame.
static JsonMap	decode(String text)	Decodes and validates one frame.
static String	encode(Map<String,?> frame)	Encodes a frame given as a map, in canonical field order, omitting absent optional fields.
static String	error(String code, String message, String topic)	An error frame.
static String	ping()
static String	pub(String topic, String payloadJson, boolean retained, long seq)	A pub frame.
static String	resyncBegin(long seq)
static String	resyncEnd(long seq)
static OptionalLong	seq(String encoded)	Extracts the seq of a frame produced by this class (it is always the last field when present).
static int	utf8Length(String s)	The UTF-8 length of a string, without allocating its bytes.

Methods inherited from class java.lang.Object

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

Field Details

VERSION

public static final int VERSION

The wire format version.

See Also:

• Constant Field Values

EVENT

public static final String EVENT

The SSE event name carrying frames.

See Also:

• Constant Field Values

TYPES

public static final Set<String> TYPES

The frame types of version 1.

Method Details

pub

public static String pub(String topic,
 String payloadJson,
 boolean retained,
 long seq)

A pub frame.

Parameters:

topic - The topic.

payloadJson - The payload, already serialized as JSON.

retained - Whether the value is retained.

seq - The session sequence number.

Returns:

The encoded frame.

clear

public static String clear(String topic,
 long seq)

A clear frame.

Parameters:

topic - The retained topic being cleared.

seq - The session sequence number.

Returns:

The encoded frame.

resyncBegin

public static String resyncBegin(long seq)

Parameters:

seq - The session sequence number. @return The encoded resync-begin frame.

resyncEnd

public static String resyncEnd(long seq)

Parameters:

seq - The session sequence number. @return The encoded resync-end frame.

ping

public static String ping()

Returns:

The encoded ping frame.

error

public static String error(String code,
 String message,
 String topic)

An error frame.

Parameters:

code - The bus:* code.

message - Fixed server text.

topic - The topic concerned. Can be null.

Returns:

The encoded frame.

encode

public static String encode(Map<String,?> frame)

Encodes a frame given as a map, in canonical field order, omitting absent optional fields.

Parameters:

frame - The frame (type required; v is always written as 1).

Returns:

The encoded frame.

Throws:

IllegalArgumentException - On an unknown type, or when topic, code or message is missing or not a string, or retained is not a boolean.

decode

public static JsonMap decode(String text)
                      throws BusRefusal

Decodes and validates one frame. The result holds only the known fields of its type, in canonical order.

Parameters:

text - The frame text (strict RFC 8259 JSON).

Returns:

The frame.

Throws:

BusRefusal - bus:bad-frame when the text is not a valid version-1 frame.

seq

public static OptionalLong seq(String encoded)

Extracts the seq of a frame produced by this class (it is always the last field when present).

Parameters:

encoded - An encoded frame.

Returns:

The sequence number, or empty for ping and error.

utf8Length

public static int utf8Length(String s)

The UTF-8 length of a string, without allocating its bytes.

Parameters:

s - The string.

Returns:

The number of UTF-8 bytes.