# Getting Started

## What This Project Does

This repository is 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. Use it as a hands-on reference for how to structure different bean types, apply common annotations, and mix EJB lifecycle patterns within a single application.

## Recommended Reading Order

Start here and work your way through the wiki in this order:

1. **"[Overview](../overview.md)"** — Big-picture context: what technologies are used, how the pieces fit together, and the project's goals.
2. **"[eo.ejb.example Module](../eo/ejb/example.md)"** — Deep dive into every class, its annotations, lifecycle, and relationships.
3. **Source files** — The six classes in `eo.ejb.example` are each under 30 lines and self-contained. Read them directly to see the annotations in context.

## Key Entry Points

These six classes are the most important to understand first. Each one is a standalone example of a distinct EJB pattern.

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

### Where to look first

- **For REST / EJB integration** — Read `AllAnnotations` to see how `@Stateless` and JAX-RS annotations (`@Path`, `@GET`, `@POST`) coexist on a single class.
- **For data persistence** — Read `EntityClass` to see a minimal JPA entity with `@Id`, `@Table`, and `@Column` mappings.
- **For asynchronous messaging** — Read `MessageBean` to see the simplest possible MDB structure.
- **For dependency injection** — Read `MultiDIBean` to see how `@EJB`, `@Autowired` (Spring), and `@Resource` (JNDI) can coexist in one class.
- **For shared application state** — Read `SingletonBean` to see the single-instance pattern useful for caches or config holders.
- **For conversational state** — Read `StatefulBean` to see the per-client stateful pattern useful for multi-step workflows.

## Project Structure

The repository centers on a single top-level package, `eo.ejb.example`, which contains six Java classes organized into three conceptual groups:

```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`) — Each demonstrates a different bean lifecycle managed by the EJB container. They are independent and share no direct code dependencies.
- **Entity** (`EntityClass`) — The single data model, mapping to the `entity_class` table via JPA.
- **DI Bean** (`MultiDIBean`) — A plain class (no EJB annotation) that shows how to wire together dependencies from EJB, Spring, and Java EE in one class.

There are no sub-packages or nested modules. All six classes live at the same level.

## Technology Stack

| 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** | `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 or serves as a reference for migration scenarios.

## Configuration

This module does not define any XML configuration files (e.g. `web.xml`, `persistence.xml`). Everything is configured through annotations:

| What | Where | Example |
|------|-------|---------|
| EJB type | Class-level annotation | `@Stateless`, `@Stateful`, `@Singleton`, `@MessageDriven` |
| Database table | `@Entity` + `@Table` | `@Entity @Table(name = "entity_class")` |
| Column mapping | `@Column` | `@Column(name = "item_name")` |
| REST path | `@Path` | `@Path("/api/annotations")` |
| JNDI resource | `@Resource` | `@Resource private DataSource dataSource` |
| DI framework | `@Inject`, `@EJB`, `@Autowired` | Per-field injection annotations |

The project uses the `javax.*` namespace (not `jakarta.*`), meaning it targets Java EE 8 or earlier. If you are migrating to Jakarta EE 9+, update the package names accordingly.

## Common Patterns

### One annotation per bean

Each EJB bean uses exactly one lifecycle annotation (`@Stateless`, `@Stateful`, `@Singleton`, or `@MessageDriven`). There is no mixing — each class represents a single lifecycle type.

```java
@Stateless              // Exactly one bean annotation
@Path("/api/annotations")  // Can layer REST annotations on top
public class AllAnnotations { ... }
```

### Minimal, intentional stubs

All classes are intentionally minimal. Methods like `onMessage()`, `doWork()`, and `restMethod()` are empty placeholders. In production code these would contain business logic. Use them as skeletons to extend.

### No cross-class dependencies

The classes in `eo.ejb.example` do not import or reference each other. Each is self-contained. Injected types like `SomeService`, `InventoryService`, and `NotificationService` come from external dependencies, not from this package.

### Thread safety on Singletons

`@Singleton` beans have a single shared instance. If you store mutable state, you must handle synchronization yourself unless you annotate the bean with `@ConcurrencyManagement(LOCK_CONTAINERS)`.

### CDI injection inside EJBs

CDI `@Inject` works inside EJBs. `AllAnnotations` demonstrates this by injecting `SomeService` using the standard CDI annotation inside a stateless EJB class.

### Bean lifecycle summary

```mermaid
flowchart LR
    SLS["Stateless
AllAnnotations"]
    SFS["Stateful
StatefulBean"]
    Sng["Singleton
SingletonBean"]
    MDB["Message Driven
MessageBean"]

    SLS -->|REST + CDI| SVC["External Services"]
    SFS -->|conversational| CLIENT["Client Session"]
    Sng -->|shared state| CACHE["Application Cache"]
    MDB -->|async| QUEUE["JMS Queue"]

    ENTITY["EntityClass
JPA Entity"] -.->|maps to| DB["entity_class Table"]
```

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

## Next Steps

- Read the **[Overview](../overview.md)** for the full project context.
- Read **[eo.ejb.example](../eo/ejb/example.md)** for per-class annotations, methods, and notes.
- Check the Java EE / Jakarta EE documentation for deep dives into EJB lifecycle, concurrency, and JPA mapping.