---
# (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 acts as an input gatekeeper for text-edit operations on a Swing document, ensuring that only replacements that keep the overall document content numerically valid are allowed to proceed. It does not itself persist data or transform business entities; instead, it enforces a UI-level validation rule before delegating the actual document update to the parent filter implementation.

From a business perspective, this is a reusable numeric-only enforcement component that protects user input fields from accepting invalid characters or malformed numeric content. The method supports a single validation path: it reconstructs the document as it would look after the proposed edit, checks that reconstructed value with `isValid(...)`, and only then allows the replacement to continue. This implements a routing/guard pattern, where all editing requests are pre-screened before being passed downstream. In the larger system, it serves as a shared input validation utility that can be attached to multiple numeric entry fields to keep screen-level data consistent and reduce downstream validation errors.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["replace(params)"])
    GET_DOC["fb.getDocument()"]
    INIT_SB["Create StringBuilder"]
    GET_TEXT["doc.getText(0, doc.getLength())"]
    APPEND_TEXT["Append current document text"]
    REPLACE_TEXT["sb.replace(offset, offset + length, text)"]
    DECISION{"isValid(sb.toString())?"}
    CALL_SUPER["super.replace(fb, offset, length, text, attrs)"]
    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" --> CALL_SUPER
    DECISION -- "No" --> END_NODE
    CALL_SUPER --> END_NODE
```

The method first acquires the active document from the filter bypass, then snapshots the current document text into a mutable buffer. It applies the proposed edit in memory so the resulting value can be evaluated before the real document is changed. If the candidate text satisfies the numeric validation rule, the method delegates to `super.replace(...)` so the replacement is committed; otherwise, the edit is rejected silently and the document remains unchanged.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Swing filter bypass handle for the current text component; it provides access to the document being edited and is the gateway used when the method delegates the approved replacement. |
| 2 | `offset` | `int` | Starting character position of the requested replacement within the current document content; it determines where the candidate numeric value will be inserted. |
| 3 | `length` | `int` | Number of existing characters to remove before inserting the new text; it controls how much of the current value is being overwritten. |
| 4 | `text` | `String` | The user-entered replacement text that may be a digit, partial numeric fragment, or empty string during deletion; it is merged into the in-memory candidate value for validation. |
| 5 | `attrs` | `AttributeSet` | Text attributes associated with the replacement operation; in business terms, this is formatting metadata passed through to the underlying document update when the edit is accepted. |

**Instance fields / external state read by the method:** none directly. The method reads the current document content via `fb.getDocument()` and relies on the sibling validation method `isValid(...)` to decide whether the edit is allowed.

## 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 | `getDocument` | SwingDocument | `javax.swing.text.Document` | Reads the active document content from the text component through the filter bypass handle. |
| R | `getText` | SwingDocument | `javax.swing.text.Document` | Reads the current document text to construct a candidate post-edit value. |
| U | `replace` | NumericFilter | `javax.swing.text.Document` | Applies the proposed text replacement to the in-memory candidate buffer for validation purposes. |
| R | `isValid` | NumericFilter | - | Validates the candidate numeric content before allowing the real document update. |
| U | `super.replace` | NumericFilter | `javax.swing.text.Document` | Commits the approved replacement to the document by delegating to the parent filter implementation. |

## 5. Dependency Trace

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

The current code search only shows the method itself and does not expose higher-level application callers in repository Java sources, so this method should be understood as a UI framework callback invoked by Swing text editing operations. Its downstream terminal behavior is the guarded document update performed by `super.replace(...)` after validation succeeds.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQ] `(replace invoked)` (L183)

> Entry point for a proposed document replacement.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `fb.getDocument();` // obtain the active document for the edit request |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // create a mutable candidate buffer |

**Block 2** — [SEQ] `(build candidate content)` (L186-L188)

> The method reconstructs the post-edit value in memory before validating it.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `doc.getText(0, doc.getLength());` // read the full current document text |
| 2 | CALL | `sb.append(doc.getText(0, doc.getLength()));` // seed the buffer with existing content |
| 3 | CALL | `sb.replace(offset, offset + length, text);` // apply the requested replacement to the candidate value |

**Block 3** — [IF] `(isValid(sb.toString()))` (L190)

> Validation gate that decides whether the replacement can be committed.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString());` // verify that the candidate content remains numeric |

**Block 3.1** — [THEN] `(candidate value is valid)` (L191)

> Approved edits are delegated to the base filter implementation.

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

**Block 3.2** — [ELSE] `(candidate value is not valid)` (L190-L192)

> Invalid edits are rejected implicitly by doing nothing, leaving the current document unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` // exit without updating the document |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Technical term | Filter bypass handle supplied by Swing for modifying the underlying document when an edit is approved. |
| `offset` | Technical term | Starting position of the replacement inside the current text value. |
| `length` | Technical term | Number of characters to remove before inserting the new text. |
| `text` | Field | User-entered replacement content that is being validated for numeric suitability. |
| `attrs` | Technical term | Formatting attributes associated with the replacement request. |
| `Document` | Technical term | Swing text model that stores the current field content. |
| `FilterBypass` | Technical term | Swing API object that allows the filter to forward an accepted edit to the document. |
| `StringBuilder` | Technical term | Mutable in-memory buffer used to simulate the post-edit value before committing it. |
| `replace` | Technical term | Text-edit operation that overwrites a segment of the current document with new content. |
| `isValid` | Technical term | Validation rule that determines whether the candidate content is acceptable. |
| NumericFilter | Business term | UI input filter that enforces numeric-only or numerically valid text entry. |
| Swing | Acronym | Java desktop UI toolkit used to build interactive form fields and document filters. |
| CRUD | Acronym | Create, Read, Update, Delete — standard operation categories used here to classify method effects. |
| UI | Business term | User interface layer responsible for screen-level interaction and input validation. |
| `super.replace(...)` | Technical term | Parent-class document update call used to commit an accepted replacement. |