Skip to main content

Configuration

All properties live under the oncebox prefix. Durations take Spring Boot's format (250ms, 10s, 5m, 24h).

Global​

oncebox:
thread-pool-size: 5
schema:
mode: flyway
distributed-lock:
resolve-by-polling-properties: true
lock-at-least-for: 1s
lock-at-most-for: 1m
PropertyDescriptionDefault
thread-pool-sizeThreads shared by all pollers and jobs, see sizingmin(available processors, 5)
schema.modeHow the tables are created: flyway, liquibase, dev or none, see Schema Migrationsnone
distributed-lock.resolve-by-polling-propertiesDerive lock times from each job's polling settingstrue
distributed-lock.lock-at-least-forMinimum lock time when not derived1s
distributed-lock.lock-at-most-forLock expiry when not derived1m

Outbox​

PropertyDescriptionDefault
oncebox.outbox.enabledEnable the outboxtrue

Sender​

oncebox:
outbox:
sender:
type: kafka
bean-name: "customKafkaTemplate"
emergency-timeout: 120s
PropertyDescriptionDefault
typekafka or rabbit; required-
bean-nameTemplate bean to use when the context has severalresolved by type
emergency-timeoutMaximum wait for the broker to acknowledge a batch120s

Defaults and events​

defaults applies to every event type; each entry under events overrides it property by property.

oncebox:
outbox:
defaults:
batch-size: 200
polling:
type: adaptive
initial-delay: 5m
min-fixed-delay: 250ms
max-fixed-delay: 1m
multiplier: 1.5
max-retries: 3
backoff:
enabled: true
delay: 10s
multiplier: 3.0
events:
create-order:
topic: orders # Kafka topic, or the exchange for RabbitMQ
batch-size: 500
polling:
min-fixed-delay: 1s
max-retries: 2
backoff:
delay: 5s
multiplier: 2.0
update-order:
topic: orders
polling:
type: fixed
initial-delay: 10m
fixed-delay: 250ms
backoff:
enabled: false # retry on the next iteration
# inherits batch-size 200 and max-retries 3
delete-order:
topic: orders
polling:
max-fixed-delay: 5m
multiplier: 5.0
# inherits batch-size 200, the other polling values, max-retries 3 and the backoff
PropertyDescriptionDefault
topicKafka topic or RabbitMQ exchange; per event only, required-
batch-sizeEvents captured per iteration200
polling.typefixed or adaptiveadaptive
polling.initial-delayDelay before the first iteration5m
polling.fixed-delayDelay between iterations, fixed only-
polling.min-fixed-delaySmallest delay, adaptive only250ms
polling.max-fixed-delayLargest delay, adaptive only1m
polling.multiplierIdle growth factor, adaptive only1.5
max-retriesSend attempts before the event becomes FAILED3
backoff.enabledDelay retries exponentially; when false, retry on the next iterationtrue
backoff.delayBase delay10s
backoff.multiplierGrowth factor per failed attempt3.0

How the delay is computed is described in Processing & Resilience.

Stuck event recovery​

oncebox:
outbox:
stuck-recovery:
batch-size: 500
max-batch-processing-time: 300s
polling:
type: adaptive
initial-delay: 5m
min-fixed-delay: 1s
max-fixed-delay: 1m
multiplier: 4.0
PropertyDescriptionDefault
batch-sizeEvents recovered per iteration500
max-batch-processing-timeAge in IN_PROCESS after which an event is considered stuck300s
polling.typefixed or adaptiveadaptive
polling.initial-delayDelay before the first iteration5m
polling.min-fixed-delaySmallest delay1s
polling.max-fixed-delayLargest delay1m
polling.multiplierIdle growth factor4.0

Cleanup​

oncebox:
outbox:
clean-up:
enabled: true
batch-size: 500
ttl: 24h
polling:
type: adaptive
initial-delay: 5m
min-fixed-delay: 5s
max-fixed-delay: 1m
multiplier: 2.0
PropertyDescriptionDefault
enabledDelete processed events; when false they accumulatetrue
batch-sizeEvents deleted per iteration500
ttlAge of a PROCESSED event after which it is deleted24h
polling.typefixed or adaptiveadaptive
polling.initial-delayDelay before the first iteration5m
polling.min-fixed-delaySmallest delay5s
polling.max-fixed-delayLargest delay1m
polling.multiplierIdle growth factor2.0

Dead letter queue​

batch-size and polling at the top of the section are the defaults of transfer-to and transfer-from.

oncebox:
outbox:
dlq:
enabled: true
batch-size: 500
polling:
type: adaptive
initial-delay: 5m
min-fixed-delay: 1s
max-fixed-delay: 2m
multiplier: 10.0
transfer-to:
polling:
multiplier: 2.5 # everything else is inherited
transfer-from: # every value set, nothing inherited
batch-size: 1000
polling:
type: fixed
initial-delay: 5m
fixed-delay: 1m
clean-up:
enabled: true
batch-size: 500
ttl: 24h
PropertyDescriptionDefault
enabledEnable the DLQ and its jobsfalse
batch-sizeEvents transferred per iteration500
polling.typefixed or adaptiveadaptive
polling.initial-delayDelay before the first iteration5m
polling.min-fixed-delaySmallest delay1s
polling.max-fixed-delayLargest delay2m
polling.multiplierIdle growth factor10.0
transfer-toOverrides for moving FAILED events into the DLQ-
transfer-fromOverrides for moving TO_RETRY events back to the outbox-
clean-upCleanup of RESOLVED events; same properties and defaults as Cleanup-

Metrics​

oncebox:
outbox:
metrics:
enabled: true
gauge:
enabled: true
cache:
ttls: [60s, 60s, 30s]
PropertyDescriptionDefault
enabledEnable outbox metricsfalse
gauge.enabledEnable the event count gaugesfalse
gauge.cache.enabledCache gauge values; always false when gauges are offtrue with gauges on
gauge.cache.ttlsCache TTLs of the gauge groups[60s, 60s, 60s]

metrics.enabled: true alone collects metrics without the event count gauges; they stay off until gauge.enabled is true.

Inbox​

PropertyDescriptionDefault
oncebox.inbox.enabledEnable the inboxfalse

Source​

oncebox:
inbox:
source:
type: kafka
PropertyDescription
typekafka or rabbit

Mappings​

oncebox:
inbox:
mappings:
create-order: "com.example.OrderCreatedDto"
update-order: "com.example.OrderUpdatedDto"

A map from event type to the class the payload is deserialized into. Keys must match the event types under oncebox.outbox.events on the publisher side. See Inbox.

Inbox cleanup​

oncebox:
inbox:
clean-up:
enabled: true
batch-size: 500
ttl: 24h
polling:
type: adaptive
initial-delay: 5m
min-fixed-delay: 5s
max-fixed-delay: 1m
multiplier: 2.0

Same properties and defaults as the outbox Cleanup; ttl is the age of an inbox record after which it is deleted.

Cache​

oncebox:
inbox:
cache:
enabled: true
cache-name: "<service-name>:oncebox:inbox"
PropertyDescriptionDefault
enabledCache consumed ids. false when the section is absent, true when it is present without enabledfalse
cache-nameName of a cache your CacheManager provides; required when the cache is enabled, unique per service-

Requires oncebox-inbox-cache. See Inbox.

Inbox metrics​

oncebox:
inbox:
metrics:
enabled: true
PropertyDescriptionDefault
enabledEnable inbox metricsfalse

Full examples​

Configurations for common setups - several event types, RabbitMQ, production, inbox, both sides in one service, local development - are in Configuration Recipes.