State Replication Template

Overview

State Replication is the simpler of Talon's two High Availability models. With State Replication, Talon automatically replicates changes to your microservice's state and the outbound messages emitted by your message handlers. In the event of failover to a backup or cold start recovery from a transaction log, your microservice's state is available at the same point where processing left off, and the engine will retransmit any outbound messages that were left in doubt as a result of the failure.

How State Replication Works

With State Replication:

• State is modeled using ADM - Define your state using the Application Data Model XML

• State changes are automatically replicated - The Talon runtime tracks and replicates all state modifications

• Transparent state management - State is managed by the runtime as a tree of POJOs

• Atomic transactions - State changes and outbound messages form atomic units of work

• Automatic failover - Backup instances maintain synchronized state for seamless takeover

Key Features

• Automatic Replication: Runtime handles state synchronization across cluster members

• Transparent State Tree: State organized as an object tree, automatically tracked by runtime

• ADM-Based Modeling: State defined using same XML modeling language as messages

• Built-in Consistency: Guaranteed state consistency across all instances

• Transaction Integration: State changes and message sends are atomic

• Disk Persistence: Transaction log enables cold start recovery

When to Use State Replication

State Replication is ideal when:

• You want automatic state synchronization with minimal code

• State can be modeled using ADM primitives and collections

• You don't need complex custom state logic or inheritance

• Simplicity and ease of development are priorities

• You need guaranteed state consistency across instances

Comparison with Event Sourcing

Aspect	State Replication	Event Sourcing
State Management	Runtime manages (transparent)	Application manages (opaque POJOs)
State Modeling	ADM XML required	No modeling required
Replication	State deltas replicated	Inbound messages replicated
Latency	Slightly higher (state tracking overhead)	Lower (no state tracking)
Complexity	Simpler application code	More complex (determinism requirements)
Recovery	State reconstructed from log	State reconstructed by message replay

See Consensus Models for detailed comparison.

---

Building a State Replication Microservice

Creating a State Replication microservice involves five main steps:

1. Model your microservice state using ADM

2. Annotate your main class for State Replication

3. Provide a state factory

4. Write message handlers that operate on state

5. Configure storage (clustering and persistence)

Step 1: Model Application State

Define your microservice's state using the ADM modeling language in your model.xml file. The state model defines entities that form a tree structure with a single root object.

Example State Model:

<model xmlns="http://www.neeveresearch.com/schema/x-ddl"
       namespace="com.example.orderprocessor.state"
       defaultFactoryId="2">

  <entities>
    <!-- Root entity of the state tree -->
    <entity name="OrderBook" id="1">
      <!-- Simple fields -->
      <field name="totalOrders" type="Long" default="0"/>
      <field name="totalValue" type="BigDecimal" default="0.0"/>

      <!-- Collection of entities -->
      <field name="orders" type="Order" collection="Map"
             key="orderId" id="1"/>

      <!-- Nested entity field -->
      <field name="statistics" type="Statistics" id="2"/>
    </entity>

    <!-- Child entity -->
    <entity name="Order" id="2">
      <field name="orderId" type="String"/>
      <field name="symbol" type="String"/>
      <field name="quantity" type="Integer"/>
      <field name="price" type="BigDecimal"/>
      <field name="status" type="String"/>
    </entity>

    <!-- Embedded entity for nested data -->
    <entity name="Statistics" id="3" embedded="true">
      <field name="ordersProcessed" type="Long" default="0"/>
      <field name="rejectCount" type="Long" default="0"/>
    </entity>
  </entities>
</model>

Important Modeling Considerations:

• The state tree must have a single root entity

• Entities can contain simple fields, entity fields, and collections

• See State Tree Limitations for restrictions

• See The Modeling Language for complete modeling guide

Step 2: Annotate Main Class for State Replication

Use the @AppHAPolicy annotation to declare that your microservice uses State Replication:

package com.example.orderprocessor;

import com.neeve.aep.AepEngine;
import com.neeve.aep.annotations.AppHAPolicy;

@AppHAPolicy(value = AepEngine.HAPolicy.StateReplication)
public class OrderProcessorApp {
    // ... application code ...
}

Step 3: Provide a State Factory

The AEP engine needs to be able to create your application's initial state. Provide a state factory method annotated with @AppStateFactoryAccessor:

import com.neeve.aep.IAepApplicationStateFactory;
import com.neeve.aep.annotations.AppStateFactoryAccessor;
import com.neeve.sma.MessageView;

@AppStateFactoryAccessor
final public IAepApplicationStateFactory getStateFactory() {
    return new IAepApplicationStateFactory() {
        @Override
        final public OrderBook createState(MessageView view) {
            // Return a new, empty state root
            return OrderBook.create();
        }
    };
}

Important: The state factory should return an empty, uninitialized object. The platform will:

1. Invoke the factory during initialization with a null argument to determine the state root type

2. Subsequently invoke it on receipt of a MessageView when state hasn't been created

3. Manage the state tree after creation - don't store references to the state yourself

Step 4: Write Message Handlers

Message handlers receive both the inbound message and the state root object. The handler updates state and sends outbound messages as an atomic transaction:

import com.neeve.aep.AepMessageSender;
import com.neeve.aep.annotations.EventHandler;
import com.neeve.aep.annotations.AppInjectionPoint;

public class OrderProcessorApp {
    private AepMessageSender messageSender;

    // Inject message sender for outbound messages
    @AppInjectionPoint
    final public void setMessageSender(AepMessageSender messageSender) {
        this.messageSender = messageSender;
    }

    @EventHandler
    final public void onNewOrder(NewOrderRequest request, OrderBook orderBook) {
        // Create and populate order entity
        Order order = Order.create();
        order.setOrderId(request.getOrderId());
        order.setSymbol(request.getSymbol());
        order.setQuantity(request.getQuantity());
        order.setPrice(request.getPrice());
        order.setStatus("ACCEPTED");

        // Update state - changes are automatically tracked and replicated
        orderBook.getOrders().put(order.getOrderId(), order);
        orderBook.setTotalOrders(orderBook.getTotalOrders() + 1);
        orderBook.setTotalValue(
            orderBook.getTotalValue().add(
                order.getPrice().multiply(
                    BigDecimal.valueOf(order.getQuantity())
                )
            )
        );

        // Update embedded statistics
        orderBook.getStatistics().setOrdersProcessed(
            orderBook.getStatistics().getOrdersProcessed() + 1
        );

        // Send outbound message - atomically replicated with state changes
        OrderConfirmation confirmation = OrderConfirmation.create();
        confirmation.setOrderId(order.getOrderId());
        confirmation.setStatus("ACCEPTED");
        messageSender.sendMessage("confirmations", confirmation);
    }

    @EventHandler
    final public void onCancelOrder(CancelOrderRequest request, OrderBook orderBook) {
        Order order = orderBook.getOrders().get(request.getOrderId());
        if (order != null && "ACCEPTED".equals(order.getStatus())) {
            // Update state
            order.setStatus("CANCELLED");
            orderBook.getStatistics().setRejectCount(
                orderBook.getStatistics().getRejectCount() + 1
            );

            // Send confirmation
            OrderConfirmation confirmation = OrderConfirmation.create();
            confirmation.setOrderId(order.getOrderId());
            confirmation.setStatus("CANCELLED");
            messageSender.sendMessage("confirmations", confirmation);
        }
    }
}

Key Points:

• State changes and message sends form an atomic transaction

• All modifications to state are automatically tracked and replicated

• No need for manual state serialization or replication code

• State root is passed to every handler method

Step 5: Configure Storage

Configure storage in your DDL to enable clustering and persistence.

Register Object Factories

Both message factories and state factories must be registered with the runtime:

DDL Configuration:

<app name="order-processor" mainClass="com.example.orderprocessor.OrderProcessorApp">
  <messaging>
    <factories>
      <factory name="com.example.orderprocessor.messages.MessageFactory"/>
    </factories>
    <buses>
      <bus name="orders-bus">
        <channels>
          <channel name="orders" join="true"/>
          <channel name="confirmations" join="false"/>
        </channels>
      </bus>
    </buses>
  </messaging>

  <storage enabled="true">
    <factories>
      <factory name="com.example.orderprocessor.state.StateFactory"/>
    </factories>
    <clustering enabled="true">
      <storeName>order-processor-store</storeName>
      <localPort>10000</localPort>
      <discoveryDescriptor>nvds://localhost:4090</discoveryDescriptor>
    </clustering>
    <persistence enabled="true">
      <flushOnCommit>false</flushOnCommit>
      <storeRoot>rdat</storeRoot>
    </persistence>
  </storage>
</app>

Programmatic Registration Alternative:

@AppInjectionPoint
public void initialize(AepEngine engine) {
    // Register message factory
    engine.registerFactory(new com.example.orderprocessor.messages.MessageFactory());

    // Register state factory for replication
    engine.registerFactory(new com.example.orderprocessor.state.StateFactory());
}

Enable Clustering

Clustering allows multiple instances to discover each other and form an HA cluster:

<clustering enabled="true">
  <storeName>order-processor-store</storeName>
  <localPort>10000</localPort>
  <localIfAddr>192.168.1.100</localIfAddr>
  <linkParams>SO_REUSEADDR=true,TCP_NODELAY=true</linkParams>
  <discoveryDescriptor>nvds://localhost:4090</discoveryDescriptor>
  <initWaitTime>5000</initWaitTime>
  <failOnMultiplePrimaries>true</failOnMultiplePrimaries>
  <memberElectionPriority>100</memberElectionPriority>
</clustering>

Key clustering concepts:

• Instances with same storeName form a cluster

• One instance elected as primary via leadership election

• Primary establishes messaging and invokes handlers

• Backups maintain synchronized state for failover

Enable Persistence

Persistence logs the replication stream to disk for cold start recovery:

<persistence enabled="true">
  <flushOnCommit>false</flushOnCommit>
  <autoFlushSize>8192</autoFlushSize>
  <storeRoot>rdat</storeRoot>
  <compaction>
    <compactOnStart>false</compactOnStart>
    <compactionThreshold>1024</compactionThreshold>
  </compaction>
</persistence>

Clustering Requires Persistence: When clustering is enabled, persistence must also be enabled. The transaction log is used to initialize new cluster members that connect to the primary.

See Storage Configuration for complete configuration reference.

---

State Tree Limitations

State Replication has several important restrictions that developers must understand. These are documented in detail in Programming Fundamentals - State Tree Limitations:

Key Restrictions

1. Single Parent Restriction: An entity can only appear in one location in the state tree (throws IllegalStateException if violated)

2. No Multiple Fields of Same Type: Cannot have multiple non-embedded entity fields of the same type in a parent

3. No State Tree Cycles: Cycles (including self-references) are not supported

4. No Primitive Collections: Collections must use boxed types (e.g., Integer not int)

5. No Inheritance: Inheritance not supported; use entity inlining for polymorphism

Workarounds

For Single Parent Restriction: Store entities in a Map and reference by ID:

// Instead of storing Customer in multiple places:
// order1.setCustomer(customer);  // Not allowed
// order2.setCustomer(customer);  // Would throw exception

// Use a Map and reference by ID:
orderBook.getCustomers().put(customer.getId(), customer);
order1.setCustomerId(customer.getId());
order2.setCustomerId(customer.getId());

See Programming Fundamentals for complete details and additional workarounds.

---

Related Documentation

Core Concepts

• Consensus Models - Understanding State Replication vs Event Sourcing

• Transactions - How transactions work with state replication

• Application Lifecycle - State creation and initialization

Development

• Modeling Messages & State - Complete ADM modeling guide

• Programming Fundamentals - State tree limitations and restrictions

• Handling Messages - Writing message handlers

Configuration

• Storage Configuration - Complete storage configuration reference

• Configuring Threading - Optimize replication performance

Operations

• Transaction Log Tool - Browse and analyze transaction logs

• Querying Transaction Logs - XPQL query language

---

Next Steps

1. Start modeling: Define your state in model.xml following ADM syntax

2. Create application class: Annotate with @AppHAPolicy and provide state factory

3. Write handlers: Implement message handlers that operate on state

4. Configure storage: Enable clustering and persistence in DDL

5. Test failover: Verify state consistency and message retransmission

6. Tune performance: Adjust threading and batching based on load testing

7. Monitor in production: Track transaction log size and replication latency