---
# (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()

`NumericFilter.replace()` is a UI-level input validation gate for text components that accept numeric values. Its business role is to intercept an edit request, rebuild the full candidate document content after the proposed replacement, and allow the edit only when the resulting text is a valid numeric string. In practice, this makes the method a protective filter for number-entry fields, preventing users from typing invalid characters or malformed numeric content into the screen. The method implements a simple routing/guard pattern: it reconstructs the would-be document state, delegates validation to `isValid()`, and only forwards the edit to the standard Swing `DocumentFilter` behavior when validation succeeds. If validation fails, the edit is silently blocked and the document remains unchanged. Because it operates through `FilterBypass`, it acts as a shared reusable UI control rather than a business service or data access entry point.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["replace(params)"]
    GET_DOC["fb.getDocument()"]
    INIT_BUILDER["Create StringBuilder"]
    READ_TEXT["doc.getText(0, doc.getLength())"]
    APPEND_TEXT["sb.append(currentDocumentText)"]
    APPLY_REPLACE["sb.replace(offset, offset + length, text)"]
    VALIDATE{["isValid(sb.toString())?"]}
    CALL_SUPER["super.replace(fb, offset, length, text, attrs)"]
    BLOCKED["Do not apply edit"]
    END_NODE["Return"]

    START --> GET_DOC
    GET_DOC --> INIT_BUILDER
    INIT_BUILDER --> READ_TEXT
    READ_TEXT --> APPEND_TEXT
    APPEND_TEXT --> APPLY_REPLACE
    APPLY_REPLACE --> VALIDATE
    VALIDATE -->|Yes| CALL_SUPER
    VALIDATE -->|No| BLOCKED
    CALL_SUPER --> END_NODE
    BLOCKED --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Swing document bypass handle used to read the current field content and forward an approved edit to the underlying text component. |
| 2 | `offset` | `int` | Zero-based insertion/replacement position within the editable numeric field. It determines where the candidate change will be applied. |
| 3 | `length` | `int` | Number of existing characters to remove before inserting `text`. It controls the size of the replacement range. |
| 4 | `text` | `String` | Proposed user-entered content that will be inserted into the field. This may be a digit, a decimal point, or an empty string for deletion. |
| 5 | `attrs` | `AttributeSet` | Text attributes passed through to the underlying document when the replacement is accepted. |

**Instance fields / external state read by this method:** none directly. The method reads the current document state via `fb.getDocument()` and `doc.getText(...)`.

## 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 | `Document.getDocument` | Swing Document | - | Retrieves the current document backing the text field so a candidate edit can be evaluated. |
| R | `Document.getText` | Swing Document | - | Reads the current document content for reconstruction of the post-edit value. |
| U | `StringBuilder.replace` | Java Standard Library | - | Applies the proposed replacement to the reconstructed text buffer. |
| R | `NumericFilter.isValid` | NumericFilter | - | Validates whether the candidate text is allowed for numeric input. |
| U | `DocumentFilter.replace` via `super.replace` | NumericFilter | - | Commits the edit to the underlying document only when validation passes. |

## 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 | CBS/Utility: `NumericFilter` internal framework callback | `Document editing event` -> `NumericFilter.replace` | `NumericFilter.isValid [R] -` |

**Notes:** The search results available in this task only show `replace(` occurrences inside `UI.java` itself, so this method is documented as a framework callback rather than a screen-specific business entry point. The method's external effect is limited to the Swing document update path.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] (L183-L191)

> Reconstructs the edited numeric value and validates it before committing the change.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `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);` |
| 5 | CALL | `if (isValid(sb.toString())) {` |

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

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

**Block 1.2** — [ELSE] invalid candidate text (L190)

> The replacement is rejected by omission, leaving the original document content unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `// no operation` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | Swing document filter that enforces numeric-only input in UI fields. |
| `replace` | Method | Replacement hook invoked when a user edits the text field content. |
| `FilterBypass` | Technical term | Swing callback handle that allows approved document changes to be applied. |
| `offset` | Field/Parameter | Starting character position for the proposed edit. |
| `length` | Field/Parameter | Count of characters to remove before inserting new text. |
| `text` | Field/Parameter | Candidate user-entered text to be inserted into the field. |
| `attrs` | Field/Parameter | Optional text attributes associated with the replacement. |
| `Document` | Technical term | Swing text model storing the current contents of the field. |
| `StringBuilder` | Technical term | Mutable buffer used to reconstruct the future document value. |
| `isValid` | Method | Local validation rule that checks whether the candidate string is numeric. |
| `super.replace` | Technical term | Default Swing document-filter behavior used to commit the accepted edit. |
| numeric input | Business term | Text input restricted to digits and a single decimal point, suitable for quantity or amount fields. |
| decimal point | Business term | Period character used to allow fractional numeric values. |
| UI | Acronym | User Interface — the presentation layer where the input filter runs. |