// ❌ Legacy (avoid)
Date date = new Date();
Calendar cal = Calendar.getInstance();
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");

// ✅ Modern
Instant instant = Instant.now();
ZonedDateTime zdt = ZonedDateTime.now();
DateTimeFormatter formatter = DateTimeFormatter.ISO_INSTANT;

Instant now = Instant.now();
System.out.println(now); // 2025-06-14T10:00:00Z

// Converting to different representations
ZonedDateTime utcZoned = now.atZone(ZoneOffset.UTC);
OffsetDateTime utcOffset = now.atOffset(ZoneOffset.UTC);

ZoneId dublin = ZoneId.of("Europe/Dublin");
ZoneId newYork = ZoneId.of("America/New_York");
ZoneId tokyo = ZoneId.of("Asia/Tokyo");

ZonedDateTime dublinTime = ZonedDateTime.now(dublin);

ZoneOffset plus5 = ZoneOffset.of("+05:00");
ZoneOffset minus8 = ZoneOffset.ofHours(-8);

OffsetDateTime offsetTime = OffsetDateTime.now(plus5);

ZoneId systemDefault = ZoneId.systemDefault();
// ⚠️ Can change between JVM restarts or deployments

// Get all available timezone IDs
Set<String> allZones = ZoneId.getAvailableZoneIds();

// Convert between timezones
ZonedDateTime londonTime = ZonedDateTime.now(ZoneId.of("Europe/London"));
ZonedDateTime tokyoTime = londonTime.withZoneSame(ZoneId.of("Asia/Tokyo"));

// Check if timezone uses DST
ZoneId zoneId = ZoneId.of("America/New_York");
boolean usesDST = zoneId.getRules().isDaylightSavings(Instant.now());

// This time doesn't exist in many timezones
ZonedDateTime springForward = ZonedDateTime.of(
    2025, 3, 30, 2, 30, 0, 0, 
    ZoneId.of("Europe/Dublin")
);
// Java resolves this to 03:30 (skips the gap)

// This time exists twice in many timezones
ZonedDateTime fallBack = ZonedDateTime.of(
    2025, 10, 26, 2, 30, 0, 0, 
    ZoneId.of("Europe/Dublin")
);
// Java uses the first occurrence by default

public class DSTHandler {
    
    // Safe DST transition handling
    public static ZonedDateTime handleTransition(LocalDateTime localDateTime, ZoneId zone) {
        try {
            return ZonedDateTime.of(localDateTime, zone);
        } catch (DateTimeException e) {
            // Handle gap or overlap
            return localDateTime.atZone(zone).withEarlierOffsetAtOverlap();
        }
    }
    
    // Check for DST transitions
    public static boolean isInDSTTransition(ZonedDateTime dateTime) {
        ZoneRules rules = dateTime.getZone().getRules();
        return rules.getTransition(dateTime.toLocalDateTime()) != null;
    }
}

// Checking historical timezone rules
ZonedDateTime historical = ZonedDateTime.of(2010, 6, 15, 12, 0, 0, 0, ZoneId.of("Europe/Moscow"));
ZonedDateTime recent = ZonedDateTime.of(2020, 6, 15, 12, 0, 0, 0, ZoneId.of("Europe/Moscow"));

// These will have different offset behaviors due to rule changes

// Various ISO 8601 formats
"2025-06-14T10:00:00Z"           // Basic with Z
"2025-06-14T10:00:00+01:00"     // With offset
"2025-06-14T10:00:00.123Z"      // With milliseconds
"2025-06-14T10:00:00,123Z"      // Comma decimal separator (European)
"20250614T100000Z"              // Compact format
"2025-W24-6T10:00:00Z"          // Week date
"2025-165T10:00:00Z"            // Ordinal date

DateTimeFormatter RFC_3339 = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX");

OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC);
String rfc3339 = now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);

public class TimeFormatters {
    
    // Common business formats
    public static final DateTimeFormatter BUSINESS_DATE = 
        DateTimeFormatter.ofPattern("MM/dd/yyyy");
    
    public static final DateTimeFormatter LOG_TIMESTAMP = 
        DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");
    
    public static final DateTimeFormatter USER_FRIENDLY = 
        DateTimeFormatter.ofPattern("EEEE, MMMM d, yyyy 'at' h:mm a");
    
    // Locale-specific formatting
    public static String formatForLocale(ZonedDateTime dateTime, Locale locale) {
        return dateTime.format(
            DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM)
                           .withLocale(locale)
        );
    }
}

// ✅ Store as UTC timestamp with separate timezone
public class EventEntity {
    @Column(name = "created_at")
    private Instant createdAt;
    
    @Column(name = "user_timezone")
    private String userTimezone;
    
    // Convert for display
    public ZonedDateTime getCreatedAtInUserTimezone() {
        return createdAt.atZone(ZoneId.of(userTimezone));
    }
}

// application.properties
spring.jpa.properties.hibernate.jdbc.time_zone=UTC

// Entity mapping
@Entity
public class Event {
    @Column(columnDefinition = "TIMESTAMP")
    private Instant timestamp;
    
    @Column(columnDefinition = "VARCHAR(50)")
    private String timezone;
}

// PostgreSQL entity with timezone-aware column
@Entity
@Table(name = "events")
public class PostgreSQLEvent {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    // Maps to PostgreSQL TIMESTAMPTZ
    @Column(name = "event_timestamp", columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime eventTimestamp;
    
    // Alternative: Use ZonedDateTime
    @Column(name = "scheduled_at", columnDefinition = "TIMESTAMPTZ")
    private ZonedDateTime scheduledAt;
}

-- PostgreSQL table definition
CREATE TABLE events (
    id BIGSERIAL PRIMARY KEY,
    event_timestamp TIMESTAMPTZ NOT NULL,
    scheduled_at TIMESTAMPTZ,
    description TEXT
);

// MySQL 8.0+ with timezone support
@Entity
@Table(name = "mysql_events")
public class MySQLEvent {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    // MySQL TIMESTAMP (UTC normalized, timezone-aware)
    @Column(name = "created_at", columnDefinition = "TIMESTAMP")
    private Instant createdAt;
    
    // MySQL DATETIME (can store timezone offset in application)
    @Column(name = "event_time", columnDefinition = "DATETIME(6)")
    private LocalDateTime eventTime;
    
    @Column(name = "event_timezone", length = 50)
    private String eventTimezone;
}

// Oracle timezone-aware storage
@Entity
@Table(name = "oracle_events")
public class OracleEvent {
    
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    private Long id;
    
    // Oracle TIMESTAMP WITH TIME ZONE
    @Column(name = "event_timestamp", columnDefinition = "TIMESTAMP WITH TIME ZONE")
    private OffsetDateTime eventTimestamp;
    
    // Oracle TIMESTAMP WITH LOCAL TIME ZONE
    @Column(name = "local_timestamp", columnDefinition = "TIMESTAMP WITH LOCAL TIME ZONE")
    private ZonedDateTime localTimestamp;
}

@Service
public class ExternalTimestampProcessor {
    
    private static final Logger log = LoggerFactory.getLogger(ExternalTimestampProcessor.class);
    
    /**
     * Process external timestamp that includes timezone information
     * and store it preserving the original timezone context
     */
    public EventEntity processExternalTimestamp(String externalTimestamp, String sourceSystem) {
        try {
            // Parse the external timestamp (could be ISO 8601, RFC 3339, or custom format)
            OffsetDateTime parsedTimestamp = parseExternalTimestamp(externalTimestamp, sourceSystem);
            
            // Create entity preserving timezone information
            EventEntity event = new EventEntity();
            
            // Option 1: Store as UTC + timezone (traditional approach)
            event.setCreatedAt(parsedTimestamp.toInstant());
            event.setOriginalTimezone(parsedTimestamp.getOffset().getId());
            
            // Option 2: Store with timezone information intact (if using TIMESTAMPTZ)
            event.setEventTimestamp(parsedTimestamp);
            
            // Store metadata about the source
            event.setSourceSystem(sourceSystem);
            event.setOriginalTimestampString(externalTimestamp);
            
            log.info("Processed external timestamp: {} from {} -> {} UTC", 
                    externalTimestamp, sourceSystem, parsedTimestamp.toInstant());
            
            return event;
            
        } catch (DateTimeParseException e) {
            log.error("Failed to parse external timestamp: {} from system: {}", 
                     externalTimestamp, sourceSystem, e);
            throw new TimestampProcessingException("Invalid timestamp format", e);
        }
    }
    
    /**
     * Parse external timestamps with fallback strategies
     */
    private OffsetDateTime parseExternalTimestamp(String timestamp, String sourceSystem) {
        // System-specific parsing strategies
        List<DateTimeFormatter> formatters = getFormattersForSystem(sourceSystem);
        
        for (DateTimeFormatter formatter : formatters) {
            try {
                return OffsetDateTime.parse(timestamp, formatter);
            } catch (DateTimeParseException e) {
                // Try next formatter
            }
        }
        
        // Last resort: try common formats
        return parseWithCommonFormats(timestamp);
    }
    
    private List<DateTimeFormatter> getFormattersForSystem(String sourceSystem) {
        Map<String, List<DateTimeFormatter>> systemFormatters = Map.of(
            "SYSTEM_A", List.of(
                DateTimeFormatter.ISO_OFFSET_DATE_TIME,
                DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss XXX")
            ),
            "SYSTEM_B", List.of(
                DateTimeFormatter.RFC_1123_DATE_TIME,
                DateTimeFormatter.ofPattern("MM/dd/yyyy HH:mm:ss Z")
            ),
            "DEFAULT", List.of(
                DateTimeFormatter.ISO_OFFSET_DATE_TIME,
                DateTimeFormatter.ISO_ZONED_DATE_TIME,
                DateTimeFormatter.RFC_1123_DATE_TIME
            )
        );
        
        return systemFormatters.getOrDefault(sourceSystem, systemFormatters.get("DEFAULT"));
    }
    
    private OffsetDateTime parseWithCommonFormats(String timestamp) {
        DateTimeFormatter[] commonFormats = {
            DateTimeFormatter.ISO_OFFSET_DATE_TIME,
            DateTimeFormatter.ISO_ZONED_DATE_TIME,
            DateTimeFormatter.RFC_1123_DATE_TIME,
            DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss XXX"),
            DateTimeFormatter.ofPattern("MM/dd/yyyy HH:mm:ss Z")
        };
        
        for (DateTimeFormatter formatter : commonFormats) {
            try {
                return OffsetDateTime.parse(timestamp, formatter);
            } catch (DateTimeParseException e) {
                // Continue to next format
            }
        }
        
        throw new DateTimeParseException("Unable to parse timestamp with any known format", timestamp, 0);
    }
}

@Entity
@Table(name = "external_events")
public class ExternalEventEntity {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    // Store the processed timestamp with timezone (PostgreSQL TIMESTAMPTZ)
    @Column(name = "event_timestamp", columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime eventTimestamp;
    
    // Store the original timezone for reference
    @Column(name = "original_timezone", length = 50)
    private String originalTimezone;
    
    // Store the raw timestamp for auditing
    @Column(name = "original_timestamp_string", length = 100)
    private String originalTimestampString;
    
    // Source system information
    @Column(name = "source_system", length = 50)
    private String sourceSystem;
    
    // Processing metadata
    @Column(name = "processed_at", columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime processedAt;
    
    // Constructors, getters, setters...
    
    /**
     * Get the event time in a specific timezone
     */
    public ZonedDateTime getEventTimeInTimezone(ZoneId targetZone) {
        return eventTimestamp.atZoneSameInstant(targetZone);
    }
    
    /**
     * Get the event time in the original timezone
     */
    public ZonedDateTime getEventTimeInOriginalTimezone() {
        if (originalTimezone != null) {
            try {
                ZoneId originalZone = ZoneId.of(originalTimezone);
                return eventTimestamp.atZoneSameInstant(originalZone);
            } catch (DateTimeException e) {
                // Fallback to offset if zone ID is invalid
                return eventTimestamp.toZonedDateTime();
            }
        }
        return eventTimestamp.toZonedDateTime();
    }
}

@Repository
public interface ExternalEventRepository extends JpaRepository<ExternalEventEntity, Long> {
    
    // Find events in a specific time range (timezone-aware)
    @Query("SELECT e FROM ExternalEventEntity e WHERE e.eventTimestamp BETWEEN :start AND :end")
    List<ExternalEventEntity> findEventsInRange(
        @Param("start") OffsetDateTime start,
        @Param("end") OffsetDateTime end
    );
    
    // Find events by source system and time range
    @Query("SELECT e FROM ExternalEventEntity e WHERE e.sourceSystem = :system " +
           "AND e.eventTimestamp >= :start AND e.eventTimestamp < :end")
    List<ExternalEventEntity> findEventsBySystemInRange(
        @Param("system") String system,
        @Param("start") OffsetDateTime start,
        @Param("end") OffsetDateTime end
    );
    
    // Native query for PostgreSQL timezone conversion
    @Query(value = "SELECT * FROM external_events WHERE " +
                   "event_timestamp AT TIME ZONE :timezone BETWEEN :startLocal AND :endLocal",
           nativeQuery = true)
    List<ExternalEventEntity> findEventsInLocalTimeRange(
        @Param("timezone") String timezone,
        @Param("startLocal") String startLocal,
        @Param("endLocal") String endLocal
    );
}

-- PostgreSQL timezone handling
SET timezone = 'UTC';  -- Set session timezone

-- Query with timezone conversion
SELECT 
    event_timestamp,
    event_timestamp AT TIME ZONE 'America/New_York' as ny_time,
    event_timestamp AT TIME ZONE 'Europe/London' as london_time
FROM external_events
WHERE event_timestamp AT TIME ZONE 'UTC' BETWEEN '2025-06-14 00:00:00' AND '2025-06-15 00:00:00';

-- Index on timestamptz column
CREATE INDEX idx_events_timestamp ON external_events USING btree (event_timestamp);

-- MySQL timezone configuration
SET time_zone = '+00:00';  -- Use UTC

-- Store timezone-aware data
INSERT INTO mysql_events (created_at, event_timezone) 
VALUES (UTC_TIMESTAMP(), 'America/New_York');

-- Query with timezone conversion
SELECT 
    created_at,
    CONVERT_TZ(created_at, '+00:00', '-05:00') as eastern_time
FROM mysql_events;

@Component
public class TimezoneAwareMigration {
    
    @Autowired
    private JdbcTemplate jdbcTemplate;
    
    /**
     * Migrate existing UTC timestamps to timezone-aware format
     */
    @Transactional
    public void migrateToTimezoneAware() {
        String sql = """
            UPDATE events 
            SET event_timestamp = created_at AT TIME ZONE 'UTC' AT TIME ZONE user_timezone
            WHERE event_timestamp IS NULL AND created_at IS NOT NULL AND user_timezone IS NOT NULL
        """;
        
        int updated = jdbcTemplate.update(sql);
        log.info("Migrated {} records to timezone-aware format", updated);
    }
    
    /**
     * Backfill timezone information for existing records
     */
    public void backfillTimezoneInfo(Map<String, String> userTimezones) {
        String sql = "UPDATE events SET user_timezone = ? WHERE user_id = ? AND user_timezone IS NULL";
        
        userTimezones.forEach((userId, timezone) -> {
            jdbcTemplate.update(sql, timezone, userId);
        });
    }
}

// ❌ Storing LocalDateTime without timezone info
@Entity
public class BadEvent {
    private LocalDateTime eventTime; // Ambiguous! What timezone?
}

// ❌ Losing timezone information
@Entity  
public class AlsoBadEvent {
    private Instant timestamp;  // UTC only, original timezone lost
}

// ✅ Preserving timezone information with database support
@Entity
public class GoodTimezoneAwareEvent {
    @Column(columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime eventTimestamp;  // Preserves timezone
    
    @Column(length = 50)
    private String sourceSystem;  // For traceability
}

// ✅ Hybrid approach for maximum compatibility
@Entity
public class FlexibleEvent {
    private Instant utcTimestamp;        // For calculations and sorting
    
    @Column(columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime originalTimestamp;  // Preserves user context
    
    private String originalTimezone;     // For display and user experience
}

@DataJpaTest
public class TimezoneAwareDatabaseTest {
    
    @Autowired
    private ExternalEventRepository repository;
    
    @Test
    public void testStoringAndRetrievingTimezoneAwareTimestamps() {
        // Create test data with different timezones
        OffsetDateTime nyTime = OffsetDateTime.of(2025, 6, 14, 10, 0, 0, 0, ZoneOffset.of("-04:00"));
        OffsetDateTime londonTime = OffsetDateTime.of(2025, 6, 14, 15, 0, 0, 0, ZoneOffset.of("+01:00"));
        
        ExternalEventEntity nyEvent = new ExternalEventEntity();
        nyEvent.setEventTimestamp(nyTime);
        nyEvent.setSourceSystem("NY_SYSTEM");
        
        ExternalEventEntity londonEvent = new ExternalEventEntity();
        londonEvent.setEventTimestamp(londonTime);
        londonEvent.setSourceSystem("LONDON_SYSTEM");
        
        // Save events
        repository.save(nyEvent);
        repository.save(londonEvent);
        
        // Verify they represent the same instant in UTC
        List<ExternalEventEntity> events = repository.findAll();
        assertEquals(2, events.size());
        
        Instant nyInstant = events.get(0).getEventTimestamp().toInstant();
        Instant londonInstant = events.get(1).getEventTimestamp().toInstant();
        
        // They should be the same instant (14:00 UTC)
        assertEquals(nyInstant, londonInstant);
        
        // But preserve original timezone information
        assertNotEquals(events.get(0).getEventTimestamp().getOffset(), 
                       events.get(1).getEventTimestamp().getOffset());
    }
}

---

## 🌐 7. Web API Best Practices

### REST API Recommendations

```java
@RestController
public class EventController {
    
    // ✅ Accept ISO 8601 with timezone
    @PostMapping("/events")
    public ResponseEntity<Event> createEvent(@RequestBody CreateEventRequest request) {
        // Parse with timezone information
        ZonedDateTime eventTime = ZonedDateTime.parse(request.getEventTime());
        
        // Store as UTC
        Event event = new Event();
        event.setTimestamp(eventTime.toInstant());
        event.setTimezone(eventTime.getZone().getId());
        
        return ResponseEntity.ok(eventService.save(event));
    }
    
    // ✅ Return ISO 8601 format
    @GetMapping("/events/{id}")
    public ResponseEntity<EventResponse> getEvent(@PathVariable Long id, 
                                                  @RequestParam(required = false) String timezone) {
        Event event = eventService.findById(id);
        
        ZoneId displayZone = timezone != null ? 
            ZoneId.of(timezone) : ZoneId.of(event.getTimezone());
            
        EventResponse response = new EventResponse();
        response.setEventTime(event.getTimestamp().atZone(displayZone)
                                 .format(DateTimeFormatter.ISO_OFFSET_DATE_TIME));
        
        return ResponseEntity.ok(response);
    }
}

// Jackson configuration
@JsonFormat(shape = JsonFormat.Shape.STRING)
private Instant timestamp;

// Custom serializer
public class InstantSerializer extends JsonSerializer<Instant> {
    @Override
    public void serialize(Instant instant, JsonGenerator gen, SerializerProvider serializers) 
            throws IOException {
        gen.writeString(instant.toString()); // ISO format
    }
}

public class TimeService {
    private final Clock clock;
    
    public TimeService(Clock clock) {
        this.clock = clock;
    }
    
    public Instant getCurrentTime() {
        return Instant.now(clock);
    }
}

// In tests
@Test
public void testTimeBasedLogic() {
    Clock fixedClock = Clock.fixed(
        Instant.parse("2025-06-14T10:00:00Z"), 
        ZoneOffset.UTC
    );
    
    TimeService service = new TimeService(fixedClock);
    
    // Test with predictable time
    Instant result = service.getCurrentTime();
    assertEquals(Instant.parse("2025-06-14T10:00:00Z"), result);
}

@Test
public void testDSTTransitions() {
    ZoneId dublin = ZoneId.of("Europe/Dublin");
    
    // Test spring forward
    LocalDateTime beforeSpring = LocalDateTime.of(2025, 3, 30, 1, 0);
    LocalDateTime duringSpring = LocalDateTime.of(2025, 3, 30, 2, 0);
    LocalDateTime afterSpring = LocalDateTime.of(2025, 3, 30, 3, 0);
    
    ZonedDateTime before = beforeSpring.atZone(dublin);
    ZonedDateTime during = duringSpring.atZone(dublin); // This gets adjusted
    ZonedDateTime after = afterSpring.atZone(dublin);
    
    // Verify the gap is handled correctly
    assertNotEquals(2, during.getHour()); // Should be 3, not 2
}

// ❌ Expensive: Creating formatters repeatedly
public String formatTime(Instant instant) {
    DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
    return instant.atZone(ZoneOffset.UTC).format(formatter);
}

// ✅ Efficient: Reuse formatters (they're thread-safe)
private static final DateTimeFormatter TIMESTAMP_FORMATTER = 
    DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

public String formatTime(Instant instant) {
    return instant.atZone(ZoneOffset.UTC).format(TIMESTAMP_FORMATTER);
}

public class TimezoneCache {
    private static final Map<String, ZoneId> ZONE_CACHE = new ConcurrentHashMap<>();
    
    public static ZoneId getZoneId(String zoneIdString) {
        return ZONE_CACHE.computeIfAbsent(zoneIdString, ZoneId::of);
    }
}

// ❌ Ambiguous - what timezone?
@RestController
public class BadController {
    @GetMapping("/now")
    public LocalDateTime getNow() {
        return LocalDateTime.now(); // Which timezone?
    }
}

// ✅ Explicit timezone information
@RestController
public class GoodController {
    @GetMapping("/now")
    public OffsetDateTime getNow() {
        return OffsetDateTime.now(ZoneOffset.UTC);
    }
}

// ❌ Using offset when you need timezone rules
OffsetDateTime meeting = OffsetDateTime.of(2025, 7, 15, 14, 0, 0, 0, ZoneOffset.of("+01:00"));
// This won't adjust for DST changes!

// ✅ Using proper timezone
ZonedDateTime meeting = ZonedDateTime.of(2025, 7, 15, 14, 0, 0, 0, ZoneId.of("Europe/Paris"));
// This will handle DST correctly

// ❌ Depends on server configuration
ZonedDateTime serverTime = ZonedDateTime.now(); // Uses system default

// ✅ Explicit timezone
ZonedDateTime utcTime = ZonedDateTime.now(ZoneOffset.UTC);
ZonedDateTime userTime = ZonedDateTime.now(ZoneId.of(userTimezone));

// ❌ Can throw uncaught exceptions
public ZonedDateTime parseDateTime(String input) {
    return ZonedDateTime.parse(input);
}

// ✅ Proper error handling
public Optional<ZonedDateTime> parseDateTime(String input) {
    try {
        return Optional.of(ZonedDateTime.parse(input));
    } catch (DateTimeParseException e) {
        log.warn("Failed to parse datetime: {}", input, e);
        return Optional.empty();
    }
}

public class TimeConversions {
    
    // Instant ↔ ZonedDateTime
    public static ZonedDateTime instantToZoned(Instant instant, ZoneId zone) {
        return instant.atZone(zone);
    }
    
    public static Instant zonedToInstant(ZonedDateTime zoned) {
        return zoned.toInstant();
    }
    
    // Legacy Date ↔ Modern API
    public static Instant dateToInstant(Date date) {
        return date.toInstant();
    }
    
    public static Date instantToDate(Instant instant) {
        return Date.from(instant);
    }
    
    // Epoch milliseconds ↔ Instant
    public static Instant epochMillisToInstant(long epochMillis) {
        return Instant.ofEpochMilli(epochMillis);
    }
    
    public static long instantToEpochMillis(Instant instant) {
        return instant.toEpochMilli();
    }
    
    // String parsing with fallbacks
    public static Optional<Instant> parseFlexible(String timeString) {
        DateTimeFormatter[] formatters = {
            DateTimeFormatter.ISO_INSTANT,
            DateTimeFormatter.ISO_OFFSET_DATE_TIME,
            DateTimeFormatter.ISO_LOCAL_DATE_TIME
        };
        
        for (DateTimeFormatter formatter : formatters) {
            try {
                return Optional.of(Instant.from(formatter.parse(timeString)));
            } catch (DateTimeParseException ignored) {
                // Try next formatter
            }
        }
        return Optional.empty();
    }
}

public class TimeCalculations {
    
    // Calculate business days between dates
    public static long businessDaysBetween(LocalDate start, LocalDate end) {
        return start.datesUntil(end)
                   .filter(date -> !isWeekend(date))
                   .count();
    }
    
    private static boolean isWeekend(LocalDate date) {
        DayOfWeek day = date.getDayOfWeek();
        return day == DayOfWeek.SATURDAY || day == DayOfWeek.SUNDAY;
    }
    
    // Age calculation
    public static Period calculateAge(LocalDate birthDate, LocalDate currentDate) {
        return Period.between(birthDate, currentDate);
    }
    
    // Time until/since
    public static Duration timeUntil(Instant target) {
        return Duration.between(Instant.now(), target);
    }
    
    // Human-readable duration
    public static String formatDuration(Duration duration) {
        long hours = duration.toHours();
        long minutes = duration.toMinutesPart();
        long seconds = duration.toSecondsPart();
        
        return String.format("%02d:%02d:%02d", hours, minutes, seconds);
    }
}

public class InternationalTimeFormatter {
    
    public static String formatForUser(ZonedDateTime dateTime, Locale locale, ZoneId userZone) {
        ZonedDateTime userTime = dateTime.withZoneSameInstant(userZone);
        
        DateTimeFormatter formatter = DateTimeFormatter
            .ofLocalizedDateTime(FormatStyle.MEDIUM)
            .withLocale(locale);
            
        return userTime.format(formatter);
    }
    
    // Different calendar systems
    public static String formatInCalendarSystem(ZonedDateTime dateTime, String calendarSystem) {
        Chronology chronology = Chronology.of(calendarSystem);
        ChronoZonedDateTime<?> chronoDateTime = dateTime.toInstant().atZone(dateTime.getZone()).chronology(chronology);
        
        return chronoDateTime.toString();
    }
}

public class TimezoneDisplayHelper {
    
    public static String getDisplayName(ZoneId zoneId, Locale locale) {
        return zoneId.getDisplayName(TextStyle.FULL, locale);
    }
    
    public static Map<String, String> getAllTimezoneDisplayNames(Locale locale) {
        return ZoneId.getAvailableZoneIds().stream()
            .collect(Collectors.toMap(
                zoneId -> zoneId,
                zoneId -> ZoneId.of(zoneId).getDisplayName(TextStyle.FULL, locale)
            ));
    }
}

# Set system timezone
-Duser.timezone=UTC

# Timezone data directory
-Djava.time.zone.DefaultZoneRulesProvider=com.example.CustomZoneRulesProvider

# Spring Boot timezone configuration
spring.jackson.time-zone=UTC
spring.jackson.date-format=yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

# Logging timestamps in UTC
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss.SSS UTC} [%thread] %-5level %logger{36} - %msg%n

# Set container timezone
ENV TZ=UTC
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# Or use UTC everywhere (recommended)
ENV TZ=UTC

@Component
public class TimeAwareLogger {
    private static final Logger log = LoggerFactory.getLogger(TimeAwareLogger.class);
    
    public void logWithTimestamp(String message, Object... args) {
        String timestamp = Instant.now().toString();
        log.info("[{}] {}", timestamp, String.format(message, args));
    }
    
    public void logTimezoneInfo() {
        log.info("System default timezone: {}", ZoneId.systemDefault());
        log.info("Current UTC time: {}", Instant.now());
        log.info("JVM timezone data version: {}", getTimezoneDataVersion());
    }
    
    private String getTimezoneDataVersion() {
        // This is implementation-specific
        return System.getProperty("java.time.zone.DefaultZoneRulesProvider", "built-in");
    }
}

@Component
public class TimeMetrics {
    
    private final MeterRegistry meterRegistry;
    
    public TimeMetrics(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }
    
    public void recordTimezoneConversion(String fromZone, String toZone) {
        Timer.Sample sample = Timer.start(meterRegistry);
        // ... perform conversion ...
        sample.stop(Timer.builder("timezone.conversion")
                        .tag("from", fromZone)
                        .tag("to", toZone)
                        .register(meterRegistry));
    }
    
    public void recordDSTTransition(String timezone) {
        meterRegistry.counter("dst.transitions", "timezone", timezone).increment();
    }
}

public class TimeDebuggingHelper {
    
    // Debug timezone information
    public static void debugTimezone(ZoneId zoneId) {
        System.out.println("Zone ID: " + zoneId);
        System.out.println("Rules: " + zoneId.getRules());
        
        Instant now = Instant.now();
        ZonedDateTime zdt = now.atZone(zoneId);
        
        System.out.println("Current offset: " + zdt.getOffset());
        System.out.println("Is DST: " + zoneId.getRules().isDaylightSavings(now));
        
        // Show next transition
        ZoneOffsetTransition nextTransition = zoneId.getRules().nextTransition(now);
        if (nextTransition != null) {
            System.out.println("Next transition: " + nextTransition);
        }
    }
    
    // Debug parsing issues
    public static void debugParsing(String input) {
        DateTimeFormatter[] formatters = {
            DateTimeFormatter.ISO_INSTANT,
            DateTimeFormatter.ISO_OFFSET_DATE_TIME,
            DateTimeFormatter.ISO_LOCAL_DATE_TIME,
            DateTimeFormatter.RFC_1123_DATE_TIME
        };
        
        for (DateTimeFormatter formatter : formatters) {
            try {
                TemporalAccessor parsed = formatter.parse(input);
                System.out.println("Successfully parsed with " + formatter + ": " + parsed);
                return;
            } catch (DateTimeParseException e) {
                System.out.println("Failed with " + formatter + ": " + e.getMessage());
            }
        }
    }
}

public class TimeBasedSecurity {
    
    private static final Duration TOKEN_VALIDITY = Duration.ofHours(1);
    private static final Duration CLOCK_SKEW_TOLERANCE = Duration.ofMinutes(5);
    
    // Secure timestamp validation
    public boolean isTimestampValid(Instant timestamp) {
        Instant now = Instant.now();
        Instant earliest = now.minus(CLOCK_SKEW_TOLERANCE);
        Instant latest = now.plus(CLOCK_SKEW_TOLERANCE);
        
        return !timestamp.isBefore(earliest) && !timestamp.isAfter(latest);
    }
    
    // Token expiration with clock skew
    public boolean isTokenExpired(Instant tokenCreated) {
        Instant expiry = tokenCreated.plus(TOKEN_VALIDITY);
        Instant now = Instant.now();
        
        // Add small tolerance for clock skew
        return now.isAfter(expiry.plus(CLOCK_SKEW_TOLERANCE));
    }
    
    // Prevent timing attacks in comparison
    public boolean constantTimeEquals(Instant a, Instant b) {
        long aEpoch = a.getEpochSecond();
        long bEpoch = b.getEpochSecond();
        
        // Use constant-time comparison
        return MessageDigest.isEqual(
            Long.toString(aEpoch).getBytes(),
            Long.toString(bEpoch).getBytes()
        );
    }
}

// Working with different calendar systems
public class ChronologyExample {
    
    public static void demonstrateChronologies() {
        LocalDate gregorianDate = LocalDate.of(2025, 6, 14);
        
        // Convert to Islamic calendar
        HijrahDate hijrahDate = HijrahDate.from(gregorianDate);
        System.out.println("Hijrah date: " + hijrahDate);
        
        // Convert to Japanese calendar
        JapaneseDate japaneseDate = JapaneseDate.from(gregorianDate);
        System.out.println("Japanese date: " + japaneseDate);
        
        // Convert to Thai Buddhist calendar
        ThaiBuddhistDate thaiDate = ThaiBuddhistDate.from(gregorianDate);
        System.out.println("Thai Buddhist date: " + thaiDate);
    }
}

public class CustomTemporalAdjusters {
    
    // Next business day
    public static final TemporalAdjuster NEXT_BUSINESS_DAY = temporal -> {
        LocalDate date = LocalDate.from(temporal);
        do {
            date = date.plusDays(1);
        } while (isWeekend(date));
        return temporal.with(date);
    };
    
    // Last day of quarter
    public static final TemporalAdjuster LAST_DAY_OF_QUARTER = temporal -> {
        LocalDate date = LocalDate.from(temporal);
        int month = ((date.getMonthValue() - 1) / 3 + 1) * 3;
        return date.withMonth(month).with(TemporalAdjusters.lastDayOfMonth());
    };
    
    private static boolean isWeekend(LocalDate date) {
        DayOfWeek day = date.getDayOfWeek();
        return day == DayOfWeek.SATURDAY || day == DayOfWeek.SUNDAY;
    }
}

public class LegacyMigrationHelper {
    
    // Date to Instant
    public static Instant dateToInstant(Date date) {
        return date != null ? date.toInstant() : null;
    }
    
    // Calendar to ZonedDateTime
    public static ZonedDateTime calendarToZonedDateTime(Calendar calendar) {
        if (calendar == null) return null;
        return ZonedDateTime.ofInstant(calendar.toInstant(), calendar.getTimeZone().toZoneId());
    }
    
    // Timestamp to Instant
    public static Instant timestampToInstant(Timestamp timestamp) {
        return timestamp != null ? timestamp.toInstant() : null;
    }
    
    // Legacy timezone handling
    public static ZoneId timeZoneToZoneId(TimeZone timeZone) {
        return timeZone != null ? timeZone.toZoneId() : ZoneOffset.UTC;
    }
    
    // Batch migration utility
    public static <T> List<T> migrateDateFields(List<T> entities, 
                                               Function<T, Date> getter,
                                               BiConsumer<T, Instant> setter) {
        return entities.stream()
                      .peek(entity -> {
                          Date date = getter.apply(entity);
                          if (date != null) {
                              setter.accept(entity, date.toInstant());
                          }
                      })
                      .collect(Collectors.toList());
    }
}

@Component
public class GradualMigrationService {
    
    private final boolean useModernTimeApi = true; // Feature flag
    
    public String formatTimestamp(Object timestamp) {
        if (useModernTimeApi && timestamp instanceof Instant) {
            return ((Instant) timestamp).toString();
        } else if (timestamp instanceof Date) {
            return new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'").format(timestamp);
        }
        throw new IllegalArgumentException("Unsupported timestamp type");
    }
    
    public Object parseTimestamp(String input) {
        if (useModernTimeApi) {
            return Instant.parse(input);
        } else {
            try {
                return new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'").parse(input);
            } catch (ParseException e) {
                throw new RuntimeException(e);
            }
        }
    }
}

// ❌ Anti-pattern
public class BadTimeHandler {
    public String getCurrentTime() {
        return LocalDateTime.now().toString(); // What timezone?
    }
}

// ✅ Fixed
public class GoodTimeHandler {
    public String getCurrentTimeUTC() {
        return Instant.now().toString();
    }
    
    public String getCurrentTimeInZone(ZoneId zone) {
        return ZonedDateTime.now(zone).toString();
    }
}

// ❌ Anti-pattern
public List<String> formatTimes(List<Instant> times) {
    return times.stream()
                .map(time -> {
                    DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
                    return time.atZone(ZoneOffset.UTC).format(formatter);
                })
                .collect(Collectors.toList());
}

// ✅ Fixed
public class TimeFormatter {
    private static final DateTimeFormatter FORMATTER = 
        DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
    
    public List<String> formatTimes(List<Instant> times) {
        return times.stream()
                    .map(time -> time.atZone(ZoneOffset.UTC).format(FORMATTER))
                    .collect(Collectors.toList());
    }
}

// ❌ Anti-pattern
public class BadScheduler {
    public LocalDateTime scheduleDaily(LocalDateTime start) {
        return start.plusDays(1); // Doesn't account for DST!
    }
}

// ✅ Fixed
public class GoodScheduler {
    public ZonedDateTime scheduleDaily(ZonedDateTime start) {
        return start.plusDays(1); // Handles DST transitions correctly
    }
}

// Custom metrics for timezone operations
@Component
public class TimeMetrics {
    private final Counter timezoneConversions;
    private final Timer parseTimer;
    
    public TimeMetrics(MeterRegistry registry) {
        this.timezoneConversions = Counter.builder("timezone.conversions")
            .description("Number of timezone conversions performed")
            .register(registry);
            
        this.parseTimer = Timer.builder("timestamp.parse")
            .description("Time taken to parse timestamps")
            .register(registry);
    }
    
    public OffsetDateTime parseWithMetrics(String input) {
        Timer.Sample sample = Timer.start();
        try {
            OffsetDateTime result = OffsetDateTime.parse(input);
            timezoneConversions.increment();
            return result;
        } finally {
            sample.stop(parseTimer);
        }
    }
}

// Timezone debugging utility
public class TimezoneDebugger {
    
    public static void printSystemInfo() {
        System.out.println("=== Timezone Debug Info ===");
        System.out.println("System Default Zone: " + ZoneId.systemDefault());
        System.out.println("UTC Now: " + Instant.now());
        System.out.println("System Now: " + ZonedDateTime.now());
        System.out.println("Available Zones: " + ZoneId.getAvailableZoneIds().size());
        
        // Check for common problematic zones
        String[] problematicZones = {"America/New_York", "Europe/London", "Asia/Shanghai"};
        for (String zoneId : problematicZones) {
            ZonedDateTime zdt = ZonedDateTime.now(ZoneId.of(zoneId));
            System.out.printf("%s: %s (offset: %s, DST: %s)%n", 
                zoneId, zdt, zdt.getOffset(), 
                zdt.getZone().getRules().isDaylightSavings(zdt.toInstant()));
        }
    }
}