Java Date and Time
Choose a temporal representation from the business meaning, then preserve that meaning
through conversion, arithmetic and external boundaries. A timestamp-shaped string is not
enough evidence to decide whether the value denotes an instant or a civil date-time.
Establish the contract
Inspect compiler release/toolchain, runtime image, existing temporal types, serializer
configuration, driver/database versions, schema and representative payloads. Guidance and
examples target Java 17 APIs without preview features or added dependencies; preserve the
project baseline. Zone rules come from the runtime's provider, so the JDK build and available
rules matter even when source code is unchanged.
For the affected value, establish its meaning, authoritative zone if any, precision and
range, equality semantics, and interval boundaries. Use existing contracts first. If a
material policy is absent, expose the choice and its consequence before changing persisted
data or a public format; do not silently infer UTC or the host's zone.
Choose the representation
| Meaning |
Representation |
Consequential constraint |
| Recorded occurrence, audit timestamp, absolute expiry |
Instant |
Display requires a zone; it does not remember the sender's offset or region. |
| Birthday, service date, accounting date |
LocalDate |
No time or zone; inventing midnight UTC can change the displayed date. |
| Civil date and time awaiting interpretation |
LocalDateTime |
No unique instant until a zone or offset and any ambiguity policy are supplied. |
| Date-time with a transmitted UTC offset |
OffsetDateTime |
Identifies an instant; an offset cannot recover a region's transition rules. |
| Resolved date-time whose region rules matter |
ZonedDateTime |
Contains local fields, zone and resolved offset; preserve the zone separately if storage drops it. |
Use LocalTime, YearMonth or MonthDay when the domain has only that information, rather
than inserting a dummy date. These distinctions follow the
Java 17 temporal model.
Work the affected path
- Identify every interpretation step. Search for
now(), systemDefault(), atZone,
toLocalDateTime, numeric epoch conversions, formatters and database mappings. Mark where
information is supplied or discarded; a display conversion should preserve the instant.
- Resolve civil time deliberately. A region such as
Europe/Paris is not a fixed
+01:00. When a local value becomes an instant, specify gap and overlap behavior before
accepting an API default. For resolution, date windows or calendar arithmetic, read
zones and calendar arithmetic.
- Choose the clock and amount independently. Current business time comes from an injected
Clock; elapsed process time comes from System.nanoTime() differences. Use Period for
calendar units and Duration for seconds/nanoseconds; a duration day is 24 hours, not a
promise about a civil day. For time-dependent code and regression checks, read
clocks and deterministic tests.
- Specify the boundary before converting. State accepted grammar, zone/offset requirements,
fractional precision, epoch units if numeric, nullability and rejection/rounding rules.
Read parsing and persistence for wire or database work.
Type compatibility alone does not establish a lossless round trip.
- Validate the property the domain needs. Compare
Instant values for occurrence identity;
compare full values only when offset/zone identity matters. Exercise the affected boundary,
including exact expiry, an invalid or ambiguous input, and precision loss where applicable.
Run on the target toolchain when available; distinguish API/source compatibility from
runtime and driver integration evidence.
Deliver the decision
For a small fix, return the temporal meaning, chosen conversion/policy, changed code and
checks run. A boundary review should additionally identify the first lossy or ambiguous
conversion, show an input that exposes it, and state any unresolved product or storage
contract. Do not label a hypothetical driver round trip as tested.
For a review-only request, return findings and a reproducing input without making changes.
Preserve an existing representation or policy when it already satisfies the contract.
Operational deadlines, timeout propagation and cancellation belong to
timeouts-and-deadlines. Public format changes may also need rpc-and-api-contracts;
broader database mapping decisions belong to orm-structural-mapping. These are optional
handoffs, not prerequisites for an ordinary temporal fix. Calendar job scheduling is outside
this skill; choosing a civil-time policy does not implement a scheduler.
For a handoff, pass the temporal meaning, target versions, reproducing input and unresolved
contract; request the relevant timeout, compatibility or mapping decision. If the specialist
is unavailable, keep that decision conditional and finish the independent temporal analysis.
1---2name: java-date-and-time3description: >-4 Model and validate Java date and time values when choosing between civil dates,5 local date-times and instants, resolving DST gaps or overlaps, applying calendar6 arithmetic, testing time-dependent rules, or preserving temporal meaning across7 parsing, JSON and JDBC. Covers java.time types, region versus offset, Duration8 versus Period, Clock injection and precision contracts. Does not cover calendar9 job scheduling or operational timeout budgets (timeouts-and-deadlines).10metadata:11 source: https://skillmd.com/skills/robsonkades/java-date-and-time12---1314# Java Date and Time1516Choose a temporal representation from the business meaning, then preserve that meaning17through conversion, arithmetic and external boundaries. A timestamp-shaped string is not18enough evidence to decide whether the value denotes an instant or a civil date-time.1920## Establish the contract2122Inspect compiler release/toolchain, runtime image, existing temporal types, serializer23configuration, driver/database versions, schema and representative payloads. Guidance and24examples target Java 17 APIs without preview features or added dependencies; preserve the25project baseline. Zone rules come from the runtime's provider, so the JDK build and available26rules matter even when source code is unchanged.2728For the affected value, establish its meaning, authoritative zone if any, precision and29range, equality semantics, and interval boundaries. Use existing contracts first. If a30material policy is absent, expose the choice and its consequence before changing persisted31data or a public format; do not silently infer UTC or the host's zone.3233## Choose the representation3435| Meaning | Representation | Consequential constraint |36| ----------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |37| Recorded occurrence, audit timestamp, absolute expiry | `Instant` | Display requires a zone; it does not remember the sender's offset or region. |38| Birthday, service date, accounting date | `LocalDate` | No time or zone; inventing midnight UTC can change the displayed date. |39| Civil date and time awaiting interpretation | `LocalDateTime` | No unique instant until a zone or offset and any ambiguity policy are supplied. |40| Date-time with a transmitted UTC offset | `OffsetDateTime` | Identifies an instant; an offset cannot recover a region's transition rules. |41| Resolved date-time whose region rules matter | `ZonedDateTime` | Contains local fields, zone and resolved offset; preserve the zone separately if storage drops it. |4243Use `LocalTime`, `YearMonth` or `MonthDay` when the domain has only that information, rather44than inserting a dummy date. These distinctions follow the45[Java 17 temporal model](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/package-summary.html).4647## Work the affected path48491. **Identify every interpretation step.** Search for `now()`, `systemDefault()`, `atZone`,50 `toLocalDateTime`, numeric epoch conversions, formatters and database mappings. Mark where51 information is supplied or discarded; a display conversion should preserve the instant.522. **Resolve civil time deliberately.** A region such as `Europe/Paris` is not a fixed53 `+01:00`. When a local value becomes an instant, specify gap and overlap behavior before54 accepting an API default. For resolution, date windows or calendar arithmetic, read55 [zones and calendar arithmetic](references/zones-and-calendar.md).563. **Choose the clock and amount independently.** Current business time comes from an injected57 `Clock`; elapsed process time comes from `System.nanoTime()` differences. Use `Period` for58 calendar units and `Duration` for seconds/nanoseconds; a duration day is 24 hours, not a59 promise about a civil day. For time-dependent code and regression checks, read60 [clocks and deterministic tests](references/clocks-and-tests.md).614. **Specify the boundary before converting.** State accepted grammar, zone/offset requirements,62 fractional precision, epoch units if numeric, nullability and rejection/rounding rules.63 Read [parsing and persistence](references/parsing-and-persistence.md) for wire or database work.64 Type compatibility alone does not establish a lossless round trip.655. **Validate the property the domain needs.** Compare `Instant` values for occurrence identity;66 compare full values only when offset/zone identity matters. Exercise the affected boundary,67 including exact expiry, an invalid or ambiguous input, and precision loss where applicable.68 Run on the target toolchain when available; distinguish API/source compatibility from69 runtime and driver integration evidence.7071## Deliver the decision7273For a small fix, return the temporal meaning, chosen conversion/policy, changed code and74checks run. A boundary review should additionally identify the first lossy or ambiguous75conversion, show an input that exposes it, and state any unresolved product or storage76contract. Do not label a hypothetical driver round trip as tested.77For a review-only request, return findings and a reproducing input without making changes.78Preserve an existing representation or policy when it already satisfies the contract.7980Operational deadlines, timeout propagation and cancellation belong to81**timeouts-and-deadlines**. Public format changes may also need **rpc-and-api-contracts**;82broader database mapping decisions belong to **orm-structural-mapping**. These are optional83handoffs, not prerequisites for an ordinary temporal fix. Calendar job scheduling is outside84this skill; choosing a civil-time policy does not implement a scheduler.85For a handoff, pass the temporal meaning, target versions, reproducing input and unresolved86contract; request the relevant timeout, compatibility or mapping decision. If the specialist87is unavailable, keep that decision conditional and finish the independent temporal analysis.