# (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 implements a numeric input validation gate for a Swing text component. Its business role is to simulate the impact of an edit before allowing that edit to reach the document, thereby preventing non-numeric content from being committed to the UI state. The method takes the current document content, applies the requested insertion/replacement in-memory, and then evaluates the resulting text through the local validation rule set. If the resulting value is acceptable, it delegates to the superclass replacement logic so the UI actually changes; otherwise, it blocks the edit entirely.

This is a classic validation-and-delegation pattern rather than a domain workflow orchestrator. It serves as a reusable UI control component that can be attached to multiple screens or fields wherever numeric-only entry is required. The method has one decision branch: valid content is forwarded to the underlying document model, while invalid content is silently rejected. In business terms, the method protects downstream processing from malformed numeric values at the point of user entry.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["replace(params)"]
    GET_DOC["fb.getDocument()"]
    INIT_SB["Create StringBuilder sb"]
    READ_TEXT["doc.getText(0, doc.getLength())"]
    APPEND_TEXT["sb.append(current document text)"]
    REPLACE_TEXT["sb.replace(offset, offset + length, text)"]
    VALIDATE{"isValid(sb.toString())?"}
    SUPER_REPLACE["super.replace(fb, offset, length, text, attrs)"]
    END_NODE["Return / Next"]

    START --> GET_DOC
    GET_DOC --> INIT_SB
    INIT_SB --> READ_TEXT
    READ_TEXT --> APPEND_TEXT
    APPEND_TEXT --> REPLACE_TEXT
    REPLACE_TEXT --> VALIDATE
    VALIDATE -->|Yes| SUPER_REPLACE
    VALIDATE -->|No| END_NODE
    SUPER_REPLACE --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Document bypass handle supplied by the Swing text filtering framework. It represents the target text model that will be updated only if the numeric validation passes. |
| 2 | `offset` | `int` | Starting character position of the proposed edit within the current field value. It determines where the replacement or insertion is simulated. |
| 3 | `length` | `int` | Number of existing characters to remove before applying the new text. It controls how much of the current value is being replaced. |
| 4 | `text` | `String` | Proposed user-entered content to insert into the numeric field. It may be empty, numeric, or non-numeric, and it is validated as part of the predicted final value. |
| 5 | `attrs` | `AttributeSet` | Text styling attributes associated with the edit operation. The method forwards them unchanged when the replacement is accepted. |

Instance state and external state read by this method:
- The current document content obtained from `fb.getDocument()`.
- The validation rule implemented by the private `isValid(String text)` method 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 contains no database or service-component CRUD activity. Its only meaningful internal call is to the local validation routine, followed by delegation to `super.replace(...)` when the edit is allowed. Because the called methods are within the same UI class hierarchy and do not access persistence, all business effects are limited to document-state mutation in the client tier.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `isValid` | NumericFilter | - | Evaluates whether the proposed text result satisfies the numeric-only rule. |
| U | `super.replace` | javax.swing.text.DocumentFilter | - | Applies the accepted change to the underlying document model. |

## 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 | `NumericFilter` | `javax.swing.text.DocumentFilter.replace` -> `NumericFilter.replace` | `isValid [R] NumericFilter` |
| 2 | `NumericFilter` | `javax.swing.text.DocumentFilter.replace` -> `NumericFilter.replace` | `super.replace [U] document model` |

This method is typically entered by the Swing document filtering pipeline when a user types, pastes, deletes, or replaces text in a bound input field. The method then performs a local validation call and, only when the result is acceptable, invokes the inherited replacement behavior that mutates the UI document state.

## 6. Per-Branch Detail Blocks

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

> Entry point for a user-driven text replacement request on a numeric-only input field.

| # | 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);` |
| 5 | CALL | `isValid(sb.toString())` |

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

> Accept the edit only when the predicted full value remains numeric.

| # | Type | Code |
|---|------|---|
| 1 | CALL | `super.replace(fb, offset, length, text, attrs);` |
| 2 | RETURN | `Method exits after delegating accepted replacement.` |

**Block 1.2** — [ELSE] `(validation failed)` (L190)

> Reject the edit and leave the document unchanged.

| # | Type | Code |
|---|------|---|
| 1 | RETURN | `Method exits without calling super.replace(...)`. |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Technical term | Filter bypass handle from Swing’s document filtering API, used to access and update the underlying text model. |
| `offset` | Technical term | Character index where the proposed edit begins. |
| `length` | Technical term | Number of existing characters to remove during the replacement operation. |
| `text` | Field | Proposed user-entered text to be inserted into the numeric field. |
| `attrs` | Technical term | Text attributes associated with the replacement request. |
| `Document` | Technical term | Swing text model holding the current field value. |
| `StringBuilder` | Technical term | Mutable buffer used to build the predicted post-edit value for validation. |
| `DocumentFilter` | Technical term | Swing extension point that intercepts text edits before they reach the document. |
| `FilterBypass` | Technical term | API object that allows the filter to delegate an approved edit to the document. |
| `replace` | Technical term | Edit operation that substitutes a span of text with new content. |
| `isValid` | Technical term | Local validation rule that checks whether the resulting field value is numeric. |
| Numeric filter | Business term | UI rule that allows only numeric content to be entered into a field. |
| UI | Business term | Presentation layer that captures and validates user input before it reaches downstream logic. |