# Getting Started

Welcome to the `eo.ejb` codebase! This guide helps new engineers orient themselves quickly.

## What This Project Does

This is a Java EE application centered on an order-processing workflow built with Enterprise JavaBeans (EJB). At its core, [`OrderService`](ServiceLayer/OrderService.java) orchestrates a three-step order lifecycle: charging a payment, reserving inventory, and sending notifications. The project also demonstrates key Java EE patterns including JPA entity mapping, reflection-based runtime class loading, and mixed dependency injection strategies.

---

## Recommended Reading Order

Follow this path to build a mental model of the codebase efficiently:

1. **[Repository Overview](../overview.md)** — High-level architecture, technology stack, and module layout.
2. **[EJB Module Overview](../eo/ejb.md)** — How the three sub-packages relate to each other.
3. **[`OrderService`](ServiceLayer/OrderService.java)** — The central orchestrator; reading this first tells you the entire order workflow.
4. **[Service Package Details](../eo/ejb/service.md)** — Deep dive into `OrderService`, its leaf services, and the mixed injection strategy.
5. **[Example Package](../eo/ejb/example.md)** — JPA entity and reflection patterns.
6. **[Wiki Package](../eo/ejb/wiki.md)** — Runtime type discovery via reflection.

---

## Key Entry Points

Start with these classes in this order:

| Class | Package | Why Start Here |
|-------|---------|----------------|
| [`OrderService`](ServiceLayer/OrderService.java) | `eo.ejb.service` | The central orchestrator — shows the full order workflow |
| [`EntityClass`](EntityLayer/EntityClass.java) | `eo.ejb.example` | Minimal JPA entity — demonstrates the persistence model |
| [`ReflectiveClass`](WikiLayer/ReflectiveClass.java) | `eo.ejb.wiki` | Runtime class loading — explains how modules wire together without compile-time dependencies |
| [`StatelessBean`](ServiceLayer/StatelessBean.java) | `eo.ejb.service` | Standard EJB pattern — demonstrates stateless session bean lifecycle |

Once you understand those, skim the remaining classes: [`PaymentGateway`](ServiceLayer/PaymentGateway.java), [`InventoryService`](ServiceLayer/InventoryService.java), [`NotificationService`](ServiceLayer/NotificationService.java), [`PatternOneVar`](EntityLayer/PatternOneVar.java), [`EJBWithArgs`](ServiceLayer/EJBWithArgs.java), and [`PlainClass`](WikiLayer/PlainClass.java).

---

## Project Structure

```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
```

**Three sub-packages, three concerns:**

- **`eo.ejb.example`** — JPA entity modeling and reflection pattern demos. Read-only data models and utility patterns.
- **`eo.ejb.service`** — The core business logic. `OrderService` is the entry point; it delegates to `PaymentGateway`, `InventoryService`, and `NotificationService`.
- **`eo.ejb.wiki`** — Runtime type discovery. `ReflectiveClass` dynamically loads and invokes classes from other packages at runtime using reflection.

---

## Configuration

This project runs in a Java EE / Jakarta EE container (e.g., WildFly). Configuration is primarily annotation-driven rather than file-based:

| Mechanism | Where | Purpose |
|-----------|-------|---------|
| `@Entity`, `@Table` | [`EntityClass`](EntityLayer/EntityClass.java) | JPA entity mapping to the `entity_class` database table |
| `@Stateless` | [`StatelessBean`](ServiceLayer/StatelessBean.java) | EJB container-managed pooling and thread safety |
| `@Inject`, `@EJB`, `@Autowired`, `@Resource` | [`OrderService`](ServiceLayer/OrderService.java) | Mixed dependency injection across CDI, EJB, Spring, and Java EE |
| `@EJB(name = "...")` | [`EJBWithArgs`](ServiceLayer/EJBWithArgs.java) | JNDI-name-based EJB lookup by explicit binding name |

The container provides:

- **Persistence unit** — JPA (`javax.persistence`) manages `EntityClass` instances via the `EntityManager`.
- **DataSource** — `@Resource` in `OrderService` expects a container-bound `DataSource` to be available at deployment time.
- **EJB pool** — `StatelessBean` is pooled and managed by the EJB container.

---

## Common Patterns

### The 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. **Charge** — `PaymentGateway.charge()` captures the customer's funds.
2. **Reserve** — `InventoryService.reserve()` locks stock for the order.
3. **Notify** — `NotificationService.notify()` alerts relevant parties.

> **Note:** All three leaf services currently have stub (empty) implementations. The structure is established; production logic needs to be added.

### Mixed Dependency Injection

`OrderService` uses four different injection mechanisms simultaneously:

| Field | Annotation | Framework |
|-------|-----------|-----------|
| `paymentGateway` | `@Inject` | CDI (JSR-346) |
| `inventory` | `@EJB` | EJB dependency injection |
| `notificationService` | `@Autowired` | Spring Framework |
| `dataSource` | `@Resource` | Java EE resource injection |

**Recommendation:** When adding new dependencies, prefer CDI `@Inject` for consistency. The coexistence of four frameworks suggests a transition period.

### Reflection-Based Runtime Loading

Both `PatternOneVar` and `ReflectiveClass` demonstrate dynamic class loading:

```java
Object obj = Class.forName("com.example.MyClass").newInstance();
```

This enables plugin-style extensibility — classes can be loaded and invoked at runtime without compile-time imports.

> **Important:** `Class.newInstance()` has been deprecated since Java 9. In new code, prefer `cls.getDeclaredConstructor().newInstance()`.

### Read-Only Entity Pattern

[`EntityClass`](EntityLayer/EntityClass.java) provides getters but no setters. Mutations happen through the JPA `EntityManager`, not direct field assignment. This is valid JPA but means any code that needs to modify the entity must do so through the persistence context.

---

## Things to Watch Out For

- **No error handling in the order flow.** If `charge()` succeeds but `reserve()` fails, the payment has been taken with no compensation. Production code needs transaction management (`@TransactionAttribute`) or explicit rollback logic.
- **Stub services.** `PaymentGateway`, `InventoryService`, and `NotificationService` have empty method bodies. Each service's key method (`charge()`, `reserve()`, `notify()`) needs production implementation.
- **Reflection safety.** Both `PatternOneVar` and `ReflectiveClass` use deprecated `Class.newInstance()`. Prefer `getDeclaredConstructor().newInstance()` in new code.
- **No null checks in ReflectiveClass.** Callers are expected to ensure well-formed input.
- **StatelessBean purity.** `StatelessBean` fields must not store instance state — the container pools and shares instances across callers.

---

## Summary: Your First 30 Minutes

1. Read the [Repository Overview](../overview.md) for the big picture.
2. Open [`OrderService.java`](ServiceLayer/OrderService.java) — it takes 30 seconds and tells you everything important about the workflow.
3. Skim [`EntityClass.java`](EntityLayer/EntityClass.java) for the persistence model.
4. Skim [`ReflectiveClass.java`](WikiLayer/ReflectiveClass.java) for the reflection bridge between modules.
5. You now know the architecture. Proceed to the detailed package guides or start coding.