---
# (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 numeric input gate for Swing text components. Its business purpose is to protect user-entered document content from becoming invalid by simulating the effect of the requested text insertion before the insertion is actually committed. The method reconstructs the document state in memory, applies the proposed insertion at the requested offset, and then delegates the decision to `isValid()` to determine whether the resulting text remains acceptable.

The method implements a validation-and-delegation pattern: it does not transform data itself, but rather evaluates whether an inbound edit request should be allowed to pass through to the underlying document model. In the larger UI system, this is a shared input-control utility that can be attached to numeric fields to ensure only permitted characters or numeric forms are entered. It has one conditional branch: if the prospective text passes validation, the method forwards the insertion to the superclass implementation; otherwise, it silently blocks the change.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["insertString(params)"]
    A["Retrieve current document from FilterBypass"]
    B["Create StringBuilder"]
    C["Read current document text with doc.getText(0, doc.getLength())"]
    D["Append current text to StringBuilder"]
    E["Insert incoming string at the requested offset"]
    F{"isValid(sb.toString())"}
    G["Call super.insertString(fb, offset, string, attr)"]
    END_NODE["Return / Next"]

    START --> A
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F -->|true| G
    F -->|false| END_NODE
    G --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Document filter gateway that provides access to the live text document being edited and allows the approved insertion to be forwarded downstream. |
| 2 | `offset` | `int` | Target character position where the user-requested text will be inserted into the current document snapshot. |
| 3 | `string` | `String` | The proposed user input that is being validated before it is committed to the document. |
| 4 | `attr` | `AttributeSet` | Formatting and metadata attributes associated with the insertion request; passed through unchanged when the change is accepted. |

Instance fields and external state read by the method:
- No instance fields are read.
- The method reads the current text content from `fb.getDocument()` and therefore depends on the live document state at the moment of editing.

## 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 | Reads the active document state to evaluate the pending insertion. |
| R | `doc.getText(0, doc.getLength())` | - | Swing Document | Reads all current text from the document snapshot. |
| C | `sb.insert(offset, string)` | - | In-memory StringBuilder | Builds the prospective post-edit text in memory. |
| R | `isValid(sb.toString())` | NumericFilter | - | Validates the candidate text to determine whether the insert is allowed. |
| C | `super.insertString(fb, offset, string, attr)` | DocumentFilter superclass | - | Commits the approved insertion into the document. |

## 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 | UI document editing framework | `DocumentFilter pipeline` -> `NumericFilter.insertString` | `isValid(sb.toString()) [R]` |

## 6. Per-Branch Detail Blocks

**Block 1** — **FORWARD PROCESSING** `(method entry)` (L170)

> The method begins by preparing a candidate version of the document that includes the requested user insertion.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `fb.getDocument();` // obtain the active document |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // create editable buffer |
| 3 | EXEC | `doc.getText(0, doc.getLength());` // read all existing text |
| 4 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` // load current text into buffer |
| 5 | EXEC | `sb.insert(offset, string);` // simulate user insertion at target position |

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

> The computed text is checked before any change is committed to the live document.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString());` // validate the candidate document text |

**Block 2.1** — **THEN** `(validation passed)` (L177)

> When the candidate text satisfies the numeric rule, the insertion is forwarded to the parent filter implementation.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.insertString(fb, offset, string, attr);` // commit the approved insertion |

**Block 2.2** — **ELSE** `(validation failed)` (L176)

> Invalid user input is ignored and nothing is written to the document.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | No operation; the method exits without calling the superclass insertion |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | Document filter that restricts text input to numeric or otherwise valid values. |
| `FilterBypass` | Technical term | Swing API handle that allows a filter to forward accepted changes to the underlying document. |
| `Document` | Technical term | The editable text model backing the user interface component. |
| `DocumentFilter` | Technical term | Swing extension point used to intercept and validate text edits before they are applied. |
| `StringBuilder` | Technical term | Mutable in-memory buffer used to build the candidate post-edit text. |
| `offset` | Field | Character position where the new text should be inserted. |
| `string` | Field | User-supplied text being validated. |
| `attr` | Field | Text attributes associated with the insertion request. |
| `isValid` | Method | Validation rule that decides whether the candidate text can be accepted. |
| `super.insertString` | Technical term | Parent-class insertion method that actually applies the change when validation succeeds. |
| numeric input | Business term | User-entered text that must remain constrained to a numeric format. |
| UI | Acronym | User Interface — the presentation layer where text entry occurs. |