---

# (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 validation gate for text replacement operations inside a Swing document that is expected to contain numeric input only. It intercepts a proposed edit, reconstructs the would-be document content after the edit, and then decides whether the replacement may proceed. If the resulting text still satisfies the numeric rule enforced by `isValid()`, the method delegates to the superclass to apply the change; otherwise, it blocks the edit by doing nothing.

From a business perspective, this is a shared UI input-protection mechanism used to prevent invalid non-numeric values from reaching downstream forms, calculations, or persistence layers. The method follows a routing/validation pattern: it does not transform business data itself, but it evaluates the candidate value and conditionally forwards the change. The only branch is the validity check, which separates acceptable numeric input from rejected edits.

In the larger system, this method is part of a reusable document filter that standardizes numeric entry behavior across screens. It provides a consistent user-experience control at the boundary of data capture, reducing the need for later validation and helping preserve data integrity at the point of input.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["replace(fb, offset, length, text, attrs)"]
    GET_DOC["fb.getDocument()"]
    NEW_SB["Create StringBuilder"]
    APPEND_TEXT["sb.append(doc.getText(0, doc.getLength()))"]
    REPLACE_TEXT["sb.replace(offset, offset + length, text)"]
    VALIDATE{"isValid(sb.toString())"}
    CALL_SUPER["super.replace(fb, offset, length, text, attrs)"]
    END["Return"]
    START --> GET_DOC
    GET_DOC --> NEW_SB
    NEW_SB --> APPEND_TEXT
    APPEND_TEXT --> REPLACE_TEXT
    REPLACE_TEXT --> VALIDATE
    VALIDATE -->|"true"| CALL_SUPER
    VALIDATE -->|"false"| END
    CALL_SUPER --> END
```

**Constant Resolution:**
No application constants are referenced in this method. The control flow depends only on runtime document content and the `isValid()` predicate.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Document filter bypass handle that provides access to the underlying text document and allows the approved replacement to be forwarded. |
| 2 | `offset` | `int` | Starting character position of the requested edit within the current field value. It determines where the new numeric text will be inserted or substituted. |
| 3 | `length` | `int` | Number of existing characters to remove before inserting the replacement text. It defines how much of the current value is being overwritten. |
| 4 | `text` | `String` | Candidate input text supplied by the user or editing component. This is the value that may be inserted into the numeric field if the resulting content remains valid. |
| 5 | `attrs` | `AttributeSet` | Formatting metadata associated with the edit request. It is passed through unchanged when the replacement is accepted. |

**Instance fields / external state read by the method:**
- No instance fields are read directly.
- The method reads the current document state through `fb.getDocument()`.
- The method relies on the local `isValid(String)` predicate to determine whether the resulting value is acceptable.

## 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 the local validation predicate to evaluate the candidate document text |
| U | `NumericFilter.replace` | NumericFilter | - | Delegates the approved replacement to the superclass document filter implementation |

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` | - | - | Reads the current editable document state from the filter bypass to reconstruct the post-edit value |
| R | `doc.getText` | - | - | Reads the existing document content so the candidate replacement can be evaluated |
| R | `doc.getLength` | - | - | Reads the current document length to capture the full existing value |
| U | `sb.replace` | - | - | Updates the in-memory candidate text buffer to simulate the requested edit |
| R | `isValid` | NumericFilter | - | Checks whether the resulting text is a permitted numeric value |
| U | `super.replace` | NumericFilter | - | Applies the accepted edit to the underlying document through the superclass implementation |

## 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` | `NumericFilter.replace` | `isValid [R]` |
| 2 | Screen: `UI` | `NumericFilter.replace` | `super.replace [U] - document update` |

**Caller analysis:**
- The search for `replace(` found this method inside `src/main/java/com/github/blaxk3/ui/UI.java`.
- No additional Java callers were found in the repository from the available search scope.
- Based on the class location and usage pattern, this method is an internal UI document filter callback rather than a business-service entry point.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] `(initial document reconstruction)` (L183-L188)

> Builds the candidate post-edit text by copying the current document content and simulating the requested replacement.

| # | 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 2** — [IF] `(isValid(sb.toString()))` (L190)

> Validates the candidate numeric text before allowing the edit to reach the document.

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

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

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

**Block 2.2** — [ELSE] `(validation failed)` (L190-L191)

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `No operation; the invalid replacement is rejected implicitly.` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Field/Parameter | Filter bypass handle that exposes the editable document and permits the approved change to be applied. |
| `offset` | Field/Parameter | Character position at which the replacement starts in the current field value. |
| `length` | Field/Parameter | Number of characters in the current value to remove before inserting the new text. |
| `text` | Field/Parameter | Incoming candidate value typed or pasted by the user. |
| `attrs` | Field/Parameter | Text attribute metadata attached to the replacement request. |
| `Document` | Technical term | Swing text model representing the current contents of the input field. |
| `FilterBypass` | Technical term | Swing callback object used to bypass the filter and apply an accepted edit. |
| `StringBuilder` | Technical term | Mutable in-memory buffer used to simulate the post-edit document content. |
| `replace` | Technical term | Text-edit operation that substitutes a range of characters with new content. |
| `NumericFilter` | Technical term | UI document filter that restricts input to numeric values. |
| `isValid` | Technical term | Local predicate that decides whether the resulting text satisfies the numeric rule. |
| `super.replace` | Technical term | Superclass document update operation that commits the accepted change to the field. |