---
# (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 guard for numeric-only text entry in the UI layer. Its business purpose is to evaluate a proposed text insertion before the application accepts it, ensuring that the text field remains compliant with the numeric formatting rules enforced by `isValid(...)`. In practice, it prevents non-numeric characters from being persisted into the document, which protects downstream screens from invalid user input and reduces the need for later validation errors. The method follows a validation-and-delegation pattern: it reconstructs the candidate document state in memory, checks whether the resulting value is acceptable, and only then delegates to the superclass insertion behavior. It has two outcomes: valid candidate text is committed to the document, while invalid input is silently rejected.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
START(["insertString(params)"])
GETDOC["Read current document from FilterBypass"]
BUILD["Build candidate text in StringBuilder"]
APPEND["Append current document text"]
INSERT["Insert incoming string at offset"]
VALIDATE{"isValid(candidateText)?"}
SUPER["super.insertString(fb, offset, string, attr)"]
END_NODE(["Return / Next"])
START --> GETDOC
GETDOC --> BUILD
BUILD --> APPEND
APPEND --> INSERT
INSERT --> VALIDATE
VALIDATE -- "true" --> SUPER
VALIDATE -- "false" --> END_NODE
SUPER --> END_NODE
```

The method does not branch on business constants or dispatch to multiple service categories. It performs a single validation path and conditionally commits the accepted text to the underlying document.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Document access handle supplied by the Swing text filter pipeline; it exposes the current document so the method can evaluate the would-be text before accepting it. |
| 2 | `offset` | `int` | Cursor position at which the user attempts to insert text; it determines where the candidate input is merged into the existing document content. |
| 3 | `string` | `String` | User-entered text fragment being proposed for insertion into the numeric field. |
| 4 | `attr` | `AttributeSet` | Text styling and attribute metadata that accompany the insertion request and are forwarded unchanged when the input is accepted. |

Instance fields and external state read by the method:
- `fb.getDocument()` to obtain the current document snapshot.
- `doc.getLength()` and `doc.getText(...)` to reconstruct the candidate value.
- `isValid(...)` to evaluate the assembled text against numeric input rules.

## 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` |

This method contains one internal business decision point and one superclass delegation. It does not invoke database-backed CRUD services, so there is no SC/CBS code or entity/table interaction to resolve.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `getDocument` | Swing API | Document | Reads the current document state to build a validation candidate. |
| R | `getLength` | Swing API | Document | Retrieves the current character count of the document. |
| R | `getText` | Swing API | Document | Reads the existing document text for candidate reconstruction. |
| C | `insert` | Swing API | Document | Inserts the proposed string into the candidate buffer in memory. |
| R | `isValid` | NumericFilter | - | Validates whether the candidate text satisfies numeric input rules. |
| C | `super.insertString` | DefaultStyledDocument / superclass behavior | Document | Commits the accepted text to the actual document when validation succeeds. |

## 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 input pipeline | `Swing text component` -> `NumericFilter.insertString` | `super.insertString [C] Document` |

The repository search found only the method declaration and its superclass call within the same file. No additional Java callers were identified in the codebase search results for `insertString(`.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] `(L169-L177)`

> Builds a candidate version of the text field content by combining the current document contents with the incoming insertion request.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Document doc = fb.getDocument();` // obtain the current document snapshot |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // prepare mutable buffer for candidate text |
| 3 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` // append all existing document text |
| 4 | EXEC | `sb.insert(offset, string);` // insert the proposed user input at the requested position |

**Block 2** — [IF] `(isValid(sb.toString()))` `(L176)`

> Validates the candidate text before it is committed to the visible document.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString())` // check numeric field rules |

**Block 2.1** — [THEN] `(validation succeeds)` `(L177-L178)`

> Accepts the insertion and delegates to the superclass implementation so the input becomes part of the document.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.insertString(fb, offset, string, attr);` // commit the accepted text to the document |

**Block 2.2** — [ELSE] `(validation fails)` `(L177-L178)`

> Rejects the insertion by taking no further action, leaving the document unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `// no-op` // invalid input is silently discarded |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | Text input filter that restricts a field to numeric-compatible content. |
| `insertString` | Method | Validation gate that decides whether a user-typed fragment may be inserted into the field. |
| `FilterBypass` | Swing API | Controlled access path that allows the filter to inspect and, when valid, modify the underlying document. |
| `offset` | Field | Character position where the new input is being inserted. |
| `string` | Field | User-entered text proposed for insertion. |
| `attr` | Field | Attribute metadata attached to the insertion request, such as text styling information. |
| `Document` | Technical term | Mutable text model used by Swing components to store the current field value. |
| `StringBuilder` | Technical term | Mutable buffer used to construct the candidate document content efficiently. |
| `isValid` | Method | Validation rule that checks whether the candidate text satisfies numeric-entry constraints. |
| `super.insertString` | Technical term | Superclass commit operation that applies the validated insertion to the live document. |
| UI | Layer | User interface layer responsible for screen-level input handling and validation. |