6.2.2 Duration Class Explained

The Duration class in Java is part of the java.time package and is used to represent a time-based amount of time, such as "34.5 seconds" or "2 hours, 30 minutes". It is designed to handle precise time intervals and is particularly useful for measuring the duration between two temporal objects.

Key Concepts

1. Duration Representation

The Duration class represents a time-based amount of time in terms of seconds and nanoseconds. It is immutable, meaning once a Duration object is created, its state cannot be changed. This ensures thread safety and reduces the risk of bugs related to mutable state.

Example

        import java.time.Duration;
        
        public class DurationExample {
            public static void main(String[] args) {
                Duration duration = Duration.ofSeconds(34, 500000000);
                System.out.println("Duration: " + duration.getSeconds() + " seconds, " + duration.getNano() + " nanoseconds");
            }
        }
    

2. Duration Creation

The Duration class provides several methods to create duration objects, such as ofDays(), ofHours(), ofMinutes(), ofSeconds(), and ofMillis(). These methods allow you to create durations from specific values.

Example

        import java.time.Duration;
        
        public class DurationCreationExample {
            public static void main(String[] args) {
                Duration oneHour = Duration.ofHours(1);
                System.out.println("One Hour: " + oneHour.getSeconds() + " seconds");
                
                Duration thirtyMinutes = Duration.ofMinutes(30);
                System.out.println("Thirty Minutes: " + thirtyMinutes.getSeconds() + " seconds");
            }
        }
    

3. Duration Manipulation

The Duration class provides methods to manipulate durations, such as adding or subtracting time. These methods return new Duration objects, ensuring the original duration remains unchanged.

Example

        import java.time.Duration;
        
        public class DurationManipulationExample {
            public static void main(String[] args) {
                Duration duration = Duration.ofMinutes(30);
                Duration newDuration = duration.plusSeconds(120).minusMinutes(5);
                System.out.println("New Duration: " + newDuration.getSeconds() + " seconds");
            }
        }
    

4. Duration Comparison

The Duration class provides methods to compare two durations, such as checking if one duration is longer, shorter, or equal to another duration. These methods are useful for time-based logic and scheduling.

Example

        import java.time.Duration;
        
        public class DurationComparisonExample {
            public static void main(String[] args) {
                Duration duration1 = Duration.ofMinutes(30);
                Duration duration2 = Duration.ofSeconds(2000);
                
                System.out.println("duration1 is longer than duration2: " + duration1.compareTo(duration2));
                System.out.println("duration1 is shorter than duration2: " + duration2.compareTo(duration1));
                System.out.println("duration1 is equal to duration2: " + duration1.equals(duration2));
            }
        }
    

5. Duration Between Temporal Objects

The Duration class provides a method to calculate the duration between two temporal objects, such as LocalTime or Instant. This method is useful for measuring the time elapsed between two events.

Example

        import java.time.Duration;
        import java.time.LocalTime;
        
        public class DurationBetweenExample {
            public static void main(String[] args) {
                LocalTime startTime = LocalTime.of(10, 0);
                LocalTime endTime = LocalTime.of(12, 30);
                
                Duration duration = Duration.between(startTime, endTime);
                System.out.println("Duration between start and end time: " + duration.getSeconds() + " seconds");
            }
        }
    

Examples and Analogies

Think of Duration as a stopwatch that measures the time between two events. For example, if you need to measure how long a task takes to complete, Duration is perfect for storing and manipulating that time interval. The immutability of Duration ensures that once a time interval is set, it cannot be altered, similar to a stopwatch that cannot be reset without starting a new measurement.

By mastering the Duration class, you can efficiently handle time-based operations in your Java SE 11 applications, ensuring accurate and reliable time interval management.