Java's Duration and Period classes provide powerful tools for working with time-based quantities. They represent two different concepts of time measurement and are essential for modern Java date/time operations.
Understanding Duration vs Period
- Duration: Measures time in seconds and nanoseconds, suitable for machine-based time
- Period: Measures time in years, months, and days, suitable for human-based time
Basic Usage Examples
Example 1: Creating Durations and Periods
import java.time.Duration;
import java.time.Period;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.temporal.ChronoUnit;
public class DurationPeriodBasics {
public static void main(String[] args) {
// Creating Durations
Duration duration1 = Duration.ofHours(2);
Duration duration2 = Duration.ofMinutes(30);
Duration duration3 = Duration.ofSeconds(45);
Duration duration4 = Duration.ofMillis(500);
Duration duration5 = Duration.ofNanos(1000000);
System.out.println("2 hours: " + duration1);
System.out.println("30 minutes: " + duration2);
System.out.println("45 seconds: " + duration3);
System.out.println("500 milliseconds: " + duration4);
System.out.println("1,000,000 nanoseconds: " + duration5);
// Creating Periods
Period period1 = Period.ofDays(5);
Period period2 = Period.ofWeeks(2);
Period period3 = Period.ofMonths(3);
Period period4 = Period.ofYears(1);
Period period5 = Period.of(1, 6, 15); // 1 year, 6 months, 15 days
System.out.println("5 days: " + period1);
System.out.println("2 weeks: " + period2);
System.out.println("3 months: " + period3);
System.out.println("1 year: " + period4);
System.out.println("1 year, 6 months, 15 days: " + period5);
// Using between() method
LocalDateTime start = LocalDateTime.of(2024, 1, 1, 10, 0);
LocalDateTime end = LocalDateTime.of(2024, 1, 1, 14, 30);
Duration betweenDuration = Duration.between(start, end);
System.out.println("Duration between: " + betweenDuration);
LocalDate date1 = LocalDate.of(2024, 1, 1);
LocalDate date2 = LocalDate.of(2024, 7, 15);
Period betweenPeriod = Period.between(date1, date2);
System.out.println("Period between: " + betweenPeriod);
}
}
Example 2: Practical Duration Operations
import java.time.Duration;
import java.time.Instant;
import java.time.LocalTime;
import java.util.concurrent.TimeUnit;
public class DurationOperations {
public static void main(String[] args) throws InterruptedException {
// Measuring execution time
Instant start = Instant.now();
Thread.sleep(1500); // Simulate work
Instant end = Instant.now();
Duration executionTime = Duration.between(start, end);
System.out.println("Execution took: " + executionTime.toMillis() + " ms");
System.out.println("Execution took: " + executionTime.toNanos() + " ns");
// Duration arithmetic
Duration d1 = Duration.ofMinutes(30);
Duration d2 = Duration.ofHours(1);
Duration d3 = Duration.ofSeconds(45);
// Addition
Duration total = d1.plus(d2).plus(d3);
System.out.println("Total duration: " + total);
System.out.println("Total minutes: " + total.toMinutes());
// Subtraction
Duration difference = d2.minus(d1);
System.out.println("Difference: " + difference);
// Multiplication and division
Duration doubled = d1.multipliedBy(2);
Duration halved = d1.dividedBy(2);
System.out.println("Doubled: " + doubled);
System.out.println("Halved: " + halved);
// Comparison
System.out.println("d1 > d2: " + (d1.compareTo(d2) > 0));
System.out.println("d1 < d2: " + (d1.compareTo(d2) < 0));
System.out.println("d1 equals d2: " + d1.equals(d2));
// Working with time units
System.out.println("d1 in hours: " + d1.toHours());
System.out.println("d1 in minutes: " + d1.toMinutes());
System.out.println("d1 in seconds: " + d1.toSeconds());
// Negative durations
Duration negative = d1.negated();
System.out.println("Negative duration: " + negative);
// Absolute value
Duration absNegative = negative.abs();
System.out.println("Absolute value: " + absNegative);
}
// Utility method for formatting duration
public static String formatDuration(Duration duration) {
long hours = duration.toHours();
long minutes = duration.toMinutesPart();
long seconds = duration.toSecondsPart();
long millis = duration.toMillisPart();
return String.format("%02d:%02d:%02d.%03d", hours, minutes, seconds, millis);
}
// Convert Duration to human-readable string
public static String toHumanReadable(Duration duration) {
if (duration.isNegative()) {
return "Negative duration";
}
long days = duration.toDays();
long hours = duration.toHoursPart();
long minutes = duration.toMinutesPart();
long seconds = duration.toSecondsPart();
StringBuilder sb = new StringBuilder();
if (days > 0) {
sb.append(days).append(" day").append(days != 1 ? "s" : "").append(" ");
}
if (hours > 0) {
sb.append(hours).append(" hour").append(hours != 1 ? "s" : "").append(" ");
}
if (minutes > 0) {
sb.append(minutes).append(" minute").append(minutes != 1 ? "s" : "").append(" ");
}
if (seconds > 0 || sb.length() == 0) {
sb.append(seconds).append(" second").append(seconds != 1 ? "s" : "");
}
return sb.toString().trim();
}
}
Example 3: Period Operations and Date Calculations
import java.time.LocalDate;
import java.time.Period;
import java.time.format.DateTimeFormatter;
public class PeriodOperations {
public static void main(String[] args) {
// Basic period operations
Period p1 = Period.ofYears(2);
Period p2 = Period.ofMonths(8);
Period p3 = Period.ofDays(15);
// Addition
Period total = p1.plus(p2).plus(p3);
System.out.println("Total period: " + total);
// Subtraction
Period difference = p1.minus(Period.ofMonths(6));
System.out.println("Difference: " + difference);
// Multiplication
Period multiplied = p2.multipliedBy(3);
System.out.println("Multiplied: " + multiplied);
// Normalization (converts 13 months to 1 year 1 month)
Period normalized = Period.of(0, 13, 45).normalized();
System.out.println("Normalized: " + normalized);
// Date calculations with periods
LocalDate today = LocalDate.now();
LocalDate futureDate = today.plus(Period.ofMonths(3));
LocalDate pastDate = today.minus(Period.ofYears(1));
System.out.println("Today: " + today);
System.out.println("3 months from now: " + futureDate);
System.out.println("1 year ago: " + pastDate);
// Age calculation
LocalDate birthDate = LocalDate.of(1990, 5, 15);
Period age = Period.between(birthDate, today);
System.out.println("Age: " + age.getYears() + " years, " +
age.getMonths() + " months, " +
age.getDays() + " days");
// Project duration calculation
LocalDate projectStart = LocalDate.of(2024, 1, 1);
LocalDate projectEnd = LocalDate.of(2024, 12, 31);
Period projectDuration = Period.between(projectStart, projectEnd);
System.out.println("Project duration: " + projectDuration);
// Working with specific units
System.out.println("Years: " + p1.getYears());
System.out.println("Months: " + p2.getMonths());
System.out.println("Days: " + p3.getDays());
// Checking if period is zero or negative
System.out.println("Is zero: " + Period.ZERO.isZero());
System.out.println("Is negative: " + p1.isNegative());
}
// Calculate business age (excluding weekends)
public static Period calculateBusinessAge(LocalDate birthDate, LocalDate currentDate) {
// This is a simplified version - real implementation would be more complex
Period age = Period.between(birthDate, currentDate);
return age;
}
// Add business days (excluding weekends)
public static LocalDate addBusinessDays(LocalDate date, int businessDays) {
LocalDate result = date;
int addedDays = 0;
while (addedDays < businessDays) {
result = result.plusDays(1);
// Skip weekends (Saturday = 6, Sunday = 7)
if (result.getDayOfWeek().getValue() < 6) {
addedDays++;
}
}
return result;
}
}
Advanced Usage Patterns
Example 4: Duration and Period in Real Applications
import java.time.*;
import java.util.concurrent.*;
import java.util.*;
public class AdvancedTimeUsage {
// Cache configuration with Duration
static class CacheConfig {
private final Duration ttl;
private final Duration refreshInterval;
private final Duration maxIdleTime;
public CacheConfig(Duration ttl, Duration refreshInterval, Duration maxIdleTime) {
this.ttl = ttl;
this.refreshInterval = refreshInterval;
this.maxIdleTime = maxIdleTime;
}
public long getTtlMillis() {
return ttl.toMillis();
}
public long getRefreshIntervalMillis() {
return refreshInterval.toMillis();
}
public boolean shouldRefresh(Instant lastRefresh) {
return Duration.between(lastRefresh, Instant.now())
.compareTo(refreshInterval) >= 0;
}
public boolean isExpired(Instant creationTime, Instant lastAccess) {
Duration sinceCreation = Duration.between(creationTime, Instant.now());
Duration sinceLastAccess = Duration.between(lastAccess, Instant.now());
return sinceCreation.compareTo(ttl) >= 0 ||
sinceLastAccess.compareTo(maxIdleTime) >= 0;
}
}
// Subscription service with Period
static class SubscriptionService {
private final Map<String, Subscription> subscriptions = new ConcurrentHashMap<>();
static class Subscription {
private final String userId;
private final LocalDate startDate;
private final Period duration;
private final SubscriptionTier tier;
public Subscription(String userId, LocalDate startDate,
Period duration, SubscriptionTier tier) {
this.userId = userId;
this.startDate = startDate;
this.duration = duration;
this.tier = tier;
}
public boolean isActive() {
LocalDate endDate = startDate.plus(duration);
return LocalDate.now().isBefore(endDate) ||
LocalDate.now().equals(endDate);
}
public LocalDate getExpiryDate() {
return startDate.plus(duration);
}
public Period getRemainingTime() {
return Period.between(LocalDate.now(), getExpiryDate());
}
public boolean isExpiringSoon() {
Period remaining = getRemainingTime();
return remaining.getMonths() == 0 && remaining.getDays() <= 7;
}
}
enum SubscriptionTier {
BASIC(Period.ofMonths(1)),
PREMIUM(Period.ofYears(1)),
ENTERPRISE(Period.ofYears(2));
private final Period defaultDuration;
SubscriptionTier(Period defaultDuration) {
this.defaultDuration = defaultDuration;
}
public Period getDefaultDuration() {
return defaultDuration;
}
}
public void createSubscription(String userId, SubscriptionTier tier) {
Subscription subscription = new Subscription(
userId,
LocalDate.now(),
tier.getDefaultDuration(),
tier
);
subscriptions.put(userId, subscription);
}
public void renewSubscription(String userId, Period additionalDuration) {
Subscription current = subscriptions.get(userId);
if (current != null) {
Period newDuration = current.duration.plus(additionalDuration);
Subscription renewed = new Subscription(
userId,
LocalDate.now(),
newDuration,
current.tier
);
subscriptions.put(userId, renewed);
}
}
public List<String> getExpiringSubscriptions() {
List<String> expiring = new ArrayList<>();
for (Subscription sub : subscriptions.values()) {
if (sub.isExpiringSoon()) {
expiring.add(sub.userId);
}
}
return expiring;
}
}
// Rate limiter with Duration
static class RateLimiter {
private final Duration window;
private final int maxRequests;
private final Queue<Instant> requests = new LinkedList<>();
public RateLimiter(Duration window, int maxRequests) {
this.window = window;
this.maxRequests = maxRequests;
}
public synchronized boolean allowRequest() {
Instant now = Instant.now();
Instant windowStart = now.minus(window);
// Remove old requests
while (!requests.isEmpty() &&
requests.peek().isBefore(windowStart)) {
requests.poll();
}
if (requests.size() < maxRequests) {
requests.offer(now);
return true;
}
return false;
}
public Duration timeUntilNextAllowed() {
if (requests.size() < maxRequests) {
return Duration.ZERO;
}
Instant oldest = requests.peek();
Instant nextAllowed = oldest.plus(window);
return Duration.between(Instant.now(), nextAllowed);
}
}
public static void main(String[] args) throws InterruptedException {
// Test CacheConfig
CacheConfig cacheConfig = new CacheConfig(
Duration.ofMinutes(30),
Duration.ofMinutes(5),
Duration.ofMinutes(10)
);
System.out.println("TTL: " + cacheConfig.getTtlMillis() + " ms");
// Test SubscriptionService
SubscriptionService subscriptionService = new SubscriptionService();
subscriptionService.createSubscription("user1",
SubscriptionService.SubscriptionTier.PREMIUM);
// Test RateLimiter
RateLimiter rateLimiter = new RateLimiter(Duration.ofSeconds(10), 5);
for (int i = 0; i < 10; i++) {
if (rateLimiter.allowRequest()) {
System.out.println("Request " + i + ": Allowed");
} else {
Duration waitTime = rateLimiter.timeUntilNextAllowed();
System.out.println("Request " + i + ": Denied. Wait " +
waitTime.getSeconds() + " seconds");
}
Thread.sleep(100);
}
}
}
Example 5: Duration and Period with Scheduled Tasks
import java.time.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
public class ScheduledTasksWithDuration {
static class TaskScheduler {
private final ScheduledExecutorService scheduler;
private final AtomicInteger taskCounter;
public TaskScheduler() {
this.scheduler = Executors.newScheduledThreadPool(4);
this.taskCounter = new AtomicInteger(0);
}
// Schedule task with fixed delay
public ScheduledFuture<?> scheduleWithFixedDelay(
Runnable task,
Duration initialDelay,
Duration delay
) {
return scheduler.scheduleWithFixedDelay(
task,
initialDelay.toMillis(),
delay.toMillis(),
TimeUnit.MILLISECONDS
);
}
// Schedule task at fixed rate
public ScheduledFuture<?> scheduleAtFixedRate(
Runnable task,
Duration initialDelay,
Duration period
) {
return scheduler.scheduleAtFixedRate(
task,
initialDelay.toMillis(),
period.toMillis(),
TimeUnit.MILLISECONDS
);
}
// Schedule one-time task
public ScheduledFuture<?> schedule(
Runnable task,
Duration delay
) {
return scheduler.schedule(
task,
delay.toMillis(),
TimeUnit.MILLISECONDS
);
}
public void shutdown() {
scheduler.shutdown();
}
}
static class HealthCheckService {
private final TaskScheduler scheduler;
private final Duration checkInterval;
private final Duration timeout;
private volatile boolean healthy = true;
public HealthCheckService(Duration checkInterval, Duration timeout) {
this.scheduler = new TaskScheduler();
this.checkInterval = checkInterval;
this.timeout = timeout;
}
public void start() {
// Schedule health checks
scheduler.scheduleAtFixedRate(
this::performHealthCheck,
Duration.ZERO,
checkInterval
);
System.out.println("Health check service started with interval: " +
checkInterval.getSeconds() + " seconds");
}
private void performHealthCheck() {
CompletableFuture<Boolean> healthFuture = CompletableFuture.supplyAsync(() -> {
// Simulate health check
try {
Thread.sleep(500); // Simulate check time
return Math.random() > 0.1; // 90% success rate
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return false;
}
});
try {
Boolean result = healthFuture.get(timeout.toMillis(), TimeUnit.MILLISECONDS);
healthy = result;
System.out.println("Health check: " + (healthy ? "HEALTHY" : "UNHEALTHY"));
} catch (TimeoutException e) {
healthy = false;
System.out.println("Health check: TIMEOUT");
} catch (Exception e) {
healthy = false;
System.out.println("Health check: ERROR - " + e.getMessage());
}
}
public boolean isHealthy() {
return healthy;
}
public void stop() {
scheduler.shutdown();
}
}
static class MaintenanceWindow {
private final LocalDate startDate;
private final Period recurrence;
private final Duration duration;
private final LocalTime startTime;
public MaintenanceWindow(LocalDate startDate, Period recurrence,
Duration duration, LocalTime startTime) {
this.startDate = startDate;
this.recurrence = recurrence;
this.duration = duration;
this.startTime = startTime;
}
public boolean isActive() {
LocalDateTime now = LocalDateTime.now();
LocalDateTime windowStart = getNextWindowStart();
LocalDateTime windowEnd = windowStart.plus(duration);
return !now.isBefore(windowStart) && !now.isAfter(windowEnd);
}
public LocalDateTime getNextWindowStart() {
LocalDateTime nextWindow = LocalDateTime.of(startDate, startTime);
LocalDateTime now = LocalDateTime.now();
while (nextWindow.isBefore(now)) {
nextWindow = nextWindow.plus(recurrence);
}
return nextWindow;
}
public Duration timeUntilNextWindow() {
LocalDateTime nextWindow = getNextWindowStart();
return Duration.between(LocalDateTime.now(), nextWindow);
}
public Duration getDuration() {
return duration;
}
}
public static void main(String[] args) throws InterruptedException {
// Test HealthCheckService
HealthCheckService healthService = new HealthCheckService(
Duration.ofSeconds(5),
Duration.ofSeconds(3)
);
healthService.start();
// Test MaintenanceWindow
MaintenanceWindow maintenance = new MaintenanceWindow(
LocalDate.of(2024, 1, 1),
Period.ofMonths(1),
Duration.ofHours(4),
LocalTime.of(2, 0) // 2:00 AM
);
System.out.println("Next maintenance: " + maintenance.getNextWindowStart());
System.out.println("Time until maintenance: " +
maintenance.timeUntilNextWindow().toDays() + " days");
// Let it run for a while
Thread.sleep(15000);
healthService.stop();
}
}
Best Practices and Common Patterns
Example 6: Utility Methods and Best Practices
import java.time.*;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoUnit;
import java.util.Objects;
public class TimeUtils {
// Prevent instantiation
private TimeUtils() {}
// Formatting utilities
public static String formatDurationShort(Duration duration) {
if (duration.isNegative()) {
return "-" + formatDurationShort(duration.abs());
}
long days = duration.toDays();
long hours = duration.toHoursPart();
long minutes = duration.toMinutesPart();
long seconds = duration.toSecondsPart();
if (days > 0) {
return String.format("%dd %02d:%02d:%02d", days, hours, minutes, seconds);
} else if (hours > 0) {
return String.format("%02d:%02d:%02d", hours, minutes, seconds);
} else {
return String.format("%02d:%02d", minutes, seconds);
}
}
public static String formatPeriod(Period period) {
List<String> parts = new ArrayList<>();
if (period.getYears() > 0) {
parts.add(period.getYears() + " year" + (period.getYears() != 1 ? "s" : ""));
}
if (period.getMonths() > 0) {
parts.add(period.getMonths() + " month" + (period.getMonths() != 1 ? "s" : ""));
}
if (period.getDays() > 0) {
parts.add(period.getDays() + " day" + (period.getDays() != 1 ? "s" : ""));
}
if (parts.isEmpty()) {
return "0 days";
}
return String.join(", ", parts);
}
// Validation utilities
public static boolean isValidDuration(String durationStr) {
try {
Duration.parse(durationStr);
return true;
} catch (Exception e) {
return false;
}
}
public static boolean isValidPeriod(String periodStr) {
try {
Period.parse(periodStr);
return true;
} catch (Exception e) {
return false;
}
}
// Conversion utilities
public static Duration toDuration(String durationStr) {
Objects.requireNonNull(durationStr, "Duration string cannot be null");
try {
return Duration.parse(durationStr);
} catch (Exception e) {
throw new IllegalArgumentException("Invalid duration format: " + durationStr, e);
}
}
public static Period toPeriod(String periodStr) {
Objects.requireNonNull(periodStr, "Period string cannot be null");
try {
return Period.parse(periodStr);
} catch (Exception e) {
throw new IllegalArgumentException("Invalid period format: " + periodStr, e);
}
}
// Business logic utilities
public static boolean isWithinBusinessHours(LocalTime time,
LocalTime businessStart,
LocalTime businessEnd) {
return !time.isBefore(businessStart) && !time.isAfter(businessEnd);
}
public static Duration calculateBusinessDuration(LocalDateTime start,
LocalDateTime end,
LocalTime businessStart,
LocalTime businessEnd) {
if (start.isAfter(end)) {
return Duration.ZERO;
}
Duration total = Duration.ZERO;
LocalDateTime current = start;
while (current.isBefore(end)) {
LocalDateTime dayStart = current.toLocalDate().atTime(businessStart);
LocalDateTime dayEnd = current.toLocalDate().atTime(businessEnd);
// Adjust to business hours
LocalDateTime segmentStart = current.isBefore(dayStart) ? dayStart : current;
LocalDateTime segmentEnd = end.isAfter(dayEnd) ? dayEnd : end;
if (segmentStart.isBefore(segmentEnd)) {
total = total.plus(Duration.between(segmentStart, segmentEnd));
}
// Move to next day
current = current.toLocalDate().plusDays(1).atTime(businessStart);
}
return total;
}
// Age calculation with precision
public static class Age {
private final Period period;
private final Duration preciseDuration;
public Age(LocalDate birthDate) {
this(birthDate, LocalDateTime.now());
}
public Age(LocalDate birthDate, LocalDateTime reference) {
this.period = Period.between(birthDate, reference.toLocalDate());
this.preciseDuration = Duration.between(
birthDate.atStartOfDay(),
reference
);
}
public int getYears() { return period.getYears(); }
public int getMonths() { return period.getMonths(); }
public int getDays() { return period.getDays(); }
public long getTotalDays() { return preciseDuration.toDays(); }
public long getTotalHours() { return preciseDuration.toHours(); }
@Override
public String toString() {
return String.format("%d years, %d months, %d days",
getYears(), getMonths(), getDays());
}
}
// Testing utility
public static void assertDurationEquals(Duration expected, Duration actual, Duration tolerance) {
Duration difference = expected.minus(actual).abs();
if (difference.compareTo(tolerance) > 0) {
throw new AssertionError(String.format(
"Durations differ by more than tolerance. Expected: %s, Actual: %s, Difference: %s, Tolerance: %s",
expected, actual, difference, tolerance
));
}
}
}
// Example usage
class TimeUtilsExample {
public static void main(String[] args) {
// Formatting examples
Duration duration = Duration.ofHours(25).plusMinutes(30);
System.out.println("Formatted: " + TimeUtils.formatDurationShort(duration));
Period period = Period.of(1, 6, 15);
System.out.println("Formatted period: " + TimeUtils.formatPeriod(period));
// Age calculation
LocalDate birthDate = LocalDate.of(1990, 5, 15);
TimeUtils.Age age = new TimeUtils.Age(birthDate);
System.out.println("Age: " + age);
System.out.println("Total days: " + age.getTotalDays());
// Business duration calculation
LocalDateTime start = LocalDateTime.of(2024, 1, 1, 8, 0); // Monday 8 AM
LocalDateTime end = LocalDateTime.of(2024, 1, 3, 16, 0); // Wednesday 4 PM
LocalTime businessStart = LocalTime.of(9, 0);
LocalTime businessEnd = LocalTime.of(17, 0);
Duration businessDuration = TimeUtils.calculateBusinessDuration(
start, end, businessStart, businessEnd);
System.out.println("Business duration: " +
TimeUtils.formatDurationShort(businessDuration));
}
}
Key Differences and When to Use
Duration
- Use for precise time measurements (seconds, milliseconds)
- Suitable for timers, timeouts, execution time
- Machine-oriented time
- ISO-8601 format:
PTnHnMnS
Period
- Use for date-based calculations (years, months, days)
- Suitable for age calculation, subscription periods
- Human-oriented time
- ISO-8601 format:
PnYnMnD
Common Pitfalls
- Mixing Duration and Period: They represent different concepts
- Time Zone Awareness: Duration is timezone-agnostic, Period may need timezone context
- Daylight Saving Time: Duration handles this automatically, Period doesn't account for it
- Month Length Variations: Period handles variable month lengths, Duration doesn't
Conclusion
Duration and Period are essential tools in modern Java for different time measurement scenarios:
- Duration: Precise, machine-time operations
- Period: Human-readable, calendar-based operations
Key takeaways:
- Use Duration for short, precise time intervals
- Use Period for longer, calendar-based periods
- Leverage their rich API for arithmetic and comparison operations
- Combine with other java.time classes for comprehensive time handling
By understanding these classes and their appropriate use cases, you can write more robust and maintainable time-handling code in your Java applications.