# Eo / Ejb / Service

## Overview

The `eo.ejb.service` package contains lightweight EJB (Enterprise JavaBean) components for the EO system. It provides both a stateless session bean (`StatelessBean`) for unmanaged background-style operations and an injection-aware client (`EJBWithArgs`) that wires in external `MyService` dependencies via the `@EJB` annotation. The package demonstrates common EJB patterns used throughout the codebase.

## Key Classes and Interfaces

### `EJBWithArgs`

Source: [EJBWithArgs.java](EJBWithArgs.java)

`EJBWithArgs` is a container-managed class that acts as a thin client for injecting and delegating to an external service. Its sole responsibility is to hold an injected `MyService` instance and forward a single call to it.

- **Dependency injection**: The field `service` is annotated with `@EJB(name = "myBean")`, telling the EJB container to inject a reference to a remote or local bean registered under the JNDI name `"myBean"`. This is the standard EJB lookup mechanism — the container resolves the reference at deployment time.
- **`run()` method** — lines 9-11: The only public method. It delegates entirely to `service.process()`. There is no local business logic; `run()` is a pass-through that exists so that another EJB or entry-point can call into this class and it will, in turn, invoke the injected service.

```java
public class EJBWithArgs {
    @EJB(name = "myBean")
    private MyService service;

    public void run() {
        service.process();
    }
}
```

### `StatelessBean`

Source: [StatelessBean.java](StatelessBean.java)

`StatelessBean` is a plain stateless session bean, marked with the `@Stateless` annotation. It represents the simplest possible EJB — a container-managed component with no conversational state and a single public method.

- **`@Stateless` annotation**: Declares this class as a stateless session bean. The EJB container will pool instances and delegate method calls to any available instance from the pool. No instance fields are used (beyond those injected by the container), making it inherently thread-safe.
- **`execute()` method** — lines 7-9: A no-argument, void-returning method that performs a simple side-effect: printing `"stateless execute"` to standard output. This appears to be a placeholder or demo bean, likely used for testing the EJB container setup or as a template for more substantial beans.

```java
@Stateless
public class StatelessBean {
    public void execute() {
        System.out.println("stateless execute");
    }
}
```

## How It Works

### Typical usage flow

There are two distinct usage patterns in this package:

1. **Injection-based delegation** (`EJBWithArgs.run()`):
   - An instance of `EJBWithArgs` is created by the EJB container.
   - The container resolves the `@EJB(name = "myBean")` annotation and injects a reference to a `MyService` implementation.
   - When `run()` is invoked, the instance has no local logic — it simply forwards the call to `service.process()`.

2. **Direct stateless invocation** (`StatelessBean.execute()`):
   - `StatelessBean` can be looked up via JNDI or injected by another component.
   - Because it is `@Stateless`, the container may pool multiple instances and route calls efficiently.
   - Calling `execute()` produces the `"stateless execute"` output on stdout.

### Design decisions

- **Minimalism**: Both classes are intentionally small. `EJBWithArgs` contains zero business logic, serving purely as an injection and delegation point. `StatelessBean` is a minimal template showing how a stateless bean is structured.
- **Separation of concerns**: Injection concerns (`@EJB`) are handled by the container, while the stateless bean's business method (`execute`) is trivially isolated with no side effects beyond logging.

## Data Model

This module has no data model classes (no entities, DTOs, or value objects). The only external type referenced is `MyService`, which is resolved through JNDI at runtime.

## Dependencies and Integration

### Internal dependencies

| Dependency | How it's used |
|---|---|
| `javax.ejb.EJB` | Imports the `@EJB` annotation for dependency injection in `EJBWithArgs`. |
| `javax.ejb.Stateless` | Imports the `@Stateless` annotation in `StatelessBean`. |

### External dependencies

| External type | Used in | How |
|---|---|---|
| `MyService` | `EJBWithArgs` | Injected via `@EJB(name = "myBean")`, then invoked through `service.process()`. |

## Diagram

The following flowchart illustrates the relationships between the classes in this package:

```mermaid
flowchart TD
    EJB["EJBWithArgs"] -->|injects| BEAN["@EJB MyService service"]
    EJB -->|invokes| RUN["run() method"]
    BEAN -->|called by| PROCESS["service.process()"]
    STATE["StatelessBean"] -->|annotated with| SLS["@Stateless"]
    STATE -->|implements| EXECUTE["execute() method"]
```

## Notes for Developers

- **`MyService` is external**: The `EJBWithArgs` class depends on `MyService` being available in the container under the JNDI name `"myBean"`. If the bean is missing or misconfigured, injection will fail at deployment.
- **`StatelessBean` is a template**: The current implementation only prints to stdout. When extending it, keep the stateless contract in mind — do not add instance fields that hold conversational state, as those will not be safe across pooled invocations.
- **No child modules**: This package is a leaf in the module hierarchy. There are no sub-packages to navigate within it.
- **Package-level location**: This package sits at the root of the `eo` module (`eo.ejb.service`), making it easily discoverable.