کد قدیمی

پیش از انتشار Java SE 8، مکانیزم تاریخ و زمان جاوا توسط کلاس‌های java.util.Date، java.util.Calendar و java.util.TimeZone و زیرکلاس‌هایشان مانند java.util.GregorianCalendar فراهم می‌شد. این کلاس‌ها چندین نقیصه داشتند، از جمله:

• کلاس Calendar Type-Safe نبود.
• چون کلاس‌ها Mutable بودند، در برنامه‌های Multi-Threaded قابل استفاده نبودند.
• باگ‌ها در کد برنامه به دلیل شماره‌گذاری غیرمعمول ماه‌ها و فقدان Type Safety رایج بودند.

سازگاری با کد قدیمی

شاید کد قدیمی‌ای دارید که از کلاس‌های تاریخ و زمان java.util استفاده می‌کند و می‌خواهید با حداقل تغییرات از قابلیت‌های java.time بهره‌مند شوید.

در انتشار JDK 8 چندین متد برای تبدیل بین اشیاء java.util و java.time اضافه شد:

• Calendar.toInstant() شیء Calendar را به Instant تبدیل می‌کند.
• GregorianCalendar.toZonedDateTime() نمونه‌ی GregorianCalendar را به ZonedDateTime تبدیل می‌کند.
• GregorianCalendar.from(ZonedDateTime) با استفاده از Locale پیش‌فرض از نمونه‌ی ZonedDateTime شیء GregorianCalendar می‌سازد.
• Date.from(Instant) شیء Date را از یک Instant می‌سازد.
• Date.toInstant() شیء Date را به Instant تبدیل می‌کند.
• TimeZone.toZoneId() شیء TimeZone را به ZoneId تبدیل می‌کند.

مثال زیر نمونه‌ی Calendar را به نمونه‌ی ZonedDateTime تبدیل می‌کند. توجه کنید برای تبدیل از Instant به ZonedDateTime باید منطقه‌ی زمانی ارائه شود:

Calendar now = Calendar.getInstance();
ZonedDateTime zdt = ZonedDateTime.ofInstant(now.toInstant(), ZoneId.systemDefault());

مثال زیر تبدیل بین Date و Instant را نشان می‌دهد:

Instant inst = date.toInstant();

Date newDate = Date.from(inst);

مثال زیر از GregorianCalendar به ZonedDateTime و سپس از ZonedDateTime به GregorianCalendar تبدیل می‌کند. کلاس‌های مبتنی بر Temporal دیگر از نمونه‌ی ZonedDateTime ساخته می‌شوند:

GregorianCalendar cal = ...;

TimeZone tz = cal.getTimeZone();
int tzoffset = cal.get(Calendar.ZONE_OFFSET);

ZonedDateTime zdt = cal.toZonedDateTime();

GregorianCalendar newCal = GregorianCalendar.from(zdt);

LocalDateTime ldt = zdt.toLocalDateTime();
LocalDate date = zdt.toLocalDate();
LocalTime time = zdt.toLocalTime();

نگاشت قابلیت‌های قدیمی تاریخ و زمان به Date-Time API

چون پیاده‌سازی جاوا برای تاریخ و زمان در انتشار Java SE 8 کاملاً بازطراحی شده، نمی‌توانید یک مетод را با متد دیگر جابه‌جا کنید. اگر می‌خواهید از قابلیت‌های غنی پکیج java.time استفاده کنید، ساده‌ترین راه‌حل استفاده از متدهای toInstant() یا toZonedDateTime() ذکرشده در بخش قبلی است. اما اگر نمی‌خواهید از این رویکرد استفاده کنید یا برای نیازهای شما کافی نیست، باید کد تاریخ-زمان خود را بازنویسی کنید.

جدول معرفی‌شده در صفحه‌ی نمای کلی نقطه‌ی شروع خوبی برای ارزیابی کلاس‌های java.time متناسب با نیازهای شماست.

نگاشت یک‌به‌یک بین دو API وجود ندارد، اما جدول زیر دید کلی از نگاشت قابلیت‌های کلاس‌های تاریخ و زمان java.util به java.time ارائه می‌دهد.

نگاشت Date قدیمی و Instant

کلاس‌های Instant و Date مشابه هم هستند. هر کدام:

• نقطه‌ی لحظه‌ای زمان روی خط زمانی (UTC) را نمایش می‌دهند
• زمانی مستقل از منطقه‌ی زمانی ذخیره می‌کنند
• به صورت Epoch Seconds (از 1970-01-01T00:00:00Z) به اضافه‌ی نانوثانیه نمایش داده می‌شوند

متدهای Date.from(Instant) و Date.toInstant() امکان تبدیل بین این کلاس‌ها را فراهم می‌کنند.

نگاشت GregorianCalendar و ZonedDateTime

کلاس ZonedDateTime جایگزین GregorianCalendar است. نمایش زمان انسانی به صورت زیر است:

• LocalDate: سال، ماه، روز
• LocalTime: ساعت، دقیقه، ثانیه، نانوثانیه
• ZoneId: منطقه‌ی زمانی
• ZoneOffset: Offset فعلی نسبت به GMT

متدهای GregorianCalendar.from(ZonedDateTime) و GregorianCalendar.toZonedDateTime() تبدیل بین این کلاس‌ها را انجام می‌دهند.

نگاشت TimeZone قدیمی و ZoneId یا ZoneOffset

کلاس ZoneId شناسه‌ی منطقه‌ی زمانی را مشخص کرده و به قوانین هر منطقه‌ی زمانی دسترسی دارد. کلاس ZoneOffset فقط Offset نسبت به گرینویچ/UTC را مشخص می‌کند. برای اطلاعات بیشتر کلاس‌های منطقه‌ی زمانی و Offset را ببینید.

نگاشت GregorianCalendar با تاریخ ۱۹۷۰-۰۱-۰۱ و LocalTime

کدی که در نمونه‌ی GregorianCalendar تاریخ را روی ۱۹۷۰-۰۱-۰۱ تنظیم می‌کند تا از اجزای زمان استفاده شود، قابل جایگزینی با نمونه‌ی LocalTime است.

نگاشت GregorianCalendar با ساعت ۰۰:۰۰ و LocalDate

کدی که در نمونه‌ی GregorianCalendar ساعت را روی ۰۰:۰۰ تنظیم می‌کند تا از اجزای تاریخ استفاده شود، قابل جایگزینی با نمونه‌ی LocalDate است. (این رویکرد GregorianCalendar ناقص بود، چون نیمه‌شب در برخی کشورها به دلیل انتقال به ساعت تابستانی یک‌بار در سال رخ نمی‌دهد.)

فرمت‌بندی تاریخ و زمان

اگرچه java.time.format.DateTimeFormatter مکانیزم قدرتمندی برای فرمت‌بندی مقادیر تاریخ و زمان ارائه می‌دهد، می‌توانید کلاس‌های مبتنی بر Temporal java.time را مستقیماً با java.util.Formatter و String.format() با استفاده از همان فرمت‌بندی الگویی که با کلاس‌های تاریخ و زمان java.util به کار می‌بردید، استفاده کنید.