# Getting Started

## What This Project Does

This is a **Jakarta EE / Java EE** application built around Enterprise JavaBeans (EJB) for order processing. The core of the system is `OrderService`, which orchestrates a three-step order workflow: charging payment, reserving inventory, and sending notifications. Beyond the business layer, the project also includes JPA entity mapping examples and reflection-based utilities for dynamic class loading — patterns used in plugin-style or configuration-driven architectures.

> **Note:** Most service method bodies are currently stubs (empty implementations). This project is in a scaffolding or demonstration phase, showing how the pieces fit together before real business logic is filled in.

---

## Recommended Reading Order

If you're new to this codebase, read in this order to build a mental model efficiently:

1. **[`OrderService.java`](OrderService.java)** — The central orchestrator. Read this first; it's the "map" of the entire system and clearly shows the high-level order flow and how dependencies are wired together.
2. **[`PaymentGateway.java`](PaymentGateway.java), [`InventoryService.java`](InventoryService.java), [`NotificationService.java`](NotificationService.java)** — Follow the order of invocation to understand each step of the order flow. These are stubs worth knowing for when implementation fills in.
3. **[`StatelessBean.java`](StatelessBean.java)** — A standalone `@Stateless` session bean; shows how a remote-facing EJB is declared.
4. **[`EntityClass.java`](EntityClass.java)** — Walk through the JPA entity mapping to understand the data model.
5. **[`ReflectiveClass.java`](ReflectiveClass.java)** and **[`PatternOneVar.java`](PatternOneVar.java)** — Study together to understand the reflection patterns used for runtime class loading.
6. **[`PlainClass.java`](PlainClass.java)** — A simple, dependency-free utility; quick finish to your orientation.

### Wiki pages to read next

| Step | Page | Purpose |
|------|------|---------|
| 1 | [eo.ejb Package Overview](eo/ejb.md) | Full package-level overview, architecture, and developer notes |
| 2 | [eo.ejb.service Module](eo/ejb/service.md) | Detailed guide on the service layer, DI patterns, and the order flow |
| 3 | [eo.ejb.wiki Module](eo/ejb/wiki.md) | Utility helpers and reflection patterns |
| 4 | [eo.ejb.example Module](eo/ejb/example.md) | JPA entity mapping and reference examples |

---

## Key Entry Points

Start with these classes to understand the system:

### `OrderService` (order of reading: #1)
The heart of the application. Its `placeOrder()` method calls three services in sequence. It uniquely demonstrates **four different dependency injection mechanisms** co-existing in one class (`@Inject`, `@EJB`, `@Autowired`, `@Resource`) — a notable architectural quirk.

```java
public void placeOrder() {
    paymentGateway.charge();      // Step 1: validate payment
    inventory.reserve();          // Step 2: lock stock
    notificationService.notify(); // Step 3: signal completion
}
```

### `PaymentGateway` (reading: #2)
Handles the first step of the order flow — payment validation. Currently an empty stub. Injected via CDI `@Inject`.

### `InventoryService` (reading: #2)
Locks stock after payment succeeds. Injected via EJB `@EJB`. Currently an empty stub.

### `NotificationService` (reading: #2)
Dispatches notifications after the order is fully processed. Injected via Spring `@Autowired`. Currently an empty stub.

### `StatelessBean` (reading: #3)
A standalone `@Stateless` session bean. Useful reference for EJB lifecycle patterns and thread-safety delegation to the container.

### `EntityClass` (reading: #4)
A JPA entity mapped to the `entity_class` database table. Demonstrates `@Entity`, `@Table`, `@Id`, and `@Column` annotations. Notable for having only getters (no setters).

### `ReflectiveClass` + `PatternOneVar` (reading: #5)
Both implement the same reflection pattern: loading a class by its fully qualified name at runtime. This supports plugin-style extensibility where the concrete class is determined by configuration rather than compile-time types.

---

## Project Structure

The codebase is organized under a single root 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
```

### Package breakdown

| Package | Contains | Purpose |
|---------|----------|---------|
| `eo.ejb.service` | `OrderService`, `PaymentGateway`, `InventoryService`, `NotificationService`, `EJBWithArgs`, `StatelessBean` | Core business layer — orchestrates the order workflow |
| `eo.ejb.wiki` | `PlainClass`, `ReflectiveClass` | Low-level utilities — string templating and dynamic class loading |
| `eo.ejb.example` | `EntityClass`, `PatternOneVar` | Reference examples — JPA entity mapping and reflection patterns |

---

## Technology Stack

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

---

## Order Processing Flow

The dominant business pattern is the sequential order placement in `OrderService.placeOrder()`:

```mermaid
flowchart LR
    subgraph OrderFlow["Order Processing Flow"]
        PlaceOrder["OrderService.placeOrder"] --> Charge["PaymentGateway.charge"]
        Charge --> Reserve["InventoryService.reserve"]
        Reserve --> Notify["NotificationService.notify"]
    end
```

**Why this order matters:** Payment is charged *before* inventory is reserved, preventing the system from allocating stock for orders that cannot be paid.

---

## Dependency Injection Patterns

`OrderService` uses **four different DI mechanisms** simultaneously — this is a significant architectural detail:

```mermaid
flowchart TD
    A["OrderService"] --> B["@Inject / CDI"]
    A --> C["@EJB / Jakarta EE EJB"]
    A --> D["@Autowired / Spring"]
    A --> E["@Resource / Jakarta EE resource"]
    F["EJBWithArgs"] --> G["@EJB with JNDI name"]
```

| Annotation | Framework | Field |
|---|---|---|
| `@Inject` | CDI (Jakarta EE) | `paymentGateway` |
| `@EJB` | Jakarta EE EJB | `inventory` |
| `@Autowired` | Spring Framework | `notificationService` |
| `@Resource` | Jakarta EE | `dataSource` |

This mix suggests either a migration in progress between frameworks or a polyglot deployment exploring multiple DI ecosystems. When adding new dependencies, be aware there is no single "canonical" injection mechanism yet.

---

## Configuration

This project has no external configuration files in the repository root. The behavior is driven by:

- **`@EJB(name = "myBean")`** in `EJBWithArgs` — performs a JNDI lookup. The target bean must be registered with that JNDI name in the application server.
- **`@Resource`** on `dataSource` — expects a container-managed JDBC resource (e.g., a `DataSource` pool configured in WildFly, GlassFish, or similar).
- **`@Entity` / `@Table` / `@Column`** on `EntityClass` — JPA mapping configuration. The actual persistence provider (Hibernate, EclipseLink) would be configured in `persistence.xml` in a production deployment.
- **Reflection class names** — `ReflectiveClass` and `PatternOneVar` accept fully qualified class names as strings, meaning the "configuration" for which classes to load lives in caller code or external configuration files not in this repo.

---

## Common Patterns

### Sequential orchestration
`OrderService.placeOrder()` calls downstream services in a fixed sequence. This is the primary integration pattern in the codebase.

### Mixed dependency injection
As shown above, four DI frameworks co-exist. When writing new code, follow the existing injection style of the class you're modifying — but consider proposing a consolidation to a single framework if the project moves forward.

### Reflection-based dynamic loading
`ReflectiveClass` and `PatternOneVar` both use `Class.forName(className).newInstance()` to resolve classes at runtime. This enables plugin-style extensibility.

> **Warning:** `Class.newInstance()` has been deprecated since Java 9. Consider migrating to `Class.getDeclaredConstructor().newInstance()`.

### JPA read-only entities
`EntityClass` exposes only getters with no setters. Mutations should go through the JPA `EntityManager`, not direct field assignment.

---

## Important Notes for New Contributors

### Stub implementations
`PaymentGateway.charge()`, `InventoryService.reserve()`, and `NotificationService.notify()` are all empty. When implementing, look for subclass definitions or integration targets.

### No error handling in placeOrder()
The current implementation has no try/catch or compensation logic. If payment succeeds but inventory reservation fails, the payment is already processed with no automatic rollback. A production implementation would use EJB declarative transaction management.

### Naming convention
`NotificationService.notify()` shadows `Object.notify()` in Java. While technically legal (different signatures), consider renaming to `sendNotification()` for clarity.

### No null checks
Neither `PlainClass` nor `ReflectiveClass` validate constructor parameters. Passing `null` will cause a `NullPointerException` later in execution.

### EJBWithArgs legacy pattern
`EJBWithArgs` uses the older `@EJB(name = "myBean")` style with JNDI lookups. Prefer direct field injection (`@EJB`) where possible.