> For the complete documentation index, see [llms.txt](https://docs.eventoframework.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eventoframework.com/evento-framework/component/service.md).

# @Service

The Evento Framework adopts the principles of the RECQ architecture, and within this context, the `@Service` annotation plays a crucial role. This chapter delves into how `@Service` is used to define services that interact with the outside world and potentially manage the internal state.

#### Understanding `@Service`

The `@Service` annotation marks a class within your Evento application as a service. Services are responsible for performing specific tasks or operations that fall outside the domain logic itself. They often interact with external systems or persist data for future use.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Component
public @interface Service {
}
```

Here's a breakdown of the annotation's definition:

* **`@Retention(RetentionPolicy.RUNTIME)`:** Ensures the annotation information is retained at runtime, allowing Evento to identify services within your application.
* **`@Target(ElementType.TYPE)`:** Specifies that the annotation can only be applied to class declarations.
* **`@Component`:** Inherits from the `@Component` annotation, indicating that the annotated class is a component within the Evento framework.

#### Services in RECQ Architecture

The RECQ architecture emphasizes the separation of concerns between domain logic and external interactions. Services act as a bridge between the internal domain events and the outside world, performing the necessary actions based on commands or interacting with external systems.

There are two main types of services within RECQ:

* **Stateless Services:** These services perform actions without maintaining any internal state. A common example is sending notifications through an external API (like sending an email notification upon an event).
* **Stateful Services:** These services manage and persist their own state. For instance, a payment gateway service might store information about ongoing transactions.

#### When to Use a Service for High-Throughput Direct Writes

Beyond bridging to external systems, `@Service` is also the right tool for **high-volume writes that do not need write-side invariants**. Because a service runs with maximum parallelism and writes **directly to its datastore**, it bypasses the `@Aggregate` → event → `@Projector` pipeline and the serialisation that pipeline imposes per context. This makes it ideal for data flows like IoT/sensor telemetry, high-volume logging, or append-only ingestion, where throughput matters and ordering/exactly-once consistency is not an application constraint.

Use an `@Aggregate` (with `@Projector`/`@Projection`) when the write side must enforce ordered, exactly-once, invariant-preserving rules; reach for a direct-write `@Service` when those guarantees are unnecessary and throughput is the priority.

{% hint style="info" %}
For the full reasoning and a per-flow decision rule, see [Choosing a Write Strategy: Reads vs Writes](/evento-framework/component/choosing-a-write-strategy.md).
{% endhint %}

#### Using `@Service` with Command Handlers

Services leverage `@CommandHandler` methods to handle incoming commands. These command handlers typically follow this pattern:

1. **Command Reception:** The command handler receives a specific command object as input.
2. **Command Validation (Optional):** You might include validation logic within the handler to ensure the received command is valid before proceeding.
3. **Interaction with External Systems:** The service interacts with external systems (e.g., databases, APIs) based on the command requirements.
4. **Event Emission (Optional):** In some scenarios, the service might emit domain events after performing its operation to update the system state.

**Example: `@Service` in Action**

```java
@Service
public class NotificationService {

    private final ExternalNotificationService service;

    public NotificationService(ExternalNotificationService service) {
       this.service = service;
    }

    @CommandHandler
    NotificationSentEvent handle(NotificationSendCommand command,
                          CommandGateway commandGateway,
                          CommandMessage<NotificationSendCommand> commandMessage) {
       if(command.getBody() == null){
          throw new RuntimeException("error.body.null");
       }
       Utils.logMethodFlow(this, "handle", command, "BEGIN");
       String notificationId = service.send(command.getBody());
       Utils.logMethodFlow(this, "handle", command, "END");
       return new NotificationSentEvent(notificationId, command.getBody());
    }

    @CommandHandler
    void handle(NotificationSendSilentCommand command) {
       Utils.logMethodFlow(this, "handle", command, "BEGIN");
       service.send(command.getBody());
       Utils.logMethodFlow(this, "handle", command, "END");
    }
}
```

The provided code example showcases a `NotificationService` class:

* The class is annotated with `@Service`, indicating it's a service component.
* It has a constructor that injects an `ExternalNotificationService` dependency.
* It defines two `@CommandHandler` methods:
  * The first method handles `NotificationSendCommand` and validates the presence of a message body before sending the notification through the external service and emitting a `NotificationSentEvent`.
  * The second method handles `NotificationSendSilentCommand` and simply sends the notification without emitting an event (potentially a stateless operation).

#### Key Takeaways

* `@Service` helps define classes that perform specific operations outside the domain logic.
* Services can be stateless, interacting with external systems without managing internal state, or stateful, maintaining their own data.
* `@Service` often works in conjunction with `@CommandHandler` methods to handle commands and trigger interactions with external systems.

By understanding `@Service`, you can effectively build services that bridge the gap between your domain and the external world in your Evento applications.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eventoframework.com/evento-framework/component/service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.