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

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

## 1. Role

### UI.button()

This method constructs the primary action button set for the currency conversion user interface. It creates three visual commands — Convert, Swap, and Clear — and standardizes their size before attaching event handlers that control the screen behavior. The method acts as a lightweight UI factory and event-routing point: one branch triggers currency conversion and output formatting, one branch swaps the source and target currencies, and one branch clears the input and result fields.

From a business perspective, the method supports the end-user workflow of entering an amount, choosing a source currency and destination currency, and either converting the value, reversing the currency direction, or resetting the form. The Convert branch delegates to an external currency rate service, while the Swap and Clear branches operate only on local UI state. Because it returns a `Component[]`, the method is designed to be reused as a shared screen-building utility for the main window layout rather than as a standalone business service.

The implementation follows a simple factory-plus-dispatch pattern: it instantiates controls, configures presentation, and registers action listeners that encapsulate the button-specific behavior. There is also defensive input validation before conversion, ensuring the user cannot trigger the API call with an empty or placeholder amount. On successful conversion, the method formats the numeric response for display in a locale-friendly grouped decimal format.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["button()"])
    CREATE["Create 3 JButton instances - Convert, Swap, Clear"]
    LOOP["Iterate over each button to set preferred size 200x35"]
    INIT_RATE["Instantiate CurrencyRateAPI"]
    ADD_CONVERT["Attach Convert action listener"]
    ADD_SWAP["Attach Swap action listener"]
    ADD_CLEAR["Attach Clear action listener"]
    RETURN_NODE["Return Component array"]
    CONVERT_CHECK{"Amount text is not empty and not a dot"}
    CONVERT_ERROR["Show validation error message dialog"]
    CONVERT_CALL["Call CurrencyRateAPI.convert(sourceCurrency, targetCurrency, amount)"]
    CONVERT_FORMAT["Format converted value with DecimalFormat #,###.###"]
    CONVERT_SET["Update result label with formatted amount"]
    CONVERT_THROW["Wrap URL or URI errors in RuntimeException"]
    SWAP_GET["Read current source currency selection"]
    SWAP_SET1["Set source currency to current target currency"]
    SWAP_SET2["Set target currency to previous source currency"]
    CLEAR_TEXT["Clear amount text field"]
    CLEAR_LABEL["Clear result label"]

    START --> CREATE
    CREATE --> LOOP
    LOOP --> INIT_RATE
    INIT_RATE --> ADD_CONVERT
    ADD_CONVERT --> ADD_SWAP
    ADD_SWAP --> ADD_CLEAR
    ADD_CLEAR --> RETURN_NODE

    ADD_CONVERT --> CONVERT_CHECK
    CONVERT_CHECK -->|yes| CONVERT_CALL
    CONVERT_CHECK -->|no| CONVERT_ERROR
    CONVERT_CALL --> CONVERT_FORMAT
    CONVERT_FORMAT --> CONVERT_SET
    CONVERT_CALL --> CONVERT_THROW

    ADD_SWAP --> SWAP_GET
    SWAP_GET --> SWAP_SET1
    SWAP_SET1 --> SWAP_SET2

    ADD_CLEAR --> CLEAR_TEXT
    CLEAR_TEXT --> CLEAR_LABEL
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | This method has no input parameters. The behavior is controlled entirely by internal UI state such as the text field content and the selected currencies in the combo boxes. |

Instance fields and external state read by the method:
- `textField` - the amount input box whose current text determines whether conversion can proceed.
- `getComboBox1()` - source currency selection used in conversion and swap actions.
- `getComboBox2()` - target currency selection used in conversion and swap actions.
- `setLabel(...)` - result display field updated after conversion or cleared by the Clear action.
- `setTextField(...)` - amount input field cleared by the Clear action.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| 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` |
| - | `UI.textField` | UI | - | Calls `textField` 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.getComboBox1` | UI | - | Reads the current source currency selection to support convert and swap behavior. |
| R | `UI.getComboBox2` | UI | - | Reads the current target currency selection to support convert and swap behavior. |
| R | `UI.getTextField` | UI | - | Reads the amount input field to validate whether conversion can be executed. |
| U | `UI.setLabel` | UI | - | Updates the result display label with either the converted value or an empty string. |
| U | `UI.setTextField` | UI | - | Clears the amount input field when the Clear button is pressed. |
| R | `UI.textField` | UI | - | Reads the direct text field instance to parse the amount entered by the user. |
| C/R | `CurrencyRateAPI.convert` | External API | Currency rate service | Requests a live currency conversion using the selected source currency, target currency, and amount. |

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `UI` constructor / layout assembly | `UI` layout initialization -> `UI.button()` | `CurrencyRateAPI.convert [C/R] External currency service` |

Trace who calls this method and what this method ultimately calls.
This method is a local UI helper used during screen construction. The only direct caller visible in the available source is the `UI` class itself, where the button array is assembled into the overall form. The business terminal path is the conversion API call; the other two branches remain local UI state changes.

## 6. Per-Branch Detail Blocks

**Block 1** — `SEQUENTIAL` (L111-L116)

> Creates the button set and establishes the default size for each control.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JButton[] button = new JButton[] { new JButton("Convert"), new JButton("Swap"), new JButton("Clear") };` |
| 2 | EXEC | `buttons.setPreferredSize(new Dimension(200, 35));` |
| 3 | CALL | `for (JButton buttons: button)` |

**Block 2** — `SEQUENTIAL` (L118)

> Initializes the external currency service client used by the Convert action.

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

**Block 3** — `ACTION LISTENER` (L119-L129)

> Handles the Convert button workflow: validate the amount, call the conversion service, format the response, and show an error dialog if the amount is invalid.

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

**Block 3.1** — `TRY` (L120-L128)

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `getTextField().getText()` |
| 2 | EXEC | `getTextField().getText().isEmpty()` |
| 3 | EXEC | `getTextField().getText().equals(".")` |
| 4 | EXEC | `Objects.requireNonNull(getComboBox1().getSelectedItem()).toString()` |
| 5 | EXEC | `Objects.requireNonNull(getComboBox2().getSelectedItem()).toString()` |
| 6 | EXEC | `textField.getText()` |
| 7 | CALL | `rate.convert(...)` |
| 8 | EXEC | `new DecimalFormat("#,###.###").format(...)` |
| 9 | CALL | `setLabel(...)` |
| 10 | CALL | `javax.swing.JOptionPane.showMessageDialog(...)` |

**Block 3.2** — `IF` `(amount text is not empty and not a dot)` (L120)

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

**Block 3.2.1** — `THEN` (L121-L122)

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

**Block 3.2.2** — `ELSE` (L123-L125)

> Displays a validation message instead of calling the conversion service.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `javax.swing.JOptionPane.showMessageDialog(null, "Please enter the amount you need", "Error", javax.swing.JOptionPane.ERROR_MESSAGE);` |

**Block 3.3** — `CATCH` `(MalformedURLException | URISyntaxException)` (L126-L127)

> Converts checked service resolution errors into an unchecked runtime failure.

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

**Block 4** — `ACTION LISTENER` (L131-L134)

> Handles the Swap button workflow by exchanging the selected source and target currencies.

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

**Block 4.1** — `SEQUENTIAL` (L132-L134)

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

**Block 5** — `ACTION LISTENER` (L136-L139)

> Handles the Clear button workflow by wiping the amount and result output.

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

**Block 5.1** — `SEQUENTIAL` (L137-L138)

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

**Block 6** — `RETURN` (L141)

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `button` | UI component | The array of action buttons used to drive the currency conversion workflow. |
| `Convert` | Business action | Executes currency conversion for the entered amount. |
| `Swap` | Business action | Exchanges the source and target currencies selected by the user. |
| `Clear` | Business action | Resets the amount input and displayed result. |
| `CurrencyRateAPI` | External service client | Client used to obtain live foreign exchange conversion values. |
| `textField` | Field | Amount input field where the user enters the value to convert. |
| `getComboBox1()` | UI field accessor | Returns the first currency selector, used as the source currency. |
| `getComboBox2()` | UI field accessor | Returns the second currency selector, used as the destination currency. |
| `setLabel(...)` | UI field mutator | Updates the output label that displays the conversion result. |
| `setTextField(...)` | UI field mutator | Clears or updates the amount input field. |
| `DecimalFormat` | Technical utility | Formats numeric output using grouped decimals for display. |
| `BigDecimal` | Technical utility | Precise numeric type used to pass the amount to the conversion service. |
| `MalformedURLException` | Technical exception | Indicates an invalid URL when resolving the conversion endpoint. |
| `URISyntaxException` | Technical exception | Indicates a malformed URI when resolving the conversion endpoint. |
| `JOptionPane` | UI utility | Swing dialog helper used to show validation errors to the user. |
| `source currency` | Business term | The currency the user is converting from. |
| `target currency` | Business term | The currency the user is converting to. |
| `amount` | Business term | The monetary value entered for conversion. |
| `conversion result` | Business term | The calculated output amount shown to the user after conversion. |