Modeling Messages & State

This section describes how to model the messages and state for your Talon microservice using the ADM (Application Data Model) language and generate Java classes from those models.

Overview

Talon microservices work with strongly-typed POJOs (Plain Old Java Objects) for both messages and state. Rather than hand-writing these classes, you define them using an XML-based modeling language, and Talon's code generator converts your models into optimized Java classes.

This approach provides several benefits:

• Type safety: Compile-time checking of message and state access

• Performance: Generated code is optimized for zero-garbage operation

• Simplicity: Focus on your data model, not Java boilerplate

• Serialization: Automatic wire format handling for messaging

• Evolution: Built-in support for schema versioning and evolution

What You'll Learn

This section covers two main topics:

The ADM Modeling Language

Learn how to define your application's data model using XML:

• Message modeling: Define inbound and outbound message types

• State modeling: Model your microservice's persistent state as entity trees

• Type system: Use built-in types (primitives, strings, decimals) and custom types

• Collections: Model arrays, lists, sets, and maps

• Field properties: Configure nullability, defaults, and constraints

• Annotations: Add metadata to control code generation

• Model composition: Import and reuse models across projects

Running the Code Generator

Integrate Talon's code generator into your build process:

• Build integration: Use with Maven, Gradle, or Ant

• Generator configuration: Control code generation options

• Encoding types: Choose wire format optimizations

• Generated artifacts: Understand the generated Java classes

• Compilation: Compile generated code with your application

Quick Start

A typical workflow for modeling and code generation:

1. Define your model in an XML file (e.g., src/main/model/model.xml):

   <model xmlns="http://www.neeveresearch.com/schema/x-ddl">
     <messages>
       <message name="OrderRequest">
         <field name="orderId" type="String"/>
         <field name="quantity" type="Integer"/>
       </message>
     </messages>
   
     <entities>
       <entity name="OrderBook">
         <field name="orders" type="OrderRequest" collection="List"/>
       </entity>
     </entities>
   </model>

2. Configure the code generator in your build file (Maven example):

   <plugin>
     <groupId>com.neeve</groupId>
     <artifactId>nvx-platform-maven-plugin</artifactId>
     <executions>
       <execution>
         <goals>
           <goal>adm</goal>
         </goals>
       </execution>
     </executions>
   </plugin>

3. Build your project - Generated POJOs are created automatically:

   mvn compile

4. Use the generated classes in your message handlers:

   @EventHandler
   public void onOrderRequest(OrderRequest order, OrderBook orderBook) {
     orderBook.getOrders().add(order);
   }

Related Topics

• Message Processing - Using generated message classes in handlers

• Introduction - See the simple example of modeling and code generation

Next Steps

1. Read The ADM Modeling Language to understand the full modeling capabilities

2. Learn about Running the Code Generator to integrate into your build

3. Explore Choosing an Encoding Type for wire format optimization