ZenWave SDK

https://www.zenwave360.io/docs/
Admin
ZenWave SDK is a set of tools to convert domain models into working software and tests, designed to...
Tokens:92,156
Snippets:711
Trust Score:5.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Infrastructure Services with Docker Compose

Source: https://www.zenwave360.io/docs/examples/ddd-examples/order-fullillment-kotlin

Use this command to start the necessary infrastructure services like PostgreSQL and Kafka for the Order Fulfillment Service. Ensure Docker and Docker Compose are installed and configured.

```bash
docker-compose up -d

```

--------------------------------

### Start Infrastructure Services

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

Start the necessary infrastructure services like Kafka and Schema Registry using Docker Compose. Ensure Rancher Desktop is configured with 'dockerd' engine if Docker Compose is not installed separately.

```bash
docker-compose -f shopping-cart/docker-compose.yml up -d
```

--------------------------------

### Start Block with Fields Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines a 'StartOrderCheckout' start event with fields like 'orderId', 'items', and an optional 'couponCode'. Supports custom types, arrays, and optional fields.

```zfl
start StartOrderCheckout {
    orderId String
    items SKU[]
    couponCode String?
}

```

--------------------------------

### Service Test Setup with In-Memory Repositories

Source: https://www.zenwave360.io/docs/examples/ddd-examples/customer-address-jpa

Demonstrates the setup for unit tests using in-memory repository implementations provided by ServicesInMemoryConfig. The setUp method reloads test data before each test execution.

```java
class CustomerServiceTest {


    private final Logger log = LoggerFactory.getLogger(getClass());


    ServicesInMemoryConfig context = new ServicesInMemoryConfig();


    CustomerServiceImpl customerService = context.customerService();


    CustomerRepositoryInMemory customerRepository = context.customerRepository();


    @BeforeEach
    void setUp() {
        context.reloadTestData();
    }

```

--------------------------------

### Start Infrastructure Services

Source: https://www.zenwave360.io/docs/examples/ddd-examples/customer-address-jpa

Use this command to start all necessary infrastructure services like databases and message brokers using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### Minimal Complete ZDL Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

This example demonstrates the smallest complete ZDL model, including an aggregate, a command, and its emitted domain event.

```ZDL
@aggregate
entity Order {
  id String
  status OrderStatus
}


service OrderService for (Order) {
  placeOrder(Order) Order withEvents OrderPlaced
}


event OrderPlaced {
  id String
  dateTime Instant
}
```

--------------------------------

### Example Client Consumer Logs

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

These are example log outputs from the shopping cart client application, showing the events being consumed and processed.

```log
2025-11-22T11:58:29.112+01:00  INFO 10652 --- [ntainer#0-0-C-1] s.c.e.ShoppingCartChannelConsumerService : onShoppingCartCreated: {"customerId": 1}
2025-11-22T11:58:29.116+01:00  INFO 10652 --- [ntainer#0-0-C-1] s.c.e.ShoppingCartChannelConsumerService : onShoppingCartItemAdded: {"customerId": 1, "shoppingCart": {"id": 1, "customerId": 1, "items": [{"name": "string", "quantity": 0}]}, "item": {"name": "string", "quantity": 0}}
2025-11-22T11:58:29.124+01:00  INFO 10652 --- [ntainer#0-0-C-1] s.c.e.ShoppingCartChannelConsumerService : onShoppingCartCreated: {"customerId": 7}
2025-11-22T11:58:29.126+01:00  INFO 10652 --- [ntainer#0-0-C-1] s.c.e.ShoppingCartChannelConsumerService : onShoppingCartItemAdded: {"customerId": 7, "shoppingCart": {"id": 2, "customerId": 7, "items": [{"name": "Item Name", "quantity": 10}]}, "item": {"name": "Item Name", "quantity": 10}}
2025-11-22T11:58:29.128+01:00  INFO 10652 --- [ntainer#0-0-C-1] s.c.e.ShoppingCartChannelConsumerService : onShoppingCartItemUpdated: {"customerId": 7, "shoppingCart": {"id": 2, "customerId": 7, "items": [{"name": "Item Name", "quantity": 10}]}, "item": {"name": "Item Name", "quantity": 10}, "previousItem": {"name": "Item Name", "quantity": 10}}
```

--------------------------------

### APIs Section Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

Illustrates how to document different types of APIs (provider/client) using OpenAPI and AsyncAPI specifications.

```zw
apis {
    asyncapi(provider) MyEventsApi {
        uri "src/main/resources/asyncapi.yml"
    }
    openapi(provider) MyRestApi {
        uri "src/main/resources/openapi.yml"
    }
    asyncapi(client) ThirdPartyEventsApi {
        uri "https://.../asyncapi.yml"
    }
    openapi(client) ThirdPartyRestApi {
        uri "https://.../openapi.yml"
    }
}

```

--------------------------------

### Complete PlaceOrderFlow Example in ZFL

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

A comprehensive example of the Arcadia Editions `PlaceOrderFlow`, showcasing systems, flow definition, actors, timers, and end states.

```ZFL
systems {
    @zdl("catalog-products-api/domain-model.zdl")
    CatalogProducts {
        service CatalogProductsService for (Product)
    }


    @zdl("orders-checkout-api/domain-model.zdl")
    OrdersCheckout {
        service OrdersCheckoutService
    }


    @zdl("payments-processing-api/domain-model.zdl")
    PaymentsProcessing {
        service PaymentsProcessingService
    }
}


flow PlaceOrderFlow {


    @actor(Customer)
    start StartOrderCheckout {
        items SKU[]
    }


    when StartOrderCheckout do startOrderCheckout {
        service OrdersCheckout.OrdersCheckoutService
        call reserveStock
        on StockReserved emits OrderCreated
        on StockUnavailable emits StockUnavailable
    }


    do reserveStock {
        service CatalogProducts.CatalogProductsService
        emits response StockReserved
        response StockUnavailable
    }


    when OrderCreated do authorizePayment {
        service PaymentsProcessing.PaymentsProcessingService
        emits PaymentAuthorized
        emits PaymentDeclined
        emits PaymentFailed
    }


    @actor(Scheduler)
    @time("10 minutes after OrderCreated and not PaymentAuthorized or PaymentDeclined or PaymentRetryExhausted")
    start ReservationExpired {
        orderId String
    }


    end {
        completed: PaymentCaptured
        stockGone: StockUnavailable
        orderCancelled: OrderCancelled
    }
}
```

--------------------------------

### Install ZenWave SDK CLI using JBang

Source: https://www.zenwave360.io/docs/getting-started

Installs the ZenWave SDK command-line interface using JBang. This command ensures you have the latest stable version of the SDK available.

```bash
jbang alias add --force --fresh --name=zw release@zenwave360/zenwave-sdk
```

--------------------------------

### ZenWave SDK CLI Help Output

Source: https://www.zenwave360.io/docs

Example output of the ZenWave SDK CLI's help command, showing usage information and available options for plugins.

```bash
$ jbang zw -h list

Usage: <main class> [-f] [-h[=<helpFormat>]] [-p[=<pluginClass>]]
                    [<String=Object>...]
  [<String=Object>...]
  -f, --force                Force overwrite
  -h, --help[=<helpFormat>]  Help with output format
  -p, --plugin[=<pluginClass>]
                             Plugin Class or short-code
INFO Reflections - Reflections took 566 ms to scan 59 urls, producing 2513 keys and 13329 values
ZW> SDK (2.0.0)


Available plugins:


BackendApplicationDefaultPlugin:    Generates a full backend application using the provided 'layout' property (2.0.0)
ZDLToOpenAPIPlugin:                 Generates a draft OpenAPI definitions from your ZDL entities and services. (2.0.0)
ZDLToAsyncAPIPlugin:                Generates a draft AsyncAPI file with events from your ZDL services. (2.0.0)
OpenAPIControllersPlugin:           Generates implementations based on ZDL models and OpenAPI definitions SpringMVC generated OpenAPI interfaces. (2.0.0)
AsyncApiJsonSchema2PojoPlugin:      Generate Plain Old Java Objects from OpenAPI/AsyncAPI schemas or full JSON-Schema files. (2.0.0)
SpringCloudStreams3Plugin:          Generates strongly typed SpringCloudStreams3 producer/consumer classes for AsyncAPI (2.0.0)
SpringCloudStreams3AdaptersPlugin:  Generates Spring Cloud Streams Consumers from AsyncAPI definitions. (2.0.0)
SpringWebTestClientPlugin:          Generates test for SpringMVC or Spring WebFlux using WebTestClient based on OpenAPI specification. (2.0.0)
OpenAPIKaratePlugin:                Generates test for KarateDSL based on OpenAPI specification. (2.0.0)
JDLToAsyncAPIPlugin:                Generates a full AsyncAPI definitions for CRUD operations from JDL models (2.0.0)
ZdlToJsonPlugin:                    Prints to StdOut ZDL Model as JSON (2.0.0)
OpenAPIToJDLPlugin:                 Generates JDL model from OpenAPI schemas (2.0.0)
ZdlToMarkdownPlugin:                Generates Markdown glossary from Zdl Models (2.0.0)



Use: "jbang zw -p <plugin | short-code> -h" to get help on a specific plugin

```

--------------------------------

### Start Block Syntax

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines the syntax for a 'start' block, which acts as a trigger for a flow. It can include optional Javadoc and annotations, followed by a name and fields.

```zfl
[<javadoc>]
[<annotation>*
]
start <StartName> {
    [<field>*]
}

```

--------------------------------

### Example Kafka Events

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

These are example events that should be visible when using the Kafka Avro console consumer, demonstrating the structure of published messages.

```json
{"customerId":7}
```

```json
{"customerId":7,"shoppingCart":{"id":2,"customerId":7,"items":[{"name":"Item Name","quantity":10}]},"item":{"name":"Item Name","quantity":10}}
```

```json
{"customerId":7,"shoppingCart":{"id":2,"customerId":7,"items":[{"name":"Item Name","quantity":10}]},"item":{"name":"Item Name","quantity":10},"previousItem":{"name":"Item Name","quantity":10}}
```

--------------------------------

### ZenWave Scripts (.zw) Configuration Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

Defines ZenWave SDK plugins and their configurations for SDK execution and code generation. This includes global properties and plugin-specific settings.

```zw
// This is a ZenWave Scripts File (.zw)
//
// This file defines ZenWave SDK plugins and their configurations for SDK execution and code generation.
//
// Usage:
// - Execute plugins using the Play button in IntelliJ IDEA ZenWave Model Editor
// - Or Copy the generated command line hovering the play button on each plugin
// - Or Run commands directly from terminal using the generated command line
//
// Plugin: https://plugins.jetbrains.com/plugin/22858-zenwave-domain-model-editor-for-zdl
//
// There are global properties that apply to all plugins, and plugin specific properties.
// Configuration Precedence (highest to lowest):
// 1. Command line arguments always have the highest precedence
// 2. Plugin-specific properties (defined in this file)
// 3. Global properties (defined in this file)
// 4. Properties from referenced .zdl files
//
config {


    // This is a global configuration that applies to all plugins.
    zdlFile "zenwave-model.zdl"




    // these should match the values of openapi-generator-maven-plugin
    // used by the OpenAPIControllersPlugin and SpringWebTestClientPlugin
    openApiApiPackage "{{basePackage}}.adapters.web"
    openApiModelPackage "{{basePackage}}.adapters.web.model"
    openApiModelNameSuffix DTO




    plugins {
        /** Generates an OpenAPI 3.0 specification from the ZDL model. */
        ZDLToOpenAPIPlugin {
            idType integer
            idTypeFormat int64
            targetFile "src/main/resources/public/apis/openapi.yml"
        }
        /** Generates an AsyncAPI 3.0 specification from the ZDL model. */
        ZDLToAsyncAPIPlugin {
            asyncapiVersion v3
            idType integer
            idTypeFormat int64
            targetFile "src/main/resources/public/apis/asyncapi.yml"
            includeCloudEventsHeaders true
            includeKafkaCommonHeaders true
        }
        /** Generates a Backend Application from the ZDL model. (Headless Core) */
        BackendApplicationDefaultPlugin {
            useLombok false
            useJSpecify true
            includeEmitEventsImplementation true
            // --force // overwite all files
        }
        /** Generates Spring MVC controllers from the OpenAPI specification (Web Adapters). */
        OpenAPIControllersPlugin {
            openapiFile "src/main/resources/public/apis/openapi.yml"
        }


        SpringWebTestClientPlugin {
            openapiFile "src/main/resources/public/apis/openapi.yml"
        }


        SpringWebTestClientPlugin {
            openapiFile "src/main/resources/public/apis/openapi.yml"
            groupBy businessFlow
            businessFlowTestName CreateUpdateDeleteCustomerIntegrationTest
            operationIds createCustomer,updateCustomer,deleteCustomer,getCustomer
        }


        OpenAPIKaratePlugin {
            openapiFile "src/main/resources/public/apis/openapi.yml"
        }


        OpenAPIKaratePlugin {
            openapiFile "src/main/resources/public/apis/openapi.yml"
            groupBy businessFlow
            businessFlowTestName CreateUpdateDeleteCustomerKarateTest
            operationIds createCustomer,updateCustomer,deleteCustomer,getCustomer
        }
    }
}

```

--------------------------------

### Run Shopping Cart Client Application

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

Start the Spring Boot application for the shopping cart client to consume and process events from Kafka.

```bash
mvn clean spring-boot:run -f client/pom.xml
```

--------------------------------

### Minimal Complete ZFL Checkout Flow

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

This example demonstrates a basic checkout flow in ZFL, including starting the checkout, authorizing payment, and handling declined payments.

```ZFL
flow CheckoutFlow {


    @actor(Customer)
    start StartCheckout {
        orderId String
    }


    when StartCheckout do authorizePayment {
        service Payments.PaymentService
        emits PaymentAuthorized
        emits PaymentDeclined
    }


    when PaymentDeclined do cancelOrder {
        service Orders.OrderService
        emits OrderCancelled
    }


    end {
        completed: PaymentAuthorized
        cancelled: OrderCancelled
    }
}
```

--------------------------------

### Service Reference Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Demonstrates how to reference a service within a ZFL flow, linking a command to the specific service that owns it.

```zfl
service OrdersCheckout.OrdersCheckoutService

```

--------------------------------

### Service with Aggregates Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Shows an extended service reference syntax within a 'systems' block, indicating the aggregates a service works with.

```zfl
service CatalogProductsService for (Product, StockReservation)

```

--------------------------------

### Package AsyncAPI+Avro Definitions

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

Build and install the 'apis' module to package AsyncAPI and Avro definition files. This command sources definitions from local files.

```bash
mvn clean install -f apis/pom.xml
```

--------------------------------

### Service Commands Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

Demonstrates a service definition for AttachmentService operating on CustomerOrder. It includes commands for uploading, listing, and downloading files, with specific annotations and event definitions.

```ZDL
/**
* Service for Order Attachments.
*/
@rest("/order-attachments")
service AttachmentService for (CustomerOrder) {

  @post
  @fileupload
  uploadFile(id, AttachmentFileInput) CustomerOrder? withEvents [AttachmentFileUploaded|AttachmentFileUploadFailed]

  @get("/{orderId}")
  listAttachmentFiles(id) AttachmentFileOutput[]

  @get("/{orderId}/{attachmentFileId}")
  @filedownload("file")
  downloadAttachmentFile(AttachmentFileId) AttachmentFileOutput
}

entity CustomerOrder {}
input AttachmentFileInput {}
output AttachmentFileOutput {}
```

--------------------------------

### ZDL Aggregate Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

An example of an aggregate definition for Delivery, including commands like createDelivery, onOrderStatusUpdated, and updateDeliveryStatus, along with their inputs and associated events.

```ZDL
aggregate DeliveryAggregate (Delivery) {

    createDelivery(DeliveryInput) withEvents DeliveryStatusUpdated

    onOrderStatusUpdated(OrderStatusUpdated) withEvents DeliveryStatusUpdated

    updateDeliveryStatus(DeliveryStatusInput) withEvents DeliveryStatusUpdated
}
```

--------------------------------

### Systems Block Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines participating systems and their services within a ZFL model. This block is optional.

```zfl
systems {
    OrdersCheckout {
        service OrdersCheckoutService
    }
}

```

--------------------------------

### Grouped When Blocks Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Shows how to group multiple triggers for a single 'when' block, demonstrating conditional logic based on different events or states.

```zfl
when PaymentDeclined, PaymentRetryExhausted do releaseStock {
    emits StockReleased
}


when InventoryReserved and PaymentAuthorized do confirmOrder {
    emits OrderConfirmed
}

```

--------------------------------

### Create Customer Service Method

Source: https://www.zenwave360.io/docs/zenwave-sdk/backend-application

Example of a Java method to create a customer, demonstrating entity mapping and repository saving. It uses MapStruct for entity copying.

```java
import org.springframework.transaction.annotation.Transactional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

// Assuming Customer, customerServiceMapper, and customerRepository are defined elsewhere

public class CustomerService {

    private static final Logger log = LoggerFactory.getLogger(CustomerService.class);

    private CustomerServiceMapper customerServiceMapper;
    private CustomerRepository customerRepository;

    @Transactional
    public Customer createCustomer(Customer input) {
        log.debug("Request to save Customer: {}", input);
        // Customer parameter is an entity, but it will be copied into a persistent entity here
        var customer = customerServiceMapper.update(new Customer(), input);
        customer = customerRepository.save(customer);
        return customer;
    }

    // Placeholder for CustomerServiceMapper and CustomerRepository for compilation
    interface CustomerServiceMapper {
        Customer update(Customer target, Customer source);
    }

    interface CustomerRepository {
        Customer save(Customer customer);
    }

    // Placeholder for Customer entity for compilation
    static class Customer {
        // fields would be here
    }
}
```

--------------------------------

### Annotation Examples

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Demonstrates the use of annotations to decorate various elements in ZFL, such as actors, time constraints, and compensation actions. Annotation values can vary.

```zfl
@actor(Customer)
@time("10 minutes after OrderCreated")
@compensates(reserveStock)

```

--------------------------------

### Service Implementation with Event Publishing

Source: https://www.zenwave360.io/docs/zenwave-sdk/producing-domain-events

Example of a service method that includes event publishing logic. This code is generated only if `includeEmitEventsImplementation` is set to true in the ZenWave SDK Backend Plugin configuration.

```java
// This will only be generated if includeEmitEventsImplementation is set to true
private final EventsMapper eventsMapper = EventsMapper.INSTANCE;
private final ICustomerEventsProducer eventsProducer;


@Transactional
public Customer createCustomer(Customer input) {
    log.debug("Request to save Customer: {}", input);
    var customer = customerServiceMapper.update(new Customer(), input);
    customer = customerRepository.save(customer);


    // This will only be generated if includeEmitEventsImplementation is set to true
    var customerEvent = eventsMapper.asCustomerEvent(customer);
    eventsProducer.onCustomerEvent(customerEvent);


    return customer;
}
```

--------------------------------

### Documentation Comment Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Shows how to use documentation comments (/** ... */) to preserve business context within ZFL code, applied here to a 'when' block.

```zfl
/**
 * Payment is captured only when the order is ready to ship.
 */
when FulfillmentScheduled do capturePayment {
    emits PaymentCaptured
}

```

--------------------------------

### ZenWave Project Structure Example

Source: https://www.zenwave360.io/docs

Generated code adheres to a flexible onion/hexagonal architecture, separating core domain logic from infrastructure and adapters. This structure promotes maintainability and testability.

```plaintext
📦 <basePackage>
   📦 adapters
       └─ web
       |  └─ RestControllers (spring mvc)
       └─ events
          └─ *EventListeners (spring-cloud-streams)
   📦 core
       ├─ 📦 domain
       |     └─ (entities and aggregates)
       ├─ 📦 inbound
       |     ├─ dtos/
       |     └─ ServiceInterface (inbound service interface)
       ├─ 📦 outbound
       |     ├─ mongodb
       |     |  └─ *RepositoryInterface (spring-data interface)
       |     └─ jpa
       |        └─ *RepositoryInterface (spring-data interface)
       └─ 📦 implementation
             ├─ mappers/
             └─ ServiceImplementation (inbound service implementation)
   📦 infrastructure
     ├─ mongodb
     |  └─ CustomRepositoryImpl (spring-data custom implementation)
     └─ jpa
        └─ CustomRepositoryImpl (spring-data custom implementation)

```

--------------------------------

### Run Spring Boot Application with Maven

Source: https://www.zenwave360.io/docs/examples/ddd-examples/order-fullillment-kotlin

Execute this Maven command to run the Spring Boot application. This will start the REST API and business logic for the Order Fulfillment Service.

```bash
mvn spring-boot:run

```

--------------------------------

### Generated Command Listener Implementation

Source: https://www.zenwave360.io/docs/zenwave-sdk/consuming-async-commands

Example of a generated command listener implementation for a specific operation. You need to implement the TODO section.

```java
@Slf4j
@Service
public class DoCancelOrderConsumerService implements IDoCancelOrderConsumerService {


    @Override
    public void doCancelOrder(CancelOrderInput payload, CancelOrderInputHeaders headers) {
        log.debug("Received CancelOrderInput: {}", payload);
        // TODO: implement this functionality
    }
}
```

--------------------------------

### Time-Based Policies with Timers in ZFL

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Illustrates how to define time-based policies using the `@time` annotation on `start` blocks, creating named triggers for business flows.

```ZFL
@actor(Scheduler)
@time("10 minutes after OrderCreated and not PaymentAuthorized or PaymentDeclined or PaymentRetryExhausted")
start ReservationExpired {
    orderId String
}


when ReservationExpired do releaseStock {
    service CatalogProducts.CatalogProductsService
    emits StockReleased
}
```

--------------------------------

### Define Create Customer Endpoint with Annotations

Source: https://www.zenwave360.io/docs/examples/ddd-examples/customer-address-jpa

Use annotations like @post to define a service command that will be exposed as a REST endpoint. This example shows the definition for creating a customer.

```java
    @post
    createCustomer(Customer) Customer withEvents CustomerEvent

```

--------------------------------

### Flow Definition Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines a 'PlaceOrderFlow' with a start event, a 'when' block for processing, and an end state. Flows group starts, policies, commands, and end states.

```zfl
flow PlaceOrderFlow {
    start StartOrderCheckout {
        items SKU[]
    }


    when StartOrderCheckout do startOrderCheckout {
        emits OrderCreated
    }


    end {
        completed: OrderCreated
    }
}

```

--------------------------------

### GET Operation with Path and Query Parameters

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

Illustrates a GET operation that includes both path and query parameters. This example fetches survey and question data for a patient, allowing for language filtering via a query parameter.

```APIDOC
## GET /public/surveys/{name}/patient/{patientId}/questions

### Description
Retrieves survey and question data for a specific patient, with an option to filter by language.

### Method
GET

### Endpoint
/public/surveys/{name}/patient/{patientId}/questions

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the survey.
- **patientId** (integer) - Required - The unique identifier of the patient.

#### Query Parameters
- **lang** (string) - Optional - The language code for filtering the survey questions.

### Responses
#### Success Response (200)
- **SurveyAndQuestions** (object) - The survey details and associated questions.

### Response Example
{
  "example": "{\"surveyName\": \"Survey A\", \"questions\": [{\"id\": 1, \"text\": \"Question 1?\"}]}"
}
```

--------------------------------

### Define GET operation with path parameter

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

Use the @get annotation to define a GET operation with a path parameter. The parameter type is inferred from the method signature. This generates a OpenAPI GET endpoint.

```typescript
    @get("/{id}")
    getCustomer(id) Customer?
```

--------------------------------

### List Available ZenWave SDK Plugins

Source: https://www.zenwave360.io/docs

Displays a list of all available plugins for the ZenWave SDK. This command helps users discover the SDK's capabilities.

```bash
jbang zw --help list
```

--------------------------------

### GET Operation with Path Parameter

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

Demonstrates how to define a GET operation with a path parameter using the @get annotation. The operation fetches a customer by ID and returns a 200 OK status by default.

```APIDOC
## GET /customers/{id}

### Description
Fetches a customer by their unique identifier.

### Method
GET

### Endpoint
/customers/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer.

### Responses
#### Success Response (200)
- **Customer** (object) - The customer details.

### Response Example
{
  "example": "{\"id\": 1, \"name\": \"John Doe\"}"
}
```

--------------------------------

### Define GET operation with path and query parameters

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

Use the @get annotation with path and params properties to define a GET operation with both path and query parameters. Parameter types are inferred from the command payload and specified types.

```typescript
    @get({ path: "/{name}/patient/{patientId}/questions", params: { lang: String } })
    getSurveyAndQuestionsForPatient(SurveyByNameAndPatient) SurveyAndQuestions
```

--------------------------------

### ZFL Flow Start with Actor

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines the start of a ZFL flow, specifying the actor initiating it and the data entering the flow.

```ZFL
@actor(Customer)
start StartOrderCheckout {
    items SKU[]
}
```

--------------------------------

### End Block Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Provides a concrete example of an 'end' block, defining 'completed' and 'cancelled' outcomes with their corresponding events.

```zfl
end {
    completed: PaymentCaptured
    cancelled: OrderCancelled
}

```

--------------------------------

### Spring Cloud Streams Configuration Example

Source: https://www.zenwave360.io/docs/zenwave-sdk/consuming-async-commands

Example of how to configure Spring Cloud Streams bindings in application.yml for message consumption.

```yaml
spring:
    stream:
      bindings:
        do-cancel-order-in-0: ## you can find this name in OnOrderEventConsumer
          destination: orders.cancel_orders
          group: orders.consumer
```

--------------------------------

### Run Shopping Cart Provider Application

Source: https://www.zenwave360.io/docs/examples/eda-examples/asyncapi-shopping-cart

Run the Spring Boot application for the shopping cart provider. Append '-Pasyncapi-http-files' to source AsyncAPI+Avro definitions from GitHub URLs instead of local files.

```bash
mvn clean spring-boot:run -f shopping-cart/pom.xml
```

--------------------------------

### Configure Project Layout and Base Package

Source: https://www.zenwave360.io/docs/zenwave-sdk/customizing-code

Set the application title, base package, and choose a project layout. Available layouts include Default, Clean Hexagonal, Layered, Simple Domain, Hexagonal, and Clean Architecture.

```groovy
config {
    title "My Backend Application"
    basePackage "com.example.my.backend"
    // Available layout options:
    //      - DefaultProjectLayout
    //      - CleanHexagonalProjectLayout
    //      - LayeredProjectLayout
    //      - SimpleDomainProjectLayout
    //      - HexagonalProjectLayout
    //      - CleanArchitectureProjectLayout
    layout CleanHexagonalProjectLayout
}
```

--------------------------------

### OpenAPI spec for GET operation with path parameter

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

This OpenAPI specification is generated from the @get annotation. It defines the path, method, parameters, and response schema for the getCustomer operation.

```yaml
  /customers/{id}:
    get:
      operationId: getCustomer
      description: "getCustomer"
      tags: [Customer]
      parameters:
        - name: "id"
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
```

--------------------------------

### ZenWave SDK Workflow Overview

Source: https://www.zenwave360.io/docs

The ZenWave SDK facilitates generating complete Event Driven Microservices by following a structured workflow. This process involves modeling the domain, generating API definitions, and then producing the necessary code implementations.

```markdown
You can generate complete Event Driven Microservices using DDD and API-First principles:
> 👉 Describe your Domain Model ⤳ Generate OpenAPI ⤳ Generate AsyncAPI → Generate API Implementations → Generate Backend → Generate Tests and Contracts 👍
```

--------------------------------

### OpenAPI spec for GET operation with path and query parameters

Source: https://www.zenwave360.io/docs/zenwave-sdk/exposing-a-rest-api

This OpenAPI specification is generated from the @get annotation with path and query parameters. It shows how path and query parameters are defined, including inferred types.

```yaml
  /public/surveys/{name}/patient/{patientId}/questions:
    get:
      operationId: getSurveyAndQuestionsForPatient
      description: "getSurveyAndQuestionsForPatient"
      tags: [Surveys]
      parameters:
        - name: "name"
          in: path
          required: true
          schema:
            type: string
        - name: "patientId"
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: "lang"
          in: query
          schema:
            type: string
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SurveyAndQuestions"
```

--------------------------------

### Get order details

Source: https://www.zenwave360.io/docs/examples/ddd-examples/order-fullillment-kotlin

Retrieves the details of a specific order.

```APIDOC
## GET /api/orders/{orderNumber}

### Description
Query order.

### Method
GET

### Endpoint
/api/orders/{orderNumber}

### Parameters
#### Path Parameters
- **orderNumber** (string) - Required - The number of the order to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - ReadOnly - The unique identifier for the order.
- **version** (integer) - Default: null - Version of the document.
- **orderNumber** (string) - MaxLength: 36 - Unique order number.
- **status** (OrderStatus) - The current status of the order.
- **totalAmount** (number) - The total amount of the order.
- **currency** (string) - The currency of the order.
```

--------------------------------

### CustomerService with Alternative Events

Source: https://www.zenwave360.io/docs/zenwave-sdk/backend-application

Demonstrates how to define a service command that can publish one of multiple alternative domain events.

```APIDOC
## CustomerService with Alternative Events

### Description
This example shows how to define a service command, `someCustomerCommand`, that can publish either `AlternativeCustomerEvent` or `AnotherCustomerEvent` upon successful execution.

### Method
- **someCustomerCommand(id, Customer) Customer? withEvents CustomerEvent [AlternativeCustomerEvent|AnotherCustomerEvent]**
  - Executes `someCustomerCommand` on a customer aggregate identified by `id` with the provided `Customer` data. Publishes either `AlternativeCustomerEvent` or `AnotherCustomerEvent` upon completion. Returns the resulting customer or null.

```

--------------------------------

### Get Order

Source: https://www.zenwave360.io/docs/examples/ddd-examples/order-fullillment-kotlin

Retrieves the details of a specific order by its order number.

```APIDOC
## GET /{orderNumber}

### Description
Query order.

### Method
GET

### Endpoint
/orders/{orderNumber}

### Parameters
#### Path Parameters
- **orderNumber** (string) - Required - The number of the order to retrieve.

### Response
#### Success Response (200)
- **Order** (Order?) - The order details, or null if not found.

#### Response Example
```json
{
  "orderNumber": "string",
  "status": "PLACED",
  "totalAmount": 10.99,
  "items": [
    {
      "productId": "string",
      "quantity": 1,
      "unitPrice": 10.99
    }
  ]
}
```
```

--------------------------------

### Generate AsyncAPI from ZDL

Source: https://www.zenwave360.io/docs/zenwave-sdk/consuming-async-commands

Use the ZenWave CLI to generate AsyncAPI definitions from ZDL models. Specify the plugin, ZDL file, ID type, and target file.

```bash
jbang zw -p io.zenwave360.sdk.plugins.ZDLToAsyncAPIPlugin \
    zdlFile=orders-model.zdl \
    idType=integer \
    idTypeFormat=int64 \
    targetFile=src/main/resources/apis/asyncapi.yml

```

--------------------------------

### Aggregate Annotation Example

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-domain-language

Demonstrates the use of the @aggregate and @extends annotations on an entity.

```ZDL
```

@aggregate
@extends(BaseEntity)
entity ParkingLot {


}

```
```

--------------------------------

### Get Latest Terms and Conditions

Source: https://www.zenwave360.io/docs/examples/ddd-examples/modulith-clinical-tool-jpa

Retrieves the latest terms and conditions for a given language.

```APIDOC
## GET /latest/{lang}

### Description
Retrieves the latest terms and conditions for a given language.

### Method
GET

### Endpoint
/terms-and-conditions/latest/{lang}

### Parameters
#### Path Parameters
- **lang** (Lang) - Required - The language code for which to retrieve terms and conditions.

### Response
#### Success Response (200)
- **TermsAndConditions** (TermsAndConditions?) - The latest terms and conditions entry for the specified language if found, otherwise null.
```

--------------------------------

### Maven Plugin Configuration for AsyncAPI Generation

Source: https://www.zenwave360.io/docs/zenwave-sdk/producing-domain-events

Configure the zenwave-sdk-maven-plugin to generate DTOs and producer implementations. Specify the input AsyncAPI specification and add necessary plugin dependencies.

```xml
<plugin>
    <groupId>io.zenwave360.sdk</groupId>
    <artifactId>zenwave-sdk-maven-plugin</artifactId>
    <version>${zenwave.version}</version>
    <configuration>
        <inputSpec>classpath:/apis/asyncapi.yml</inputSpec><!-- classpath, file, http(s) -->
        <addCompileSourceRoot>true</addCompileSourceRoot><!-- default is true -->
        <addTestCompileSourceRoot>true</addTestCompileSourceRoot><!-- default is true -->
    </configuration>


    <executions>
        <!-- DTOs -->
        <execution>
            <id>generate-asyncapi-provider-dtos</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <generatorName>jsonschema2pojo</generatorName>
                <configOptions>
                    <modelPackage>${basePackage}.core.domain.events</modelPackage>
                    <jsonschema2pojo.isUseJakartaValidation>true</jsonsonschema2pojo.isUseJakartaValidation>
                    <jsonschema2pojo.useLongIntegers>true</jsonschema2pojo.useLongIntegers>
                </configOptions>
            </configuration>
        </execution>
        <!-- Generate PROVIDER -->
        <execution>
            <id>generate-asyncapi-provider-implementation</id>
            <phase>generate-sources</phase>
            <goals><goal>generate</goal></goals>
            <configuration>
                <generatorName>spring-cloud-streams3</generatorName>
                <configOptions>
                    <role>provider</role>
                    <style>imperative</style>
                    <modelPackage>${basePackage}.core.domain.events</modelPackage>
                    <producerApiPackage>${basePackage}.core.outbound.events</producerApiPackage>
                    <consumerApiPackage>${basePackage}.adapters.commands</consumerApiPackage>
                </configOptions>
            </configuration>
        </execution>
    </executions>


    <!-- add any sdk plugin (custom or standard) as dependency here -->
    <dependencies>
        <dependency>
            <groupId>io.zenwave360.sdk.plugins</groupId>
            <artifactId>asyncapi-spring-cloud-streams3</artifactId>
            <version>${zenwave.version}</version>
        </dependency>
        <dependency>
            <groupId>io.zenwave360.sdk.plugins</groupId>
            <artifactId>asyncapi-jsonschema2pojo</artifactId>
            <version>${zenwave.version}</version>
        </dependency>
    </dependencies>
</plugin>
```

--------------------------------

### Get Terms and Conditions by ID

Source: https://www.zenwave360.io/docs/examples/ddd-examples/modulith-clinical-tool-jpa

Retrieves a specific terms and conditions entry by its ID.

```APIDOC
## GET /{id}

### Description
Retrieves a specific terms and conditions entry by its ID.

### Method
GET

### Endpoint
/terms-and-conditions/{id}

### Parameters
#### Path Parameters
- **id** (Long) - Required - The ID of the terms and conditions to retrieve.

### Response
#### Success Response (200)
- **TermsAndConditions** (TermsAndConditions?) - The terms and conditions entry if found, otherwise null.
```

--------------------------------

### Get Order in Kotlin

Source: https://www.zenwave360.io/docs/examples/ddd-examples/order-fullillment-kotlin

Retrieves an order by its order number. This operation is marked as read-only and transactional.

```kotlin
@Transactional(readOnly = true)
    override fun getOrder(orderNumber: String): Order? {
        log.debug("Request getOrder: {}", orderNumber)
        val order = orderRepository.findByOrderNumber(orderNumber)
        return order
    }
}
```

--------------------------------

### AsyncAPI Plugin Configuration for ZDL

Source: https://www.zenwave360.io/docs/examples/ddd-examples/customer-address-jpa

Configure the `ZDLToAsyncAPIPlugin` to generate AsyncAPI specifications. This example sets the AsyncAPI version, schema format to Avro, specifies the Avro package, ID type, target file, and includes Kafka common headers.

```groovy
        ZDLToAsyncAPIPlugin {
            asyncapiVersion v3
            schemaFormat avro
            avroPackage "io.zenwave360.example.core.outbound.events.dtos"
            idType long
            targetFile "src/main/resources/public/apis/asyncapi.yml"
            includeKafkaCommonHeaders true
        }

```

--------------------------------

### Public Surveys API

Source: https://www.zenwave360.io/docs/examples/ddd-examples/modulith-clinical-tool-jpa

Public service to get Surveys and Questions for a patient and to answer the survey.

```APIDOC
## GET /public/surveys/{name}/patient/{patientId}/questions

### Description
Retrieves a survey and its questions for a specific patient, with language support.

### Method
GET

### Endpoint
/public/surveys/{name}/patient/{patientId}/questions

### Parameters
#### Path Parameters
- **name** (String) - Required - The name of the survey.
- **patientId** (Long) - Required - The ID of the patient.

#### Query Parameters
- **lang** (String) - Optional - The language code for translations (e.g., 'en', 'es').

### Response
#### Success Response (200)
- **SurveyAndQuestions** - An object containing the survey details and translated questions.
```

```APIDOC
## POST /public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Description
Submits answers for a survey for a specific patient on a given date.

### Method
POST

### Endpoint
/public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Parameters
#### Path Parameters
- **surveyId** (Long) - Required - The ID of the survey.
- **patientId** (Long) - Required - The ID of the patient.
- **date** (LocalDate) - Required - The date the answers were provided.

### Request Body
- **SurveyAnswers** - Required - The object containing the patient's answers.

### Response
#### Success Response (200)
- **SurveyAnswers** - The submitted survey answers.
```

```APIDOC
## PATCH /public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Description
Updates existing answers for a survey for a specific patient on a given date.

### Method
PATCH

### Endpoint
/public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Parameters
#### Path Parameters
- **surveyId** (Long) - Required - The ID of the survey.
- **patientId** (Long) - Required - The ID of the patient.
- **date** (LocalDate) - Required - The date the answers were provided.

### Request Body
- **SurveyAnswers** - Required - The object containing the updated survey answers.

### Response
#### Success Response (200)
- **SurveyAnswers?** - The updated survey answers, or null if not found.
```

```APIDOC
## GET /public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Description
Retrieves the submitted answers for a survey for a specific patient on a given date.

### Method
GET

### Endpoint
/public/surveys/{surveyId}/patient/{patientId}/answers/{date}

### Parameters
#### Path Parameters
- **surveyId** (Long) - Required - The ID of the survey.
- **patientId** (Long) - Required - The ID of the patient.
- **date** (LocalDate) - Required - The date the answers were provided.

### Response
#### Success Response (200)
- **SurveyAnswers?** - The submitted survey answers, or null if not found.
```

--------------------------------

### Flow Structure Syntax

Source: https://www.zenwave360.io/docs/event-driven-design/zenwave-flow-language

Defines the basic structure of a flow in ZFL, which can contain a sequence of start, when, do, and end blocks.

```zfl
flow <FlowName> {
    [<start> | <when> | <do> | <end>]*
}

```

--------------------------------

### Base WebTestClient Test Setup

Source: https://www.zenwave360.io/docs/examples/ddd-examples/customer-address-jpa

This snippet shows the base class for web integration tests, configuring Spring Boot and WebTestClient. It uses MockMvc for mock environments and can be configured with Docker Compose for integration tests.

```java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@ActiveProfiles("test")
@DockerComposeInitializer.EnableDockerCompose
@org.springframework.transaction.annotation.Transactional
public abstract class BaseWebTestClientTest {


    @Autowired
    protected WebApplicationContext context;


    protected WebTestClient webTestClient;


    @BeforeEach
    void setup() {
        this.webTestClient = 
                MockMvcWebTestClient.bindToApplicationContext(this.context).build();
    }
}
```
Tokens:
Raw