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

`NumericFilter.insertString()` acts as a document-input guard for numeric-only text fields in the UI layer. Its business purpose is to intercept a user’s attempted text insertion, reconstruct the would-be document content, and allow the edit only when the resulting text is considered valid by the filter’s validation rule. In practice, this method protects forms and input components from accepting non-numeric characters before the text is committed to the Swing document model.

The method implements a lightweight routing/validation pattern: it does not transform persisted business data or call backend services, but instead evaluates a candidate input value and conditionally delegates to the parent `DocumentFilter` implementation. This makes it a shared presentation-layer control used wherever the application needs constrained numeric entry. The only branch in the method is the validation gate: when `isValid(...)` returns true, the insertion is forwarded; otherwise, the edit is silently rejected.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["insertString(params)"])
    D1{"Build candidate text from current document and insertion"}
    D2{"isValid(candidateText)?"}
    P1["Append current document text"]
    P2["Insert incoming string at offset"]
    P3["Delegate to super.insertString(fb, offset, string, attr)"]
    END_NODE(["Return / Next"])

    START --> P1
    P1 --> P2
    P2 --> D2
    D2 -->|Yes| P3
    D2 -->|No| END_NODE
    P3 --> END_NODE
```

**Constant Resolution:** No application constants are referenced in this method. The control flow is driven only by local values and the result of `isValid(...)`.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Swing filter bypass handle that represents the document-edit channel being protected by the numeric input rule. It provides access to the current document and is the gateway used when the insertion is finally approved. |
| 2 | `offset` | `int` | Character position where the user is attempting to insert text. It determines the insertion point used to simulate the future document content before validation. |
| 3 | `string` | `String` | The user-entered text fragment being added to the field. This is the proposed numeric input that must pass validation before being committed. |
| 4 | `attr` | `AttributeSet` | Swing text attributes associated with the insertion request. These attributes are passed through unchanged when the edit is accepted. |

**Instance fields / external state read by the method:** none directly. The method reads the current document text through `fb.getDocument()` and uses the inherited validation rule `isValid(...)` to decide whether to continue.

## 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 | `Document` | Reads the current document state so the filter can evaluate the proposed text as a whole. |
| R | `doc.getText` | Swing Document API | `Document` | Retrieves the existing document contents for reconstruction of the candidate input value. |
| C | `StringBuilder.append` | JDK | - | Builds the candidate document text by copying the current field content. |
| U | `StringBuilder.insert` | JDK | - | Simulates the user’s insertion at the requested offset to produce the post-edit text. |
| R | `isValid` | `NumericFilter` | - | Validates the simulated text and determines whether the edit may proceed. |
| C | `super.insertString` | `DocumentFilter` | Swing Document model | Commits the approved insertion to the document through the parent filter mechanism. |

## 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 | `UI.textField()` -> `PlainDocument.setDocumentFilter(new NumericFilter())` -> `NumericFilter.insertString` | `super.insertString [C] Document` |

## 6. Per-Branch Detail Blocks

**Block 1** — **SEQUENCE** `(candidate document construction)` (L170-L174)

> This block reconstructs the document content that would exist if the insertion were accepted.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Document doc = fb.getDocument();` // obtain current editable document [R: Document state] |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // initialize candidate-text buffer |
| 3 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` // copy the current document text into the buffer |
| 4 | EXEC | `sb.insert(offset, string);` // simulate inserting the user-entered fragment at the requested position |

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

> This block enforces the numeric-input rule. Only valid content is allowed to reach the document model.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `isValid(sb.toString())` // evaluate whether the simulated text is acceptable |

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

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

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

| # | Type | Code |
|---|------|------|
| 1 | RETURN | No document update occurs; the attempted insertion is rejected implicitly by falling through without calling `super.insertString(...)` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `NumericFilter` | Class | UI document filter that restricts text input to numeric-compatible values. |
| `insertString` | Method | Intercepts and validates an attempted text insertion before it reaches the field. |
| `DocumentFilter` | Technical term | Swing extension point used to control edits to a text document. |
| `FilterBypass` | Technical term | Swing callback object that allows approved edits to be applied to the underlying document. |
| `Document` | Technical term | Swing text model holding the current field contents. |
| `offset` | Field/parameter | Character position where the new text is inserted. |
| `string` | Parameter | User-entered text fragment being validated. |
| `attr` | Parameter | Formatting attributes attached to the insertion request. |
| `isValid` | Method | Internal validation rule that determines whether the candidate text is allowed. |
| `super.insertString` | Technical term | Parent implementation used to commit an approved insertion. |
| numeric input | Business term | Text that represents digits and related numeric formatting permitted by the field rule. |
| UI | Layer | Presentation layer that manages user interaction and on-screen input control. |
| Swing | Framework | Java desktop UI toolkit used to build and validate text-field interactions. |
| PlainDocument | Technical term | Swing document implementation commonly used by text fields for editable content. |
| candidate text | Business term | The full text value that would result after applying the proposed user edit. |