---

# (DD08) Business Logic — Example.uploadFile() [12 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `io.github.biezhi.java11.http.Example` |
| Layer | Utility (Package: `io.github.biezhi.java11.http`) |
| Module | `http` (Package: `io.github.biezhi.java11.http`) |

## 1. Role

### Example.uploadFile()

This method demonstrates how to perform an HTTP POST file upload using Java 11's built-in `HttpClient` API (introduced in Java 11 as part of JEP 321). It acts as a **self-contained utility example** that creates an HTTP client, configures a POST request with a local file as the request body, sends the request to a target server (`http://localhost:8080/upload/`), and prints the HTTP response status code. The method is part of the `java11-http` demonstration project by Biezhi, showcasing idiomatic Java 11 HTTP client usage. There are no conditional branches — the method follows a single linear execution path. It is not called by any other method in the codebase (it is a standalone demo entry point). The method is declared `static`, making it directly invocable without instantiating the `Example` class.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["uploadFile()"])

    START --> GET_CLIENT["GET Client: HttpClient.newHttpClient()"]

    GET_CLIENT --> BUILD_REQ["Build: HttpRequest.newBuilder()"]

    BUILD_REQ --> SET_URI["SET URI: http://localhost:8080/upload/"]

    SET_URI --> SET_BODY["SET Body: POST with /tmp/files-to-upload.txt"]

    SET_BODY --> SET_BUILD["CALL: .build() -> HttpRequest"]

    SET_BUILD --> SEND_REQ["CALL: client.send(request, BodyHandlers.discarding())"]

    SEND_REQ --> PRINT_STATUS["EXEC: System.out.println(response.statusCode())"]

    PRINT_STATUS --> END_NODE(["Return / Next"])

    START --> GET_CLIENT
    GET_CLIENT --> BUILD_REQ
    BUILD_REQ --> SET_URI
    SET_URI --> SET_BODY
    SET_BODY --> SET_BUILD
    SET_BUILD --> SEND_REQ
    SEND_REQ --> PRINT_STATUS
    PRINT_STATUS --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | This method takes no parameters. All configuration (target URL, file path) is hardcoded. |

**Instance fields or external state read by the method:**
- None. The method is static and creates all state locally.

**Hardcoded values used:**
| Value | Meaning |
|-------|---------|
| `http://localhost:8080/upload/` | Target HTTP endpoint — the local development server URL receiving the file upload |
| `/tmp/files-to-upload.txt` | Source file path — a local text file located in the system temporary directory to be sent as the POST body |

## 4. CRUD Operations / Called Services

This method does not perform database CRUD operations. It invokes Java 11 HTTP client APIs to send an HTTP request. The operations performed are classified as follows:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| N/A | `HttpClient.newHttpClient()` | (built-in) | (none) | Creates a new synchronous HTTP client instance |
| N/A | `HttpRequest.newBuilder()` | (built-in) | (none) | Begins building an HTTP request via the fluent builder pattern |
| N/A | `HttpRequest.BodyPublishers.ofFile(Path)` | (built-in) | (none) | Creates a body publisher that streams a local file as POST body content |
| N/A | `client.send(HttpRequest, HttpResponse.BodyHandler)` | (built-in) | (none) | Synchronously sends the HTTP request and waits for the response |
| N/A | `HttpRequest.BodyHandlers.discarding()` | (built-in) | (none) | Response handler that discards the response body (no body processing needed) |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Standalone Demo Entry | `Example.uploadFile` | HTTP POST -> http://localhost:8080/upload/ |

**Notes:** No other method in the codebase calls `uploadFile()`. It is a standalone demonstration method intended for showcase/educational purposes only. It is not part of any production call chain.

## 6. Per-Branch Detail Blocks

### Block 1 — [SETUP] `HttpClient` Creation (L104)

> Creates an HTTP client instance. No branching or constants involved.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `HttpClient.newHttpClient()` // Creates a new default synchronous HTTP client. Java 11 HttpClient is thread-safe and reusable. [-> Creates client instance] |

### Block 2 — [SETUP] `HttpRequest` Construction via Builder (L106-L110)

> Uses the builder pattern (Fluent API) to construct an HTTP POST request. Four builder methods are chained: `newBuilder()` -> `uri()` -> `POST()` -> `build()`.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `HttpRequest.newBuilder()` // Begins request building chain |
| 2 | SET | `.uri(new URI("http://localhost:8080/upload/"))` // Sets the target URI. No constant resolution needed — hardcoded string literal. |
| 3 | SET | `.POST(HttpRequest.BodyPublishers.ofFile(Paths.get("/tmp/files-to-upload.txt")))` // Configures POST body. Sources the file content from `/tmp/files-to-upload.txt` as the request body. |
| 4 | CALL | `.build()` // Finalizes the HttpRequest, producing an immutable HttpRequest object |

### Block 3 — [EXEC] Synchronous Request Execution (L112)

> Sends the constructed request to the server and waits for the response. The response body is discarded since only the status code is needed.

| # | Type | Code |
|---|------|------|
| 1 | SET | `HttpResponse<Void> response = client.send(request, HttpResponse.BodyHandlers.discarding())` // Synchronously sends the POST request. The BodyHandlers.discarding() handler discards the response body to avoid unnecessary memory allocation. |

### Block 4 — [EXEC] Status Code Output (L113)

> Prints the HTTP response status code to standard output for diagnostic/debugging purposes.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `System.out.println(response.statusCode())` // Prints the HTTP status code (e.g., 200 OK, 404 Not Found, 500 Internal Server Error) to console |

### Block 5 — [RETURN] Method Exit (L114)

> The method returns `void`. No explicit return statement is needed. The `throws Exception` declaration propagates any IOException, InterruptedException, or URISyntaxException to the caller.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `void` // Method completes. All HTTP client resources are managed automatically by Java's HttpClient (no manual close needed). |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| HttpClient | Class | Java 11 built-in HTTP client (`java.net.http.HttpClient`) — a thread-safe, modern replacement for `HttpURLConnection`. Provides both synchronous and asynchronous request support. |
| HttpRequest | Class | Java 11 HTTP request model object (`java.net.http.HttpRequest`). Immutable. Built using the fluent builder pattern with methods like `uri()`, `POST()`, `header()`, `timeout()`. |
| HttpResponse | Class | Java 11 HTTP response model object (`java.net.http.HttpResponse`). Contains status code, headers, and body. Generic type parameter specifies body type (e.g., `Void` when body is discarded). |
| BodyPublishers | Class | Factory class for creating request body publishers (`java.net.http.HttpRequest.BodyPublishers`). Provides static methods like `ofString()`, `ofFile()`, `ofBytes()` to wrap different data sources as request bodies. |
| BodyHandlers | Class | Factory class for creating response body handlers (`java.net.http.HttpHttpResponse.BodyHandlers`). Provides static methods like `discarding()`, `ofString()`, `ofByteArray()`, `ofFile()` to define how response bodies are consumed. |
| URI | Class | Uniform Resource Identifier (`java.net.URI`) — identifies the target server endpoint. Here: `http://localhost:8080/upload/`. |
| Path | Class | File system path (`java.nio.file.Paths`) — represents the local file `/tmp/files-to-upload.txt` to be streamed as the POST body. |
| POST | HTTP method | HTTP POST method — used to submit data (in this case, file content) to a server for processing. |
| `throws Exception` | Language construct | Declares that this method may throw checked exceptions (`IOException`, `InterruptedException`, `URISyntaxException`) which the caller must handle or propagate. |

---