public final class Outbox

A durable queue of outgoing messages, kept in the application’s own database, for a device whose link to the server comes and goes.

The device records what it has to say with [#enqueue(String, byte[])] and sends it with flush(Transport) whenever the link might be up. Messages survive a restart or a power cut, leave in the order they were enqueued, and are removed only once the transport reports them delivered.

The table lives in the database of the Session the outbox was opened on, and an enqueue inside one of that session’s transactions belongs to the transaction: a reading saved through the ORM and the message announcing it commit together or not at all. That is the point of keeping the queue there rather than in a file of its own.

Outbox outbox = Outbox.open(session, "readings@" + deviceId);
session.beginTransaction();
session.persist(reading);
outbox.enqueue("/v1/readings", body);
session.commitTransaction();

// Later, from a timer or when the network comes back. postToServer is the
// application's own call: Rest on a client, Web on the backend.
outbox.flush(message -> {
    int status = postToServer(message.getTopic(), message.getKey(), message.getPayload());
    return status < 300 ? Outbox.DELIVERED : status < 500 ? Outbox.REJECTED : Outbox.RETRY;
});

Delivery is at least once. A message is removed after the transport answers DELIVERED; if the answer never arrives the same message, with the same OutboxMessage.getKey(), is sent again, and the receiver drops the copy. Several devices feeding one server should put their identity in the outbox name, which is the first half of the key.

Like its session, an outbox is used from one thread at a time. The outbox works on the client and on the backend alike.