# Repository Overview

Welcome to this codebase! This repository is a small but representative collection of **Enterprise JavaBeans (EJB)** patterns and Java EE service classes. It demonstrates how to structure business logic around order processing — covering dependency injection across multiple frameworks (CDI, EJB, Spring), JPA entity mapping, and runtime class loading via reflection. Whether you're learning EJB, looking for a reference implementation, or exploring how different Java EE concepts fit together, this repo is a good place to start.

---

## Overview

This repository serves as a practical showcase of several core Java EE / EJB 3.x patterns:

- **Order processing workflow** — a central `OrderService` orchestrates payment, inventory reservation, and notification through dependency injection.
- **JPA entity mapping** — a simple persistent entity class demonstrates how to declare a domain model backed by a relational table.
- **Dynamic class loading** — utility classes show how to load and instantiate classes at runtime using Java reflection.
- **EJB lifecycle** — stateless session beans and named EJB injection illustrate the EJB container model.

The code is organized under the `eo.ejb` package namespace and is split into three logical modules: `example`, `service`, and `wiki`.

---

## Technology Stack

| Technology | Role |
|------------|------|
| **Java** | Core programming language |
| **EJB 3.x** (`@Stateless`, `@EJB`) | Enterprise session beans and dependency injection |
| **JPA** (`@Entity`, `@Table`, `@Id`, `@Column`) | Object-relational mapping and persistence |
| **CDI** (`@Inject`) | Contexts and Dependency Injection |
| **Spring** (`@Autowired`) | Spring-managed bean integration |
| **JNDI** (`@Resource`) | Java Naming and Directory Interface for resource lookups |
| **Java Reflection** (`Class.forName`, `Method.invoke`) | Dynamic class loading and method dispatch |

---

## Architecture

```mermaid
flowchart TD
    A["ejb<br/>Enterprise Java Beans"]
    B["example<br/>Entity mapping &amp; dynamic loading"]
    C["service<br/>Order processing &amp; business logic"]
    D["wiki<br/>Utility classes &amp; reflection"]
    A --> B
    A --> C
    A --> D
    C -->|depends on| PG["PaymentGateway"]
    C -->|depends on| INV["InventoryService"]
    C -->|depends on| NS["NotificationService"]
```

At a high level, the repository is organized as a single package (`eo.ejb`) with three submodules:

- **`example`** — Illustrates foundational patterns: JPA entity declarations and runtime class loading via reflection.
- **`service`** — Contains the core business logic: the order-placement workflow and its three supporting services (payment, inventory, notification).
- **`wiki`** — Provides lightweight utility classes: a plain data model and a reflection-based dispatch helper.

---

## Module Guide

### `example` — Foundational Patterns

The `example` package demonstrates two essential Java EE patterns. `EntityClass` is a JPA entity mapped to the `entity_class` table, showing how to declare a persistent domain model with `@Entity`, `@Table`, `@Id`, and `@Column` annotations. It holds a simple identifier (`Long id`) and a name (`String name`). `PatternOneVar` demonstrates dynamic class loading — it accepts a fully-qualified class name as a string, loads the class via `Class.forName()`, and instantiates it with `newInstance()`. This pattern is commonly used in plugin systems and configuration-driven factories. Note that `Class.newInstance()` is deprecated since Java 9; production code should prefer `Constructor.newInstance()`.

### `service` — Order Processing Business Logic

The `service` package is the heart of the repository. `OrderService` orchestrates the full order-placement workflow by delegating to three specialized services:

1. **`PaymentGateway`** — Processes customer payments. Injected via CDI (`@Inject`). Currently a stub awaiting integration with a real payment processor.
2. **`InventoryService`** — Reserves inventory for ordered items. Injected via EJB (`@EJB`). Expected to be deployed as a stateless session bean.
3. **`NotificationService`** — Sends order confirmations. Injected via Spring (`@Autowired`). Requires Spring-managed context.

The sequential order — charge, then reserve, then notify — is a simple optimistic model. If any step after the charge fails, there is no visible rollback logic, which is a known design gap for production use.

The package also includes `StatelessBean`, a minimal stateless session bean demonstrating the EJB lifecycle, and `EJBWithArgs`, which shows how to inject a named EJB reference using `@EJB(name = "...")`.

#### Order Placement Flow

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

### `wiki` — Utility Classes

The `wiki` package contains two lightweight utility classes. `PlainClass` is a simple data-bearing class with a `name` field and a `greet()` method, following standard JavaBeans conventions. `ReflectiveClass` is a reflection-based utility that loads arbitrary classes by fully-qualified name and invokes methods on them at runtime. It holds a `targetClass` string and provides `loadByReflection()` (which instantiates the named class) and `invokeMethod()` (which looks up and calls a convention-based `execute()` method). Like the reflection pattern in `example`, `ReflectiveClass` uses the deprecated `Class.newInstance()` and should be reviewed for modern Java compatibility.

---

## Getting Started

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

1. **`eo/ejb/example/EntityClass.java`** — Start here to understand the JPA entity mapping pattern. It's the smallest and most straightforward class in the repo.
2. **`eo/ejb/example/PatternOneVar.java`** — Learn how dynamic class loading works via reflection.
3. **`eo/ejb/service/OrderService.java`** — The central orchestrator. This class ties everything together by showing dependency injection across CDI, EJB, and Spring.
4. **`eo/ejb/service/StatelessBean.java`** — A minimal example of the EJB stateless session bean lifecycle.
5. **`eo/ejb/service/PaymentGateway.java`, `InventoryService.java`, `NotificationService.java`** — The three supporting services. Each is a stub, but the injection annotations show how they would connect in a real application.
6. **`eo/ejb/wiki/PlainClass.java`** — A simple data model class, good for understanding JavaBeans conventions.
7. **`eo/ejb/wiki/ReflectiveClass.java`** — A more advanced reflection utility, building on the pattern introduced in `example`.

Key entry points to keep in mind:

- **`OrderService.placeOrder()`** — The main business workflow. Everything in the `service` module revolves around this method.
- **`PatternOneVar.load()`** and **`ReflectiveClass.loadByReflection()`** — The two entry points for dynamic class loading patterns.
- **`StatelessBean.execute()`** — A minimal demonstration of the EJB stateless bean lifecycle.

The top-level Java files on the repository root are the same classes documented above — they are the actual source files. The `.codewiki/` directory contains auto-generated documentation for each module.