# Io / Github / Biezhi / Java11 / Time

## Overview

This module lives under `io.github.biezhi.java11.time` and demonstrates **bridging the legacy `java.util.concurrent.TimeUnit` API with the modern `java.time.Duration` API** introduced in Java 9. While Java 8 brought `java.time` (JSR-310) to the language, many concurrent utilities still use `TimeUnit` for time-based operations. This module shows how to convert between the two, making it easy to use `Duration` values with existing `TimeUnit`-based APIs like `ScheduledExecutorService`, `Lock.tryLock(timeout, unit)`, and `ConcurrentHashMap` methods.

## Key Classes

### `Example`

**Source:** [src/main/java/io/github/biezhi/java11/time/Example.java](src/main/java/io/github/biezhi/java11/time/Example.java)

A simple demonstration class with no state — just a static `main` method that exercises the `TimeUnit.convert(Duration)` overload.

#### `main(String[] args)`

**Signature:** `public static void main(String[] args) : void`

The sole method in the module. It performs three conversions using the `TimeUnit.convert(Duration)` method (available since Java 9):

| Conversion | Input | Expected Output |
|---|---|---|
| Hours → Days | `Duration.ofHours(24)` | `1` |
| Hours → Days | `Duration.ofHours(26)` | `1` (truncates) |
| Seconds → Minutes | `Duration.ofSeconds(60)` | `1` |

Key implementation details:

- **`TimeUnit.DAYS.convert(Duration.ofHours(24))`** — converts a 24-hour duration into days, yielding `1`. The boolean check `day == 1` is printed as `true`.
- **`TimeUnit.DAYS.convert(Duration.ofHours(26))`** — converts 26 hours into days, yielding `1`. Note that the conversion **truncates** toward zero; it does not round up.
- **`TimeUnit.MINUTES.convert(Duration.ofSeconds(60))`** — converts a 60-second duration into minutes, yielding `1`.

There are no parameters beyond the standard `args`, no return value, and no side effects other than printing to `System.out`.

## How It Works

The conversion flow is straightforward:

```mermaid
flowchart LR
    A["Duration.ofHours(n)"] -->|"creates a Duration"| B["java.time.Duration"]
    C["TimeUnit.DAYS / MINUTES"] -->|"calls .convert()"| B
    B -->|"returns long"| D["TimeUnit conversion result"]
    D -->|"printed via"| E["System.out.println"]
    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#fff3e0,stroke:#f57c00
    style D fill:#e8f5e9,stroke:#388e3c
```

1. **Create a `Duration`** — `Duration.ofHours()` or `Duration.ofSeconds()` builds a `Duration` from the given scalar value. `Duration` is the modern JDK 9+ way to represent an amount of time (e.g., "24 hours" or "60 seconds") independent of any date or time zone.

2. **Convert via `TimeUnit.convert()`** — The `TimeUnit` enum (from `java.util.concurrent`) provides overloaded `convert()` methods. Since Java 9, one overload accepts a `Duration` directly. Internally, it extracts the total seconds and nanoseconds from the `Duration` and performs the arithmetic conversion to the target `TimeUnit`.

3. **Print the result** — The converted `long` value is printed. This is purely demonstrative; in real code you would use the `long` to pass into methods that still require `TimeUnit`-based timeouts.

### Design note

This module does **not** introduce a new abstraction or helper library. Instead, it serves as a concise reference showing that the conversion is a single method call — no manual arithmetic with `getSeconds()` or `toNanos()` is needed.

## Data Model

There are no entity, DTO, or model classes in this module. The data flow involves:

- **`java.time.Duration`** — Immutable representation of a time-based amount (seconds + nanos). Created via factory methods like `ofHours()`, `ofSeconds()`.
- **`java.util.concurrent.TimeUnit`** — An enum (`NANOSECONDS`, `MICROSECONDS`, `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, `DAYS`) that provides conversion utilities.

## Dependencies and Integration

| Dependency | Purpose |
|---|---|
| `java.time.Duration` | JDK core — modern time duration representation |
| `java.util.concurrent.TimeUnit` | JDK core — legacy concurrent-time-unit abstraction |

No external library dependencies. No cross-module relationships detected.

## Notes for Developers

- **Truncation behavior**: `TimeUnit.convert()` truncates toward zero. If you need rounded results, use `Duration.toXxx()` methods instead, or perform explicit rounding before converting.
- **Zero or negative durations**: `Duration.ZERO` converts cleanly to `0` in any `TimeUnit`. Negative durations follow the same truncation rules.
- **Duration overflow**: Converting very large durations (e.g., `Duration.ofDays(Long.MAX_VALUE)`) may overflow the target `TimeUnit` and wrap. Always validate ranges in production code.
- **Purpose of this module**: This is a learning/example module in the `java11` collection. It complements sibling modules like [collections](src/main/java/io/github/biezhi/java11/collections/Example.java), [files](src/main/java/io/github/biezhi/java11/files/Example.java), [http](src/main/java/io/github/biezhi/java11/http/Example.java), [string](src/main/java/io/github/biezhi/java11/string/Example.java), and others — each demonstrating a Java 11+ feature area.