# Eo / Ejb / Service

## Overview

The `eo.ejb.service` package provides the core business services for an order-processing workflow. It coordinates four primary operations — payment processing, inventory reservation, notification dispatch, and database connectivity — through an orchestrating [`OrderService`](OrderService.java). One additional class, [`UnresolvedInjection`](UnresolvedInjection.java), documents a known compilation issue involving a missing type referenced via dependency injection.

## Key Classes and Interfaces

### [`OrderService`](OrderService.java)

`OrderService` is the central orchestrator in this package. It brings together all supporting services through dependency injection and exposes the primary business operation: placing an order.

**Injection mechanisms** — `OrderService` uses four different injection annotations, each pulling in a different framework or spec:

| Field | Injection Annotation | Framework / Spec |
|---|---|---|
| `paymentGateway` | `@Inject` | JSR-330 (Dependency Injection for Java) |
| `inventory` | `@EJB` | EJB 3.x (Enterprise JavaBeans) |
| `notificationService` | `@Autowired` | Spring Framework |
| `dataSource` | `@Resource` | JSR-250 (Common Annotations) |

This mixed-use of injection styles is unusual and suggests the system may be in the process of migrating between frameworks, or that different services were acquired/developed by different teams using different ecosystems.

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

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

- **Purpose**: Executes the full order-placing flow.
- **Parameters**: None.
- **Return**: `void`.
- **Side effects**: Invokes each dependency in a fixed sequence:
  1. `paymentGateway.charge()` — charges the customer.
  2. `inventory.reserve()` — reserves the ordered items.
  3. `notificationService.notify()` — sends a confirmation notification.
- **Notes**: The method is synchronous and runs each step sequentially. If any step throws an exception, subsequent steps will not execute. There is no explicit transaction management or rollback logic visible in this method.

### [`PaymentGateway`](PaymentGateway.java)

A standalone service class responsible for processing payments. Its single method, `charge()`, is called by `OrderService` as the first step in `placeOrder()`.

- **Key method — `charge()`**: Processes a payment. Currently a stub (empty body), awaiting implementation.

### [`InventoryService`](InventoryService.java)

Handles inventory reservation. Injected into `OrderService` via `@EJB`, indicating it is expected to run as an EJB component within an application server.

- **Key method — `reserve()`**: Reserves stock for the order. Currently a stub (empty body), awaiting implementation.

### [`NotificationService`](NotificationService.java)

Handles sending notifications (e.g., order confirmations). Injected via Spring's `@Autowired`, which ties it to the Spring IoC container rather than the EJB or JSR-330 container.

- **Key method — `notify()`**: Dispatches the notification. Currently a stub (empty body), awaiting implementation.

### [`DataSource`](DataSource.java)

Provides database connectivity for the order services. Injected into `OrderService` via `@Resource` (JSR-250), the standard way to look up a resource (such as a JNDI datasource) in a Java EE environment.

- **Key method — `getConnection()`**: Returns a database connection. Currently a stub (empty body), awaiting implementation.

### [`UnresolvedInjection`](UnresolvedInjection.java)

A class that demonstrates a compilation problem. It declares a field of type `UnknownType` annotated with `@Inject`, but `UnknownType` does not exist anywhere in the codebase.

```java
@Inject
private UnknownType unknown;

public void process() {
    unknown.execute();
}
```

This class will **fail to compile** because `UnknownType` is unresolved. It serves as a useful cautionary example: when using dependency injection, the injected type must be resolvable by the DI container at build time. If a dependency is removed or renamed, any class that depends on it through `@Inject` will immediately surface the breakage as a compilation error.

## How It Works — The Order Placement Flow

The primary use case this package supports is placing an order. The flow through `OrderService.placeOrder()` proceeds as follows:

```mermaid
flowchart LR
    A["OrderService"] --> B["PaymentGateway"]
    A --> C["InventoryService"]
    A --> D["NotificationService"]
    A --> E["DataSource"]
```

1. **`paymentGateway.charge()`** — The customer is charged first. This ordering is deliberate: you want to secure payment before committing inventory.
2. **`inventory.reserve()`** — After payment succeeds, stock is reserved for the order.
3. **`notificationService.notify()`** — Once both payment and reservation succeed, a confirmation is sent to the customer.

The sequence is synchronous and unguarded — an exception in any step halts the flow and the subsequent steps are skipped. In a production system, you would likely wrap this in a transactional boundary (e.g., `@TransactionAttribute(REQUIRED)` on the EJB) and implement compensation logic (e.g., refunding the charge if reservation fails).

### Dependency Injection at a Glance

```mermaid
flowchart TD
    A["OrderService"] --> B["@Inject PaymentGateway"]
    A --> C["@EJB InventoryService"]
    A --> D["@Autowired NotificationService"]
    A --> E["@Resource DataSource"]
    F["UnresolvedInjection"] --> G["@Inject UnknownType"]
```

The use of four different injection annotations in a single class is worth noting:

- **`@Inject`** (JSR-330) is portable across CDI-compatible containers (Weld, OpenWebBeans).
- **`@EJB`** is an EJB-specific annotation requiring an application server runtime.
- **`@Autowired`** is Spring-specific, meaning `OrderService` also depends on the Spring Framework classpath.
- **`@Resource`** is the Java EE standard for resource lookups.

This mixed dependency-injection stack is atypical. It suggests the system is either:
- Migrating from Spring to EJB (or vice versa), with `@Autowired` used on the path out.
- A polyglot microservice environment where different teams picked different frameworks.

## Data Model

This package does not define entity or DTO classes. The services operate through method calls with no visible data structures. Any data would be passed as parameters in the stub methods, which are currently empty. As implementation progresses, expect domain objects (e.g., `Order`, `OrderItem`, `PaymentResult`) to be introduced.

## Dependencies and Integration

- **JSR-330** (`javax.inject.Inject`): Used by `OrderService` and `UnresolvedInjection` for portable DI.
- **JSR-38 (EJB 3.2)** (`javax.ejb.EJB`): Used by `OrderService` to inject `InventoryService` as an enterprise bean.
- **Spring Framework** (`org.springframework.beans.factory.annotation.Autowired`): Used by `OrderService` to inject `NotificationService`.
- **JSR-250** (`javax.annotation.Resource`): Used by `OrderService` to inject `DataSource`.

The package does not depend on any external packages beyond these standard frameworks. There are no cross-module relationships detected in the index — all classes are self-contained within `eo.ejb.service`.

## Notes for Developers

- **All service methods are currently stubs.** The bodies of `charge()`, `reserve()`, `notify()`, and `getConnection()` are empty. Implementation is needed before these services can be used in production.
- **The `@EJB` / `@Autowired` mix requires both an EJB container and Spring on the classpath.** Ensure your deployment environment includes both. If you remove Spring from the classpath, `@Autowired` will become a compile-time error.
- **`UnresolvedInjection` will not compile.** The `UnknownType` class it references does not exist. This is likely a placeholder or leftover from a refactoring. Before merging changes, resolve or remove this class.
- **No error handling in `placeOrder()`.** If `paymentGateway.charge()` throws, `inventory.reserve()` and `notificationService.notify()` never run. Consider wrapping the method in a transaction or adding explicit try/catch / compensation logic.
- **No idempotency guarantees.** Calling `placeOrder()` twice will charge the customer twice and reserve inventory twice. An idempotency key or similar guard should be added before production use.