Annotations Reference

This page lists all annotation types currently present in ConvEngine and how consumers should use them.

Consumer entry annotations

Use these in your consumer app

Annotation	Target	Purpose	Typical usage
`@EnableConvEngine(stream = true|false)`	Spring Boot app class	Bootstraps ConvEngine auto-configuration and stream setting.	Always required to activate framework.
`@EnableConvEngineCaching`	Spring Boot app class	Hooks ConvEngine's pipeline to Spring's CacheManager to intercept slow relational DB saves.	Apply to resolve conversation I/O latency.
`@EnableConvEngineAsyncConversation`	Spring Boot app class	Ties ConvEngine into Spring's thread pools for asynchronous background tasks.	Apply alongside caching.
`@EnableConvEngineAsyncAuditDispatch`	Spring config/app class	Forces async audit dispatch marker mode.	Use when you intentionally want async listener dispatch.
`@EnableConvEngineStompBrokerRelay`	Spring config/app class	Forces STOMP broker relay marker mode.	Use when deploying with external STOMP broker relay.

Basic enablement

JAVA

@SpringBootApplication
@EnableConvEngine(stream = true)
@EnableConvEngineCaching
@EnableConvEngineAsyncConversation
public class MyApplication {
  public static void main(String[] args) {
    SpringApplication.run(MyApplication.class, args);
  }
}

Optional relay + async markers

JAVA

@Configuration
@EnableConvEngineAsyncAuditDispatch
@EnableConvEngineStompBrokerRelay
public class ConvEngineFeatureFlags {
}

How stream mode works

stream is an annotation parameter on @EnableConvEngine, not a YAML key. Keep it aligned with convengine.transport.sse.enabled and convengine.transport.stomp.enabled.

Extension annotations (consumer customization)

Extension points

Annotation	Must implement	Purpose	Key parameters
`@ResponseTransformer`	`ResponseTransformerHandler`	Last-mile payload shaping by intent/state.	`intent`, `state`
`@ContainerDataTransformer`	`ContainerDataTransformerHandler`	Transforms CCF container data before session attach.	`intent`, `state`
`@ContainerDataInterceptor`	`ContainerDataRequestInterceptor` and/or `ContainerDataResponseInterceptor`	Intercepts CCF request/response around execution.	`intent`, `state`, `order`

Response transformer example

JAVA

@Component
@ResponseTransformer(intent = "REQUEST_TRACKER", state = "IDLE")
public class TrackerResponseTransformer implements ResponseTransformerHandler {
  @Override
  public OutputPayload transform(OutputPayload responsePayload,
  EngineSession session,
  Map<String, Object> inputParams) {
    return responsePayload;
  }
}

Container transformer example

JAVA

@Component
@ContainerDataTransformer(intent = "DISCONNECT_ELECTRICITY", state = "COLLECTING")
public class DisconnectContainerTransformer implements ContainerDataTransformerHandler {
  @Override
  public Map<String, Object> transform(ContainerComponentResponse response,
  EngineSession session,
  Map<String, Object> inputParams) {
    return Map.of("normalized", response);
  }
}

Container interceptor example

JAVA

@Component
@ContainerDataInterceptor(intent = "*", state = "*", order = 10)
public class TraceContainerInterceptor
implements ContainerDataRequestInterceptor, ContainerDataResponseInterceptor {

  @Override
  public void intercept(ContainerComponentRequest request, EngineSession session) {
    // mutate request if needed
  }

  @Override
  public ContainerComponentResponse intercept(ContainerComponentResponse response, EngineSession session) {
    return response;
  }
}

Transformer/interceptor registration rules

If a class uses @ResponseTransformer or @ContainerDataTransformer but does not implement the required handler interface, startup fails.

Internal pipeline annotations (advanced / framework contributors)

Engine DAG annotations

Annotation	Role	Who should use it
`@MustRunAfter(...)`	Declares DAG dependency: step runs after listed steps.	Framework contributors adding new `EngineStep` beans.
`@MustRunBefore(...)`	Declares DAG dependency: step runs before listed steps.	Framework contributors adding new `EngineStep` beans.
`@RequiresConversationPersisted`	Forces ordering after bootstrap persistence step.	Framework/internal step authors.
`@ConversationBootstrapStep`	Marks the single bootstrap step in pipeline.	Framework internals only.
`@TerminalStep`	Marks the single terminal step in pipeline.	Framework internals only.
`@PromptVar`	Maps fields in internal prompt context models to template aliases.	Framework internals only; not for consumer app classes.

Custom step with ordering

JAVA

@Component
@RequiresConversationPersisted
@MustRunAfter(IntentResolutionStep.class)
@MustRunBefore(ResponseResolutionStep.class)
public class CustomValidationStep implements EngineStep {
  @Override
  public StepResult execute(EngineSession session) {
    return new StepResult.Continue();
  }
}

Important constraints

Pipeline requires exactly one @ConversationBootstrapStep and one @TerminalStep. Misuse can break startup DAG validation.

Quick recommendations for consumers

1. Use @EnableConvEngine, @EnableConvEngineCaching, and @EnableConvEngineAsyncConversation initially for zero-latency pipelines.
2. Add @ResponseTransformer or container annotations only when you have a concrete customization need.
3. Avoid pipeline DAG annotations unless you are intentionally adding custom engine steps and can test full ordering.
4. Keep annotation usage paired with integration tests for one real conversation flow.

Related pages

See Consumer Guide, New Consumer Onboarding, and Extensions for end-to-end integration context.