Components and effects

Use a component when its runtime behavior is needed: durable state, an agent interaction, a workflow, a projection, or an endpoint. Keep calculations and business rules in ordinary Java classes that components call. The component guide compares component types and explains how to choose one.

An endpoint exposes a service to callers. Entities own state, workflows coordinate durable steps, agents interact with models, and views build read models. Consumers react to streams of changes, while timers arrange later calls. A service combines these responsibilities rather than requiring a component for every class.

A component returns an effect describing what the runtime should do: persist an event, update state, transition to a step, reply, or reject a command. Returning that description separates the decision from its execution.

Each component type has an Effect API suited to its behavior. The SDK guide for that component defines the available operations. Code executed outside an effect does not acquire persistence or retry behavior merely because it runs inside a component.

A command asks a component to do something and can be accepted or rejected. An event records something that has happened. Keeping requests separate from recorded facts lets the runtime recover state, deliver changes to other components, and build read models.

Components communicate through direct calls or subscriptions to changes. A direct call requests a result; an event subscription lets another component react independently. Location transparency means callers address a component by identity rather than by the node on which it runs.

The runtime supports durable multi-step execution, short transactional operations, and continuous streams. A workflow persists progress across steps. An entity processes commands against its state. A consumer processes a stream at its own pace. These share an actor-based core with isolation and asynchronous messaging.

Durable execution does not make arbitrary external side effects exactly once. Calls can be retried, and handlers must account for duplicate execution. See Durable execution and Events and streaming.