docs(datetime-api): explain advantages of java.time over legacy Date/Calendar

What
- Added documentation outlining problems with legacy APIs (`java.util.Date`, `java.util.Calendar`) and how `java.time` solves them.
- Highlighted key issues with old APIs:
  - Mutability → not thread-safe.
  - Poor design (e.g., months starting at 0).
  - Ambiguous and misleading method names.
  - Weak, error-prone time zone handling.
- Explained Java 8+ improvements:
  - Immutable, thread-safe classes.
  - Clear separation of concerns (`LocalDate`, `LocalTime`, `LocalDateTime`, `ZonedDateTime`).
  - Powerful formatting & parsing via `DateTimeFormatter`.
  - Inspired by Joda-Time library.
- Provided detailed notes on core classes:
  - `LocalDate` → only date.
  - `LocalTime` → only time.
  - `LocalDateTime` → date + time (no zone).
  - Emphasis on immutability and return of new instances for modifications.
- Added Old vs New API comparison:
  - `Date` mutable vs `LocalDate` immutable.
  - Deprecated setters vs fluent methods (`plusDays`, `minusMonths`, `withYear`).

Why
- To help developers migrate from legacy APIs to modern `java.time`.
- Clarifies pitfalls of using `Date`/`Calendar` in multi-threaded environments.
- Shows clear benefits in readability, maintainability, and safety with new API.

How to use
- Prefer `java.time` classes for all new development.
- Use `LocalDate`/`LocalTime`/`LocalDateTime` for date & time handling.
- Use `ZonedDateTime` for timezone-aware applications.
- Use `Period` for date differences and `Duration` for time differences.

Real-life applications
- Safer handling of financial transactions with immutable timestamps.
- Accurate time zone conversions for global applications.
- Cleaner and more readable APIs for UIs, reporting, and scheduling systems.
- Thread-safe logging and auditing with precise timestamps.

Notes
- Legacy `Date` and `Calendar` still exist for backward compatibility.
- For new projects, always prefer `java.time` package.
- `java.time` classes integrate well with JDBC, JSON APIs, and frameworks like Spring.

Signed-off-by: https://github.com/Someshdiwan <[email protected]>

Author: Someshdiwan

Section26DateandTimeAPI/Time/src/Why New Date-Time API.txt

@@ -0,0 +1,66 @@
+Why New Date-Time API (java.time)?
+
+1. Problems with Old API (java.util.Date, java.util.Calendar):
+   - Mutable: `Date` and `Calendar` objects can be modified → not thread-safe.
+   - Poor Design: Months start from 0 (January = 0), causing confusion.
+   - Ambiguous: `java.util.Date` stores both date & time, but names like `getYear()`, `getMonth()` are misleading.
+   - Time Zone Issues: Very limited and error-prone handling of zones.
+   - Not Immutable: Harder to use in multi-threaded apps safely.
+
+2. Java 8 Date-Time API Advantages:
+   - Immutable → Once created, cannot be changed (thread-safe).
+   - Clear separation of concerns:
+     ✔ `LocalDate` → Date only (no time).
+     ✔ `LocalTime` → Time only (no date).
+     ✔ `LocalDateTime` → Date + Time (no zone).
+     ✔ `ZonedDateTime` → Date + Time + Zone.
+   - Better formatting and parsing with `DateTimeFormatter`.
+   - Inspired by the popular Joda-Time library.
+
+=========================
+Core Classes
+=========================
+
+1. LocalDate:
+   - Represents only a calendar date (year, month, day).
+   - Example: `LocalDate today = LocalDate.now();`
+   - Immutable → You cannot change the date directly.
+   - Instead, use methods like:
+     - `plusDays(5)`, `minusMonths(2)`, `withYear(2020)` → returns new objects.
+
+2. LocalTime:
+   - Represents only the time (hour, minute, second, nanosecond).
+   - Example: `LocalTime now = LocalTime.now();`
+   - No date, no time zone.
+
+3. LocalDateTime:
+   - Represents date + time, down to nanoseconds.
+   - Example: `LocalDateTime dt = LocalDateTime.now();`
+   - Useful for timestamps without zones.
+   - Still immutable → all modifications return new instances.
+
+=========================
+Old API vs New API
+=========================
+
+Old (java.util.Date):
+----------------------
+Date d = new Date();
+// Stores date-time internally as milliseconds since 1 Jan 1970 (epoch).
+
+✔ Can modify:
+   d.setTime(1234567890L);
+   d.setYear(2025);  // Deprecated, mutable, error-prone.
+
+New (java.time):
+----------------------
+LocalDate date = LocalDate.now();
+LocalDate newDate = date.plusDays(5); // Creates a NEW object, original unchanged.
+
+✔ Immutable and thread-safe.
+✔ Easier to read, maintain, and extend.
+
+✔ Old API (`Date`, `Calendar`) → mutable, buggy, confusing.
+✔ New API (`LocalDate`, `LocalTime`, `LocalDateTime`) → immutable, clean, safe.
+✔ Separation of Date, Time, and DateTime = better clarity.
+✔ Use `Period` (date-based) or `Duration` (time-based) for differences.