# Eo / Ejb / Service

## Overview

The `eo.ejb.service` package defines the core order-processing backbone of the application. At its center is `OrderService`, which coordinates a typical e-commerce order lifecycle — charging a payment, reserving inventory, and notifying the customer. It pulls together several supporting classes (`PaymentGateway`, `InventoryService`, `NotificationService`, `DataSource`) through dependency injection, and includes an example (`UnresolvedInjection`) of a class with an unresolved reference that is useful for diagnosing injection wiring issues.

## Key Classes and Interfaces

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

`OrderService` is the central orchestrator in this package. It exposes a single public method, `placeOrder()`, which coordinates the end-to-end order flow.

**Dependencies (injected via annotations):**

| Field | Annotation | Source |
|---|---|---|
| `paymentGateway` | `@Inject` (JSR-330) | `PaymentGateway` |
| `inventory` | `@EJB` | `InventoryService` |
| `notificationService` | `@Autowired` (Spring) | `NotificationService` |
| `dataSource` | `@Resource` (JSR-250) | `DataSource` |

**Key method:**

- **`placeOrder()`** — Executes the three-step order pipeline: it calls `paymentGateway.charge()`, then `inventory.reserve()`, then `notificationService.notify()`. The method returns `void`, meaning callers fire-and-forget; errors in any step are not caught or logged here.

**Design notes:**
- `OrderService` mixes four different injection frameworks (`javax.inject.Inject`, `@EJB`, Spring's `@Autowired`, and `@Resource`). This is unusual and suggests the code may have been migrated between technologies, or serves as a regression test for injection resolution. Each field uses the annotation most natural to its source dependency.
- The method body is currently just three sequential calls with no error handling, transaction boundary, or rollback logic. In production, this would likely need wrapping in a `@TransactionAttribute` or explicit try/catch.

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

A thin wrapper around external payment processing.

**Key method:**

- **`charge()`** — Initiates a payment charge. Returns `void`. The body is a stub, so the actual payment network interaction is not yet implemented.

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

Handles inventory reservation for ordered items.

**Key method:**

- **`reserve()`** — Locks inventory quantities for a given order. Returns `void`. The body is a stub.

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

Sends notifications (e.g., confirmation emails) after an order is processed.

**Key method:**

- **`notify()`** — Dispatches a notification to the customer. Returns `void`. The body is a stub.

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

Provides database connections for the application.

**Key method:**

- **`getConnection()`** — Returns a database connection. Returns `void` (the implementation body is empty; in a real system this would return a `java.sql.Connection`).

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

An example class with a deliberately unresolved injection reference. It injects a field of type `UnknownType`, which does not exist in this package or anywhere else in the index.

**Key method:**

- **`process()`** — Calls `unknown.execute()`. Because `unknown` is injected with a type that cannot be resolved, this class will fail to compile or deploy. It exists as a diagnostic example for testing dependency resolution tooling.

## How It Works

### Typical Order Flow

When a client invokes `OrderService.placeOrder()`, the following sequence occurs:

```mermaid
sequenceDiagram
    participant C as Caller
    participant O as OrderService
    participant P as PaymentGateway
    participant I as InventoryService
    participant N as NotificationService

    C->>O: placeOrder()
    O->>P: charge()
    O->>I: reserve()
    O->>N: notify()
```

The flow is strictly sequential:

1. **Payment charge** — `PaymentGateway.charge()` processes the customer's payment.
2. **Inventory reserve** — `InventoryService.reserve()` locks the ordered quantities.
3. **Notification** — `NotificationService.notify()` sends a confirmation to the customer.

### Injection Wiring

`OrderService` demonstrates multiple injection strategies side by side. Here is the dependency map:

```mermaid
flowchart LR
    OA["OrderService"] --> P["PaymentGateway"]
    OA --> I["InventoryService"]
    OA --> N["NotificationService"]
    OA --> D["DataSource"]
```

The coexistence of `@Inject`, `@EJB`, `@Autowired`, and `@Resource` on the same class is notable:

- `@Inject` (JSR-330) for `PaymentGateway` — standard CDI injection.
- `@EJB` — EJB-specific injection, used here for `InventoryService`.
- `@Autowired` — Spring's injection mechanism, used for `NotificationService`.
- `@Resource` (JSR-250) for `DataSource` — common for JNDI-looked up resources like data sources.

This mixture may indicate a codebase in transition, or a test fixture to validate that injection frameworks can coexist. In a production system, you should pick one injection strategy per project to avoid confusion and framework conflicts.

## Data Model

This package does not define entity classes, DTOs, or value objects. The classes are purely service-layer thin wrappers — most methods are stubs returning `void`. The only structural "data" is the injected field types that define the runtime dependency graph.

## Dependencies and Integration

### Internal package dependencies

All four collaborator classes (`PaymentGateway`, `InventoryService`, `NotificationService`, `DataSource`) live in the same `eo.ejb.service` package. `OrderService` depends on all of them through injection.

### External imports

`OrderService` imports from three different frameworks:

- `javax.inject.Inject` — JSR-330 (standard dependency injection)
- `javax.ejb.EJB` — EJB 3.x container injection
- `org.springframework.beans.factory.annotation.Autowired` — Spring framework
- `javax.annotation.Resource` — JSR-250 common annotations

`UnresolvedInjection` imports `javax.inject.Inject` and references a type (`UnknownType`) that is not present in the codebase, making it a useful test case for unresolved dependency detection.

### No external library dependencies

Beyond the standard Java EE / CDI / Spring annotations above, no other third-party libraries are imported.

## Notes for Developers

- **Stub methods**: All service methods (`charge()`, `reserve()`, `notify()`, `getConnection()`) have empty method bodies. Implementation placeholders need to be filled in before this code can process real orders.
- **Mixed injection frameworks**: The combination of `@Inject`, `@EJB`, `@Autowired`, and `@Resource` on `OrderService` is atypical. Consider consolidating to a single framework to reduce configuration complexity and avoid classpath conflicts.
- **No error handling**: `placeOrder()` does not catch exceptions. If `charge()` succeeds but `reserve()` fails, the payment has already been processed with no rollback. Any production extension should add try/catch blocks or use container-managed transactions.
- **`UnresolvedInjection`**: This class references a non-existent `UnknownType`. It is likely intentionally included as a test case or leftover from refactoring. Remove or resolve the `UnknownType` dependency before production deployment.
- **`DataSource` unused**: Although `OrderService` injects `DataSource` via `@Resource`, the `placeOrder()` method never calls `getConnection()`. The data source is wired but not currently used.