# Eo / Ejb / Service

## Overview

The `eo.ejb.service` package provides the core business service layer for an order-processing system built on Java EE Enterprise JavaBeans (EJB). It coordinates the key steps involved in placing an order — charging a payment, reserving inventory, and sending notifications — through [OrderService](OrderService.java:8), which acts as the central orchestrator. The package also includes a stateless EJB ([StatelessBean](StatelessBean.java:5)) for generic background tasks and a demo class ([EJBWithArgs](EJBWithArgs.java:5)) illustrating `@EJB` injection by name.

## Key Classes and Interfaces

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

The central business facade for the order workflow. It brings together three distinct services — payment, inventory, and notification — and wires them together using multiple injection mechanisms.

**Dependencies and injection strategies**

[OrderService](OrderService.java:8) demonstrates a mixed-strategy dependency injection setup, using four different annotations:

| Field | Type | Annotation | Injection framework |
|---|---|---|---|
| `paymentGateway` | [PaymentGateway](PaymentGateway.java:3) | `@Inject` | CDI (JSR-346) |
| `inventory` | [InventoryService](InventoryService.java:3) | `@EJB` | EJB dependency injection |
| `notificationService` | [NotificationService](NotificationService.java:3) | `@Autowired` | Spring Framework |
| `dataSource` | `DataSource` | `@Resource` | Java EE resource injection |

This coexistence of CDI, EJB, Spring, and Java EE resource injection is notable — it suggests this module may be in a transition period or running in a container that supports all four (e.g. WildFly with Spring integration).

**Key method — `placeOrder()`**

- **Location**: [OrderService.java:21](OrderService.java:21)
- **Signature**: `public void placeOrder()`
- **Behavior**: Executes the order lifecycle in a fixed sequence:
  1. Calls `paymentGateway.charge()` to process the customer's payment.
  2. Calls `inventory.reserve()` to lock the ordered items in stock.
  3. Calls `notificationService.notify()` to alert the customer or internal systems.
- **Side effects**: None beyond the delegated calls. The stubs in the current implementation are no-ops; production code would likely perform actual transactions, database writes, and external communication.
- **Order matters**: Payment is charged first, then inventory is reserved, then notification fires. This order avoids the awkward case where inventory is reserved but payment later fails (though no compensation / rollback logic is present in the current stub).

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

A service class responsible for processing payment charges.

- **Key method — `charge()`**: Located at [PaymentGateway.java:4](PaymentGateway.java:4). Currently a stub (empty method body). In a production system this would interface with a payment processor (e.g. Stripe, PayPal, or an internal ledger) to charge the customer.

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

A service class responsible for managing inventory reservations.

- **Key method — `reserve()`**: Located at [InventoryService.java:4](InventoryService.java:4). Currently a stub. In production, this would decrement stock levels, place holds on reserved items, and potentially validate availability before committing.

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

A service class responsible for sending notifications related to order events.

- **Key method — `notify()`**: Located at [NotificationService.java:4](InventoryService.java:4). Currently a stub. In production, this would dispatch order confirmations via email, SMS, push notifications, or internal event publishing.

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

A standard Java EE stateless session bean. It is annotated with `@Stateless` ([StatelessBean.java:7](StatelessBean.java:7)), which means the container can pool and share instances across multiple callers.

- **Key method — `execute()`**: Located at [StatelessBean.java:7](StatelessBean.java:7). Currently prints `"stateless execute"` to `stdout`. This appears to be a generic, reusable bean for background or utility tasks that don't need to maintain conversational state between invocations.

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

A demonstration class showing how to look up and use an EJB by its JNDI name.

- Declares a field `service` of type `MyService` (not defined in this package) annotated with `@EJB(name = "myBean")` ([EJBWithArgs.java:7](EJBWithArgs.java:7)).
- **Key method — `run()`**: Located at [EJBWithArgs.java:9](EJBWithArgs.java:9). Delegates to `service.process()`. This pattern — injecting an EJB by name and then calling a business method — is a common EJB lookup pattern used when the target bean is deployed in a different module or needs a specific JNDI binding.

## How It Works

The primary workflow in this package is the order placement flow, orchestrated by [OrderService](OrderService.java:8). Here's the step-by-step flow:

```mermaid
sequenceDiagram
    participant Caller
    participant OS as OrderService
    participant PG as PaymentGateway
    participant IS as InventoryService
    participant NS as NotificationService
    Caller->>OS: placeOrder()
    OS->>PG: charge()
    OS->>IS: reserve()
    OS->>NS: notify()
```

1. **Caller invokes `OrderService.placeOrder()`** — This is the entry point for the order workflow.
2. **Payment charge** — `PaymentGateway.charge()` is called first. This captures the customer's funds before any inventory is committed.
3. **Inventory reservation** — `InventoryService.reserve()` locks the items. Charging first ensures that reserved stock has been paid for.
4. **Notification** — `NotificationService.notify()` fires last, informing relevant parties that the order has been processed.

At present, all three downstream services are stub implementations (empty method bodies), so the current `placeOrder()` call is effectively a no-op. The structure, however, establishes the contract and ordering for future production implementations.

## Data Model

This package does not define entity classes or DTOs. All data transfer and state management is delegated to the downstream services ([PaymentGateway](PaymentGateway.java:3), [InventoryService](InventoryService.java:3), [NotificationService](NotificationService.java:3)), which are expected to define their own models externally.

## Dependencies and Integration

### Internal relationships

```mermaid
flowchart TD
    OS["OrderService"] --> PG["PaymentGateway"]
    OS --> IS["InventoryService"]
    OS --> NS["NotificationService"]
    SB["StatelessBean"]
    EA["EJBWithArgs"] --> ES["MyService (external)"]
```

- [OrderService](OrderService.java:8) is the sole orchestrator, depending on all three leaf services ([PaymentGateway](PaymentGateway.java:3), [InventoryService](InventoryService.java:3), [NotificationService](NotificationService.java:3)).
- [StatelessBean](StatelessBean.java:5) stands alone as a generic stateless EJB.
- [EJBWithArgs](EJBWithArgs.java:5) depends on `MyService`, which is defined outside this package and injected via its `@EJB(name = "myBean")` binding.

### External frameworks

| Framework | Usage | Classes |
|---|---|---|
| Java EE / EJB | `@Stateless`, `@EJB` | [StatelessBean](StatelessBean.java:5), [OrderService](OrderService.java:8), [EJBWithArgs](EJBWithArgs.java:5) |
| CDI (JSR-346) | `@Inject` | [OrderService](OrderService.java:8) |
| Spring Framework | `@Autowired` | [OrderService](OrderService.java:8) |
| Java EE Resource | `@Resource` | [OrderService](OrderService.java:8) |

## Notes for Developers

- **Mixed injection frameworks**: [OrderService](OrderService.java:8) uses four different injection annotations across its fields. When adding new dependencies, prefer one framework consistently to avoid confusion and potential lifecycle conflicts. CDI `@Inject` is the recommended default for new code in modern Java EE containers.
- **Stub implementations**: All leaf services ([PaymentGateway](PaymentGateway.java:3), [InventoryService](InventoryService.java:3), [NotificationService](NotificationService.java:3)) have empty method bodies. Production logic needs to be implemented in these classes.
- **No error handling**: The current `placeOrder()` implementation does not handle failures from any of the three downstream calls. If `charge()` succeeds but `reserve()` fails, for example, the payment has already been taken with no compensation. Consider adding transaction management (`@TransactionAttribute`) or explicit rollback logic.
- **Execution order matters**: `placeOrder()` charges payment before reserving inventory. If this ordering is intentional (to prevent reserved-but-unpaid inventory), document that rationale. If not, consider swapping the order or using a JTA transaction to allow atomic rollback.
- **StatelessBean** is a standard stateless EJB — the container manages pooling and thread safety. Do not store instance state in fields of `@Stateless` beans.
- **EJBWithArgs** demonstrates JNDI-name-based injection (`@EJB(name = "myBean")`). This pattern is useful when the target bean lives in a different deployment unit or when you need an explicit JNDI binding name.