---

# (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 a numeric input gate for a text component, ensuring that a proposed edit keeps the document in a valid state before the underlying text is actually replaced. In business terms, it supports controlled entry of numeric values by simulating the post-edit document content, validating that result, and only then allowing the edit to proceed. The method follows a routing/guard pattern: it constructs the would-be final text, delegates the validation decision to `isValid()`, and conditionally delegates to the parent implementation only when the edit is acceptable.

Its role in the larger system is that of a reusable UI-level validator that can be attached to multiple screens or fields requiring numeric-only input. The method does not perform persistence, service orchestration, or domain record updates; instead, it protects user input at the component boundary. There are two effective branches: one branch accepts the edit and passes control to the superclass replacement behavior, while the other branch rejects the edit by doing nothing further.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["replace(params)"])
    GETDOC(["fb.getDocument()"])
    INITSB(["Create StringBuilder"])
    GETTEXT(["doc.getText(0, doc.getLength())"])
    APPEND(["sb.append(existing text)"])
    REPLACE(["sb.replace(offset, offset + length, text)"])
    VALIDATE{"isValid(sb.toString())?"}
    SUPERREPLACE(["super.replace(fb, offset, length, text, attrs)"])
    END_NODE(["Return / Next"])

    START --> GETDOC
    GETDOC --> INITSB
    INITSB --> GETTEXT
    GETTEXT --> APPEND
    APPEND --> REPLACE
    REPLACE --> VALIDATE
    VALIDATE -->|Yes| SUPERREPLACE
    VALIDATE -->|No| END_NODE
    SUPERREPLACE --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | The document-edit bypass handle supplied by the text component framework. It provides access to the underlying document so the method can inspect the current text before deciding whether a new value may be accepted. |
| 2 | `offset` | `int` | The starting character position of the proposed replacement. It determines where the incoming text will be inserted or substituted inside the current document content. |
| 3 | `length` | `int` | The number of existing characters to remove before inserting the new text. It represents the span of the current value that will be replaced by the user's input. |
| 4 | `text` | `String` | The candidate user-entered text that should replace the selected document range. It is evaluated as part of the simulated final value used for validation. |
| 5 | `attrs` | `AttributeSet` | Character attribute metadata associated with the text replacement request. In this method it is passed through unchanged to the superclass once validation succeeds. |

**External state read by the method:** the current document content obtained from `fb.getDocument()`, and the validation rules encapsulated in `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 | `NumericFilter.isValid` | NumericFilter | - | Reads the simulated post-edit document content and validates whether the proposed input is numerically acceptable. |
| U | `NumericFilter.replace` | NumericFilter | - | Updates the text component content by applying the replacement only after 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 | UI text component framework / document filter pipeline | `TextComponent / DocumentFilter infrastructure` -> `NumericFilter.replace` | `NumericFilter.isValid [R] -` |

## 6. Per-Branch Detail Blocks

**Block 1** — [METHOD ENTRY] `(replace(FilterBypass fb, int offset, int length, String text, AttributeSet attrs))` (L183)

> Initializes validation for a proposed document replacement.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `fb.getDocument();` |
| 2 | SET | `Document doc = fb.getDocument();` |
| 3 | SET | `StringBuilder sb = new StringBuilder();` |

**Block 1.1** — [SEQUENTIAL PROCESS] `(build simulated next value)` (L185-L188)

> Reads the current document text and applies the candidate replacement to a temporary buffer.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `doc.getText(0, doc.getLength());` |
| 2 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` |
| 3 | EXEC | `sb.replace(offset, offset + length, text);` |

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

> Validates whether the simulated document content is acceptable for numeric input.

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

**Block 2.1** — [THEN] `(validation succeeds)` (L191)

> Applies the replacement to the underlying document by delegating to the superclass implementation.

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

**Block 2.2** — [ELSE] `(validation fails)` (L190-L192)

> Rejects the edit by skipping the superclass call and leaving the document unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Technical term | Filter bypass handle from the Swing document filtering framework. It grants access to the backing document so edits can be validated before being committed. |
| `offset` | Technical term | Start position of the proposed text replacement within the current document. |
| `length` | Technical term | Number of existing characters that will be removed before inserting the new text. |
| `text` | Technical term | Candidate replacement content entered by the user. |
| `attrs` | Technical term | Text attribute metadata carried by the UI editing framework. |
| `Document` | Technical term | Swing text model holding the current field value. |
| `StringBuilder` | Technical term | Temporary buffer used to simulate the post-edit document content. |
| `DocumentFilter` | Technical term | Swing extension point used to validate or transform edits before they are applied. |
| `FilterBypass` | Technical term | Framework object that allows the filter to forward a validated edit to the document. |
| `isValid` | Technical term | Validation method that determines whether the resulting text satisfies the numeric input rule. |
| Numeric input | Business term | A field value that must contain only acceptable numeric characters and structure according to UI validation rules. |
| UI | Layer term | Presentation-layer component responsible for user interaction and input control. |