# (DD01) Business Logic — UI.button() [37 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.github.blaxk3.ui.UI` |
| Layer | Utility / Presentation Support |
| Module | `ui` (Package: `com.github.blaxk3.ui`) |

## 1. Role

### UI.button()

`UI.button()` is a presentation-layer factory method that creates and configures the three primary action buttons used by the currency converter screen: Convert, Swap, and Clear. Its business role is to encapsulate the button creation and all click-handling behavior for the screen so the UI can present a consistent action bar without duplicating listener setup in the layout code. The method applies a shared sizing standard to all buttons, then wires each button to a distinct user journey: conversion of the entered amount, reversal of the selected currency direction, and reset of the input/output state.

From a design-pattern perspective, the method acts as a small UI builder and event-routing dispatcher. It returns a `Component[]` so the caller can attach the buttons to the frame or panel while the method itself owns the business-specific interaction logic. In the larger system, this method is a reusable screen helper for the currency exchange view and serves as the point where user input is validated, sent to the exchange-rate API layer, and reflected back into the visible output fields.

The method contains three branch behaviors. The Convert branch validates the amount field before invoking the API and formatting the result; the Swap branch exchanges the selected currencies between the two combo boxes; and the Clear branch empties both the amount input and the displayed result. If conversion input is invalid, the method shows an error dialog instead of calling the API.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["button()"]
    CREATE["Create JButton array: Convert, Swap, Clear"]
    LOOP["For each button set preferred size to 200x35"]
    RATE["Instantiate CurrencyRateAPI"]
    CONVERT["Attach Convert action listener"]
    COND1{"Text field is not empty and not '.'"}
    READ1["Read selected currencies from combo boxes and amount from text field"]
    CALL1["rate.convert(fromCurrency, toCurrency, amount)"]
    FORMAT["Format converted amount with DecimalFormat #,###.###"]
    SETLABEL["setLabel(formatted amount)"]
    MSG["Show validation error dialog"]
    EX1["Catch MalformedURLException and URISyntaxException"]
    THROW1["Throw RuntimeException"]
    SWAP["Attach Swap action listener"]
    READ2["Read selected item from first combo box"]
    SET2["Set first combo box to second combo box value"]
    SET3["Set second combo box to original first combo box value"]
    CLEAR["Attach Clear action listener"]
    SETTEXT["setTextField(\"\")"]
    SETLABEL2["setLabel(\"\")"]
    RET["Return Component[]"]

    START --> CREATE
    CREATE --> LOOP
    LOOP --> RATE
    RATE --> CONVERT
    CONVERT --> COND1
    COND1 -->|true| READ1
    READ1 --> CALL1
    CALL1 --> FORMAT
    FORMAT --> SETLABEL
    SETLABEL --> RET
    COND1 -->|false| MSG
    MSG --> RET
    CONVERT --> EX1
    EX1 --> THROW1
    SWAP --> READ2
    READ2 --> SET2
    SET2 --> SET3
    SET3 --> RET
    CLEAR --> SETTEXT
    SETTEXT --> SETLABEL2
    SETLABEL2 --> RET
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|----------------------|
| - | (none) | - | - |

Instance fields and external state read by this method:
- `textField` through `getTextField()` and direct `textField.getText()` access: the entered amount to convert.
- `comboBox1` through `getComboBox1()`: the source currency selected by the user.
- `comboBox2` through `getComboBox2()`: the target currency selected by the user.
- `label` through `setLabel(...)`: the result display field updated after conversion or reset.

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `CurrencyRateAPI.convert` | CurrencyRateAPI | - | Calls `convert` in `CurrencyRateAPI` |
| R | `UI.getComboBox1` | UI | - | Calls `getComboBox1` in `UI` |
| R | `UI.getComboBox2` | UI | - | Calls `getComboBox2` in `UI` |
| R | `UI.getTextField` | UI | - | Calls `getTextField` in `UI` |
| - | `UI.setLabel` | UI | - | Calls `setLabel` in `UI` |
| - | `UI.setTextField` | UI | - | Calls `setTextField` in `UI` |

Analyze all method calls within this method and classify each as a CRUD operation.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `UI.getTextField` | UI | - | Reads the current amount entered by the user to decide whether conversion may proceed. |
| R | `UI.getComboBox1` | UI | - | Reads the source currency selection used as the origin pair for conversion or swap. |
| R | `UI.getComboBox2` | UI | - | Reads the target currency selection used as the destination pair for conversion or swap. |
| - | `CurrencyRateAPI.convert` | CurrencyRateAPI | - | Calls the exchange-rate API service to obtain the conversion result for the selected currency pair and amount. |
| - | `UI.setLabel` | UI | - | Updates the visible result area with the formatted converted amount or clears it. |
| - | `UI.setTextField` | UI | - | Clears the input amount field when the user presses Clear. |
| - | `JOptionPane.showMessageDialog` | Swing | - | Displays a validation error message when the amount input is missing or invalid. |

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.
Terminal operations from this method: `setLabel` [-], `setTextField` [-], `getComboBox2` [R], `getComboBox2` [R], `getComboBox1` [R], `getComboBox1` [R], `setLabel` [-], `convert` [-], `getComboBox2` [R], `getComboBox1` [R], `getTextField` [R], `getTextField` [R]

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` layout initialization | `UI.initialize` -> `UI.button` | `UI.getTextField` [R], `UI.getComboBox1` [R], `UI.getComboBox2` [R], `CurrencyRateAPI.convert` [-], `UI.setLabel` [-], `UI.setTextField` [-] |

## 6. Per-Branch Detail Blocks

**Block 1** — [ENTRY] `(method start)` (L111)

> Creates the three action buttons and prepares them for the converter screen.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JButton[] button = new JButton[] { new JButton("Convert"), new JButton("Swap"), new JButton("Clear") };` |

**Block 2** — [FOR] `(each JButton in button)` (L117)

> Applies a fixed size to every action button so the layout stays visually consistent.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `buttons.setPreferredSize(new Dimension(200, 35));` |

**Block 3** — [SETUP] `(create API client)` (L120)

> Initializes the exchange-rate API client used by the Convert action.

| # | Type | Code |
|---|------|------|
| 1 | SET | `CurrencyRateAPI rate = new CurrencyRateAPI();` |

**Block 4** — [ACTION] `(button[0] Convert listener)` (L121)

> Registers the conversion workflow for the Convert button.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `button[0].addActionListener(convert -> { ... });` |

**Block 4.1** — [IF] `(amount is not empty and not ".")` (L123)

> Validates that the user entered a usable amount before sending a conversion request.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `getTextField().getText().isEmpty()` |
| 2 | EXEC | `getTextField().getText().equals(".")` |
| 3 | CALL | `getTextField()` |

**Block 4.1.1** — [THEN] `(valid amount)` (L124-L125)

> Reads the selected currencies, calls the external rate service, and formats the returned amount for display.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `Objects.requireNonNull(getComboBox1().getSelectedItem()).toString()` |
| 2 | EXEC | `Objects.requireNonNull(getComboBox2().getSelectedItem()).toString()` |
| 3 | EXEC | `BigDecimal.valueOf(Double.parseDouble(textField.getText()))` |
| 4 | CALL | `rate.convert(...)` |
| 5 | EXEC | `new DecimalFormat("#,###.###").format((Number) Double.parseDouble(...))` |
| 6 | CALL | `setLabel(...)` |

**Block 4.1.2** — [ELSE] `(invalid amount)` (L127)

> Shows a user-facing validation error instead of performing the conversion.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `javax.swing.JOptionPane.showMessageDialog(...)` |

**Block 4.2** — [CATCH] `(MalformedURLException | URISyntaxException)` (L128-L129)

> Converts checked API construction or URI errors into an unchecked runtime failure.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `throw new RuntimeException(ex);` |

**Block 5** — [ACTION] `(button[1] Swap listener)` (L132)

> Registers the currency swap workflow for the Swap button.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `button[1].addActionListener(swap -> { ... });` |

**Block 5.1** — [SEQUENCE] `(swap selected currencies)` (L133-L135)

> Saves the first selected currency, then exchanges the two combo box selections.

| # | Type | Code |
|---|------|------|
| 1 | SET | `String boxItem = Objects.requireNonNull(getComboBox1().getSelectedItem()).toString();` |
| 2 | EXEC | `getComboBox1().setSelectedItem(getComboBox2().getSelectedItem());` |
| 3 | EXEC | `getComboBox2().setSelectedItem(boxItem);` |

**Block 6** — [ACTION] `(button[2] Clear listener)` (L137)

> Registers the reset workflow for the Clear button.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `button[2].addActionListener(clear -> { ... });` |

**Block 6.1** — [SEQUENCE] `(clear input and output)` (L138-L139)

> Resets the amount entry and clears the displayed conversion result.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `setTextField("");` |
| 2 | CALL | `setLabel("");` |

**Block 7** — [RETURN] `(end of method)` (L141)

> Returns the prepared button array to the caller for rendering in the UI.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return button;` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `CurrencyRateAPI` | Service class | Client wrapper for the external exchange-rate service used to fetch currency conversions. |
| `convert` | Method | API call that converts an amount from one currency code to another. |
| `button` | UI component group | The three action buttons shown on the currency conversion screen. |
| `Convert` | UI action | User action that submits the selected currencies and amount for exchange-rate conversion. |
| `Swap` | UI action | User action that reverses the source and destination currency selections. |
| `Clear` | UI action | User action that resets the amount input and the displayed result. |
| `textField` | Field | Amount entry field where the user types the value to convert. |
| `comboBox1` | Field | Source-currency selector, representing the currency being converted from. |
| `comboBox2` | Field | Destination-currency selector, representing the currency being converted to. |
| `label` | Field | Result display field showing the formatted conversion output. |
| `DecimalFormat` | Technical term | Java formatting utility used to display the converted amount with grouped separators and up to three decimals. |
| `MalformedURLException` | Technical term | Checked exception raised when a URL cannot be formed correctly for the API call. |
| `URISyntaxException` | Technical term | Checked exception raised when the constructed URI is invalid. |
| `JOptionPane` | Technical term | Swing dialog utility used to show validation errors to the user. |
| `BigDecimal` | Technical term | Arbitrary-precision numeric type used to pass the amount into the exchange-rate API. |
| `FTTH` | Acronym | Fiber To The Home — not used by this method. |
| `CRUD` | Acronym | Create, Read, Update, Delete — used here to classify UI reads and state updates, not database actions. |
| `UI` | Acronym/Module name | User interface layer for the currency converter screen. |