---

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

`insertString()` is a UI input-guard method that enforces numeric-only entry behavior for the text field used by the currency converter screen. It acts as a validation gate before any typed characters are committed to the Swing document, reconstructing the would-be full text and approving the insertion only when the resulting content satisfies the numeric format rules implemented by `isValid()`. In business terms, this prevents users from entering invalid amount values and protects downstream conversion logic from malformed input.

The method is part of a shared document-filtering pattern rather than a screen-specific controller flow: it is attached to the `JTextField` document in `UI.textField()` and therefore intercepts all text input events that attempt to modify the amount entry field. It has one implicit branch: if the reconstructed text is valid, the method delegates to `super.insertString(...)`; otherwise, it suppresses the insertion and leaves the current document unchanged. This is a defensive presentation-layer control that supports the larger system by ensuring the monetary amount field remains parseable by the conversion action.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
START(["insertString(params)"])
GET_DOC["Get document from FilterBypass"]
BUILD_SB["Create StringBuilder and copy existing text"]
INSERT_TEXT["Insert incoming string at offset"]
VALIDATE["Call isValid(mergedText)"]
DECISION{"isValid returns true"}
SUPER_INSERT["Call super.insertString(fb, offset, string, attr)"]
END_NODE(["Return without insertion"])
START --> GET_DOC
GET_DOC --> BUILD_SB
BUILD_SB --> INSERT_TEXT
INSERT_TEXT --> VALIDATE
VALIDATE --> DECISION
DECISION -->|Yes| SUPER_INSERT
DECISION -->|No| END_NODE
SUPER_INSERT --> END_NODE
```

The method first acquires the current `Document` from the supplied `FilterBypass`. It then builds a candidate text value by copying the current document contents into a `StringBuilder` and inserting the new string at the requested offset. Next, the merged text is passed to `isValid()` to determine whether the document would still satisfy the numeric-entry rules after the edit. If the validation succeeds, the method delegates the insertion to `super.insertString(...)`, which commits the user’s input into the Swing document. If validation fails, the method intentionally performs no insertion, effectively rejecting the keystroke.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `fb` | `FilterBypass` | Swing document gateway that provides access to the current text model and allows the filter to forward an approved insertion into the amount field. |
| 2 | `offset` | `int` | Character position where the new user input should be inserted into the current amount text. It determines the resulting numeric string that is validated. |
| 3 | `string` | `String` | The user-entered text fragment, typically a typed digit or paste content, that is being evaluated for numeric validity before display. |
| 4 | `attr` | `AttributeSet` | Swing text attributes associated with the insertion request. They are passed through unchanged when the edit is accepted. |

The method reads the current document state through `fb.getDocument()` and `doc.getText(0, doc.getLength())`. It does not read any instance fields from `NumericFilter`; its behavior depends only on the live document content and the incoming insertion arguments.

## 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 | `FilterBypass.getDocument` | Swing DocumentFilter API | Swing `Document` | Reads the current text model before evaluating the candidate insertion. |
| R | `Document.getText` | Swing Document API | Swing `Document` | Reads existing characters from the amount field. |
| R | `Document.getLength` | Swing Document API | Swing `Document` | Reads the current document length for full-text reconstruction. |
| U | `StringBuilder.insert` | Java Standard Library | In-memory string buffer | Builds the post-edit candidate text for validation. |
| R | `isValid` | `NumericFilter` | - | Validates the reconstructed text against numeric-only rules. |
| C | `super.insertString` | `DocumentFilter` | Swing `Document` | Commits the approved insertion into the document, updating the visible field content. |

## 5. Dependency Trace

| # | 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] Swing Document` |

This method is not directly invoked by business service code; it is triggered by Swing text-edit events once the `NumericFilter` is attached to the amount text field. The only identified caller in the codebase is `UI.textField()`, which registers the filter on the `PlainDocument` used by the converter input. The ultimate terminal operation is the approved insertion into the Swing document, which updates the UI state rather than a database entity.

## 6. Per-Branch Detail Blocks

**Block 1** — **START** `(entry: insertString(FilterBypass fb, int offset, String string, AttributeSet attr))` (L170)

> Initializes numeric validation for a proposed text insertion into the amount field.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `fb.getDocument();` |
| 2 | SET | `Document doc = fb.getDocument();` |
| 3 | SET | `StringBuilder sb = new StringBuilder();` |

**Block 2** — **PROCESS** `(build candidate text)` (L172-L174)

> Reconstructs the document content as it would appear after the user’s input is applied.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `doc.getText(0, doc.getLength());` |
| 2 | SET | `sb.append(doc.getText(0, doc.getLength()));` |
| 3 | CALL | `doc.getLength();` |
| 4 | EXEC | `sb.insert(offset, string);` |

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

> Checks whether the resulting text remains a valid numeric amount.

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

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

> Commits the insertion only when the merged text is numeric-safe.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.insertString(fb, offset, string, attr);` |
| 2 | RETURN | `return;` implicit after method completion |

**Block 3.2** — **ELSE** `(validation failed)` (L176-L179)

> Rejects the keystroke by doing nothing, preserving the current document content.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` implicit after method completion |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `fb` | Parameter | Swing document bypass handle used to read the current text and forward an approved edit. |
| `offset` | Parameter | Cursor position where the new text is inserted into the amount field. |
| `string` | Parameter | User-entered content being tested for numeric validity. |
| `attr` | Parameter | Text attributes for the proposed insertion request. |
| `Document` | Technical term | Swing model representing the current text content of the input field. |
| `DocumentFilter` | Technical term | Swing extension point that intercepts and validates text edits before they are applied. |
| `FilterBypass` | Technical term | Swing API object that allows a filter to apply or forward document changes. |
| `NumericFilter` | Class | Custom input filter that restricts the amount field to numeric values only. |
| `isValid` | Method | Internal validation routine that checks whether a candidate string contains only acceptable numeric characters. |
| `JTextField` | UI component | Text input control used for entering the currency amount. |
| `PlainDocument` | Technical term | Default Swing text document implementation used by the amount field. |
| `Currency Converter` | Business term | The application’s user-facing function for converting amounts between currencies. |
| numeric-only input | Business rule | Validation rule that allows digits and a limited decimal format, preventing invalid amount entry. |