# Repository Overview

Welcome to this codebase. This repository contains an example Enterprise JavaBeans (EJB) module — `eo.ejb.example` — that demonstrates the major EJB component types available in the Java EE / Jakarta EE platform. It includes a stateless session bean, a stateful session bean, a singleton bean, a message-driven bean, a JPA entity, and a class illustrating cross-framework dependency injection. If you're new here, think of it as a hands-on reference guide for how to structure different bean types, apply common annotations, and mix EJB lifecycle patterns within a single application.

## Overview

This project is an EJB example module showcasing the various Enterprise JavaBean component types and related Java EE patterns. It provides one representative class for each major EJB category — stateless session beans, stateful session beans, singleton beans, and message-driven beans — along with a JPA entity and a class demonstrating multi-framework dependency injection. It serves as a reference for how to structure different bean types, apply common annotations, and mix EJB lifecycle patterns within a single application.

## Technology Stack

The project relies on the following Java EE / Jakarta EE technologies:

| Category | Technology |
|----------|-----------|
| **EJB** | `javax.ejb.*` — `@Stateless`, `@Stateful`, `@Singleton`, `@MessageDriven`, `@EJB` |
| **JPA** | `javax.persistence.*` — `@Entity`, `@Table`, `@Id`, `@Column` |
| **CDI** | `javax.inject.*` — `@Inject` |
| **JAX-RS** | `javax.ws.rs.*` — `@Path`, `@GET`, `@POST` |
| **Common Annotations** | `javax.annotation.*` — `@Resource` |
| **Spring Framework** | `org.springframework.beans.factory.annotation.*` — `@Autowired` |

The presence of Spring's `@Autowired` alongside EJB annotations suggests this module may be used in a hybrid environment where EJB containers coexist with Spring, or it serves as a reference for migration scenarios.

## Architecture

The repository centers around a single top-level package, `eo.ejb.example`, which contains six classes organized into three conceptual groups: EJB lifecycle beans, a JPA entity, and a multi-framework DI example class.

```mermaid
flowchart TD
    subgraph Package["eo.ejb.example Package"]
        BEAN["EJB Beans"]
        ENTITY["Entity"]
        MULTI["DI Bean"]
        DB["Database"]
    end

    BEAN -->|uses| ENTITY
    MULTI -->|depends on| ENTITY
    ENTITY -->|maps to| DB
```

**How the pieces relate:**

- **EJB Beans** (`AllAnnotations`, `StatefulBean`, `SingletonBean`, `MessageBean`) are the core of the module. Each demonstrates a different bean lifecycle managed by the EJB container.
- **Entity** (`EntityClass`) is the single data model, mapping to the `entity_class` database table via JPA. The EJB beans and DI bean conceptually interact with it, though no persistence logic is implemented in this module.
- **DI Bean** (`MultiDIBean`) is a plain class that shows how to wire together dependencies from multiple frameworks (EJB, Spring, Java EE) in a single class.

## Module Guide

### `eo.ejb.example`

The `eo.ejb.example` package is an example/demo module showcasing the various Enterprise JavaBean (EJB) component types and related Java EE patterns. It provides one representative class for each major EJB category:

- **`AllAnnotations`** — A stateless session bean that doubles as a JAX-RS REST resource. It combines `@Stateless`, `@Path`, `@GET`, and `@POST` annotations on a single class, and uses CDI `@Inject` for dependency injection. Useful for understanding how EJBs and REST endpoints can coexist.

- **`EntityClass`** — A minimal JPA entity mapped to the `entity_class` table. It has a `Long` primary key and a `name` field stored under a custom column name (`item_name`). This is a standard reference for JPA entity mapping conventions.

- **`MessageBean`** — A message-driven bean (MDB) that receives asynchronous JMS messages. It is the simplest possible MDB structure, showing how to declare a message listener with minimal boilerplate.

- **`MultiDIBean`** — Demonstrates multi-framework dependency injection by accepting `@EJB`, `@Autowired` (Spring), and `@Resource` (JNDI) injected dependencies simultaneously. This is useful for legacy or hybrid applications running EJB alongside other DI containers.

- **`SingletonBean`** — A singleton session bean with a single shared instance per application. It includes a placeholder `init()` method, which in practice would be annotated with `@PostConstruct`. Ideal for application-scoped services like caches or configuration holders.

- **`StatefulBean`** — A stateful session bean that maintains conversational state across method invocations for a given client. Useful for multi-step workflows like shopping carts or wizard-style forms.

## Getting Started

If you're exploring this codebase for the first time, here is a recommended reading order:

1. **Read this overview** (you're here!) to get the big picture.
2. **Read the `eo.ejb.example` module page** (`.codewiki/eo/ejb/example.md`) for a deep dive into each class, its annotations, and its relationships.
3. **Scan the source files directly** if you want to see the annotations in context. The six classes in `eo.ejb.example` are small and self-contained — each can be understood in isolation.

### Key classes to know

| Class | Role | Annotation |
|-------|------|-----------|
| `AllAnnotations` | Stateless session bean + REST resource | `@Stateless` |
| `EntityClass` | JPA data model | `@Entity` |
| `MessageBean` | Async JMS message listener | `@MessageDriven` |
| `MultiDIBean` | Multi-framework DI showcase | *(none — plain class)* |
| `SingletonBean` | Application-scoped shared service | `@Singleton` |
| `StatefulBean` | Client-specific conversational state | `@Stateful` |

### Bean lifecycle quick reference

| Bean | Annotation | Instance Scope |
|------|-----------|---------------|
| `AllAnnotations` | `@Stateless` | Pooled per request |
| `StatefulBean` | `@Stateful` | One per client |
| `SingletonBean` | `@Singleton` | One per application |
| `MessageBean` | `@MessageDriven` | Pooled by container |

> **Note:** All classes in this module are intentionally minimal — methods like `onMessage()`, `doWork()`, and `restMethod()` are empty placeholders. In production code, these would contain actual business logic.