Java LocalDateTime vysvětleno: základy, formátování, parsování a praktické použití

1. Cílové publikum a co se naučíte

Už jste někdy měli potíže s tím, jak používat třídu LocalDateTime při práci s daty a časy v Javě? Tento článek je určen pro všechny, od začátečníků v Javě až po inženýry aktivně vyvíjející podnikové systémy, a pečlivě vysvětluje vše od základů LocalDateTime po praktické, reálné použití.

Co získáte z tohoto článku

• Pochopit základní strukturu a charakteristiky LocalDateTime
• Naučit se, jak vytvářet, převádět, formátovat a provádět aritmetiku s daty a časy pomocí konkrétních příkladů
• Pochopit rozdíly mezi LocalDateTime a staršími API, jako jsou Date a Calendar, a kdy které použít
• Naučit se, jak řešit běžné případy použití, jako je integrace s databází a často se vyskytující chyby
• Vyhnout se běžným úskalím ve vývoji a efektivně a bezpečně zpracovávat logiku datum‑čas

Doporučeno pro následující čtenáře

• Vývojáři, kteří chtějí v Javě bezpečně a čistě pracovat s daty a časy
• Ti, kteří chtějí komplexně ovládnout LocalDateTime
• Inženýři hledající osvědčené postupy v řízení datum‑čas pro návrh a vývoj systémů
• Vývojáři pracující s databázemi jako MySQL nebo PostgreSQL
• Každý, kdo má potíže s migrací ze starších API (Date / Calendar)

Čtením tohoto článku získáte znalosti a sebevědomí, abyste přestali mít starosti s manipulací s daty a časy v Javě. Začněme vysvětlením základů LocalDateTime a toho, jak se liší od ostatních často srovnávaných tříd.

2. Co je LocalDateTime? Základy a rozdíly od ostatních tříd

Základní přehled LocalDateTime

LocalDateTime je součástí moderního API pro datum a čas, zavedeného v Javě 8 v balíčku java.time. Jeho hlavní vlastností je, že dokáže současně zpracovávat datum i čas, ukládá hodnoty až po rok, měsíc, den, hodinu, minutu, sekundu a nanosekundy.

Na rozdíl od starších API, jako jsou java.util.Date a Calendar, LocalDateTime neobsahuje informaci o časovém pásmu. To ho činí ideálním pro reprezentaci jednoduchého lokálního data a času, například naplánované události nebo záznamu jako „10. července 2025, 15:30:00“, kde časová pásma nejsou relevantní.

Další důležitou vlastností je, že LocalDateTime je neměnný a vláknově bezpečný. Jakákoli úprava vrací novou instanci, což zajišťuje bezpečné používání v prostředí s více vlákny.

Rozdíly od starých API a ostatních tříd datum‑čas

Java poskytuje několik tříd pro datum a čas, z nichž každá slouží jinému účelu. Tabulka níže shrnuje jejich rozdíly a typické případy použití.

Klíčové body

• Používejte ZonedDateTime nebo OffsetDateTime, když jsou časová pásma důležitá
• Používejte LocalDate nebo LocalTime, když potřebujete jen datum nebo čas
• Používejte LocalDateTime, když spravujete lokální datum a čas bez časových pásem

Typické případy použití LocalDateTime

• Systémy plánování a termíny úkolů
• Logování a auditní záznamy v lokálním čase
• Integrace s databázovými sloupci DATETIME

Při práci napříč servery nebo uživateli v různých regionech se stává správa časových pásem kritickou. V takových případech zvažte použití ZonedDateTime.

3. Jak vytvořit instance LocalDateTime (s ukázkami kódu)

Při zahájení práce s LocalDateTime je jednou z prvních věcí, kterou se musíte naučit, vytvoření instancí. Tato sekce představuje nejčastěji používané metody tvorby s praktickými příklady.

3-1. Získání aktuálního data a času (now)

Nejjednodušší použití je získání aktuálního lokálního data a času. I když není zahrnuto časové pásmo, hodnota je založena na výchozím časovém pásmu systému.

import java.time.LocalDateTime;

LocalDateTime now = LocalDateTime.now();
System.out.println(now); // Example: 2025-07-10T15:30:45.123

3-2. Vytvoření konkrétního data a času (of)

Pro vytvoření specifického data a času použijte metodu of(). Můžete specifikovat hodnoty až po sekundy a nanosekund (které jsou volitelné).

LocalDateTime dateTime = LocalDateTime.of(2025, 7, 10, 15, 30, 0);
System.out.println(dateTime); // 2025-07-10T15:30

3-3. Vytváření z řetězce (parse)

LocalDateTime lze také vytvořit z řetězců ve formátu ISO-8601 (např. "2025-07-10T15:30:00") nebo vlastních formátech.

Použití standardního ISO formátu:

LocalDateTime parsed = LocalDateTime.parse("2025-07-10T15:30:00");
System.out.println(parsed); // 2025-07-10T15:30

Použití vlastního formátu (s DateTimeFormatter):

import java.time.format.DateTimeFormatter;

String input = "2025/07/10 15:30:00";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
LocalDateTime parsedCustom = LocalDateTime.parse(input, formatter);
System.out.println(parsedCustom); // 2025-07-10T15:30

3-4. Běžná chyba: DateTimeParseException

Často se vyskytující chyba při používání parse() je DateTimeParseException. Hlavní příčinou je nesoulad mezi formátem vstupního řetězce a formátovačem.

Příklad:

LocalDateTime.parse("2025/07/10 15:30:00");
// Error: not in ISO-8601 format

Řešení:

• Vždy specifikujte DateTimeFormatter, pokud formát není ISO-8601.
• Ověřujte vstupní řetězce předem, kdykoli je to možné.

Shrnutí

• Použijte LocalDateTime.now() pro aktuální datum a čas
• Použijte of() k vytvoření specifického data a času
• Použijte parse() s DateTimeFormatter pro řetězce
• Zajistěte konzistenci formátu, aby se vyhnuli chybám při parsování

4. Formátování LocalDateTime a konverze na řetězce

Při zpracování dat data a času v Javě budete často muset věnovat pozornost formátům zobrazení a vstupním/výstupním formátům. Zatímco LocalDateTime výchozí výstupem formát ISO-8601 (např. 2025-07-10T15:30:00), aplikace v reálném světě často vyžadují vlastní formátování. Tato sekce vysvětluje, jak formátovat hodnoty LocalDateTime a na co si dát pozor.

4-1. Výchozí výstup a formát ISO-8601

Když výstupně vytisknete instanci LocalDateTime přímo pomocí System.out.println(), zobrazí se ve formátu ISO-8601 YYYY-MM-DDTHH:MM:SS. Znak T představuje oddělovač mezi datem a časem, jak je definováno ISO standardem.

LocalDateTime now = LocalDateTime.now();
System.out.println(now); // Example: 2025-07-10T15:30:45.123

4-2. Konverze na vlastní formáty (pomocí DateTimeFormatter)

V obchodních aplikacích a integraci databází často potřebujete vlastní nebo regionálně specifické formáty. V takových případech použijte třídu DateTimeFormatter.

Příklad: Běžně používaný vzor v Japonsku

import java.time.format.DateTimeFormatter;

LocalDateTime dateTime = LocalDateTime.of(2025, 7, 10, 15, 30, 0);
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
String formatted = dateTime.format(formatter);

System.out.println(formatted); // 2025/07/10 15:30:00

Můžete volně definovat jiné formáty, jako:

• "yyyy年MM月dd日 HH時mm分ss秒"
• "yyyyMMdd_HHmmss"

4-3. Kdy výstup obsahuje „T“ a kdy ne

• „T“ se objeví při používání toString() nebo DateTimeFormatter.ISO_LOCAL_DATE_TIME .
• „T“ lze odstranit specifikací vlastního vzoru formátu.

Příklad: Výstup bez „T“

DateTimeFormatter noT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
System.out.println(dateTime.format(noT)); // 2025-07-10 15:30:00

4-4. Konverze řetězců zpět na LocalDateTime

Jak bylo zmíněno v sekci 3, konverze řetězce s vlastním formátem zpět na LocalDateTime vyžaduje použití DateTimeFormatter s parse().

String input = "2025/07/10 15:30:00";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
LocalDateTime parsed = LocalDateTime.parse(input, formatter);
System.out.println(parsed); // 2025-07-10T15:30

Shrnutí

• Výchozí výstup následuje ISO-8601 (s „T“)
• Používejte DateTimeFormatter pro vlastní formáty výstupu
• Používejte formátovače k bezpečnému parsování řetězců do LocalDateTime
• Flexibilně přizpůsobte formáty tak, aby vyhovovaly požadavkům podnikání a integrace

5. Přidávání, odečítání a porovnávání dat a časů (Běžné v praxi)

V reálných aplikacích je běžné provádět operace jako „vypočítat datum o několik dní později“ nebo „porovnat dvě hodnoty data-času.“ LocalDateTime poskytuje intuitivní API pro tyto operace.

5-1. Přidávání a odečítání hodnot data-času (plus / minus)

LocalDateTime nabízí bohatou sadu metod pro přidávání a odečítání časových jednotek. Níže jsou některé běžně používané příklady.

Příklady přidávání:

LocalDateTime base = LocalDateTime.of(2025, 7, 10, 15, 30, 0);
LocalDateTime plusDays = base.plusDays(5);        // 5 days later
LocalDateTime plusHours = base.plusHours(3);      // 3 hours later
LocalDateTime plusMonths = base.plusMonths(1);    // 1 month later

System.out.println(plusDays);   // 2025-07-15T15:30
System.out.println(plusHours);  // 2025-07-10T18:30
System.out.println(plusMonths); // 2025-08-10T15:30

Příklady odečítání:

LocalDateTime minusDays = base.minusDays(2);        // 2 days earlier
LocalDateTime minusMinutes = base.minusMinutes(45); // 45 minutes earlier

System.out.println(minusDays);    // 2025-07-08T15:30
System.out.println(minusMinutes); // 2025-07-10T14:45

5-2. Porovnávání hodnot data-času (isBefore, isAfter, equals)

K určení, zda je jedno datum-čas před, po nebo rovno jinému, použijte následující metody.

LocalDateTime a = LocalDateTime.of(2025, 7, 10, 10, 0, 0);
LocalDateTime b = LocalDateTime.of(2025, 7, 10, 15, 0, 0);

System.out.println(a.isBefore(b)); // true
System.out.println(a.isAfter(b));  // false
System.out.println(a.equals(b));   // false

5-3. Výpočet rozdílů (Duration vs Period)

Když potřebujete vypočítat rozdíl mezi dvěma hodnotami data-času, vyberte mezi Duration a Period v závislosti na tom, co chcete měřit.

• Duration : Pro rozdíly založené na čase (sekundy, minuty, hodiny)
• Period : Pro rozdíly založené na datech (roky, měsíce, dny)

Příklad: Duration (rozdíl času)

import java.time.Duration;

LocalDateTime start = LocalDateTime.of(2025, 7, 10, 10, 0, 0);
LocalDateTime end = LocalDateTime.of(2025, 7, 10, 15, 0, 0);

Duration duration = Duration.between(start, end);
System.out.println(duration.toHours());   // 5
System.out.println(duration.toMinutes()); // 300

Příklad: Period (rozdíl data)

import java.time.Period;

LocalDateTime dateTime1 = LocalDateTime.of(2025, 7, 10, 0, 0, 0);
LocalDateTime dateTime2 = LocalDateTime.of(2025, 8, 5, 0, 0, 0);

// Convert to LocalDate before calculating the difference
Period period = Period.between(dateTime1.toLocalDate(), dateTime2.toLocalDate());
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays());   // 26

Shrnutí

• Používejte plus a minus pro snadné aritmetické operace
• Používejte isBefore a isAfter k porovnávání hodnot data-času
• Používejte Duration pro rozdíly založené na čase a Period pro rozdíly založené na datech
• Kombinováním těchto API udržíte obchodní logiku čistou a čitelnou

6. Převod LocalDateTime s jinými třídami a typy databáze

Při integraci s obchodními systémy nebo existujícími aplikacemi je velmi běžné převádět LocalDateTime na jiné třídy data-času nebo typy databáze. Tato sekce shrnuje často používané vzory převodu a důležité body k poznámce.

6-1. Převod mezi LocalDate a LocalTime

Zatímco LocalDateTime představuje jak datum, tak čas, existuje mnoho případů, kdy potřebujete zpracovávat pouze datum nebo pouze čas.

LocalDateTime → LocalDate / LocalTime

LocalDateTime dateTime = LocalDateTime.of(2025, 7, 10, 15, 30, 0);

LocalDate date = dateTime.toLocalDate();
LocalTime time = dateTime.toLocalTime();

System.out.println(date); // 2025-07-10
System.out.println(time); // 15:30

LocalDate / LocalTime → LocalDateTime

LocalDate date = LocalDate.of(2025, 7, 10);
LocalTime time = LocalTime.of(15, 30);

LocalDateTime dateTime = LocalDateTime.of(date, time);
System.out.println(dateTime); // 2025-07-10T15:30

6-2. Converting with java.util.Date, Calendar, and java.sql.Timestamp

When working with legacy APIs or JDBC, you may need to convert between LocalDateTime and older date-time types such as Date or Timestamp.

LocalDateTime → java.sql.Timestamp

import java.sql.Timestamp;
import java.time.LocalDateTime;

LocalDateTime dateTime = LocalDateTime.now();
Timestamp timestamp = Timestamp.valueOf(dateTime);
System.out.println(timestamp); // Příklad: 2025-07-10 15:30:00.123

java.sql.Timestamp → LocalDateTime

Timestamp timestamp = Timestamp.valueOf("2025-07-10 15:30:00");
LocalDateTime dateTime = timestamp.toLocalDateTime();
System.out.println(dateTime); // 2025-07-10T15:30

Converting java.util.Date or Calendar requires an intermediate Instant

Date date = new Date();
LocalDateTime dateTime =
    date.toInstant()
        .atZone(ZoneId.systemDefault())
        .toLocalDateTime();

6-3. Mapping to Database DATETIME Types (MySQL / PostgreSQL)

LocalDateTime works very well with DATETIME columns in MySQL and PostgreSQL. Using JDBC drivers, you can convert smoothly via setTimestamp and getTimestamp.

• MySQL / PostgreSQL DATETIME ↔ Java LocalDateTime or java.sql.Timestamp
• When reading: use getTimestamp() → toLocalDateTime()
• When writing: convert with Timestamp.valueOf(LocalDateTime) and use setTimestamp()

Important: Be careful with time zone management

• DATETIME columns in MySQL and PostgreSQL do not store time zone information.
• It is critical to keep a consistent time zone policy within the application.
• If strict time zone control is required, consider TIMESTAMP WITH TIME ZONE or using ZonedDateTime .

6-4. Converting with ZonedDateTime and OffsetDateTime

When time zone information is required, conversions between LocalDateTime and ZonedDateTime are commonly used.

LocalDateTime localDateTime = LocalDateTime.now();
ZoneId zone = ZoneId.of("Asia/Tokyo");

ZonedDateTime zonedDateTime = localDateTime.atZone(zone);
System.out.println(zonedDateTime); // 2025-07-10T15:30+09:00[Asia/Tokyo]

LocalDateTime backToLocal = zonedDateTime.toLocalDateTime();
System.out.println(backToLocal); // 2025-07-10T15:30

Summary

• LocalDateTime can be easily converted to and from other date-time classes and database types
• JDBC integration works smoothly via Timestamp
• Use ZonedDateTime or OffsetDateTime when time zone handling is required
• Ensure time zone consistency when integrating with databases

7. Practical Use Cases and Quick Reference by Scenario

This section organizes real-world use cases for LocalDateTime and helps you choose the appropriate class depending on the situation.

7-1. Common Practical Use Cases

(1) Task and Schedule Management Systems

LocalDateTime is ideal when managing schedules and deadlines that require both date and time. It allows intuitive handling of task start and end times.

LocalDateTime deadline =
    LocalDateTime.of(2025, 7, 31, 23, 59, 59);

(2) Attendance and Time Tracking

Clock-in and clock-out records require both date and time. Integration with database DATETIME columns is straightforward.

LocalDateTime clockIn = LocalDateTime.now();

(3) Logging and Audit Trails

System logs and error histories often record event timestamps using LocalDateTime. It is suitable when time zone adjustments are unnecessary or logs are internal to the application.

7-2. Quick Reference Table by Use Case

7-3. When You Need a Time Zone and When You Do Not

Typical cases where a time zone is not required

• Date-time values used only within the application
• Single-location systems (e.g., domestic-only services)

Typical cases where a time zone is required

• Systems involving multiple regions or international users
• Servers running in different time zones
• Applications that display times differently based on user location

Decision guideline

Ask yourself: “Does this date-time represent an absolute moment in time?” If yes, use ZonedDateTime or OffsetDateTime.

7-4. Simple Class Selection Flow

1. Does the date-time require time zone awareness?

• Yes → ZonedDateTime or OffsetDateTime
• No → Go to step 2

1. Do you need date only, time only, or both?

• Date only → LocalDate
• Time only → LocalTime
• Date and time → LocalDateTime

Summary

• LocalDateTime is ideal for managing local date and time without time zones
• Choosing the right class simplifies system design and maintenance
• Clearly understanding requirements helps avoid future bugs and inconsistencies

8. Common Errors, Troubleshooting, and Solutions

When using LocalDateTime, developers often encounter recurring errors or sources of confusion. This section summarizes common issues and their solutions in a Q&A format, allowing you to respond quickly when problems arise.

Q1. DateTimeParseException Occurs

Cause

• This exception occurs when the string passed to LocalDateTime.parse() does not match the expected format.
• Strings that are not in ISO-8601 format (e.g., "2025-07-10T15:30:00" ) require a DateTimeFormatter .

Solution

• Always verify that the format matches and use DateTimeFormatter when necessary.

  String input = "2025/07/10 15:30:00";
  DateTimeFormatter formatter =
      DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
  LocalDateTime.parse(input, formatter); // OK
  

Q2. Beware of NullPointerException

Cause

• Calling methods on a null LocalDateTime reference.

Solution

• Check for null values before use.
• Wrapping values in Optional can also be effective.

Q3. Incorrect Time Zone Handling

Cause

• LocalDateTime does not store time zone information, so changes in system or database time zones can cause unexpected results.

Solution

• Unify server and database time zone settings.
• Use ZonedDateTime or OffsetDateTime when time zone accuracy is required.

Q4. Date-Time Values Shift When Integrating with Databases

Cause

• Mismatches between database column types or time zone settings and Java application settings.

Solution

• Clearly define the time zone basis when using DATETIME and LocalDateTime .
• Consider using TIMESTAMP WITH TIME ZONE or ZonedDateTime when strict accuracy is required.

Q5. Loss of Precision (Milliseconds / Nanoseconds)

Cause

• Some JDBC drivers or databases support only millisecond precision, truncating nanoseconds.

Solution

• Confirm whether this precision loss is acceptable in your system requirements.
• Use alternative handling if nanosecond precision is mandatory.

Q6. Errors When Converting from Legacy APIs (Date, Calendar)

Cause

• Attempting to convert Date or Calendar directly into LocalDateTime .

Solution

• Always convert through Instant and ZoneId .

  Date date = new Date();
  LocalDateTime dateTime =
      date.toInstant()
          .atZone(ZoneId.systemDefault())
          .toLocalDateTime();
  

Practical Development Tips

• Věnujte pozornost formátování, časovým pásmům a kontrolám null, aby se předešlo většině problémů
• Vždy ověřujte konzistenci typů a konfigurace při integraci s databázemi nebo jinými systémy
• Když nastanou chyby, pečlivě si přečtěte zprávy výjimek a zkontrolujte vstupní hodnoty, konverzní logiku a nastavení prostředí

9. Často kladené otázky (FAQ)

Tato sekce odpovídá na často kladené otázky o LocalDateTime, které se běžně vyskytují v reálných vývojových scénářích. Použijte ji jako rychlý odkaz při řešení problémů nebo navrhování systémů.

Q1. Dokáže LocalDateTime pracovat s časovými pásmy?

Ne. LocalDateTime neukládá informaci o časovém pásmu. Pokud potřebujete spravovat absolutní okamžiky v čase, použijte ZonedDateTime nebo OffsetDateTime.

Q2. Jaký je nejbezpečnější způsob migrace z Date / Calendar na LocalDateTime?

Nelze přímo převést Date nebo Calendar. Vždy převádějte přes Instant a ZoneId.

Date date = new Date();
LocalDateTime dateTime =
    date.toInstant()
        .atZone(ZoneId.systemDefault())
        .toLocalDateTime();

Q3. Proč výstup někdy obsahuje “T”?

Znak „T“ je standardní oddělovač podle ISO‑8601. Objevuje se při použití toString() nebo DateTimeFormatter.ISO_LOCAL_DATE_TIME. Pro jeho odstranění zadejte vlastní formátovací vzor.

Q4. Na co si dát pozor při ukládání hodnot do databáze?

Sloupce DATETIME v databázi neukládají informaci o časovém pásmu. Zajistěte, aby aplikace konzistentně používala jedno časové pásmo. Pokud je vyžadována přísná přesnost, zvažte použití TIMESTAMP WITH TIME ZONE nebo ZonedDateTime.

Q5. Jakou přesnost podporuje LocalDateTime?

LocalDateTime podporuje přesnost na nanosekundy. Mnoho databází a JDBC driverů však podporuje jen milisekundy, což může oříznout jemnější přesnost.

Q6. Je LocalDateTime ovlivněn letním časem (DST)?

Ne. LocalDateTime sám o sobě neaplikuje úpravy pro letní čas. Použijte ZonedDateTime, pokud je nutná manipulace s DST.

Q7. Co použít, pokud potřebuji jen datum nebo jen čas?

Použijte LocalDate jen pro datum a LocalTime jen pro čas. LocalDateTime je ideální, když jsou potřeba oba.

Q8. Jak mám zacházet s výjimkami?

Pečlivě si přečtěte zprávy výjimek a zkontrolujte:

• Zda jsou formáty řetězců správné
• Zda jsou přítomny null nebo neplatné hodnoty
• Zda jsou kroky konverze implementovány správně

10. Shrnutí a odkazy na reference

Tento článek pokrývá vše od základů LocalDateTime po praktické použití, běžné úskalí a často kladené otázky. Níže je stručné shrnutí a užitečné odkazy pro další učení.

10-1. Klíčové poznatky pro správné používání LocalDateTime

• LocalDateTime je bezpečná a intuitivní třída pro správu lokálního data a času bez časových pásem. Podporuje aritmetické operace, formátování, porovnávání a parsování s lehkostí.
• Vyberte vhodnou třídu pro datum a čas podle požadavků systému.
• Použijte LocalDate jen pro datum
• Použijte LocalTime jen pro čas
• Použijte ZonedDateTime nebo OffsetDateTime, pokud jsou důležitá časová pásma
• Věnujte velkou pozornost časovým pásmům a formátům při integraci s databázemi nebo externími systémy.
• Pochopení běžných chyb předem pomáhá předcházet problémům. Odkazujte se na sekci FAQ a řešení problémů pro rychlé vyřešení.

10-2. Odkazy na reference a dokumentaci

• Java SE 8 API Dokumentace (LocalDateTime)
• Oficiální dokumentace DateTimeFormatter
• Průvodce Oracle Java Date and Time API
• Přehled Java Date and Time API (externí článek)

10-3. Závěrečné poznámky pro vývojáře

S vědomostmi z tohoto článku byste již neměli mít potíže s používáním LocalDateTime. Když se objeví nové požadavky, vždy se odkazujte na oficiální dokumentaci a důvěryhodné technické zdroje, abyste zůstali aktuální.

Aplikací správných konceptů a osvědčených postupů můžete učinit práci s daty a časem v Javě bezpečnější, čistší a lépe udržovatelnou v reálných systémech.