# Repository Overview

Welcome! This repository contains a small **Enterprise JavaBeans (EJB)** application organized under the `eo.ejb` package. It provides an order-processing service layer that demonstrates common Jakarta EE patterns — JPA entity mapping, enterprise beans, and dependency injection — along with utility helpers for runtime class loading via Java reflection and a self-contained reference package for common patterns. If you're new to this codebase, start here: read the **Getting Started** section below to orient yourself, then dive into the module pages linked throughout.

---

## Overview

At its core, this project is an EJB-based order-processing system. The central piece is `OrderService`, which orchestrates a three-step order flow — charging payment, reserving inventory, and sending notifications — using managed beans. Beyond the business layer, the repository also includes:

- **JPA entity mapping** (`EntityClass`), showing how persistent data is modeled.
- **Reflection utilities** (`ReflectiveClass`, `PatternOneVar`) that demonstrate runtime class loading, a pattern used by plugins or configuration-driven architectures.
- **Simple helpers** (`PlainClass`) offering side-effect-free string templating.

The code appears to be in a scaffolding or demonstration phase: most service classes have empty method bodies, and the package mixes multiple dependency injection frameworks (Jakarta EE CDI, Spring, and EJB-specific annotations), which may reflect a migration in progress or a polyglot deployment exploration.

---

## Technology Stack

This project is built with standard **Jakarta EE / Java EE** and includes references to a few external libraries:

| Layer | Technology |
|---|---|
| **Enterprise Beans** | Jakarta EE `@Stateless`, `@EJB` |
| **Persistence** | JPA (`@Entity`, `@Table`, `@Id`, `@Column`) |
| **Dependency Injection** | Jakarta CDI (`@Inject`), `@Resource`, Spring (`@Autowired`) |
| **Resources** | JDBC `DataSource` |
| **Reflection** | JDK `java.lang.reflect` (`Class.forName`, `Method.invoke`) |

No well-known third-party frameworks beyond these were detected.

---

## Architecture

The project consists of a single top-level package (`eo.ejb`) with three sub-packages:

```mermaid
flowchart TD
    Root["eo.ejb (Root Package)"] --> Service["eo.ejb.service
(Business Layer)"]
    Root --> Wiki["eo.ejb.wiki
(Utilities)"]
    Root --> Example["eo.ejb.example
(Reference Patterns)"]

    Service --> OrderService["OrderService"]
    Service --> PaymentGateway["PaymentGateway"]
    Service --> InventoryService["InventoryService"]
    Service --> NotificationService["NotificationService"]
    Service --> EJBWithArgs["EJBWithArgs"]
    Service --> StatelessBean["StatelessBean"]

    Wiki --> PlainClass["PlainClass"]
    Wiki --> ReflectiveClass["ReflectiveClass"]

    Example --> EntityClass["EntityClass"]
    Example --> PatternOneVar["PatternOneVar"]

    OrderService --> PaymentGateway
    OrderService --> InventoryService
    OrderService --> NotificationService
```

The **service** package is the primary consumer, orchestrating the order workflow. The **wiki** package provides reflection-based utilities consumed by the service layer, and the **example** package offers reference patterns for JPA entity mapping and runtime class loading.

### The order placement flow

```mermaid
flowchart LR
    subgraph OrderProcessing["Order Processing Flow"]
        OrderService["OrderService.placeOrder"] --> PaymentGateway["PaymentGateway.charge"]
        PaymentGateway --> InventoryService["InventoryService.reserve"]
        InventoryService --> NotificationService["NotificationService.notify"]
    end
```

The order is processed in a fixed sequence: **payment** first (to validate the order is financially valid), then **inventory** reservation (locking stock only after payment succeeds), and finally **notification** dispatching (confirming the completed order). The current stub has no explicit error handling or rollback logic; in production, this would likely use EJB declarative transaction management.

---

## Module Guide

### `eo.ejb.service` — The Business Layer

This is the most functionally significant sub-package. It implements the core service layer, wrapping business operations behind enterprise Java beans.

**Key classes:**

- **`OrderService`** — The central orchestrator. Its `placeOrder()` method coordinates three services — `PaymentGateway`, `InventoryService`, and `NotificationService` — by invoking them in sequence. Notably, it demonstrates four different dependency injection mechanisms (`@Inject`, `@EJB`, `@Autowired`, `@Resource`) co-existing in one class, which is unusual and worth noting.
- **`PaymentGateway`** — Handles payment processing. Currently a stub with an empty `charge()` method.
- **`InventoryService`** — Manages inventory reservation. Currently a stub with an empty `reserve()` method. Injected via `@EJB`.
- **`NotificationService`** — Dispatches order notifications. Currently a stub with an empty `notify()` method. Injected via Spring's `@Autowired`.
- **`EJBWithArgs`** — Demonstrates the older, name-based `@EJB(name = "...")` injection style using JNDI lookups. Delegates to a `MyService.process()` call.
- **`StatelessBean`** — A standalone `@Stateless` session bean that prints a status message. Likely serves as a remote-facing endpoint or scheduled task entry point.

**Notes:**

- Payment, inventory, and notification services are all stubs with empty method bodies. The real implementation logic may live in external modules or subclasses.
- The mix of DI annotations (`@Inject` + `@EJB` + `@Autowired` + `@Resource`) on the same class suggests the application may be running in a container supporting multiple DI ecosystems, or is in a migration state.
- There is no error handling or rollback logic in `placeOrder()`'s current implementation.

### `eo.ejb.wiki` — Utility Helpers

This package provides two small but conceptually distinct utilities used by the broader service layer.

**Key classes:**

- **`PlainClass`** — A simple, side-effect-free value object for generating greeting strings. Given a name, `greet()` returns `"Hello, {name}"`. It has no external dependencies.
- **`ReflectiveClass`** — A reflection-based helper that dynamically loads classes by fully qualified name (`Class.forName()`) and invokes a hardcoded `execute()` method on them. Supports plugin-style extensibility or configuration-driven object creation.

**Notes:**

- `ReflectiveClass` is brittle — it hardcodes the method name `"execute"` and expects it to be a static, no-argument method. Failures surface as runtime exceptions.
- It uses `Class.newInstance()`, which has been deprecated since Java 9. Consider migrating to `getDeclaredConstructor().newInstance()`.
- Neither class validates that constructor parameters are non-null.

### `eo.ejb.example` — Reference Patterns

This is a self-contained demonstration package with no internal dependencies. It showcases two fundamental Java EE patterns:

**Key classes:**

- **`EntityClass`** — A JPA entity mapped to the `entity_class` database table. Holds an `id` (primary key) and a `name` field mapped to the `item_name` column. Exposes only getters (no setters), suggesting read-only access or mutations through the JPA persistence context.
- **`PatternOneVar`** — A minimal example of runtime class loading via reflection. Accepts a fully qualified class name, instantiates it via `Class.forName()`, and prints the result.

**Notes:**

- `EntityClass` has no setters, so mutations would typically happen through the JPA `EntityManager`.
- `PatternOneVar.load()` uses `Class.newInstance()`, deprecated since Java 9. The method also propagates a broad `throws Exception`, so callers must handle `ClassNotFoundException`, `InstantiationException`, and `IllegalAccessException` individually.

---

## Getting Started

If you're new to this codebase, here's the recommended reading order to build a mental model:

1. **`OrderService.java`** — Start here. It's the main entry point and orchestrates the entire order workflow. Even though it's a stub, it clearly shows the high-level flow and how dependencies are wired together.
2. **`PaymentGateway.java`**, **`InventoryService.java`**, **`NotificationService.java`** — Follow the order of invocation to understand each step of the order flow. These are currently empty stubs worth keeping an eye on for future implementation.
3. **`StatelessBean.java`** — See the standalone EJB pattern. This shows how a `@Stateless` session bean is declared and used.
4. **`EntityClass.java`** — Walk through the JPA entity mapping to understand the data model.
5. **`ReflectiveClass.java`** and **`PatternOneVar.java`** — Study these together to understand the reflection patterns used for dynamic class loading.
6. **`PlainClass.java`** — A lightweight utility with no dependencies; good as a quick read to finish your orientation.

### Recommended reading order

| Step | File | Why |
|---|---|---|
| 1 | `OrderService.java` | Central orchestrator — the "map" of the system |
| 2 | `PaymentGateway.java` | Step 1 of order flow |
| 3 | `InventoryService.java` | Step 2 of order flow |
| 4 | `NotificationService.java` | Step 3 of order flow |
| 5 | `StatelessBean.java` | Standalone EJB example |
| 6 | `EntityClass.java` | JPA entity pattern |
| 7 | `ReflectiveClass.java` | Reflection utilities |
| 8 | `PatternOneVar.java` | Reflection pattern example |
| 9 | `PlainClass.java` | Simple utility |
| 10 | [ejb.md](eo/ejb.md) | Full sub-package overview |

### Where to look next

- **[`eo.ejb.service` module](eo/ejb/service.md)** — Detailed guide on the service layer, dependency injection patterns, and the order flow.
- **[`eo.ejb.wiki` module](eo/ejb/wiki.md)** — Detailed guide on utility helpers and reflection patterns.
- **[`eo.ejb.example` module](eo/ejb/example.md)** — Detailed guide on JPA entity mapping and reference examples.
- **[`eo.ejb` package overview](eo/ejb.md)** — Full package-level overview tying everything together.