# Getting Started

## What This Project Does

This codebase 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.

---

## Recommended Reading Order

Start from the simplest classes and work outward to the orchestration layer:

1. **[EntityClass](eo/ejb/example/EntityClass.java)** -- A JPA entity with two fields (`id`, `name`). The smallest class; learn the persistence pattern first.
2. **[PatternOneVar](eo/ejb/example/PatternOneVar.java)** -- Demonstrates dynamic class loading via `Class.forName()` + `newInstance()`. Introduces reflection usage.
3. **[OrderService](eo/ejb/service/OrderService.java)** -- The central orchestrator. Shows mixed dependency injection (CDI, EJB, Spring, JNDI). The "brain" of the repository.
4. **[PaymentGateway](eo/ejb/service/PaymentGateway.java), [InventoryService](eo/ejb/service/InventoryService.java), [NotificationService](eo/ejb/service/NotificationService.java)** -- The three supporting services. Each is a stub, but the injection annotations show how they connect in a real application.
5. **[StatelessBean](eo/ejb/service/StatelessBean.java)** -- A minimal stateless session bean. Learn the EJB lifecycle pattern.
6. **[PlainClass](eo/ejb/wiki/PlainClass.java)** -- A simple JavaBeans data model. Quick read for basic encapsulation.
7. **[ReflectiveClass](eo/ejb/wiki/ReflectiveClass.java)** -- A reflection-based dispatch utility. Builds on the pattern from `PatternOneVar` with dynamic method invocation.

---

## Key Entry Points

These are the most important classes to understand first -- they anchor the project's architecture:

- **[OrderService.placeOrder()](eo/ejb/service/OrderService.java)** -- The main business workflow. Everything in the `service` module revolves around this method. It chains three operations: charge -> reserve -> notify.
- **[PatternOneVar.load()](eo/ejb/example/PatternOneVar.java)** and **[ReflectiveClass.loadByReflection()](eo/ejb/wiki/ReflectiveClass.java)** -- The two entry points for dynamic class loading patterns used throughout the project.
- **[StatelessBean.execute()](eo/ejb/service/StatelessBean.java)** -- A minimal demonstration of the EJB stateless bean lifecycle.
- **[EntityClass](eo/ejb/example/EntityClass.java)** -- The only JPA entity, showing how persistent data models are declared.

---

## Project Structure

The codebase lives in the `eo.ejb` package namespace and is split into three logical sub-modules:

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

| Sub-module | Classes | Purpose |
|------------|---------|---------|
| **example** | `EntityClass`, `PatternOneVar` | Foundational patterns: JPA entity mapping and dynamic class loading via reflection. Fully self-contained. |
| **service** | `OrderService`, `PaymentGateway`, `InventoryService`, `NotificationService`, `StatelessBean`, `EJBWithArgs` | Core business logic: the order-placement workflow and its three supporting services. Mixes CDI, EJB, Spring, and JNDI injection. |
| **wiki** | `PlainClass`, `ReflectiveClass` | Lightweight utilities: a simple data model and a reflection-based dispatch helper. The only sub-module with a cross-package dependency (on `service`). |

---

## Configuration

This is a lightweight demonstration repository -- there are no build files, dependency descriptors, or application server configuration files included. The key "configuration" is the annotation-based wiring:

| Annotation | Framework | Where It Appears |
|-----------|-----------|-----------------|
| `@Entity`, `@Table`, `@Id`, `@Column` | JPA | `EntityClass` |
| `@Inject` | CDI (JSR-365) | `OrderService` (for `PaymentGateway`) |
| `@EJB` | EJB 3.x | `OrderService` (for `InventoryService`), `EJBWithArgs` (for `MyService`) |
| `@Autowired` | Spring Framework | `OrderService` (for `NotificationService`) |
| `@Resource` | JNDI | `OrderService` (for `DataSource`) |
| `@Stateless` | EJB 3.x | `StatelessBean` |

For a real deployment you would need:

- A JPA persistence unit configured in the application server
- A Spring application context for `@Autowired` beans
- An EJB container with the appropriate deployment descriptors
- A `DataSource` bound in JNDI

---

## Common Patterns

### Multi-Framework Dependency Injection

The standout architectural pattern is `OrderService`, which uses **four different injection mechanisms** simultaneously:

```
@Inject          -> CDI  -> PaymentGateway
@EJB             -> EJB  -> InventoryService
@Autowired       -> Spring -> NotificationService
@Resource        -> JNDI -> DataSource
```

This demonstrates that the runtime supports all four containers coexisting. In production code, standardizing on a single injection framework is recommended.

### Sequential Business Flow

The order-placement flow is linear and fire-and-forget:

```
Client -> OrderService.placeOrder()
  1. PaymentGateway.charge()     -- charge the customer
  2. InventoryService.reserve()  -- reserve the stock
  3. NotificationService.notify() -- send confirmation
```

**Known design gap:** If step 2 or 3 fails after step 1 succeeds, there is no rollback or compensation logic. The customer would be charged for an order that was not placed.

### Reflection as a Recurring Theme

Both `PatternOneVar` (in `example`) and `ReflectiveClass` (in `wiki`) use `Class.forName()` + `newInstance()` for runtime class loading. This pattern is common in plugin systems, DI containers, and test runners.

> **Note:** `Class.newInstance()` has been deprecated since Java 9. Modern code should use `clazz.getDeclaredConstructor().newInstance()` instead.

### Stateless Session Beans

`StatelessBean` is the simplest possible EJB -- annotated with `@Stateless`, containing a single `execute()` method. Stateless beans are the default EJB type: they are thread-safe by contract, pooled by the container, and hold no conversational state.

### JPA Entity Without Mutators

`EntityClass` exposes only getters (`getId()`, `getName()`) -- no setters. This suggests the entity is used for read-only access through the JPA `EntityManager`, with modifications handled through proper persistence operations rather than direct field mutation.