# Eo / Ejb

## Overview

The `eo.ejb` package serves as the EJB (Enterprise Java Bean) layer of the application. It provides the infrastructure for enterprise-grade service execution, encompassing business logic orchestration, persistent data modeling, and runtime reflection utilities.

This area of the codebase appears to be in an early or scaffolding state. Most service classes contain stub implementations with empty method bodies, and the package demonstrates a mix of dependency injection frameworks (Jakarta EE CDI, Spring, and EJB-specific) that suggests either a migration in progress or an exploration of polyglot deployment patterns. The sub-packages together cover three distinct concerns:

- **Service orchestration** (`eo.ejb.service`) — The core business layer that coordinates cross-cutting operations like payment, inventory, and notifications through enterprise beans.
- **Runtime utilities** (`eo.ejb.wiki`) — Low-level helpers for string templating and dynamic class loading via Java reflection, consumed by the broader service layer.
- **Demonstrations** (`eo.ejb.example`) — Reference examples illustrating JPA entity mapping and reflection patterns used elsewhere in the EJB subsystem.

At a high level, `eo.ejb.service` is the primary entry point for application functionality (currently centered on an order-processing workflow), while `eo.ejb.wiki` provides supporting utilities and `eo.ejb.example` offers patterns that developers can reference when extending the system.

## Sub-module Guide

### eo.ejb.service — The Business Layer

`eo.ejb.service` is the most functionally significant sub-package. It implements the core service layer, wrapping business operations behind enterprise Java beans. Its centerpiece is `OrderService`, which orchestrates the order placement workflow by invoking three downstream services — payment, inventory, and notifications — in a fixed sequence.

The package also demonstrates several EJB and dependency injection patterns:

- **`PaymentGateway`**, **`InventoryService`**, and **`NotificationService`** are injected into `OrderService` using different DI mechanisms (`@Inject`, `@EJB`, `@Autowired` respectively). Each is currently a stub.
- **`EJBWithArgs`** shows the older, name-based `@EJB` injection style using JNDI lookups.
- **`StatelessBean`** is a standalone `@Stateless` session bean, likely serving as a remote-facing endpoint.

### eo.ejb.wiki — Utility Helpers

`eo.ejb.wiki` provides two small but conceptually distinct utilities:

- **`PlainClass`** — A simple, side-effect-free value object for generating formatted greeting strings. This is a straightforward utility with no external dependencies.
- **`ReflectiveClass`** — A reflection-based helper that dynamically loads classes by fully qualified name and invokes a hardcoded `execute()` method on them. This appears to support plugin-style extensibility or configuration-driven object creation.

`ReflectiveClass` is the more consequential of the two: it is referenced as an internal dependency by `eo.ejb.service`, suggesting that dynamic class resolution is used somewhere in the service infrastructure. `PlainClass`, by contrast, appears to be a self-contained helper with no downstream consumers documented.

### eo.ejb.example — Reference Patterns

`eo.ejb.example` is a self-contained demonstration package with no internal dependencies. It showcases two fundamental Java EE patterns:

- **`EntityClass`** — A JPA entity mapped to an `entity_class` database table with `@Id` and `@Column` annotations. It exposes only read-only accessors (getters, no setters), implying mutations occur through the JPA persistence context.
- **`PatternOneVar`** — A minimal example of runtime class loading via reflection, equivalent in approach to `ReflectiveClass` but structured as a free-standing utility method rather than an instance-based class.

This package is intended as a reference for developers extending the EJB subsystem — it illustrates the JPA and reflection patterns that appear in the more production-facing packages.

### How the sub-modules relate

The sub-packages form a layered structure where `service` is the primary consumer and `wiki` / `example` serve as supporting layers:

- `eo.ejb.service` depends on `eo.ejb.wiki` for reflection-based dynamic class loading at runtime.
- `eo.ejb.wiki` also references `eo.ejb.service` internally, creating a low-level → high-level dependency that the utilities serve the business layer.
- `eo.ejb.example` is independent — it does not depend on other packages and is intended as documentation-by-example rather than production code.

## Key Patterns and Architecture

### Order Processing Flow

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

```
OrderService.placeOrder
  --> PaymentGateway.charge()      -- Financial validation first
  --> InventoryService.reserve()   -- Lock stock after payment confirmed
  --> NotificationService.notify() -- Signal completion
```

The order of operations is intentional: payment is charged before inventory is reserved, preventing the system from allocating stock for orders that cannot be paid. However, the current stub implementation has no error handling or rollback logic — if `charge()` succeeds but `reserve()` fails, the payment is already processed with no automatic compensation. A production implementation would likely rely on declarative EJB transaction management to ensure all-or-nothing semantics.

### Mixed Dependency Injection

A notable architectural decision is the coexistence of four different dependency injection mechanisms within a single class (`OrderService`):

```
OrderService
  --> @Inject (CDI) for PaymentGateway
  --> @EJB (Jakarta EE) for InventoryService
  --> @Autowired (Spring) for NotificationService
  --> @Resource (Jakarta EE) for DataSource
```

This mix is architecturally significant. It suggests the application may be running in a container that supports multiple DI ecosystems simultaneously (such as WildFly with Spring extensions), or the project is in a transitional state migrating between frameworks. For developers adding new dependencies, this means there is no single "canonical" injection mechanism to follow — the existing codebase provides conflicting precedent.

### Reflection-based Dynamic Loading

Both `ReflectiveClass` (in `wiki`) and `PatternOneVar` (in `example`) demonstrate the same reflection pattern: resolving a class by its fully qualified string name at runtime and instantiating it. This pattern supports plugin-style extensibility, where the concrete class to load is determined by configuration rather than compile-time type resolution.

Key implementation details shared by both:
- Uses `Class.forName(className).newInstance()` to resolve and instantiate classes.
- Requires the target class to have a public no-argument constructor.
- `ReflectiveClass.invokeMethod()` hardcodes the method name `execute`, limiting flexibility.

Both use the deprecated `Class.newInstance()` approach (deprecated since Java 9). Consider migrating to `Class.getDeclaredConstructor().newInstance()` for newer Java versions.

### JPA Entity Design

`EntityClass` in the example package demonstrates a minimal JPA entity pattern:
- Uses default naming for the primary key column (`id`).
- Explicitly maps a non-standard column name (`name` field → `item_name` column).
- Exposes only getters, implying read-only semantics or persistence-context mutations.
- Has no relationships, foreign keys, or cascading behavior.

## Dependencies and Integration

### Internal Dependencies

| Producer | Consumed by | Injection / Usage |
|----------|-------------|-------------------|
| `PaymentGateway` | `OrderService` | `@Inject` (CDI) |
| `InventoryService` | `OrderService` | `@EJB` (Jakarta EE EJB) |
| `NotificationService` | `OrderService` | `@Autowired` (Spring) |
| `MyService` | `EJBWithArgs` | `@EJB(name = "myBean")` |
| `ReflectiveClass` | `eo.ejb.service` | Runtime class loading |

### External Dependencies

| Dependency | Used By | Purpose |
|------------|---------|---------|
| `javax.persistence` | `EntityClass` | JPA entity annotations |
| `javax.ejb` | `OrderService`, `EJBWithArgs`, `StatelessBean` | EJB annotations |
| `javax.inject` | `OrderService` | CDI injection |
| `org.springframework.beans.factory` | `OrderService` | Spring `@Autowired` |
| `javax.sql` | `OrderService` | `DataSource` resource injection |
| `java.lang.reflect` | `ReflectiveClass` | Runtime reflection |

### Module Relationship Diagram

```mermaid
flowchart TD
    subgraph ejb["Package: eo.ejb"]
        SVC["eo.ejb.service
Core service layer"]
        WIKI["eo.ejb.wiki
Utilities"]
        EXM["eo.ejb.example
Demonstrations"]
    end
    SVC --> ORD["OrderService"]
    WIKI --> PC["PlainClass"]
    WIKI --> RC["ReflectiveClass"]
    EXM --> EC["EntityClass"]
    EXM --> PV["PatternOneVar"]
    RC --> SVC
```

## Notes for Developers

### Stub Implementations
`PaymentGateway`, `InventoryService`, and `NotificationService` all have empty method bodies. These are scaffolds — the real implementation likely lives in subclasses, external modules, or is intended to be filled in later. When adding functionality, look for subclass definitions or integration targets.

### Mixed DI Annotations
The presence of `@Inject`, `@EJB`, `@Autowired`, and `@Resource` on the same class is unusual. If you are adding new dependencies to `OrderService`, be aware that the package does not enforce a single DI standard. Consider determining the canonical framework for the project before choosing an injection style.

### No Error Handling in placeOrder
The current `placeOrder()` implementation has no try/catch blocks or compensation logic. If payment succeeds but inventory reservation fails, there is no automatic rollback. Production code should add transactional semantics via the EJB container or explicit compensation steps.

### Reflection Deprecation
Both `ReflectiveClass` and `PatternOneVar` use `Class.newInstance()`, which has been deprecated since Java 9. If this code is extended or the project targets Java 9+, migrate to `getDeclaredConstructor().newInstance()`.

### ReflectiveClass Brittleness
`ReflectiveClass.invokeMethod()` hardcodes the method name `execute` and expects a static, no-argument method. This is not validated at compile time — failures will surface as runtime exceptions if the target class does not conform. Consider extending this to support parameterised invocations and instance method calls.

### No Null Checks
Neither `PlainClass` nor `ReflectiveClass` validate that constructor parameters are non-null. Passing `null` will likely cause a `NullPointerException` later in execution.

### Naming Convention
`NotificationService.notify()` shadows the `Object.notify()` method in Java. While technically legal due to different signatures, this can cause confusion in code reviews and IDE autocomplete. Consider renaming to `sendNotification()` for clarity.

### EJBWithArgs Legacy Pattern
`EJBWithArgs` uses the older `@EJB(name = "myBean")` style with JNDI lookups. Prefer direct field injection (`@EJB`) where possible for clarity and maintainability.

### Entity Read-Only Semantics
`EntityClass` exposes only getters with no setters. If you need to modify entity state, mutations should happen through the JPA `EntityManager` rather than direct field assignment. Ensure corresponding setters are defined elsewhere if needed.