# (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 numeric-only input at the text-document layer by intercepting replacement operations before the Swing text component is updated. It reconstructs the would-be document content, applies the proposed replacement in memory, and validates the resulting text through the shared numeric validation rule. Only when the full post-change value satisfies that rule does it delegate to the parent filter to complete the update.

From a business perspective, the method acts as a guardrail for user-entered numeric values such as quantities, codes, or amounts that must never contain non-numeric characters. It is not a formatting method; instead, it is a pre-commit validation gate that prevents invalid data from reaching the field state. The method follows a routing/validation pattern: it builds the candidate value, evaluates it, and conditionally forwards the update.

In the larger system, this method supports a reusable UI constraint that can be attached to a text field document. It centralizes input validation so every replacement operation follows the same rule, regardless of whether the change comes from typing, pasting, or programmatic text replacement. The only branch handled here is the acceptance path versus the rejection path: valid numeric content is accepted and passed through, while invalid content is silently blocked.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["replace(fb, offset, length, text, attrs)"])
    GET_DOC(["Get document from FilterBypass"])
    INIT_SB(["Create StringBuilder"])
    READ_TEXT(["Read current document text"])
    APPEND_TEXT(["Append existing text to StringBuilder"])
    APPLY_REPLACE(["Apply proposed replacement to StringBuilder"])
    CHECK_VALID{["isValid(candidateText)?"]}
    CALL_SUPER(["super.replace(fb, offset, length, text, attrs)"])
    END_NODE(["Return / Next"])
    BLOCKED(["Reject invalid replacement and exit"])

    START --> GET_DOC
    GET_DOC --> INIT_SB
    INIT_SB --> READ_TEXT
    READ_TEXT --> APPEND_TEXT
    APPEND_TEXT --> APPLY_REPLACE
    APPLY_REPLACE --> CHECK_VALID
    CHECK_VALID -->|Yes| CALL_SUPER
    CHECK_VALID -->|No| BLOCKED
    CALL_SUPER --> END_NODE
    BLOCKED --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | The document-update gateway provided by the Swing text system. It represents the active text component state and is used to read the current document before deciding whether the replacement may proceed. |
| 2 | `offset` | `int` | The insertion point where the proposed text change begins. Business-wise, it marks the position in the user-entered numeric field that will be overwritten or extended. |
| 3 | `length` | `int` | The number of characters to remove starting at `offset`. It represents the portion of the current value that the user intends to replace. |
| 4 | `text` | `String` | The candidate input text to be inserted into the field. This is the new user-entered content that may contain digits only if the replacement is to be accepted. |
| 5 | `attrs` | `AttributeSet` | The style and formatting metadata associated with the replacement request. It does not influence numeric validation, but it is forwarded when the update is allowed. |

External state read by the method:
- The current document text obtained from `fb.getDocument()`.
- The validation rule implemented by `isValid(...)` in the same class.

## 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` |

This method performs no database CRUD. Its only business action is a UI-level update control around a document replacement operation, plus a validation call in the same class.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `NumericFilter.isValid` | NumericFilter | In-memory candidate text | Validates the reconstructed candidate value before permitting the document update. |
| U | `DocumentFilter.replace` via `super.replace` | javax.swing.text.DocumentFilter | Swing document | Applies the accepted text replacement to the active text document. |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | UI component document pipeline | `JTextField document event` -> `DocumentFilter.replace` -> `NumericFilter.replace` | `NumericFilter.isValid [R] in-memory candidate text` |

The direct caller is the Swing document-editing framework, not an application screen or batch class. This method ultimately calls the local validation routine and, on success, delegates to the parent document filter implementation to complete the update.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] (L183-L188)
> Builds the candidate post-edit text by reading the current document and applying the requested replacement in memory.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Document doc = fb.getDocument();` // obtains the active text document |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // prepares a mutable buffer for the candidate value |
| 3 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` // reads the full current text and appends it |
| 4 | EXEC | `sb.replace(offset, offset + length, text);` // simulates the requested document replacement |

**Block 2** — [IF] (`isValid(sb.toString())`) (L190)
> Validates the reconstructed value before allowing the document to change.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString());` // checks whether the candidate text is numeric |

**Block 2.1** — [THEN] (valid candidate) (L191)
> Accepts the update and forwards it to the Swing document filter implementation.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.replace(fb, offset, length, text, attrs);` // commits the replacement to the document |

**Block 2.2** — [ELSE] (invalid candidate) (L190-L192)
> Rejects the change by doing nothing, leaving the document unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `// implicit return with no document update` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Technical term | Filter bypass handle used by Swing to access and update the current text document. |
| `offset` | Technical term | Starting character position for the requested replacement. |
| `length` | Technical term | Number of characters to remove starting at `offset`. |
| `text` | Field | Replacement content entered by the user or provided programmatically. |
| `attrs` | Technical term | Character attribute metadata carried with the text change request. |
| `DocumentFilter` | Technical term | Swing filter that intercepts document edits before they are applied. |
| `FilterBypass` | Technical term | Swing mechanism that allows controlled access to the underlying document. |
| `PlainDocument` | Technical term | Swing text document implementation used by the field in this UI. |
| `StringBuilder` | Technical term | Mutable text buffer used to build the candidate post-edit value. |
| `isValid` | Method | Local validation rule that checks whether the resulting text is acceptable. |
| `NumericFilter` | Component | Reusable input guard that permits only numeric text changes. |
| `super.replace` | Technical term | Parent implementation that applies the approved document change. |