---
# (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 a document-input gate for numeric-only UI fields. It intercepts every attempted text insertion, reconstructs what the document would look like after the change, and then validates the full candidate string before allowing the edit to proceed. In business terms, it protects user-entered values from becoming non-numeric at the point of entry, which reduces downstream validation errors and prevents invalid characters from ever reaching the screen model.

The method implements a simple routing-and-validation pattern: it does not transform the input into another business object, but instead routes the edit through a guard condition. There is one branch only: when the proposed content satisfies `isValid(...)`, the insertion is delegated to the superclass and accepted; otherwise, the method silently rejects the change by doing nothing. As a result, this method serves as a shared presentation-layer control used by any numeric input component that relies on `NumericFilter`.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["insertString(params)"])
    GET_DOC["fb.getDocument()"]
    INIT_SB["StringBuilder sb = new StringBuilder()"]
    APPEND_TEXT["sb.append(doc.getText(0, doc.getLength()))"]
    INSERT_TEXT["sb.insert(offset, string)"]
    VALIDATE{ "isValid(sb.toString())?" }
    SUPER_INSERT["super.insertString(fb, offset, string, attr)"]
    END_NODE(["Return / Next"])

    START --> GET_DOC
    GET_DOC --> INIT_SB
    INIT_SB --> APPEND_TEXT
    APPEND_TEXT --> INSERT_TEXT
    INSERT_TEXT --> VALIDATE
    VALIDATE -->|"true"| SUPER_INSERT
    VALIDATE -->|"false"| END_NODE
    SUPER_INSERT --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | The document-edit gateway supplied by the Swing text infrastructure. It represents the active input target whose contents are being protected from invalid numeric edits. |
| 2 | `offset` | `int` | The insertion position inside the current text value. It determines where the new characters would be placed before validation is performed. |
| 3 | `string` | `String` | The user-entered text fragment being attempted for insertion. In business terms, it is the candidate numeric input that may be accepted or rejected. |
| 4 | `attr` | `AttributeSet` | The text attributes associated with the insertion request. The method passes them through unchanged when the edit is accepted. |

Instance field / external state read by the method:

- `fb.getDocument()` returns the current document state.
- `doc.getText(0, doc.getLength())` reads the existing field contents.
- `isValid(...)` is an external validation method on the same filter class.

## 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` | SwingTextAPI | - | Reads the current editable document attached to the filter. |
| R | `doc.getText` | SwingTextAPI | - | Reads the current field contents for candidate reconstruction. |
| C | `super.insertString` | NumericFilter | - | Commits the accepted insertion into the underlying document model. |
| R | `isValid` | NumericFilter | - | Validates the candidate text before the edit is committed. |

## 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 text component | `JTextComponent document edit pipeline` -> `NumericFilter.insertString` | `isValid [R] -` |

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENTIAL] (L170-L178)

> Reconstructs the prospective text value, validates it, and conditionally commits the insertion.

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

> Accepts only those edits that keep the full field content valid for the numeric input rule.

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

**Block 1.1.1** — [THEN] `isValid(sb.toString()) == true` (L177)

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

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

| # | Type | Code |
|---|------|------|
| 1 | RETURN | No insertion is performed; the edit is rejected silently. |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | A presentation-layer text filter that enforces numeric-only entry in UI fields. |
| `insertString` | Method | The interception point for attempted text insertion into a document. |
| `FilterBypass` | Technical term | Swing API object that provides controlled access to the underlying document edit path. |
| `offset` | Field/Parameter | The insertion index at which the user’s text is placed. |
| `string` | Field/Parameter | The user-entered text fragment attempted for insertion. |
| `AttributeSet` | Technical term | Swing text styling metadata carried with the insertion request. |
| `Document` | Technical term | The editable text model backing the UI field. |
| `StringBuilder` | Technical term | Mutable buffer used to reconstruct the candidate field value for validation. |
| `isValid` | Method | Validation rule that determines whether the proposed document content is acceptable. |
| `super.insertString` | Technical term | The superclass commit path that applies the insertion when validation succeeds. |
| `JTextComponent` | Technical term | Swing text component family that hosts the document editing workflow. |
| Numeric input | Business term | A field that must contain only numbers or number-compatible content. |
| Validation gate | Business term | A control step that rejects invalid user input before it reaches the model. |