# Getting Started

Welcome to the EO project. If you just joined the team, this guide will help you orient yourself quickly and start contributing.

## What This Project Does

EO is a small **Enterprise JavaBean (EJB)** reference project that demonstrates core Java EE patterns: stateless session beans with container-managed dependency injection, and reflection-based dynamic class loading. It contains no external framework dependencies beyond the `javax.ejb` API and is intentionally minimal -- about 5 source files across 3 subpackages. Think of it as a teaching module and pattern reference, not a production application.

## Recommended Reading Order

Read the wiki pages in this order to build understanding incrementally:

1. **[Overview](../overview.md)** -- High-level summary of the project, technology stack, and architecture.
2. **[eo/ejb/example](../eo/ejb/example.md)** -- The simplest class (`PatternOneVar`) that shows reflection-based loading in 5 lines of code.
3. **[eo/ejb/wiki](../eo/ejb/wiki.md)** -- The more capable reflection utilities (`PlainClass` and `ReflectiveClass`), plus the one cross-package dependency in the codebase.
4. **[eo/ejb/service](../eo/ejb/service.md)** -- The EJB-side: `@Stateless` beans and `@EJB` dependency injection.
5. **[eo/ejb module](../eo/ejb.md)** -- A deep dive into dependencies, interaction flows, and developer notes with important caveats.

## Key Entry Points

Start with these classes, in order:

- **[PatternOneVar](../eo/ejb/example.md)** (`eo.ejb.example.PatternOneVar`) -- The simplest class in the project. One method, one responsibility: load a class by name and instantiate it via reflection. Read this first to understand the core pattern.
- **[PlainClass](../eo/ejb/wiki.md)** (`eo.ejb.wiki.PlainClass`) -- A 3-line data holder with a `greet()` method. Establishes the coding style of the project.
- **[ReflectiveClass](../eo/ejb/wiki.md)** (`eo.ejb.wiki.ReflectiveClass`) -- Builds on `PatternOneVar`'s pattern with two methods: `loadByReflection()` and `invokeMethod()`. This is the most code-heavy class in the project.
- **[StatelessBean](../eo/ejb/service.md)** (`eo.ejb.service.StatelessBean`) -- The simplest EJB: a single `@Stateless` bean with one `execute()` method.
- **[EJBWithArgs](../eo/ejb/service.md)** (`eo.ejb.service.EJBWithArgs`) -- Shows `@EJB` dependency injection delegating to an external `MyService`. Zero local business logic by design.

## Project Structure

```mermaid
flowchart TD
    ROOT["eo.ejb Package"]
    ROOT --> EX["eo.ejb.example
standalone reflection example"]
    ROOT --> SVC["eo.ejb.service
EJB beans + injection"]
    ROOT --> WIKI["eo.ejb.wiki
string utility + reflection"]
    SVC --> SB["StatelessBean
@Stateless"]
    SVC --> EA["EJBWithArgs
@EJB client"]
    WIKI --> PC["PlainClass
greeting utility"]
    WIKI --> RC["ReflectiveClass
reflection factory"]
    WIKI -->|depends on| SVC
```

The package breakdown:

| Package | Files | Purpose |
|---------|-------|---------|
| `eo.ejb.example` | `PatternOneVar.java` | Standalone reflection demo; no dependencies |
| `eo.ejb.service` | `StatelessBean.java`, `EJBWithArgs.java` | EJB stateless beans and injection client |
| `eo.ejb.wiki` | `PlainClass.java`, `ReflectiveClass.java` | String utility + reflection factory |

There is exactly one cross-package dependency: `eo.ejb.wiki` depends on `eo.ejb.service`. Everything else is self-contained.

## Configuration

This project has no build configuration files (Maven `pom.xml` or Gradle `build.gradle`) in the root directory. The `javax.ejb` annotations (`@Stateless`, `@EJB`) imply an EJB container is required at deployment time, but the project itself is not wired to a specific container or server.

Key things to know:

- `EJBWithArgs` expects a `MyService` bean available in the container under the JNDI name `"myBean"`. If the container does not provide this bean, injection will fail at deployment.
- The reflection utilities (`ReflectiveClass`, `PatternOneVar`) require target classes to have accessible no-argument constructors. There is no mechanism to pass constructor arguments.

## Common Patterns

### Reflection-based class loading

Two packages independently implement the same pattern:

1. Accept a fully qualified class name as a `String`.
2. Resolve the class via `Class.forName(clsName)`.
3. Instantiate via `newInstance()`.
4. Return or act on the resulting object.

```java
// PatternOneVar (simple)
Object obj = Class.forName(clsName).newInstance();

// ReflectiveClass (with method invocation)
Object obj = Class.forName(targetClass).newInstance();
Method m = cls.getMethod("execute");
m.invoke(null);
```

Note: `Class.newInstance()` was deprecated in Java 9. For newer Java versions, replace with `Class.getDeclaredConstructor().newInstance()`.

### EJB stateless bean

`StatelessBean` follows the classic EJB stateless pattern:

- Annotated with `@Stateless` -- the container pools instances.
- No instance fields holding conversational state -- inherently thread-safe.
- A single business method (`execute()`) performs a side effect.

When extending, **do not add instance fields** that hold state. The container pools and reuses bean instances, and fields would be unsafe across invocations.

### Thin client / delegation

`EJBWithArgs` is a pure delegation class -- it contains zero business logic. Its sole purpose is to demonstrate `@EJB` injection and pass-through to a resolved dependency. This "thin client" pattern keeps concerns separated: the EJB container handles wiring, and the injected `MyService` carries the actual logic.

### Error handling

None of the reflection methods catch specific exceptions. They declare `throws Exception` and leave error handling to callers. Key exceptions to watch for:

- `ClassNotFoundException` -- class name not found on the classpath.
- `InstantiationException` / `IllegalAccessException` -- target class has no accessible no-arg constructor.
- `NoSuchMethodException` -- target class lacks a public static `execute()` method.

### Security note

The reflection utilities accept arbitrary class names. Passing untrusted input to `loadByReflection()` or `PatternOneVar.load()` is a security risk. Consider whitelisting allowed class names in production use.

## What's Not Here

- No entity classes, DTOs, or persistent data models.
- No test files.
- No build configuration (Maven / Gradle / Ant).
- No third-party libraries beyond `javax.ejb`.

If you need to set up a build or add tests, that configuration does not exist yet in this project.