# Getting Started

Welcome to the project! This guide will help you orient yourself and hit the ground running. Read through it in about 5–10 minutes.

## What This Project Does

This is an educational Java repository that demonstrates two contrasting programming approaches side by side: **direct, compile-time-safe programming** and **dynamic, runtime-driven reflection**. The single module `eo.ejb.wiki` contains a simple data-carrier class and a reflection-based utility class — both independent, with no external dependencies. Think of it as a self-contained reference for understanding fundamental Java patterns.

## Recommended Reading Order

New engineers should read in this order to build understanding progressively:

1. **[PlainClass.java](PlainClass.java)** — The simplest entry point (~13 lines). Read it in 30 seconds. It shows how straightforward object-oriented programming works: a constructor, a field, a single method.
2. **[ReflectiveClass.java](ReflectiveClass.java)** — Equally short (~18 lines) but introduces Java Reflection: `Class.forName()`, `Class.newInstance()`, and `java.lang.reflect.Method`. This shows the dynamic-programming alternative.
3. **[The wiki documentation](eo/ejb/wiki.md)** — A deep dive into constructors, methods, exception handling, null safety, and integration notes.
4. **[Repository overview](.codewiki/overview.md)** — The big-picture context, architecture diagram, and technology stack.

```mermaid
flowchart TD
    A["Reading Order"] --> B["PlainClass.java"]
    B --> C["ReflectiveClass.java"]
    C --> D["eo/ejb/wiki.md"]
    D --> E["Overview"]
```

## Key Entry Points

These are the two classes you should understand first:

### PlainClass

A minimal POJO located at [`PlainClass.java`](PlainClass.java). It wraps a single `name` field and provides a `greet()` method. No dependencies, no side effects — just pure data and a derived operation. This is your anchor for understanding the "direct" approach.

Key methods:
- **`PlainClass(String name)`** — Constructor. Stores the name; no null checks.
- **`greet()`** — Returns `"Hello, " + name`. A pure, stateless computation.

### ReflectiveClass

A reflection utility located at [`ReflectiveClass.java`](ReflectiveClass.java). It takes a fully qualified class name as a string and uses `Class.forName()` to dynamically load and instantiate it at runtime. This is your anchor for understanding the "reflective" approach.

Key methods:
- **`ReflectiveClass(String targetClass)`** — Constructor. Stores the target class name.
- **`loadByReflection()`** — Dynamically loads a class and creates an instance. Throws `Exception` (broad — callers should handle `ClassNotFoundException`, `InstantiationException`, `IllegalAccessException`).
- **`invokeMethod(Class<?> cls)`** — Looks up and invokes a static no-arg `execute()` method on the given class via reflection.

## Project Structure

The codebase is intentionally minimal — a single flat package with two classes and no sub-modules.

```mermaid
flowchart LR
    Wiki["Package eo.ejb.wiki"]
    subgraph Classes [ ]
        PC["PlainClass"]
        RC["ReflectiveClass"]
    end
    Wiki --> PC
    Wiki --> RC
```

| File / Directory | Purpose |
|---|---|
| `PlainClass.java` | Simple data-carrier class (direct programming example) |
| `ReflectiveClass.java` | Reflection utility class (dynamic programming example) |
| `.codewiki/eo/ejb/wiki.md` | Detailed class documentation for `eo.ejb.wiki` |
| `.codewiki/overview.md` | Repository-level overview and architecture |
| `.codewiki/tree.json` | Structural index of the codebase |

## Configuration

This project has minimal configuration:

- **No build tools detected** — There is no `pom.xml`, `build.gradle`, or equivalent. To compile, use `javac` directly:
  ```bash
  javac PlainClass.java ReflectiveClass.java
  ```
- **No external dependencies** — Everything runs on the JDK core (`java.base`). No third-party libraries are needed.
- **Java version** — The code uses `Class.newInstance()`, which has been deprecated since Java 9. For modern Java (9+), the recommended replacement is:
  ```java
  Class.forName(targetClass).getDeclaredConstructor().newInstance();
  ```
  Expect compiler warnings on Java 9+ unless you update this.

## Common Patterns

### Direct vs. Reflective Programming

This codebase demonstrates two contrasting patterns:

| Approach | Class | Characteristics |
|----------|-------|-----------------|
| Direct | `PlainClass` | Compile-time safety, known structure, no exceptions |
| Reflective | `ReflectiveClass` | Runtime flexibility, deferred type resolution, exceptions at runtime |

### Exceptions

Reflective methods declare `throws Exception` broadly. When using `ReflectiveClass`, catch specific exception types for cleaner error handling:

- **`ClassNotFoundException`** — The class name is invalid or not on the classpath.
- **`InstantiationException`** — The class cannot be instantiated (e.g., abstract class).
- **`IllegalAccessException`** — The constructor is not accessible.
- **`NoSuchMethodException`** — The target method does not exist.
- **`InvocationTargetException`** — The invoked method itself threw an exception.

### Null Safety

Neither class performs null checks on constructor parameters. Passing `null` will either produce unexpected output (`"Hello, null"`) or a runtime exception. Always validate inputs before instantiation.

### Security

Dynamically loading and invoking classes via reflection can be a security concern if the class name or method originates from untrusted input. Validate and sanitize these values before use in production code.

### Reflection Deprecation

If you need to update `ReflectiveClass` for Java 9+ compatibility, replace `Class.newInstance()` with:

```java
Class.forName(targetClass).getDeclaredConstructor().newInstance();
```

This is a straightforward find-and-replace and restores the ability to use reflection without deprecation warnings.

---

That is all there is to this repository. It is intentionally small — designed to be fully understood in a single sitting. If you have questions, the [wiki documentation](eo/ejb/wiki.md) has you covered.