# Eo / Ejb / Service

## Overview

The `eo.ejb.service` package provides the core service layer for an EJB-based application, wrapping business operations behind enterprise Java beans and managed dependencies. It contains order-processing logic, infrastructure callbacks (inventory reservation, notifications, payment processing), and two standalone EJB beans. The package demonstrates a mixed dependency injection stack that supports Jakarta EE (`@Inject`, `@EJB`, `@Resource`) and Spring (`@Autowired`) annotations side by side.

## Key Classes and Interfaces

### [OrderService](OrderService.java:8)

**Purpose** — The central orchestrator for the order placement workflow. It coordinates three independent services — payment, inventory, and notifications — by invoking them in a fixed sequence.

**Why it exists** — Order processing is a cross-cutting concern that touches multiple bounded contexts (billing, stock management, customer communication). `OrderService` acts as the single entry point, keeping calling code simple and ensuring the services are called in the correct order.

#### Dependency injection

The class demonstrates four different DI mechanisms, all co-existing in one class:

| Field | Type | Annotation | Framework |
|---|---|---|---|
| `paymentGateway` | `PaymentGateway` | `@Inject` | CDI (Jakarta EE) |
| `inventory` | `InventoryService` | `@EJB` | Jakarta EE EJB |
| `notificationService` | `NotificationService` | `@Autowired` | Spring Framework |
| `dataSource` | `DataSource` | `@Resource` | Jakarta EE resource injection |

This mix of DI annotations is notable — the package is not committed to a single DI container. This may reflect a migration in progress or a polyglot deployment environment.

#### Key method: `placeOrder()`

```java
public void placeOrder() {
    paymentGateway.charge();
    inventory.reserve();
    notificationService.notify();
}
```

- **What it does** — Places an order by executing three steps in sequence:
  1. **Charge** the payment (`PaymentGateway.charge()`)
  2. **Reserve** inventory (`InventoryService.reserve()`)
  3. **Notify** interested parties (`NotificationService.notify()`)
- **Parameters** — None (a stub method; in production these would accept an order payload)
- **Returns** — `void`
- **Side effects** — Each called method performs its own external operation (payment charge, stock reservation, notification dispatch).
- **Important design notes** — The order of operations is deliberate: payment is processed before inventory is reserved, which protects against reserving stock for an order that cannot be paid. There is no explicit error handling or rollback logic in this stub, which suggests the real implementation likely delegates exception handling to the EJB container or that this is a scaffold.

### [PaymentGateway](PaymentGateway.java:3)

**Purpose** — Handles payment processing operations.

**Design role** — This is a dependency of `OrderService`. The `charge()` method is called first in the order placement flow. The current implementation is a stub with an empty body, which indicates that either the real payment logic lives in a subclass / external module, or this is a placeholder for integration with a real payment provider.

#### Key method: `charge()`

- **What it does** — Processes a payment charge.
- **Parameters** — None (stub)
- **Returns** — `void`
- **Side effects** — None in the stub; in a real implementation this would communicate with a payment processor.

### [InventoryService](InventoryService.java:3)

**Purpose** — Manages inventory reservation operations.

**Design role** — Injected into `OrderService` via `@EJB`. The `reserve()` method is invoked after payment succeeds, locking the necessary stock for the pending order.

#### Key method: `reserve()`

- **What it does** — Reserves inventory for an order.
- **Parameters** — None (stub)
- **Returns** — `void`
- **Side effects** — None in the stub; in production this would update stock levels or create a reservation record.

### [NotificationService](NotificationService.java:3)

**Purpose** — Sends notifications related to order processing.

**Design role** — Injected into `OrderService` via Spring's `@Autowired`. The `notify()` method is called as the final step in the order flow, likely sending confirmation emails, SMS messages, or updating dashboards.

#### Key method: `notify()`

- **What it does** — Dispatches notifications.
- **Parameters** — None (stub)
- **Returns** — `void`
- **Side effects** — None in the stub; in production this would invoke email/SMS push services or message queues.

### [EJBWithArgs](EJBWithArgs.java:5)

**Purpose** — Demonstrates EJB dependency injection by name using the `@EJB(name = "...")` annotation.

**Design role** — Unlike `OrderService`, which injects dependencies directly as typed fields, `EJBWithArgs` uses the `@EJB` annotation with a JNDI-style `name` attribute. This is the older, name-based injection style. It looks up a bean registered as `"myBean"` and delegates to `MyService.process()`.

#### Key method: `run()`

- **What it does** — Delegates to the injected `MyService.process()` call.
- **Parameters** — None
- **Returns** — `void`
- **Side effects** — Triggers the business logic inside `MyService`.

### [StatelessBean](StatelessBean.java:5)

**Purpose** — A Jakarta EE `@Stateless` session bean that executes a simple task.

**Design role** — Demonstrates the EJB 3.0 `@Stateless` annotation, which tells the container to pool and manage the lifecycle of this bean. Stateless beans are the default EJB type and are ideal for stateless business operations where thread safety and connection management are delegated to the container.

#### Key method: `execute()`

- **What it does** — Prints a status message to standard output (`"stateless execute"`).
- **Parameters** — None
- **Returns** — `void`
- **Side effects** — Writes to `System.out`. In a real application this would perform a business operation, likely with transaction management provided by the EJB container.

## How It Works

### The order placement flow

The primary business flow runs through `OrderService.placeOrder()`. Here is the step-by-step sequence:

```mermaid
flowchart TD
    subgraph order["Order Processing"]
        A["OrderService.placeOrder"] --> B["PaymentGateway.charge"]
        A --> C["InventoryService.reserve"]
        A --> D["NotificationService.notify"]
    end
```

1. **Payment first** — `PaymentGateway.charge()` is called. This ensures the order is financially valid before any resources are committed.
2. **Inventory reservation** — `InventoryService.reserve()` locks the needed stock. This happens after payment because reserving inventory that cannot be sold would waste stock availability.
3. **Notification** — `NotificationService.notify()` fires after both financial and inventory steps complete, signaling that the order has been successfully processed.

The sequential, fire-and-forget pattern in the stub suggests that a production implementation would likely use declarative transaction management (via the EJB container) to ensure all-or-nothing semantics.

### Dependency injection patterns

The package showcases four DI approaches co-existing:

```mermaid
flowchart TD
    A["OrderService"] --> B["@Inject / CDI"]
    A --> C["@EJB / Jakarta EE EJB"]
    A --> D["@Autowired / Spring"]
    A --> E["@Resource / Jakarta EE resource"]

    F["EJBWithArgs"] --> G["@EJB with JNDI name"]
```

This mix of annotations is architecturally significant:

- **`@Inject`** — The modern Jakarta Contexts and Dependency Injection (CDI) standard. Used for `PaymentGateway`.
- **`@EJB`** — The EJB-specific injection annotation. Used for `InventoryService` and by `EJBWithArgs`.
- **`@Autowired`** — Spring Framework's annotation, indicating Spring beans are also available in the deployment environment. Used for `NotificationService`.
- **`@Resource`** — Used for injecting container-managed resources like JDBC `DataSource`s.

## Data Model

This package does not define any entity, DTO, or data model classes. All data structures are likely passed as parameters through method calls or managed by external services. The `OrderService.placeOrder()` stub has no parameters, suggesting that in a full implementation, order data would be passed as a domain object (e.g., an `Order` entity or request DTO).

## Dependencies and Integration

### Internal dependencies

All classes in this package depend on each other through the dependency injection layer:

| Producer | Consumed by | Injection style |
|---|---|---|
| `PaymentGateway` | `OrderService` | `@Inject` |
| `InventoryService` | `OrderService` | `@EJB` |
| `NotificationService` | `OrderService` | `@Autowired` |
| `MyService` | `EJBWithArgs` | `@EJB(name = "myBean")` |

### External dependencies

- **Jakarta EE / Java EE** — `javax.ejb.EJB`, `javax.ejb.Stateless`, `javax.inject.Inject`, `javax.annotation.Resource`
- **Spring Framework** — `org.springframework.beans.factory.annotation.Autowired`
- **JDBC** — `javax.sql.DataSource` (referenced as a `@Resource` field)

The presence of both Jakarta EE and Spring annotations on the same class is unusual and worth noting: it suggests the application may be running in a container that supports both DI ecosystems simultaneously (such as WildFly with Spring extensions), or the project is in a migration state.

## Notes for Developers

- **Stub implementations** — `PaymentGateway`, `InventoryService`, and `NotificationService` all have empty method bodies. These are scaffolds. Look for subclasses or external modules for the real implementations.
- **Mixed DI annotations** — `OrderService` uses four different DI annotations. If you are adding new dependencies, be aware that the package does not enforce a single DI standard. Consider which framework is the "canonical" one for new additions.
- **No error handling in `placeOrder()`** — The current implementation has no try/catch blocks or compensation logic. If `charge()` succeeds but `reserve()` fails, the payment is already processed and there is no automatic rollback. Production code should add transactional semantics or explicit compensation steps.
- **`EJBWithArgs` uses name-based injection** — Unlike the field-injection in `OrderService`, `EJBWithArgs` uses `@EJB(name = "myBean")`, which performs a JNDI lookup. This is a legacy pattern; prefer direct field injection (`@EJB`) where possible for clarity.
- **`StatelessBean` is a standalone session bean** — It is not wired as a dependency of any other class in this package. It likely serves as a remote-facing endpoint or a scheduled task entry point.
- **`notify()` naming convention** — The method is named `notify()`, which shadows the `Object.notify()` method in Java. While technically legal (different signatures), this can cause confusion in code reviews and IDE autocomplete. Consider renaming to `sendNotification()` or similar for clarity.