Java දිනය සහ වේලාව API පැහැදිලි කිරීම: පරණ Date සිට නව java.time හොඳම ක්‍රියාමාර්ග දක්වා

1. හැඳින්වීම

Java-අධාරිත පද්ධති සංවර්ධනය සහ ව්‍යාපාරික යෙදුම් වල, දිනයන් සහ වේලාවන්ගේ නිරවද්‍ය සැකසීම අත්‍යවශ්‍ය වේ. පැමිණිලි කළමනාකරණය, කාලසටහන්, ලොග් රෙකෝඩ්, ගොනු කාල සලකුණු කළමනාකරණය—දිනය සහ වේලාව සැකසීම සැම පද්ධතියකම මූලික අවශ්‍යතාවයකි.

කෙසේ වෙතත්, Java හි දිනය-සම්බන්ධ API ගූඩු එහි හඳුන්වා දීමෙන් පසු විශාල ලෙස සංවර්ධනය වී ඇත. වසර ගණනාවක් පුරා භාවිතා කර ඇති java.util.Date සහ Calendar වැනි පරණ පන්තීන්, නිර්මාණ සීමා සහ භාවිතා ගැටළු වලින් පීඩිත වන අතර, ඒවා බොහෝවිට අනපේක්ෂිත දෝෂ සහ සැකසුම් ගැටළු ඇති කරයි. තවද, Java 8 සිට, සම්පූර්ණයෙන් නව Date සහ Time API (java.time) හඳුන්වා දී, පාරම්පරික රීතිවලට මූලික වෙනස්කම් සිදු කර ඇත.

මෙම ලිපිය Java දිනය සහ වේලාව සැකසීමේ පද්ධතිමය හා ප්‍රායෝගික විස්තරයක් ලබා දේ, මූලික සංකල්ප සහ නව API ගූඩු සිට නිෂ්පාදන පරිසරවල සාමාන්‍ය වැරදි, සහ ප්‍රායෝගික ක්‍රියාත්මක කිරීමේยุත්‍රාන්තරයන් දක්වා සියල්ල ආවරණය කරයි. ආරම්භකයන්ට දිනය සැකසීමේ දෝෂප්‍රවණතාවය ඇයි කියා ඉගෙන ගත හැකි අතර, මධ්‍යම සහ උසස් මට්ටමේ සංවර්ධකයන්ට වාස්තුක ගැටළු, විසඳුම්, සහ පරණ හා නව API අතර මාරුยุත්‍රාන්තරයන් පිළිබඳ අවබෝධයක් ලැබේ.

අද, Java හි දිනයන් සහ වේලාවන් නිවැරදිව සහ විශ්වාසයෙන් සැකසීම විශ්වාසනීය පද්ධති ගොඩනැගීමේ මූලික කුසලතාව වේ. මෙම ලිපියේ අවසානයේදී, ඔබට නවීන දැනුම සහ ක්‍රියාත්මක කිරීමේ තාක්ෂණයන් ලැබෙනු ඇත, ඒවා පරණ නොවනු ඇත.

2. Java දිනය වර්ගයන්ගේ මූලික කරුණු

Java හි දිනයන් සහ වේලාවන් සමඟ වැඩ කරන විට, සංවර්ධකයන් මුලින්ම හමුවන සංකල්පය Date වර්ගය වේ. Java 1.0 අනුවාදයෙන් පසු, java.util.Date පන්තිය දිනය සහ වේලාව අගයන් නියෝජනය කිරීමේ ප්‍රමිතියක් ලෙස ලබා දී ඇත. වසර ගණනාවක් පුරා පුළුල් ලෙස භාවිතා කර තිබුණද, එහි නිර්මාණ සීමා සහ භාවිතා ගැටළු කාලයත් සමඟ වැඩි වශයෙන් පෙනී ඇත.

Date වර්ගය කුමක්ද?

java.util.Date පන්තිය 1970 ජනවාරි 1, 00:00:00 UTC (UNIX epoch) සිට ගත වූ මිලිසෙකන්ඩ් ගණන ලෙස දිනය සහ වේලාව නියෝජනය කරයි. ඇතුළත, මෙම තොරතුර එක long අගයක් ලෙස ගබඩා කරයි.

එහි සරලත්වය සත්‍ය වුවත්, Date වර්ගයට කිහිපයක් ප්‍රසිද්ධ ගැටළු ඇත:

• අවුරුදු, මාසය, දිනය වැනි තනි කොටස් සෘජුව ප්‍රවේශ වීමට හෝ වෙනස් කිරීමට අවබෝධය දක්වන ක්‍රම ලබා නොදේ. මෙම ප්‍රවේශක හා වෙනස්කාරක ක්‍රම බොහෝමයක් අහෝසි කර ඇත.
• කාල කලාප සැකසීම සහ ලීප් වර්ෂ ගණනය කිරීම අවබෝධය දක්වන නොවන අතර, ජාත්‍යන්තරීකරණය කටයුතු කර ගැනීමට අපහසුය.
• එය ත්‍රෙඩ්-ආරක්ෂිත නොවන බැවින්, බහු-ථ්‍රෙඩ් පරිසරවල අනපේක්ෂිත හැසිරීමක් සිදුවිය හැක.

Java දිනය සහ වේලාව API ගූඩු සමාලෝචනය

Java දිනය සහ වේලාව API ගූඩු විශාල වශයෙන් ත්‍රිත්ව පරම්පරාවලියකට වර්ගීකරණය කළ හැක:

1. පරණ API ගූඩු java.util.Date (Date වර්ගය) java.util.Calendar (Calendar වර්ගය) මෙම පන්තීන් Java හි මුල් දිනවල සිට පවති ඇත.
2. නව API ගූඩු (Java 8 සහ පසු) java.time පැකේජය LocalDate, LocalTime, LocalDateTime, ZonedDateTime වැනි පන්තීන් මෙම API ගූඩු අස්ථානික නොවන, ත්‍රෙඩ්-ආරක්ෂිත, සහ කාල කලාප සහය සමඟ නිර්මාණය කර ඇත.
3. අතිරේක සහ SQL-සම්බන්ධ API ගූඩු java.sql.Date සහ java.sql.Timestamp වැනි වර්ගයන් ප්‍රධාන වශයෙන් දත්ත ගබඩා ඒකාබද්ධ කිරීම සඳහා භාවිතා වේ.

වාස්තුක ලෝක ව්‍යාපෘතිවල සාමාන්‍යයෙන් භාවිතා වන API ගූඩු

• Date සහ Calendar පිළිබඳ දැනුම පවත්නා පද්ධති සහ පරණ කේත පදනම් රැක ගැනීමට අත්‍යවශ්‍ය වේ.
• නව සංවර්ධනය සහ නව පද්ධති සඳහා, java.time පැකේජය දැන් ප්‍රමිතිය තේරීම වේ.

Date සහ වේලාව සැකසීම සුළු දෝෂවල සාමාන්‍ය මූලාශ්‍රයකි. පසුගිය කොටස්වල, අපි එක් එක් API ගූඩු විස්තරාත්මකව පරීක්ෂා කර, ඒවායේ ලක්ෂණ සසඳා, ප්‍රායෝගික උදාහරණ සමඟ නිවැරදි භාවිතය පෙන්වන්නෙමු.

3. Date වර්ගය භාවිතා කිරීම (පරණ API)

java.util.Date පන්තිය Java හි පැරණිතම API ගූඩු අතරින් එකක් වන අතර, දිනයන් සහ වේලාවන් නියෝජනය කිරීම සඳහා දිගු කාලයක් භාවිතා කර ඇත. අදත්, එය වාස්තුක ලෝක ව්‍යාපෘතිවල බොහෝවිට හමුවේ. මෙම කොටස Date වර්ගයේ මූලික භාවිතය පැහැදිලි කර, අවධානයෙන් බැලිය යුතු වැදගත් කරුණු උදෙසා අවධාරණය කරයි.

3-1. වත්මන් දිනය සහ වේලාව ලබා ගැනීම සහ පෙන්වීම

To obtain the current date and time using the Date type, simply create a new instance:

Date now = new Date();
System.out.println(now);

The default output is displayed in English and includes a format and time zone that are often difficult to interpret. As a result, this raw output is rarely used directly in production systems. To display dates in a specific format or language, SimpleDateFormat is typically used, as described later.

3-2. මූලික Date ක්‍රම (ප්‍රාප්තිය, සංශෝධනය, සංසන්දනය)

The java.util.Date class provides methods for accessing and modifying individual date and time fields, but many of them are deprecated. Examples include:

• getYear()
• setMonth()
• getDate()
• setHours()
• getMinutes() , etc.

The use of these methods is not recommended in modern Java development.

However, comparison methods are still commonly used:

• before(Date when) : මෙම දිනය නියමිත දිනයට පෙරදැයි පරීක්ෂා කරයි
• after(Date when) : මෙම දිනය නියමිත දිනයට පසුදැයි පරීක්ෂා කරයි
• compareTo(Date anotherDate) : දිනයන් දෙකක් කාලානුකූලව සැසඳේ

උදාහරණය:

Date date1 = new Date();
Date date2 = new Date(System.currentTimeMillis() + 1000); // 1 second later

if (date1.before(date2)) {
    System.out.println("date1 is before date2");
}

3-3. දිනය ආකෘතිකරණය (SimpleDateFormat භාවිතා කරමින්)

To display dates in a custom format such as YYYY/MM/DD or July 10, 2025, use the SimpleDateFormat class.

SimpleDateFormat sdf = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss");
String str = sdf.format(now);
System.out.println(str); // Example: 2025/07/10 09:15:20

සාමාන්‍ය ආකෘති සංකේත:

• yyyy : වසර (අංක 4 ක්)
• MM : මාසය (අංක 2 ක්)
• dd : මාසයේ දිනය (අංක 2 ක්)
• HH : පැය (24-පැය ආකෘතිය)
• mm : මිනිත්තුව
• ss : තත්පරය

සටහන: SimpleDateFormat තන්තුව-ආරක්ෂිත නොවේ. බහු-තන්තුව පරිසරවල, සෑම භාවිතයකටම නව උදාහරණයක් සෑදීම අත්‍යවශ්‍ය වේ.

3-4. Strings සහ Date වස්තු අතර පරිවර්තනය

SimpleDateFormat is also used to convert between strings and Date objects.

String dateStr = "2025/07/10 09:00:00";
Date parsed = sdf.parse(dateStr);

String formatted = sdf.format(parsed);

Be sure to handle ParseException appropriately.

3-5. Date වර්ගයේ අඩුපාඩු සහ අයෝජිත ක්‍රම

Although the Date type appears simple, it has several pitfalls:

• Many methods for accessing or modifying year and month values are deprecated, reducing long-term maintainability
• Time zone handling is not intuitive, often causing confusion between local time and UTC
• Thread-safety issues, including those related to SimpleDateFormat
• Date arithmetic and end-of-month calculations require additional care

For these reasons, the modern java.time API is strongly recommended for new development. ඇත්තාත්, Date තවමත් පවතින පද්ධති සහ තෙවන පාර්ශව පුස්තකාලවල පුළුල් ලෙස භාවිතා වන බැවින්, සංවර්ධකයන් එහි මූලික භාවිතය සහ සීමා ගැන දැනුවත් විය යුතුය.

4. Calendar සහ Date එකතු කිරීම

Another major legacy API for date and time manipulation in Java is the java.util.Calendar class. Calendar was introduced to address limitations of the Date type, particularly for date arithmetic and field-based calculations. This section explains how Calendar works together with Date and highlights practical usage patterns.

Calendar සමඟ දිනය ගණනය (එකතු කිරීම, අඩු කිරීම, මාස අවසාන)

The Date type stores only a millisecond value and is not well suited for date calculations. Calendar provides a more intuitive way to perform such operations.

උදාහරණය: අද සිට සතියක් (7 දින) පසු දිනය ලබා ගැනීම

Calendar cal = Calendar.getInstance(); // initialized with current date and time
cal.add(Calendar.DATE, 7);             // add 7 days
Date future = cal.getTime();           // convert to Date
System.out.println(future);

උදාහරණය: වත්මන් මාසයේ අවසන් දිනය ලබා ගැනීම

Calendar cal = Calendar.getInstance();
cal.set(Calendar.DAY_OF_MONTH, cal.getActualMaximum(Calendar.DAY_OF_MONTH));
Date endOfMonth = cal.getTime();
System.out.println(endOfMonth);

දිනදර්ශන සහ දිනය අතර පරිවර්තනය

දිනදර්ශන සහ දිනය වස්තු අතර ආපසු-ආපසු පරිවර්තනය කළ හැක:

• Calendar#getTime() : දිනදර්ශන → දිනය
• Calendar#setTime(Date date) : දිනය → දිනදර්ශන

දිනය දිනදර්ශනයට පරිවර්තනය කිරීම

Date date = new Date();
Calendar cal = Calendar.getInstance();
cal.setTime(date);

දිනදර්ශනය දිනයට පරිවර්තනය කිරීම

Date converted = cal.getTime();

මෙය දත්ත ගබඩා හෝ බාහිර API වලින් ලැබෙන දිනයේ අගයන් දිනදර්ශනය භාවිතා කරමින් සවිස්තරාත්මකව සැකසීමට ඉඩ සලසයි.

ප්‍රායෝගික භාවිතය සම්බන්ධ සලකුණු

• දිනදර්ශනය එකතු කිරීම සහ අඩු කිරීම සඳහා පමණක් නොව, සතියේ දින, මාස සීමා සහ අනෙකුත් දිනදර්ශන-සම්බන්ධ ගණනය කිරීම් තීරණය කිරීමටද ප්‍රයෝජනවත් වේ.
• එහෙත්, දිනදර්ශනය වෙනස් කළ හැකි සහ ත්‍රෙඩ්-ආරක්ෂිත නොවන වස්තුවකි. බහු ත්‍රෙඩ් අතර උදාහරණ බෙදා ගැනීමෙන් වැළකින්න.
• නවීන යෙදුම් සඳහා, Java 8 හි හඳුන්වා දුන් java.time පැකේජය ආරක්ෂිත සහ ශක්තිමත් විකල්ප ලබා දේ. දිනදර්ශනය දැන් ප්‍රධාන වශයෙන් පරණ සමඟ අනුකූලතාව සඳහා භාවිතා වේ.

දිනදර්ශනය සහ දිනය පිළිබඳ අවබෝධය පරණ Java ව්‍යාපෘති නඩත්තු කිරීම සඳහා තවමත් වැදගත් වේ. මෙම මූලික කරුණු පාලනය කිරීමෙන් සංවර්ධකයන්ට වාස්තු විශාල පරාසයක වාස්තු-සත්‍ය පද්ධති වලට සවිස්තරාත්මකව ප්‍රතිචාර දැක්වීමට හැකියාව ලැබේ.

5. Java 8 සහ පසුකාලීනව හඳුන්වා දුන් නව API (java.time පැකේජය)

Java 8 සිට, දිනයන් සහ වේලාවන් කළමනාකරණය සඳහා නව ප්‍රමිතී API එකක් හඳුන්වා දුන්: java.time පැකේජය. මෙම API Date සහ Calendar හි අඩුපාඩු මූලිකව විසඳීමට නිර්මාණය කර ඇත, සහ නව Java සංවර්ධනය සඳහා ප්‍රායෝගික ප්‍රමිතිය බවට පත්ව ඇත. මෙම කොටස නව API එකේ සමස්ත ව්‍යුහය, ප්‍රධාන ලක්ෂණ, සහ පරණ API සමඟ එය කෙසේ වෙනස් වේද යන්න පැහැදිලි කරයි.

5-1. නව API එකේ පසුබැසි සහ වාසි

සාම්ප්‍රදායික Date සහ Calendar API ගණනාවක් පළපුරුදු ගැටළු වලින් පීඩිත වූවා:

• වෙනස් කළ හැකි නිර්මාණය : අගයන් අනිසි ලෙස වෙනස් විය හැක
• ත‍්‍රෙඩ් ආරක්ෂාව නොමැතිකම : බහු-ත‍්‍රෙඩ් පරිසරවල අසුරක්ෂිත හැසිරීම
• කාලකලාප සැකසීමේ සංකීර්ණතාව : ජාත්‍යන්තරීකරණය සහ DST සහය ලබා ගැනීම දුෂ්කර

java.time පැකේජය මෙම ගැටළු විසඳීමට සහ දිනය සහ වේලාව කළමනාකරණය සඳහා ආරක්ෂිත, වඩාත් ප්‍රකාශක, සහ ප්‍රායෝගික ආකාරයක් ලබා දීමට නිර්මාණය කර ඇත. එහි ප්‍රධාන වාසි මෙසේය:

• අවලංගු නොකළ හැකි නිර්මාණය (වස්තු වෙනස් කළ නොහැක)
• සම්පූර්ණ ත‍්‍රෙඩ්-ආරක්ෂිත
• කාලකලාප සහ දිනදර්ශන පද්ධති සඳහා ශක්තිමත් සහය
• පෙළපත්-විශේෂිත පන්තීන් භාවිතා කරමින් පැහැදිලි සහ අවබෝධය සලසන API නිර්මාණය

5-2. මූලික පන්තීන් සහ ඒවායේ භාවිතය

නව API විවිධ භාවිතයන් සඳහා විශේෂිත පන්තීන් ලබා දේ. සාමාන්‍යයෙන් භාවිතා වන පන්තීන් පහත දැක්වේ.

LocalDate, LocalTime, LocalDateTime

• LocalDate : දිනය පමණක් (උදා., 2025-07-10)
• LocalTime : වේලාව පමණක් (උදා., 09:30:00)
• LocalDateTime : කාලකලාප නොමැති දිනය සහ වේලාව (උදා., 2025-07-10T09:30:00)

උදාහරණය: වත්මන් දිනය සහ වේලාව ලබා ගැනීම

LocalDate date = LocalDate.now();
LocalTime time = LocalTime.now();
LocalDateTime dateTime = LocalDateTime.now();

System.out.println(date);
System.out.println(time);
System.out.println(dateTime);

උදාහරණය: දිනය ගණිතය

LocalDate future = date.plusDays(7);
LocalDate past = date.minusMonths(1);

ZonedDateTime සහ Instant

• ZonedDateTime : කාලකලාප තොරතුරු සමඟ දිනය සහ වේලාව
• Instant : UNIX epoch සිට තත්පර සහ නැනෝතත්පර නියෝජනය කරන කාල-මොහොතක්

උදාහරණය: කාලකලාප සමඟ වත්මන් දිනය සහ වේලාව

ZonedDateTime zoned = ZonedDateTime.now();
System.out.println(zoned);

උදාහරණය: epoch-අධාරිත කාල-මොහොතක් ලබා ගැනීම

Instant instant = Instant.now();
System.out.println(instant);

DateTimeFormatter සමඟ ආකෘතිකරණය

The new API uses DateTimeFormatter for formatting and parsing dates and times. This class is thread-safe and designed for modern applications.

DateTimeFormatter fmt = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
String str = dateTime.format(fmt);
System.out.println(str);

5-3. පරණ API සමඟ අන්තර්ක්‍රියාකාරීත්වය

පවත්නා පද්ධති හෝ බාහිර පුස්තකාල සමඟ වැඩ කරන විට, පරණ API සහ නව java.time වර්ග අතර පරිවර්තනය කිරීම අවශ්‍ය විය හැක.

උදාහරණය: Date → Instant → LocalDateTime පරිවර්තනය

Date oldDate = new Date();
Instant instant = oldDate.toInstant();
LocalDateTime ldt = LocalDateTime.ofInstant(instant, ZoneId.systemDefault());

උදාහරණය: LocalDateTime → Date පරිවර්තනය

ZonedDateTime zdt = ldt.atZone(ZoneId.systemDefault());
Date newDate = Date.from(zdt.toInstant());

නව API එක සුරක්ෂිතතාව, නඩත්තු කිරීමේ පහසුව, සහ පැහැදිලිත්වය වැනි වැදගත් වාසි ලබා දේ. නව සංවර්ධනය සඳහා පමණක් නොව, පවත්නා කේත පදනම් නැවත සැකසීමේදීද මෙය දැඩි ලෙස නිර්දේශ කරයි.

6. සාමාන්‍ය වාස්තුක ලෝකයේ වැරදි සහ දෝෂ අවස්ථා

දිනයන් සහ වේලාවන් හසුරවන වැඩසටහන් මුලින්ම සරල ලෙස පෙනේ, නමුත් වාස්තුක පරිසරයන්හි ඒවා සුළු දෝෂ සහ නිෂ්පාදන ගැටළු වල සාමාන්‍ය මූලාශ්‍ර වේ. ජාවා භාෂාවේ, Date, Calendar, හෝ නව API භාවිතා කරන විට, සංවර්ධකයන් මුහුණ දෙන නැවත නැවත සිදුවන වැරදි කිහිපයක් ඇත. මෙම කොටස සාමාන්‍ය අසාර්ථක රටා සහ ප්‍රායෝගික ප්‍රතිකාර හඳුන්වා දෙයි.

පැහැදිලි වින්‍යාසය නොමැතිව ඇති වේලා කලාප අසමතුලිතතා

ඉතා සාමාන්‍ය ගැටළුව වේලා කලාප සම්බන්ධ වේ. Date, Calendar, සහ LocalDateTime පන්තීන් පද්ධතියේ පෙරනිමි වේලා කලාප භාවිතා කරයි, ඔබ පැහැදිලිව එකක් සඳහන් නොකළහොත්. එබැවින්, සේවාදායක සහ ගනුදෙනුකරු පරිසරයන් අතර වෙනස්කම් අනපේක්ෂිත ධාරිතාවයන් සහ අසමතුලිතතා ඇති කරයි.

ප්‍රතිකාර:

• සේවාදායක, යෙදුම්, සහ දත්ත ගබඩා අතර වේලා කලාප පැහැදිලිව සම්මත කිරීම
• වේලා කලාප සැකසීම පැහැදිලි කිරීම සඳහා ZonedDateTime හෝ Instant භාවිතා කරන්න

SimpleDateFormat සමඟ තාරක-ආරක්ෂිත ගැටළු

SimpleDateFormat තාරක-ආරක්ෂිත නොවේ. වෙබ් යෙදුම් හෝ බැච් රැකවරණයන්හි එක් උදාහරණයක් ත්‍රෙඩ් අතර බෙදා ගන්නා විට, මෙය අනපේක්ෂිත විග්‍රහ දෝෂ හෝ විකෘති ප්‍රතිඵල ඇති කරයි.

ප්‍රතිකාර:

• භාවිතා කරන සෑම අවස්ථාවකටම නව SimpleDateFormat උදාහරණයක් සාදන්න
• නව API එකේ තාරක-ආරක්ෂිත DateTimeFormatter භාවිතා කිරීම ප්‍රාථමික කරගන්න

ලීප් වසර සහ මාස අවසාන ගණනයේ අඩුපාඩු

ෆෙබ්‍රවාරි 29 හෝ මාස අවසාන සීමා සම්බන්ධ ගණනයන් තවත් සාමාන්‍ය දෝෂ මූලාශ්‍ර වේ. Date හෝ Calendar වැරදි ලෙස භාවිතා කරන විට, සංවර්ධකයන් ලීප්-වසර තර්කය අමතක කරනු ඇත.

උදාහරණය:

Calendar cal = Calendar.getInstance();
cal.set(2024, Calendar.FEBRUARY, 28); // leap year
cal.add(Calendar.DATE, 1);
System.out.println(cal.getTime()); // Results in 2024-02-29 (correct)

එයට විරුද්ධව, LocalDate වැනි නව API පද්ධති ස්වයංක්‍රීයව සහ නිවැරදිව ලීප් වසර සහ මාස සීමා හසුරවයි.

මයික්‍රොසෙකන්ඩ් සහ නැනෝසෙකන්ඩ් නිරවද්‍යතාව අවශ්‍යතා

පරණ Date සහ Calendar API පමණක් මිලිසෙකන්ඩ් නිරවද්‍යතාවය ලබා දෙයි. මූල්‍ය ගනුදෙනු හෝ ඉහළ නිරවද්‍ය ලොග් කිරීම වැනි අවශ්‍යතා සඳහා මෙම නිරවද්‍යතාවය ප්‍රමාණවත් නොවිය හැක.

එවැනි අවස්ථාවල, නව API ඉහළ-විභේදන කාල නිරවද්‍යතා ලබා දෙයි.

උදාහරණය:

Instant instant = Instant.now();
long nano = instant.getNano(); // nanosecond precision

වෙනත් සාමාන්‍ය ගැටළු: ආකෘතිකරණ දෝෂ සහ ජාත්‍යන්තරීකරණය

• ආකෘති සංකේතයන් ගැලපීම (උදාහරණයක් ලෙස, මාස සඳහා MM සහ මිනිත්තුව සඳහා mm අතර ගැලපීම)
• ප්‍රදේශය (locale) සඳහන් නොකිරීම, ප්‍රදේශවලට අනුව වැරදි ප්‍රතිඵල ලබා දීම
• දින-කාල සුරක්ෂිත කිරීම (DST) මාරුකාලීනවල අනපේක්ෂිත හැසිරීම

සාරාංශය

To safely handle dates and times in Java, it is essential to understand these real-world failure patterns in advance. Choosing the correct API and designing robust test cases from the outset is key to maintaining stable and reliable systems.

7. ඉක්මන් සැසඳීම: පරණ API ගණ vs නව API ගණ

When handling dates and times in Java, developers often face the decision of whether to use legacy APIs (Date and Calendar) or the modern java.time package. The following table summarizes their key differences.

පරණ API භාවිතා කළ යුතු අවස්ථා

• පවත්නා පද්ධති හෝ පරණ කේත පදනම් රැක ගැනීම
• Date හෝ Calendar අවශ්‍ය කරන තෙවන පාර්ශව පුස්තකාල සමඟ අන්තර්ක්‍රියා කිරීම

නව API භාවිතා කළ යුතු අවස්ථා

• නව සංවර්ධන ව්‍යාපෘති
• වේලා කලාප අවබෝධය හෝ ජාත්‍යන්තරීකරණය අවශ්‍ය වන යෙදුම්
• සංකීර්ණ දිනය සහ වේලාව ගණනයන් හෝ උසස් නිරවද්‍යතාව

සටහන: API අතර සම්බන්ධ කිරීම

Legacy and modern APIs can coexist through conversion methods such as Date ⇔ Instant and Calendar ⇔ ZonedDateTime. This allows developers to modernize systems incrementally while maintaining compatibility.

Each generation of Java’s date and time APIs has distinct characteristics. Selecting the appropriate API based on system requirements and long-term maintainability is critical for successful development.

8. දිනය සහ වේලාව හසුරවීම සඳහා හොඳම ක්‍රියාමාර්ග

When working with dates and times in Java, achieving stable and reliable systems requires not only choosing the right API, but also following practical design and coding best practices. This section summarizes key guidelines that should be observed in real-world projects.

නව සංවර්ධනය සඳහා නව API (java.time) භාවිතා කරන්න

• ඔබ Java 8 හෝ ඊට පසු භාවිතා කරන්නේ නම්, සෑම විටම java.time පැකේජය ප්‍රමුඛ කරගන්න .
• එය පරණ API වලට වඩා උසස් ආරක්ෂාව, කියවීමට පහසුව, සහ රැකවරණය ලබා දේ.

පරණ API සමඟ අන්තර්ක්‍රියා කිරීමේදී අවධානම්

• පරණ පද්ධති හෝ බාහිර පුස්තකාලයන් තවම Date හෝ Calendar අවශ්‍ය විය හැක.
• එවැනි අවස්ථාවල, පරිවර්තන ක්‍රම (උදා: Date ⇔ Instant, Calendar ⇔ ZonedDateTime) භාවිතා කර API අතර ආරක්ෂිත සම්බන්ධතාවක් සකසන්න.
• පරණ වස්තු නව වර්ග වෙත ඉක්මනින් පරිවර්තනය කර, අවශ්‍ය නම් පමණක් පසුපසට පරිවර්තනය කරන්න.

වේලා කලාප සහ ප්‍රදේශයන් සදහා සෑම විටම පැහැදිලිව නියම කරන්න

• LocalDateTime සහ SimpleDateFormat වැනි පන්තීන්, වේලා කලාප සහ ප්‍රදේශයන් පැහැදිලිව නියම නොකළහොත්, ක්‍රියාත්මක පරිසරය අනුව වෙනස් හැසිරෙයි.
• වේලා වෙනස්කම් හෝ දින-කාලය වෙනස් කිරීම (Daylight Saving Time) ඇතුළත් යෙදුම් සඳහා ZoneId, ZonedDateTime භාවිතා කර, Locale පැහැදිලිව නියම කරන්න.

දිනය සහ වේලාව ආකෘති සැලසුම් කිරීමේදී අවධානයෙන් සිටින්න

• DateTimeFormatter ත්‍රෙඩ්-ආරක්ෂිත이며 බහු-තන්තුව පරිසර සඳහා සුදුසුය.
• ආකෘති සංකේත (උදා: මාසය සඳහා MM vs මිනිත්තුව සඳහා mm) ගැලපීමෙන් වැළකී සිටින්න.
• ආකෘති පද්ධති අතර බෙදාගන්නා විට, ඒවා ස්ථිරයන් ලෙස නියම කරන්න ώστε සමගාමීතාව සහ රැකවරණය තහවුරු කරයි.

සවිස්තරාත්මක පරීක්ෂණ කේස් සකසන්න

• අධිවර්ෂ, මාස සීමා, දින-කාලය වෙනස් කිරීමේ පරිවර්තන, වේලා කලාප අස්ථාන, සහ අතිශය අගයන් (උදා: 1970 epoch, 2038 වසරේ ගැටලුව) සාමාන්‍ය දෝෂ මූලාශ්‍ර වේ.
• ඒකක සහ ඒකාබද්ධ පරීක්ෂණ දෙකම සීමා තත්ත්ව සහ අග්‍රාන්‍ය අවස්ථා ආවරණය කරන්න.

නිල ලේඛන සහ විශ්වාසනීය මූලාශ්‍ර භාවිතා කරන්න

• නිල Java API ලේඛන සහ නිකුත් සටහන් නිතර සමාලෝචනය කරන්න.
• දිනය සහ වේලාව දෝෂයන් සුක්ෂ්ම විස්තර හෝ අනුවාද වෙනස්කම් නිසා සිදුවේ.

සාරාංශය

Date and time handling is often underestimated, but it is one of the most error-prone areas in software development. By following best practices and prioritizing modern APIs, you can build systems that are safe, accurate, and easy to maintain.

9. අනෙකුත් භාෂා (Python, JavaScript) සමඟ වෙනස්කම්

Java හි දිනය සහ වේලාව කළමනාකරණය කිරීමේ ආකාරය Python සහ JavaScript වැනි අනෙකුත් ප්‍රධාන වැඩසටහන් භාෂා වලින් ගැඹුරු ලෙස වෙනස් වේ. මෙම වෙනස්කම් තේරුම් ගැනීම, පද්ධති ඒකාබද්ධ කිරීමේදී හෝ සංවර්ධකයන් වෙනත් භාෂා වලින් Java වෙත මාරු වන විට අත්‍යවශ්‍ය වේ.

Python සමඟ සංසන්දනය

Python හි, දිනය සහ වේලාව කළමනාකරණය ප්‍රධාන වශයෙන් ප්‍රමිතිය datetime මොඩියුලය භාවිතා කර සිදු කරයි.

• සමහර Python datetime වස්තු mutable objects ලෙස හැසිරේ, Java හි අස්ථිර (immutable) නව API වලට වඩා වෙනස් වේ.
• දිනය ආකෘතිකරණය සහ විග්‍රහය C‑ශෛලී ආකෘතිකරණ නියමයන් (strftime() සහ strptime()) භාවිතා කරයි.
• වේලා කලාප (time zone) කළමනාකරණය සංකීර්ණ විය හැකි අතර, සාමාන්‍යයෙන් pytz හෝ zoneinfo වැනි අතිරේක පුස්තකාල අවශ්‍ය වේ.

ප්‍රධාන සැලකිල්ල:

Java හි java.time API අස්ථිර (immutable) සහ ත්‍රෙඩ්-ආරක්ෂිත (thread‑safe) වේ. Java සහ Python අතර දිනය දත්ත හුවමාරු කරන විට වේලා කලාප තොරතුරු සහ 문자열 ආකෘතිකරණයේ සමතුලිතතාව පිළිබඳව අවධානයෙන් සිටින්න.

JavaScript සමඟ සංසන්දනය

JavaScript හි, Date වස්තුව දිනය සහ වේලාව කළමනාකරණය සඳහා මූලික යන්ත්‍රය වේ.

• අභ්‍යන්තරයෙන්, JavaScript Date 1970-01-01 00:00:00 UTC සිට මිලිසෙකන්ඩ් ගණන සුරකිති, Java හි පරණ Date සමඟ සමාන වේ.
• එහෙත්, JavaScript හි කිහිපයක් අසාමාන්‍ය හැසිරීම් ඇත, උදාහරණයක් ලෙස ශූන්‍ය-අධාරිත මාස (zero‑based months) සහ ස්ථානීය වේලාව හා UTC එකට මිශ්‍රව භාවිතා කිරීම.
• දිනය ආකෘතිකරණය බොහෝ විට toLocaleDateString() වැනි ප්‍රාදේශීය-නිර্ভර ක්‍රම මත පදනම් වේ, එය Java සමඟ වඩාත් නිරවද්‍ය පාලනය ලබා දීමට අඩු වේ.

ප්‍රධාන සැලකිල්ල:

Java සහ JavaScript අතර දිනයන් පරිවර්තනය කරන විට, අගයන් UTC හෝ ස්ථානීය වේලාව නියෝජනය කරන්නේදැයි සදහටම පැහැදිලි කර, ISO 8601 වැනි ප්‍රමිතීකරණ ආකෘති භාවිතා කරන්න.

බහු‑භාෂා ඒකාබද්ධ කිරීමේ දෝෂ

• Java අස්ථිරත්වය, දැඩි වර්ගීකරණය, සහ පැහැදිලි වේලා කලාප කළමනාකරණය මත අවධානය යොදයි.
• අනෙකුත් භාෂා අඩු දැඩි හෝ වඩා ලච්චනීය හැසිරීම් ඉඩ දී, දත්ත හුවමාරු කිරීමේදී අසමතුලිතතා ඇති වීමට අවදානම වැඩි කරයි.

ප්‍රායෝගික ඒකාබද්ධ කිරීමේ උපදෙස්

• පොදු හුවමාරු ආකෘතියක් ලෙස UNIX ටයිම්ස්ටැම්ප් හෝ ISO 8601 문자열 (උදා: 2025-07-10T09:00:00Z) භාවිතා කරන්න.
• ටයිම්ස්ටැම්ප්ස් UTC නියෝජනය කරන්නේද නැතහොත් ස්ථානීය වේලාවද යන්න ලේඛනය කරන්න.

Java හි දැඩි නීති සහ අනෙකුත් භාෂා වල ලච්චනීයත්වය අතර සන්තුලනය තේරුම් ගැනීම, ආරක්ෂිත සහ පුරෝකථනීය පද්ධති ඒකාබද්ධ කිරීම සඳහා අත්‍යවශ්‍ය වේ.

10. නිතර අසන ප්‍රශ්න (FAQ)

Q1. java.util.Date තවමත් භාවිතා කළ යුතුද?

නව සංවර්ධනය සහ දිගුකාලීන නඩත්තු සඳහා java.time API හොඳම තේරීමයි. එNevertheless, පරණ පද්ධති හෝ තෙවන පාර්ශව පුස්තකාල සමඟ අනුකූලතාවය සඳහා Date සහ Calendar තවමත් අවශ්‍ය විය හැක. එවැනි අවස්ථාවල, හැකි ඉක්මනින් නව API වෙත පරිවර්තනය කරන්න.

Q2. SimpleDateFormat භාවිතා කිරීමේ ආරක්ෂිත ක්‍රමය කුමක්ද?

SimpleDateFormat ත්‍රෙඩ්-ආරක්ෂිත නොවේ. බහු‑ත‍්‍රෙඩ් පරිසරයන්හි, භාවිතා කිරීමේදී නව උදාහරණයක් සාදන්න හෝ ThreadLocal මඟින් උදාහරණ කළමනාකරණය කරන්න. හැකි තරම්, ත්‍රෙඩ්‑ආරක්ෂිත DateTimeFormatter භාවිතා කරන්න.

Q3. වේලා කලාප වෙනස්කම් කෙසේ හසුරවන්නේද?

සෑම විටම වේලා කලාපය පැහැදිලිව සඳහන් කරන්න. ZonedDateTime, ZoneId, සහ DateTimeFormatter.withZone() භාවිතා කර දිනය සහ වේලාව කෙසේ අර්ථ දක්වයි සහ පෙන්වයි යන්න පැහැදිලිව නියම කරන්න.

Q4. පරණ API සහ නව API අතර පරිවර්තන අත්‍යවශ්‍යද?

ඔව්. පරණ සහ නව API වර්ග වෙනස් වන බැවින්, ඒවා එකට පවතින විට පරිවර්තන අවශ්‍ය වේ. සාමාන්‍ය රටාවන් වන්නේ Date → Instant → LocalDateTime සහ Calendar → ZonedDateTime වැනි පරිවර්තන වේ.

Q5. සංවර්ධකයන් Date/Calendar සහ java.time අතර කෙසේ තේරීම කළ යුතුද?

සාමාන්‍ය නීතිය:

• නව සංවර්ධනය → java.time
• පරණ අනුකූලතාව → Date/Calendar සමඟ පරිවර්තනය

Q6. UNIX ටයිම්ස්ටැම්ප් Java හි කෙසේ හසුරවයි?

Java Instant සහ Date#getTime() වැනි ක්‍රම මඟින් UNIX ටයිම්ස්ටැම්ප් (UNIX epoch සිට මිලිසෙකන්ඩ්) පහසුවෙන් ලබා ගත හැක.

Q7. අර්ධරෑය හෝ මාස අවසානය වැනි දිනය සීමා (date boundaries) සම්බන්ධයෙන් කුමන කරුණු සැලකිල්ලට ගත යුතුද?

Boundary values such as midnight, end-of-month dates, and daylight saving transitions are common sources of bugs. Always include them in test cases and be aware of API-specific behaviors.

11. අවසාන සාරාංශය

Date and time handling in Java may appear straightforward, but in real-world systems it requires careful design and attention to detail. This article has covered legacy APIs, modern alternatives, real-world pitfalls, cross-language differences, and best practices.

ප්‍රධාන සාරාංශ

• පරණ API (Date/Calendar) ප්‍රධාන වශයෙන් අනුකූලතාව සඳහා වේ. නව සංවර්ධනය සඳහා, නව java.time API දැඩි ලෙස නිර්දේශ කරයි.
• නව API අස්ථිර නොවන (immutable) සහ තන්තුව-ආරක්ෂිත (thread-safe) වේ, වේලා කලාප සහ ජාත්‍යන්තරීකරණයට ශක්තිමත් සහාය ලබා දේ.
• බොහෝ සැබෑ ලෝක බග්‌වල වේලා කලාප, අධිවර්ෂ, මාස සීමා, දින ආලෝක සුරක්ෂිත පරිවර්තන, සහ තන්තුව-ආරක්ෂිත ගැටළු වලින් උද्भව වේ.
• අනෙකුත් භාෂා හෝ බාහිර පද්ධති සමඟ ඒකාබද්ධ කිරීමේදී, දත්ත වර්ග, වේලා කලාප, සහ 문자열 ආකෘති පිළිබඳ අවධානයෙන් සිටින්න.

ඉක්මන් තීරණ මාර්ගෝපදේශය

• නව ව්‍යාපෘති → java.time
• පවත්නා පද්ධති → කාර්යක්ෂම පරිවර්තනය සමඟ පරණ API
• සෑම විටම වේලා කලාප සහ ආකෘති පැහැදිලිව සඳහන් කරන්න

ඉදිරියට බලන විදිහ

විශ්වාසදායක දිනය සහ වේලාව කළමනාකරණය යනු සියලු පරිසර සහ අවශ්‍යතා තුළ නිවැරදි හැසිරීම සහතික කිරීමයි—කේතය “ක්‍රියාත්මක” කිරීම පමණක් නොව. ඔබේ දැනුම නිතර නවීකරණය කිරීම, නිල ලේඛන පරීක්ෂා කිරීම, සහ සම්පූර්ණ පරීක්ෂණ ආවරණය රැක ගැනීම මඟින්, ඔබට ශක්තිමත් සහ අනාගත-ආරක්ෂිත Java පද්ධති ගොඩනැගිය හැක.

මෙම ලිපිය ඔබට ආරක්ෂිත, වඩා විශ්වාසදායක Java යෙදුම් නිර්මාණය සහ ක්‍රියාත්මත් කිරීමේදී උපකාරී වේයි කියා අපි බලාපොරොත්තු වෙමු.