# (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 text insertion into a Swing document. Its business role is to allow only values that remain valid numeric text after the proposed insertion is applied, thereby protecting the UI from accepting non-numeric characters at the point of entry. The method does not transform business data into another domain object; instead, it enforces a presentation-layer constraint that supports downstream numeric calculations, currency handling, and other number-based operations in the screen.

The method follows a validation-and-delegation pattern. First, it reconstructs what the document would look like after the new text is inserted, then it delegates the decision to `isValid(...)` to determine whether the resulting text conforms to the numeric rule set. If the candidate value passes validation, it delegates to the superclass `DocumentFilter.insertString(...)` to perform the actual insertion. If validation fails, the insertion is blocked and the document remains unchanged.

In the larger system, this method is a reusable UI safeguard used by a text field configured with `NumericFilter`. It centralizes numeric input enforcement so that multiple screens can share the same rule instead of duplicating per-field key handling logic. The method has two business outcomes only: accept the proposed insertion when the resulting text is numeric, or reject it when the result would break the numeric format.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["insertString(fb, offset, string, attr)"])
    DOC(["Get Document from FilterBypass"])
    TEXT(["Read current document text"])
    SB(["Create StringBuilder and append current text"])
    INSERT(["Insert incoming string at offset"])
    CALLVALID(["Call isValid(sb.toString())"])
    VALID{"isValid(updatedText)?"}
    SUPER(["Call super.insertString(fb, offset, string, attr)"])
    END_NODE(["Return / Next"])

    START --> DOC
    DOC --> TEXT
    TEXT --> SB
    SB --> INSERT
    INSERT --> CALLVALID
    CALLVALID --> VALID
    VALID -->|Yes| SUPER
    VALID -->|No| END_NODE
    SUPER --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Document filter bypass handle that provides access to the target document and allows the method to delegate the approved insertion to the underlying document model. |
| 2 | `offset` | `int` | Character position where the user-typed text is proposed to be inserted; it determines where the candidate numeric value is reconstructed for validation. |
| 3 | `string` | `String` | The incoming user-entered text to be inserted into the field; this may contain digits or invalid characters and is evaluated as part of the candidate value. |
| 4 | `attr` | `AttributeSet` | Text attributes associated with the insertion request; passed through unchanged to preserve the caller's formatting metadata when the insertion is accepted. |

Instance state and external state read by the method:
- `fb.getDocument()` to access the current document content.
- The current document text and length via `doc.getText(0, doc.getLength())`.
- The validation rule implemented by the local `isValid(...)` method.
- The superclass insertion behavior via `super.insertString(...)`.

## 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 | Retrieves the target document to inspect the current text state before insertion. |
| R | `doc.getText(0, doc.getLength())` | - | Swing Document | Reads the existing document content to reconstruct the candidate value. |
| R | `doc.getLength()` | - | Swing Document | Reads the current document length to define the text extraction range. |
| C | `sb.append(...)` | - | In-memory StringBuilder | Builds the candidate value by copying the existing document text into a mutable buffer. |
| C | `sb.insert(offset, string)` | - | In-memory StringBuilder | Creates the proposed post-insertion text used for validation. |
| R | `isValid(sb.toString())` | `NumericFilter` | - | Evaluates whether the candidate text satisfies the numeric-only business rule. |
| C | `super.insertString(fb, offset, string, attr)` | `DocumentFilter` | Swing Document | Applies the approved insertion to the underlying document model. |

## 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 text field setup in `UI.textField()` | `UI.textField()` -> `PlainDocument.setDocumentFilter(new NumericFilter())` -> Swing document editing flow -> `NumericFilter.insertString` | `super.insertString [C] Swing Document` |

## 6. Per-Branch Detail Blocks

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

> Builds a hypothetical post-insertion document value and validates it before mutating the actual document.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Document doc = fb.getDocument();` // obtain the current target document |
| 2 | SET | `StringBuilder sb = new StringBuilder();` // prepare a mutable candidate buffer |
| 3 | EXEC | `sb.append(doc.getText(0, doc.getLength()));` // copy the current document content |
| 4 | EXEC | `sb.insert(offset, string);` // simulate the proposed user input at the requested position |
| 5 | CALL | `isValid(sb.toString())` // validate the candidate text against the numeric rule |
| 6 | IF | `if (isValid(sb.toString()))` // proceed only when the candidate remains valid |

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

> Accepts the insertion only when the resulting text is still numeric.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.insertString(fb, offset, string, attr);` // delegate the approved insertion to the base document filter |

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

> Rejects the insertion by doing nothing, leaving the document unchanged.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` // no-op path; invalid input is blocked |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `fb` | Technical term | Filter bypass handle used by Swing `DocumentFilter` to access and modify the underlying document. |
| `offset` | Technical term | Insert position within the text field where the user input should be placed. |
| `attr` | Technical term | Attribute set carrying text formatting metadata for the insertion request. |
| `Document` | Technical term | Swing text model holding the current contents of the field. |
| `DocumentFilter` | Technical term | Swing extension point used to validate or transform text edits before they are applied. |
| `FilterBypass` | Technical term | API object that allows an approved edit to be forwarded to the document. |
| `StringBuilder` | Technical term | Mutable buffer used to construct the candidate post-edit text for validation. |
| Numeric filter | Business term | UI rule that permits only numeric text to be entered into the field. |
| Numeric input | Business term | User-entered value expected to contain only digits, optionally constrained by the validation rule in `isValid(...)`. |
| Swing | Technical term | Java desktop UI framework used to render and manage the text field. |
| `insertString` | Technical term | Text-edit hook invoked when a new string is being inserted into the document. |
| `super.insertString(...)` | Technical term | Base-class insertion operation that performs the actual document update after validation succeeds. |