# Repository Overview

Welcome! If you're new to this codebase, you've landed in the right place. This repository implements a Java EE application built on top of Enterprise JavaBeans (EJB) and the Java Persistence API (JPA). It demonstrates a practical order-processing workflow — from charging a payment, to reserving inventory, to sending notifications — while also showcasing common Java EE patterns such as dependency injection, reflection-based class loading, and stateless session beans. Whether you're here to extend the order pipeline, add new services, or simply understand the architecture, this guide will orient you quickly.

---

## Overview

This project is a Java EE application centered around an EJB-based order management system. At its core, [`OrderService`](ServiceLayer/OrderService.java) orchestrates a three-step order lifecycle: it charges a customer's payment via a `PaymentGateway`, reserves stock through an `InventoryService`, and triggers a `NotificationService` to alert the relevant parties. Beyond the order workflow, the codebase includes supporting modules that illustrate JPA entity mapping, dynamic class loading via reflection, and the use of stateless session beans for background tasks.

The repository is organized into three subpackages under `eo.ejb`:

- **`example`** — JPA entity modeling and a reflection-based class-loading utility.
- **`service`** — The core order-processing business logic with multiple injection strategies.
- **`wiki`** — A reflection utility that dynamically resolves and invokes methods on classes from other modules at runtime.

---

## Technology Stack

| Layer | Technology | Notes |
|---|---|---|
| Runtime | Java EE / Jakarta EE | EJB container (e.g. WildFly) provides the execution environment |
| Persistence | JPA (`javax.persistence`) | Used by `EntityClass` for database mapping |
| Dependency Injection | CDI (`@Inject`), EJB (`@EJB`), Spring (`@Autowired`), Java EE (`@Resource`) | `OrderService` demonstrates a mixed-strategy setup across all four |
| Reflection | `java.lang.Class`, `java.lang.reflect` | Used by `PatternOneVar` and `ReflectiveClass` for runtime type resolution |
| Architecture | Enterprise JavaBeans (EJB) | Stateless session beans (`@Stateless`) and EJB injection patterns |

No well-known third-party frameworks beyond the Java EE platform were detected from import analysis.

---

## Architecture

The system follows a layered architecture with a central service facade coordinating three downstream concerns — payment, inventory, and notifications. The `example` and `wiki` packages provide supporting utilities and data models that plug into this service layer.

```mermaid
flowchart TD
    EJB["eo.ejb module"]

    subgraph EX["eo.ejb.example"]
        EC["EntityClass"]
        PV["PatternOneVar"]
    end

    subgraph SVC["eo.ejb.service"]
        OS["OrderService"]
        PG["PaymentGateway"]
        IS["InventoryService"]
        NS["NotificationService"]
        SB["StatelessBean"]
        EA["EJBWithArgs"]
    end

    subgraph WIKI["eo.ejb.wiki"]
        PC["PlainClass"]
        RC["ReflectiveClass"]
    end

    EJB --> EX
    EJB --> SVC
    EJB --> WIKI
    OS --> PG
    OS --> IS
    OS --> NS
    RC --> OS
```

**Key architectural observations:**

- **`OrderService` is the central orchestrator.** It depends on `PaymentGateway`, `InventoryService`, and `NotificationService` — the three leaf services that handle the specifics of payment processing, stock reservation, and alert dispatch.
- **Mixed dependency injection.** `OrderService` uses four different injection mechanisms (`@Inject`, `@EJB`, `@Autowired`, `@Resource`), which suggests the project may be in a transition period or running in a polyglot container.
- **`ReflectiveClass` bridges modules at runtime.** Located in the `wiki` package, it uses `Class.forName()` to dynamically load classes from the `service` module (and others) without compile-time imports. This enables plugin-style extensibility.
- **`EntityClass` is a minimal JPA entity.** It maps to a single database table with two columns (`id` and `name`) and provides read-only accessors (no setters).

### Order Workflow

The primary business flow runs through `OrderService.placeOrder()`:

```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. **Payment is charged first** via `PaymentGateway.charge()` — this captures the customer's funds.
2. **Inventory is reserved** via `InventoryService.reserve()` — stock is locked for the order.
3. **A notification fires** via `NotificationService.notify()` — the customer or relevant systems are alerted.

Note: All three leaf services currently have stub (empty) implementations, so `placeOrder()` is effectively a no-op today. The structure, however, establishes the contract and ordering for future production implementations.

---

## Module Guide

### `eo.ejb.example`

The `example` package serves as a demonstration area within the EJB module. It contains two classes that showcase foundational Java patterns used across the application:

- **[`EntityClass`](EntityLayer/EntityClass.java)** — A JPA entity mapped to the `entity_class` database table. It holds a simple two-field data model (`id` as primary key, `name` as a string column). The class is read-only from the outside (no setters), meaning mutations happen through the JPA `EntityManager`. This is a minimal entity, intended as an example rather than a production-ready data model.
- **[`PatternOneVar`](EntityLayer/PatternOneVar.java)** — A utility class that demonstrates reflection-based dynamic class loading. Its `load()` method accepts a fully-qualified class name as a string, resolves it via `Class.forName()`, creates an instance, and prints the result. This pattern is useful for plugin discovery and configuration-driven instantiation.

### `eo.ejb.service`

The `service` package is the heart of the application. It provides the core business service layer for the order-processing system:

- **[`OrderService`](ServiceLayer/OrderService.java)** — The central business facade. It wires together payment, inventory, and notification services using a mix of CDI, EJB, Spring, and Java EE resource injection. Its `placeOrder()` method executes the three-step order lifecycle in a fixed sequence.
- **[`PaymentGateway`](ServiceLayer/PaymentGateway.java)** — Handles payment charges. Currently a stub; in production, this would interface with a payment processor.
- **[`InventoryService`](ServiceLayer/InventoryService.java)** — Manages inventory reservations. Currently a stub; would decrement stock levels and place holds on items.
- **[`NotificationService`](ServiceLayer/NotificationService.java)** — Sends notifications for order events. Currently a stub; would dispatch confirmations via email, SMS, or internal events.
- **[`StatelessBean`](ServiceLayer/StatelessBean.java)** — A standard stateless session bean (`@Stateless`) for generic background or utility tasks. The container manages pooling and thread safety.
- **[`EJBWithArgs`](ServiceLayer/EJBWithArgs.java)** — A demonstration class showing EJB lookup by JNDI name (`@EJB(name = "myBean")`), useful when the target bean lives in a different deployment unit.

### `eo.ejb.wiki`

The `wiki` package contains utility classes that enable runtime type discovery and method invocation:

- **[`PlainClass`](WikiLayer/PlainClass.java)** — A simple POJO that stores a name string and returns a greeting. It has no EJB annotations and serves as a basic data carrier or DTO.
- **[`ReflectiveClass`](WikiLayer/ReflectiveClass.java)** — The most significant class in this package. It dynamically loads classes by their fully qualified name and invokes a standard `execute()` method on them. This is the primary mechanism by which the `wiki` package bridges to `eo.ejb.service` and other external modules without compile-time dependencies.

---

## Getting Started

If you're a new developer picking up this codebase, here's a recommended reading order:

1. **Start with [`OrderService`](ServiceLayer/OrderService.java)** — This is the entry point for understanding the application's primary workflow. It shows how payment, inventory, and notification services are wired together and what the order lifecycle looks like.

2. **Explore the leaf services** — Read [`PaymentGateway`](ServiceLayer/PaymentGateway.java), [`InventoryService`](ServiceLayer/InventoryService.java), and [`NotificationService`](ServiceLayer/NotificationService.java) to understand the interfaces that `OrderService` depends on. These are currently stubs, but their method signatures define the contract for production implementations.

3. **Understand the data model** — Read [`EntityClass`](EntityLayer/EntityClass.java) to see how the JPA persistence layer maps Java objects to database tables.

4. **Explore runtime extensibility** — Read [`ReflectiveClass`](WikiLayer/ReflectiveClass.java) in the `wiki` package to understand how classes can be loaded and invoked dynamically without compile-time knowledge. This is key to the plugin-style architecture.

5. **Review the utilities** — Finally, skim [`PatternOneVar`](EntityLayer/PatternOneVar.java), [`StatelessBean`](ServiceLayer/StatelessBean.java), [`EJBWithArgs`](ServiceLayer/EJBWithArgs.java), and [`PlainClass`](WikiLayer/PlainClass.java) for patterns around reflection, stateless EJBs, and simple data carriers.

### Key Classes to Know

| Class | Package | Role |
|---|---|---|
| [`OrderService`](ServiceLayer/OrderService.java) | `service` | Central orchestrator for the order workflow |
| [`EntityClass`](EntityLayer/EntityClass.java) | `example` | JPA entity for database persistence |
| [`ReflectiveClass`](WikiLayer/ReflectiveClass.java) | `wiki` | Runtime class loading and method invocation |
| [`StatelessBean`](ServiceLayer/StatelessBean.java) | `service` | Generic stateless EJB for background tasks |
| [`PaymentGateway`](ServiceLayer/PaymentGateway.java) | `service` | Payment processing (stub) |
| [`InventoryService`](ServiceLayer/InventoryService.java) | `service` | Stock reservation (stub) |
| [`NotificationService`](ServiceLayer/NotificationService.java) | `service` | Alert dispatch (stub) |

### Things to Watch Out For

- **Mixed injection frameworks** — `OrderService` uses four different dependency injection annotations. When adding new dependencies, prefer one framework consistently to avoid lifecycle conflicts.
- **Stub implementations** — All leaf services have empty method bodies. Production logic needs to be implemented in these classes.
- **No error handling in the order flow** — If `charge()` succeeds but `reserve()` fails, the payment has already been taken with no compensation. Consider adding transaction management.
- **Reflection safety** — Both `PatternOneVar` and `ReflectiveClass` use deprecated `Class.newInstance()`. In modern Java (9+), prefer `getDeclaredConstructor().newInstance()`.