---

# (DD11) Business Logic — NumericFilter.insertString() [12 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.github.blaxk3.ui.NumericFilter` |
| Layer | Utility |
| Module | `ui` (Package: `com.github.blaxk3.ui`) |

## 1. Role

### NumericFilter.insertString()

This method acts as an input validation gate for a numeric text field. It reconstructs the would-be document content after an insertion request, validates the full resulting text through the shared `isValid()` rule, and only then delegates to the Swing framework to commit the edit. In business terms, it protects the UI from accepting characters that would make the field non-numeric, which is essential for forms that capture amounts, quantities, or any other decimal-only values. The method follows a guard-and-delegate pattern: it does not transform the value itself, but instead decides whether the user’s keystroke should be allowed to propagate. When validation fails, it silently blocks the update by not calling `super.insertString(...)`. This method is therefore a shared front-end control point for data quality at the point of entry.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["insertString(params)"]
    D1{"Get document from FilterBypass"}
    S1["Read full current document text"]
    S2["Insert incoming string at offset into buffer"]
    D2{"isValid(bufferedText)?"}
    C1["Call super.insertString(fb, offset, string, attr)"]
    END_NODE["Return / Next"]

    START --> D1
    D1 --> S1
    S1 --> S2
    S2 --> D2
    D2 -->|Yes| C1
    D2 -->|No| END_NODE
    C1 --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Swing edit bypass handle that exposes the current document state and allows the method to forward an approved text insertion. |
| 2 | `offset` | `int` | The character position where the user is trying to insert text; it determines where the proposed numeric update is evaluated. |
| 3 | `string` | `String` | The text fragment entered by the user, such as digits or a decimal point, that is being validated for numeric compatibility. |
| 4 | `attr` | `AttributeSet` | Formatting metadata associated with the text insertion request; it is forwarded unchanged when the edit is accepted. |

Instance fields / external state read by the method:
- `fb.getDocument()` to obtain the current document snapshot.
- `doc.getText(0, doc.getLength())` to read the existing field content.
- `isValid(...)` to evaluate the reconstructed value against the numeric rule set.
- `super.insertString(...)` to commit the insertion only when validation passes.

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| C | `NumericFilter.insertString` | NumericFilter | - | Calls `insertString` in `NumericFilter` |
| - | `NumericFilter.isValid` | NumericFilter | - | Calls `isValid` 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 | `fb.getDocument()` | Swing Document API | - | Reads the current editable document to build the candidate text state. |
| R | `doc.getText(0, doc.getLength())` | Swing Document API | - | Reads the existing field content before applying the requested insertion. |
| C | `isValid(String)` | NumericFilter | NumericFilter | Validates the proposed new value before allowing creation of updated text state. |
| C | `super.insertString(fb, offset, string, attr)` | PlainDocument / DocumentFilter base behavior | - | Commits the approved insertion into the document. |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen/UI component invoking a numeric text field filter | `UI text component input event -> NumericFilter.insertString` | `super.insertString [C] Swing document update` |

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] `(insertString entry)` (L170-L178)

> Builds a candidate version of the text field content and decides whether the user edit should be accepted.

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

**Block 1.1** — [IF] `(isValid(sb.toString()) == true)` (L176-L178)

| # | Type | Code |
|---|------|---|
| 1 | CALL | `super.insertString(fb, offset, string, attr);` |

**Block 1.2** — [ELSE] `(isValid(sb.toString()) == false)` (L176-L178)

> The invalid input is rejected by omission; no document update is performed.

| # | Type | Code |
|---|------|---|
| 1 | RETURN | `// No operation - insertion is blocked` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `NumericFilter` | Class | UI text filter that constrains entered content to numeric formats only. |
| `FilterBypass` | Technical term | Swing editing gateway that lets a document filter forward an approved change. |
| `Document` | Technical term | The current editable text model behind the UI field. |
| `offset` | Field / Parameter | Cursor position where the user requested insertion will be applied. |
| `AttributeSet` | Technical term | Formatting metadata attached to a text insertion request. |
| `isValid` | Method | Internal validation rule that checks whether the proposed text is numeric. |
| `StringBuilder` | Technical term | Mutable buffer used to simulate the post-edit field content before acceptance. |
| `super.insertString` | Technical term | Base Swing document operation that actually commits the accepted text. |
| numeric field | Business term | Any input field intended to store digits and an optional decimal point, such as quantity or amount. |
| input validation gate | Business term | A control point that blocks invalid user input before it reaches the stored value. |
| UI | Module | User interface layer responsible for screen-level input handling. |
| Swing | Framework | Java desktop UI toolkit used for form and text component behavior. |