جافا 8 تاريخ – LocalDate، LocalDateTime، Instant

الدروس التعليمية

واجهة برمجة التاريخ والوقت هي واحدة من أكبر الميزات في إصدار Java 8. كانت Java تفتقر إلى نهج متسق للتاريخ والوقت من البداية وواجهة برمجة التاريخ والوقت في Java 8 هي إضافة مرحب بها إلى واجهات برمجة التطبيقات الأساسية في Java.

لماذا نحتاج إلى واجهة برمجة تطبيقات Java Date Time الجديدة؟

قبل أن نبدأ في النظر إلى واجهة برمجة تاريخ ووقت Java 8، دعونا نرى لماذا نحتاج إلى واجهة برمجة تطبيقات جديدة لهذا. كانت هناك عدة مشاكل مع الفئات ذات الصلة بالتاريخ والوقت الحالية في جافا، بعضها:

لم تُعرف فئات Java Date Time بشكل متسق، لدينا فئة Date في كل من حزمتي java.util و java.sql. مرة أخرى، تم تحديد فئات التنسيق والتحليل في حزمة java.text.
تحتوي java.util.Date على قيم تاريخ ووقت بينما تحتوي java.sql.Date فقط على قيمة تاريخ. وجود هذا في حزمة java.sql لا يُعني أي شيء. أيضًا، كلا الفئتين لهما نفس الاسم، وهو تصميم سيء للغاية بحد ذاته.
لا توجد فئات محددة بوضوح للوقت، الطابع الزمني، التنسيق، والتحليل. لدينا فئة java.text.DateFormat الكائنة لتلبية احتياجات التحليل والتنسيق. عادةً، يُستخدم الفصل SimpleDateFormat للتحليل والتنسيق.
جميع فئات التاريخ قابلة للتغيير، لذا فهي غير آمنة في الخيوط. إنها واحدة من أكبر المشاكل في فئات التاريخ والتقويم في Java.
لا توفر فئة Date تدويلًا، ولا دعم للمناطق الزمنية. لذلك تم تقديم فئتي java.util.Calendar و java.util.TimeZone، ولكنهما لديهما جميع المشاكل المذكورة أعلاه.

هناك بعض المشاكل الأخرى مع الأساليب المعرفة في فئات Date و Calendar ولكن المشاكل المذكورة أعلاه توضح بوضوح أنه كان هناك حاجة إلى واجهة برمجة تطبيقات للتاريخ والوقت قوية في جافا. لهذا السبب لعبت Joda Time دورًا رئيسيًا كبديل جيد الجودة لمتطلبات تاريخ ووقت جافا.

مبادئ تصميم تاريخ ووقت جافا 8

واجهة برمجة تطبيقات تاريخ ووقت جافا 8 هي تنفيذ لـ JSR-310. تم تصميمها للتغلب على جميع العيوب في تنفيذات التاريخ والوقت التقليدية. بعض مبادئ تصميم واجهة برمجة تطبيقات التاريخ والوقت الجديدة هي:

اللاقابلية للتغيير: جميع الفئات في واجهة برمجة تطبيقات التاريخ والوقت الجديدة لا تقبل التغيير وهي جيدة للبيئات متعددة الخيوط.
فصل الاهتمامات: تفصل الواجهة الجديدة بوضوح بين التاريخ والوقت القابل للقراءة بشكل بشري والوقت الآلي (الطابع الزمني ليونكس). وهي تحدد فئات منفصلة للتاريخ، الوقت، التاريخ والوقت المجتمعي، الطابع الزمني، المنطقة الزمنية، وما إلى ذلك.
الوضوح: تم تحديد الطرق بوضوح وتقوم بنفس الإجراء في جميع الفئات. على سبيل المثال، للحصول على الحالة الحالية لدينا طريقة now(). هناك طرق format() و parse() المحددة في جميع هذه الفئات بدلاً من وجود فئة منفصلة لها.

جميع الفئات تستخدم نمط الصانع (Factory Pattern) ونمط الاستراتيجية (Strategy Pattern) لمعالجة أفضل. بمجرد استخدام الطرق في إحدى الفئات، لن يكون العمل مع الفئات الأخرى صعبًا.
العمليات المساعدة: تأتي جميع فئات واجهة برمجة التطبيقات الجديدة للتاريخ والوقت مع أساليب لأداء المهام الشائعة، مثل الجمع، والطرح، والتنسيق، والتحليل، والحصول على الجزء المنفصل في التاريخ/الوقت، إلخ.
قابل للتوسيع: تعمل واجهة برمجة التطبيقات الجديدة للتاريخ والوقت على نظام التقويم ISO-8601 ولكن يمكننا استخدامها مع أنظمة تقويم غير ISO أيضًا.

حزم واجهة برمجة التطبيقات للتاريخ والوقت

تتكون واجهة برمجة التطبيقات للتاريخ والوقت في جافا 8 من الحزم التالية.

java.time: هذه هي الحزمة الأساسية لواجهة برمجة التطبيقات الجديدة للتاريخ والوقت في جافا. جميع الفئات الأساسية الرئيسية هي جزء من هذه الحزمة، مثل LocalDate، LocalTime، LocalDateTime، Instant، Period، Duration، إلخ. جميع هذه الفئات لا تتغير وآمنة للتعددية الخيوط. في معظم الأحيان، ستكون هذه الفئات كافية للتعامل مع المتطلبات الشائعة.
java.time.chrono: تعرّف هذه الحزمة واجهات برمجة التطبيقات العامة لأنظمة التقويم غير ISO. يمكننا توسيع فئة AbstractChronology لإنشاء نظام تقويم خاص بنا.
java.time.format: تحتوي هذه الحزمة على فئات تستخدم لتنسيق وتحليل كائنات التاريخ والوقت. في معظم الأحيان لن نستخدمها مباشرة بسبب الفئات الرئيسية في حزمة java.time التي توفر أساليب التنسيق والتحليل.
java.time.temporal: تحتوي هذه الحزمة على كائنات زمنية ويمكننا استخدامها لمعرفة التواريخ أو الأوقات المحددة المتعلقة بكائنات التاريخ/الوقت. على سبيل المثال، يمكننا استخدامها لمعرفة أول أو آخر يوم في الشهر. يمكنك التعرف على هذه الأساليب بسهولة لأنها تحمل دائمًا التنسيق “withXXX”.
java.time.zone Package: تحتوي هذه الحزمة على فئات تدعم مختلف المناطق الزمنية وقواعدها.

Java 8 Date Time API Classes Examples

لقد قمنا بالنظر في معظم الأجزاء الهامة لـ Java Date Time API. حان الوقت الآن للنظر في الفئات الأكثر أهمية لـ Date Time API مع الأمثلة.

1. LocalDate

LocalDate هي فئة لا يمكن تغييرها تمثل تاريخًا بتنسيق افتراضي yyyy-MM-dd. يمكننا استخدام الطريقة now() للحصول على التاريخ الحالي. يمكننا أيضًا توفير الوسائط الدخلية لسنة وشهر وتاريخ لإنشاء مثيل LocalDate.

تقدم هذه الفئة طريقة محملة لـ now() حيث يمكننا تمرير ZoneId للحصول على التواريخ في منطقة زمنية محددة. تقدم هذه الفئة نفس الوظيفة كـ java.sql.Date.

package com.journaldev.java8.time;

import java.time.LocalDate;
import java.time.Month;
import java.time.ZoneId;

/**
 * أمثلة على LocalDate
 * @author pankaj
 *
 */
public class LocalDateExample {

	public static void main(String[] args) {
		
		// التاريخ الحالي
		LocalDate today = LocalDate.now();
		System.out.println("Current Date="+today);
		
		// إنشاء LocalDate عن طريق توفير مدخلات الإدخال
		LocalDate firstDay_2014 = LocalDate.of(2014, Month.JANUARY, 1);
		System.out.println("Specific Date="+firstDay_2014);
		
		
		// حاول إنشاء تاريخ عن طريق توفير مدخلات غير صالحة
		// LocalDate feb29_2014 = LocalDate.of(2014, Month.FEBRUARY, 29);
		// استثناء في الموضوع "الرئيسي" java.time.DateTimeException:
		// التاريخ غير صالح '29 فبراير' حيث أن '2014' ليس عامًا كبيسًا
		
		// التاريخ الحالي في "Asia/Kolkata"، يمكنك الحصول عليه من توثيق ZoneId
		LocalDate todayKolkata = LocalDate.now(ZoneId.of("Asia/Kolkata"));
		System.out.println("Current Date in IST="+todayKolkata);

		// java.time.zone.ZoneRulesException: معرف منطقة زمنية غير معروف: IST
		// LocalDate todayIST = LocalDate.now(ZoneId.of("IST"));
		
		// الحصول على التاريخ من التاريخ الأساسي أي 01/01/1970
		LocalDate dateFromBase = LocalDate.ofEpochDay(365);
		System.out.println("365th day from base date= "+dateFromBase);
		
		LocalDate hundredDay2014 = LocalDate.ofYearDay(2014, 100);
		System.out.println("100th day of 2014="+hundredDay2014);
	}

}

يتم توضيح طرق LocalDate في التعليقات. عند تشغيل هذا البرنامج، نحصل على الناتج التالي.

Current Date=2014-04-28
Specific Date=2014-01-01
Current Date in IST=2014-04-29
365th day from base date= 1971-01-01
100th day of 2014=2014-04-10

2. LocalTime

LocalTime هي فئة لا تتغير، والتي يُمثل مثيلها الوقت في تنسيق قابل للقراءة من الإنسان. التنسيق الافتراضي لها هو ساعة:دقيقة:ثانية.زوز. تمامًا كما هو الحال مع LocalDate، توفر هذه الفئة دعمًا للمنطقة الزمنية وإنشاء مثيل عن طريق تمرير الساعة والدقيقة والثانية كمعاملات إدخالية.

package com.journaldev.java8.time;

import java.time.LocalTime;
import java.time.ZoneId;

/**
 * أمثلة على LocalTime
 * @author pankaj
 *
 */
public class LocalTimeExample {

	public static void main(String[] args) {
		
		// الوقت الحالي
		LocalTime time = LocalTime.now();
		System.out.println("Current Time="+time);
		
		// إنشاء LocalTime عن طريق توفير معاملات الإدخال
		LocalTime specificTime = LocalTime.of(12,20,25,40);
		System.out.println("Specific Time of Day="+specificTime);
		
		
		// حاول إنشاء وقت عن طريق توفير إدخالات غير صالحة
		// LocalTime invalidTime = LocalTime.of(25,20);
		// استثناء في thread "main" java.time.DateTimeException: 
		// قيمة غير صالحة لـ HourOfDay (القيم الصالحة 0 - 23): 25
		
		// التاريخ الحالي في "Asia/Kolkata"، يمكنك الحصول عليه من وثائق ZoneId
		LocalTime timeKolkata = LocalTime.now(ZoneId.of("Asia/Kolkata"));
		System.out.println("Current Time in IST="+timeKolkata);

		// java.time.zone.ZoneRulesException: معرف المنطقة الزمنية غير معروف: IST
		// LocalTime todayIST = LocalTime.now(ZoneId.of("IST"));
		
		// الحصول على التاريخ من التاريخ الأساسي أي 01/01/1970
		LocalTime specificSecondTime = LocalTime.ofSecondOfDay(10000);
		System.out.println("10000th second time= "+specificSecondTime);

	}

}

الإخراج:

Current Time=15:51:45.240
Specific Time of Day=12:20:25.000000040
Current Time in IST=04:21:45.276
10000th second time= 02:46:40

3. LocalDateTime

LocalDateTime هو كائن تاريخ-ووقت لا يمكن تغييره يُمثّل تاريخًا ووقتًا بتنسيق افتراضي كـ yyyy-MM-dd-HH-mm-ss.zzz. يوفر طريقة مصنع يأخذ مدخلات LocalDate و LocalTime لإنشاء مثيل LocalDateTime.

package com.journaldev.java8.time;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.Month;
import java.time.ZoneId;
import java.time.ZoneOffset;

public class LocalDateTimeExample {

	public static void main(String[] args) {
		
		//التاريخ الحالي
		LocalDateTime today = LocalDateTime.now();
		System.out.println("Current DateTime="+today);
		
		//التاريخ الحالي باستخدام LocalDate و LocalTime
		today = LocalDateTime.of(LocalDate.now(), LocalTime.now());
		System.out.println("Current DateTime="+today);
		
		//إنشاء LocalDateTime عن طريق توفير مدخلات
		LocalDateTime specificDate = LocalDateTime.of(2014, Month.JANUARY, 1, 10, 10, 30);
		System.out.println("Specific Date="+specificDate);
		
		
		//جرّب إنشاء التاريخ عن طريق توفير مدخلات غير صالحة
		//LocalDateTime feb29_2014 = LocalDateTime.of(2014, Month.FEBRUARY, 28, 25,1,1);
		//Exception in thread "main" java.time.DateTimeException: 
		//قيمة غير صالحة لـ ساعة اليوم (القيم الصالحة 0 - 23): 25

		
		//التاريخ الحالي في "Asia/Kolkata"، يمكنك الحصول عليه من وثائق جافا لـ ZoneId
		LocalDateTime todayKolkata = LocalDateTime.now(ZoneId.of("Asia/Kolkata"));
		System.out.println("Current Date in IST="+todayKolkata);

		//java.time.zone.ZoneRulesException: معرف منطقة زمنية غير معروف: IST
		//LocalDateTime todayIST = LocalDateTime.now(ZoneId.of("IST"));
		
		//الحصول على التاريخ من التاريخ الأساسي أي 01/01/1970
		LocalDateTime dateFromBase = LocalDateTime.ofEpochSecond(10000, 0, ZoneOffset.UTC);
		System.out.println("10000th second time from 01/01/1970= "+dateFromBase);

	}

}

في جميع الأمثلة الثلاث، رأينا أنه إذا قدمنا مدخلات غير صالحة لإنشاء التاريخ/الوقت، فإنه يُطرح java.time.DateTimeException، وهو RuntimeException لذا لا يلزمنا التقاطه بوضوح.

لقد رأينا أيضًا أنه يمكننا الحصول على بيانات التاريخ/الوقت عن طريق تمرير ZoneId، يمكنك الحصول على قائمة القيم المدعومة لـ ZoneId من JavaDoc الخاص به. عند تشغيل الفصل أعلاه، نحصل على الإخراج التالي.

Current DateTime=2014-04-28T16:00:49.455
Current DateTime=2014-04-28T16:00:49.493
Specific Date=2014-01-01T10:10:30
Current Date in IST=2014-04-29T04:30:49.493
10000th second time from 01/01/1970= 1970-01-01T02:46:40

4. فوري

يُستخدم فئة Instant للعمل مع تنسيق الوقت القابل للقراءة بواسطة الآلة. تخزن Instant التاريخ والوقت في الطابع الزمني لـ Unix.

package com.journaldev.java8.time;

import java.time.Duration;
import java.time.Instant;

public class InstantExample {

	public static void main(String[] args) {
		// الطابع الزمني الحالي
		Instant timestamp = Instant.now();
		System.out.println("Current Timestamp = "+timestamp);
		
		// فوري من الطابع الزمني
		Instant specificTime = Instant.ofEpochMilli(timestamp.toEpochMilli());
		System.out.println("Specific Time = "+specificTime);
		
		// مثال على المدة
		Duration thirtyDay = Duration.ofDays(30);
		System.out.println(thirtyDay);
	}

}

الإخراج:

Current Timestamp = 2014-04-28T23:20:08.489Z
Specific Time = 2014-04-28T23:20:08.489Z
PT720H

وحدات تاريخ جافا 8

معظم فئات مبادئ تاريخ الوقت توفر مجموعة متنوعة من الأساليب المساعدة مثل زيادة/نقصان الأيام، الأسابيع، الشهور إلخ. هناك بعض الأساليب المساعدة الأخرى لضبط التاريخ باستخدام TemporalAdjuster ولحساب الفترة بين تاريخين.

package com.journaldev.java8.time;

import java.time.LocalDate;
import java.time.LocalTime;
import java.time.Period;
import java.time.temporal.TemporalAdjusters;

public class DateAPIUtilities {

	public static void main(String[] args) {
		
		LocalDate today = LocalDate.now();
		
		//الحصول على السنة والتحقق مما إذا كانت سنة كبيسة
		System.out.println("Year "+today.getYear()+" is Leap Year? "+today.isLeapYear());
		
		//مقارنة اثنين من LocalDate للتأكد ما إذا كانت قبل أم بعد
		System.out.println("Today is before 01/01/2015? "+today.isBefore(LocalDate.of(2015,1,1)));
		
		//إنشاء LocalDateTime من LocalDate
		System.out.println("Current Time="+today.atTime(LocalTime.now()));
		
		//عمليات الجمع والطرح
		System.out.println("10 days after today will be "+today.plusDays(10));
		System.out.println("3 weeks after today will be "+today.plusWeeks(3));
		System.out.println("20 months after today will be "+today.plusMonths(20));

		System.out.println("10 days before today will be "+today.minusDays(10));
		System.out.println("3 weeks before today will be "+today.minusWeeks(3));
		System.out.println("20 months before today will be "+today.minusMonths(20));
		
		//مُعدلات الزمن لتعديل التواريخ
		System.out.println("First date of this month= "+today.with(TemporalAdjusters.firstDayOfMonth()));
		LocalDate lastDayOfYear = today.with(TemporalAdjusters.lastDayOfYear());
		System.out.println("Last date of this year= "+lastDayOfYear);
		
		Period period = today.until(lastDayOfYear);
		System.out.println("Period Format= "+period);
		System.out.println("Months remaining in the year= "+period.getMonths());		
	}
}

الناتج:

Year 2014 is Leap Year? false
Today is before 01/01/2015? true
Current Time=2014-04-28T16:23:53.154
10 days after today will be 2014-05-08
3 weeks after today will be 2014-05-19
20 months after today will be 2015-12-28
10 days before today will be 2014-04-18
3 weeks before today will be 2014-04-07
20 months before today will be 2012-08-28
First date of this month= 2014-04-01
Last date of this year= 2014-12-31
Period Format= P8M3D
Months remaining in the year= 8

تحليل وتنسيق التواريخ في جافا 8

من الشائع جدًا تنسيق التاريخ بتنسيقات مختلفة ومن ثم تحليل سلسلة نصية للحصول على كائنات تاريخ ووقت.

package com.journaldev.java8.time;

import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class DateParseFormatExample {

	public static void main(String[] args) {
		
		//أمثلة للتنسيق
		LocalDate date = LocalDate.now();
		//التنسيق الافتراضي
		System.out.println("Default format of LocalDate="+date);
		//تنسيق محدد
		System.out.println(date.format(DateTimeFormatter.ofPattern("d::MMM::uuuu")));
		System.out.println(date.format(DateTimeFormatter.BASIC_ISO_DATE));
		
		
		LocalDateTime dateTime = LocalDateTime.now();
		//التنسيق الافتراضي
		System.out.println("Default format of LocalDateTime="+dateTime);
		//تنسيق محدد
		System.out.println(dateTime.format(DateTimeFormatter.ofPattern("d::MMM::uuuu HH::mm::ss")));
		System.out.println(dateTime.format(DateTimeFormatter.BASIC_ISO_DATE));
		
		Instant timestamp = Instant.now();
		//التنسيق الافتراضي
		System.out.println("Default format of Instant="+timestamp);
		
		//أمثلة للتحليل
		LocalDateTime dt = LocalDateTime.parse("27::Apr::2014 21::39::48",
				DateTimeFormatter.ofPattern("d::MMM::uuuu HH::mm::ss"));
		System.out.println("Default format after parsing = "+dt);
	}

}

الناتج:

Default format of LocalDate=2014-04-28
28::Apr::2014
20140428
Default format of LocalDateTime=2014-04-28T16:25:49.341
28::Apr::2014 16::25::49
20140428
Default format of Instant=2014-04-28T23:25:49.342Z
Default format after parsing = 2014-04-27T21:39:48

دعم تاريخ/وقت التراث في واجهة برمجة التطبيقات لجافا

تستخدم فئات التاريخ/الوقت التراث في معظم التطبيقات تقريبًا، لذلك يجب أن يكون هناك التوافق مع الإصدارات السابقة. ولهذا السبب هناك العديد من الطرق المساعدة التي يمكننا من خلالها تحويل الفئات التراثية إلى الفئات الجديدة والعكس بالعكس.

package com.journaldev.java8.time;

import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.TimeZone;

public class DateAPILegacySupport {

	public static void main(String[] args) {
		
		//تحويل من Date إلى Instant
		Instant timestamp = new Date().toInstant();
		//يمكننا الآن تحويل Instant إلى LocalDateTime أو فئات مماثلة أخرى
		LocalDateTime date = LocalDateTime.ofInstant(timestamp, 
						ZoneId.of(ZoneId.SHORT_IDS.get("PST")));
		System.out.println("Date = "+date);
		
		//تحويل من Calendar إلى Instant
		Instant time = Calendar.getInstance().toInstant();
		System.out.println(time);
		//تحويل من TimeZone إلى ZoneId
		ZoneId defaultZone = TimeZone.getDefault().toZoneId();
		System.out.println(defaultZone);
		
		//إنشاء ZonedDateTime من تقويم معين
		ZonedDateTime gregorianCalendarDateTime = new GregorianCalendar().toZonedDateTime();
		System.out.println(gregorianCalendarDateTime);
		
		//تحويل من واجهة برمجة التطبيقات للتاريخ إلى الفئات التراثية
		Date dt = Date.from(Instant.now());
		System.out.println(dt);
		
		TimeZone tz = TimeZone.getTimeZone(defaultZone);
		System.out.println(tz);
		
		GregorianCalendar gc = GregorianCalendar.from(gregorianCalendarDateTime);
		System.out.println(gc);
		
	}

}

الناتج:

Date = 2014-04-28T16:28:54.340
2014-04-28T23:28:54.395Z
America/Los_Angeles
2014-04-28T16:28:54.404-07:00[America/Los_Angeles]
Mon Apr 28 16:28:54 PDT 2014
sun.util.calendar.ZoneInfo[id="America/Los_Angeles",offset=-28800000,dstSavings=3600000,useDaylight=true,transitions=185,lastRule=java.util.SimpleTimeZone[id=America/Los_Angeles,offset=-28800000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]]
java.util.GregorianCalendar[time=1398727734404,areFieldsSet=true,areAllFieldsSet=true,lenient=true,zone=sun.util.calendar.ZoneInfo[id="America/Los_Angeles",offset=-28800000,dstSavings=3600000,useDaylight=true,transitions=185,lastRule=java.util.SimpleTimeZone[id=America/Los_Angeles,offset=-28800000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=2,minimalDaysInFirstWeek=4,ERA=1,YEAR=2014,MONTH=3,WEEK_OF_YEAR=18,WEEK_OF_MONTH=5,DAY_OF_MONTH=28,DAY_OF_YEAR=118,DAY_OF_WEEK=2,DAY_OF_WEEK_IN_MONTH=4,AM_PM=1,HOUR=4,HOUR_OF_DAY=16,MINUTE=28,SECOND=54,MILLISECOND=404,ZONE_OFFSET=-28800000,DST_OFFSET=3600000]

كما يمكنك أن ترى أن طرق toString() لفئات TimeZone وGregorianCalendar التراثية طويلة وغير ودية للمستخدم.

الاستنتاج

I like this new Date Time API a lot. Some of the most used classes will be LocalDate and LocalDateTime. It’s very easy to work with the new classes. And, having similar methods that does a particular job makes it easy to find. It will take some time from moving legacy classes to new Date Time classes, but I believe it will be worth the time and effort.

Source:
https://www.digitalocean.com/community/tutorials/java-8-date-localdate-localdatetime-instant