---

# (DD12) Business Logic — NumericFilter.replace() [12 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.github.blaxk3.ui.NumericFilter` |
| Layer | Utility |
| Module | `ui` (Package: `com.github.blaxk3.ui`) |

## 1. Role

### NumericFilter.replace()

This method enforces a numeric-only input rule at the point where a text document is being modified. It simulates the next document state by taking the current text, applying the proposed replacement, and then validating the resulting value before allowing the edit to proceed. In business terms, it acts as a front-line data quality gate for user-entered numeric fields, preventing invalid characters from ever being committed to the UI model.

The method is not a general-purpose text editor; it is a focused input-filtering routine that supports a single service category: numeric entry. Its design follows a validate-then-delegate pattern. First it reconstructs the candidate document content, then it delegates to `isValid()` for rule enforcement, and only if the result passes does it invoke `super.replace(...)` to perform the actual update. Within the larger system, this method is a reusable UI guardrail that can be attached to input components wherever numeric values must be protected from accidental non-numeric entry.

Because the method contains a single conditional branch, its business behavior is binary: valid candidate values are accepted and written to the document, while invalid candidate values are silently rejected by doing nothing. The absence of error messaging indicates that the method is intended to prevent invalid state rather than manage user-facing validation feedback.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["replace(params)"])
    GET_DOC["Get document from FilterBypass"]
    INIT_SB["Create StringBuilder"]
    GET_TEXT["Read current document text"]
    APPEND_TEXT["Append text into StringBuilder"]
    REPLACE_TEXT["Replace range in StringBuilder"]
    DECISION{"isValid(candidateText)?"}
    SUPER_REPLACE["Call super.replace(...) to apply numeric input"]
    END_NODE(["Return / Next"])

    START --> GET_DOC
    GET_DOC --> INIT_SB
    INIT_SB --> GET_TEXT
    GET_TEXT --> APPEND_TEXT
    APPEND_TEXT --> REPLACE_TEXT
    REPLACE_TEXT --> DECISION
    DECISION -->|Yes| SUPER_REPLACE
    DECISION -->|No| END_NODE
    SUPER_REPLACE --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | The document-edit bypass handle supplied by the Swing text filtering framework. It provides access to the underlying document so the method can evaluate the proposed text after the edit is simulated. |
| 2 | `offset` | `int` | The insertion/replacement start position within the current document content. It determines where the user’s numeric input attempt will be applied in the candidate text. |
| 3 | `length` | `int` | The number of existing characters to remove before inserting the new text. It controls whether the operation is a pure insert, a replace, or a delete-and-insert combination. |
| 4 | `text` | `String` | The user-entered text that is about to be inserted into the field. This is the proposed numeric content that must pass validation before the edit is accepted. |
| 5 | `attrs` | `AttributeSet` | Formatting and style attributes associated with the edit request. The method forwards these attributes unchanged to the parent implementation if validation succeeds. |

**Instance fields or external state read by the method:** None directly. The method reads the current document contents from `fb.getDocument()` and depends on the inherited validation behavior exposed through `isValid(...)`.

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `NumericFilter.isValid` | NumericFilter | - | Calls `isValid` in `NumericFilter` |
| U | `NumericFilter.replace` | NumericFilter | - | Calls `replace` in `NumericFilter` |

Analyze all method calls within this method and classify each as a CRUD operation.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `fb.getDocument` | Swing Document API | - | Reads the underlying document so the method can reconstruct the candidate text value. |
| R | `doc.getText` | Swing Document API | - | Reads the current field contents for validation against the proposed edit. |
| U | `StringBuilder.replace` | Java Standard Library | - | Produces the candidate post-edit value by applying the user’s requested change to the in-memory text buffer. |
| R | `isValid` | `NumericFilter` | - | Evaluates whether the reconstructed content satisfies the numeric-entry rule. |
| U | `super.replace` | `NumericFilter` | - | Applies the edit to the document only when validation succeeds. |

## 5. Dependency Trace

Trace who calls this method and what this method ultimately calls.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen / UI component using `NumericFilter` | `UI text component` -> `NumericFilter.replace` | `super.replace [U] Swing Document` |

## 6. Per-Branch Detail Blocks

**Block 1** — `TRY` `(method entry)` (L183)

> Entry point for a proposed document replacement request.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Document doc = fb.getDocument();` |
| 2 | SET | `StringBuilder sb = new StringBuilder();` |
| 3 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` |
| 4 | EXEC | `sb.replace(offset, offset + length, text);` |

**Block 1.1** — `IF` `(isValid(sb.toString()))` (L190)

> Validates the candidate document content after applying the requested edit.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString());` |

**Block 1.1.1** — `THEN` `(validation passed)` (L191)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.replace(fb, offset, length, text, attrs);` |

**Block 1.2** — `ELSE` `(validation failed)` (L190)

| # | Type | Code |
|---|------|------|
| 1 | RETURN | No document update is performed; the invalid edit is rejected silently. |

**Block 2** — `RETURN` `(method exit)` (L193)

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `void` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | A UI input filter that restricts edits to numeric values only. |
| `replace` | Method | The document-edit interception method that validates a proposed replacement before applying it. |
| `FilterBypass` | Technical term | Swing callback object that grants controlled access to the underlying text document. |
| `Document` | Technical term | The text model backing the UI field being edited. |
| `StringBuilder` | Technical term | Mutable buffer used to simulate the post-edit document content. |
| `offset` | Field / parameter | The starting character position where the edit will be applied. |
| `length` | Field / parameter | The number of characters to remove at the edit position. |
| `text` | Field / parameter | The incoming user-entered text intended for insertion. |
| `attrs` | Field / parameter | Formatting attributes associated with the edit operation. |
| `isValid` | Method | Validation rule that decides whether the resulting text satisfies the numeric-only constraint. |
| `super.replace` | Technical term | Parent implementation call that commits the edit to the document when validation passes. |
| CRUD | Acronym | Create, Read, Update, Delete — standard operation categories used to classify method effects. |
| UI | Acronym | User Interface — the presentation layer where the field editing behavior is applied. |