Class TracedQueue

java.lang.Object

org.j7m.middleware.integrations.TracedQueue

public final class TracedQueue
extends Object

Real replicated-queue facade carrying a bounded, versioned W3C context envelope. Message context is supplied explicitly and must remain identical on retries. Payloads remain opaque and are never exported. Send and consumer spans share the persisted production context.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TracedQueue.Handler	Handler called under the persisted consumer context.
static final record	TracedQueue.Message	Immutable delivery envelope.

Constructor Summary

Constructors

Constructor	Description
TracedQueue(org.j7m.middleware.distributed.ReplicatedQueue queue, Observability telemetry)	Creates an instrumented facade over the real queue.

Method Summary

Modifier and Type	Method	Description
String	ack(String request, String name, String group, String member, long generation, String id, long receipt, Instant deadline)	Acknowledges only a committed consumer effect and records confirmed acknowledgements.
String	claim(String request, String name, String group, String member, long generation, long visibilityMillis, Instant deadline)	Claims a delivery and records an actual queue claim observation.
void	consume(byte[] envelope, TracedQueue.Handler handler)	Processes an encoded queue payload under its persisted remote parent.
List<String>	deadLetters(String name, Instant deadline)	Observes the actual retained dead-letter page without exporting identities.
static TracedQueue.Message	decode(byte[] envelope)	Decodes an immutable envelope, rejecting unsupported formats and trailing bytes.
static byte[]	encode(TracedQueue.Message message)	Encodes a bounded context envelope for a queue or transactional outbox.
String	send(String request, String name, String id, TracedQueue.Message message, int attempts, Instant deadline)	Publishes a deterministic message envelope using a stable request/message identity.

Methods inherited from class Object

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

Constructor Details

TracedQueue

public TracedQueue(org.j7m.middleware.distributed.ReplicatedQueue queue,
 Observability telemetry)

Creates an instrumented facade over the real queue.

Parameters:

queue - authenticated replicated queue

telemetry - concrete export integration

Method Details

send

public String send(String request,
 String name,
 String id,
 TracedQueue.Message message,
 int attempts,
 Instant deadline)
            throws IOException

Publishes a deterministic message envelope using a stable request/message identity.

Parameters:

request - stable request identity

name - queue name

id - stable message identity

message - immutable payload and retry-stable propagation metadata

attempts - queue delivery attempt limit

deadline - absolute deadline

Returns:

underlying durable queue result

Throws:

IOException - on unavailable/unknown outcome

claim

public String claim(String request,
 String name,
 String group,
 String member,
 long generation,
 long visibilityMillis,
 Instant deadline)
             throws IOException

Claims a delivery and records an actual queue claim observation.

Parameters:

request - stable claim request

name - queue name

group - consumer group

member - member identity

generation - current assignment generation

visibilityMillis - delivery lease milliseconds

deadline - absolute deadline

Returns:

underlying MESSAGE/EMPTY result, preserving receipt metadata

Throws:

IOException - for unavailable or unknown claim

ack

public String ack(String request,
 String name,
 String group,
 String member,
 long generation,
 String id,
 long receipt,
 Instant deadline)
           throws IOException

Acknowledges only a committed consumer effect and records confirmed acknowledgements.

Parameters:

request - stable acknowledgement request

name - queue name

group - consumer group

member - live member

generation - current group generation

id - message identity

receipt - current delivery receipt

deadline - absolute deadline

Returns:

underlying acknowledgement result

Throws:

IOException - for unknown or unavailable acknowledgement

deadLetters

public List<String> deadLetters(String name,
 Instant deadline)
                         throws IOException

Observes the actual retained dead-letter page without exporting identities.

Parameters:

name - queue name

deadline - absolute deadline

Returns:

actual first retained dead-letter page

Throws:

IOException - for query failure

consume

public void consume(byte[] envelope,
 TracedQueue.Handler handler)
             throws Exception

Processes an encoded queue payload under its persisted remote parent.

Parameters:

envelope - bytes returned by a successful real queue claim

handler - application callback, such as a transactional inbox consumer

Throws:

Exception - if the envelope or callback fails

encode

public static byte[] encode(TracedQueue.Message message)
                     throws IOException

Encodes a bounded context envelope for a queue or transactional outbox.

Parameters:

message - immutable payload/context

Returns:

deterministic version-one bytes

Throws:

IOException - if encoding fails

decode

public static TracedQueue.Message decode(byte[] envelope)
                                  throws IOException

Decodes an immutable envelope, rejecting unsupported formats and trailing bytes.

Parameters:

envelope - at most 32768 encoded bytes

Returns:

decoded context and independent payload

Throws:

IOException - for unsupported or malformed bytes