java.time.Duration

Advanced Java Services

java.time.Duration

Duration

Die Klasse Duration modelliert eine Zeitdauer und ist zuständig für die Bereiche Nanosekunden bis Tage. Für größere Einheiten ist dann die Klasse Period zuständig.

Factorymethoden

Factorymethoden sind die ofXxx()- und die parse()-Methoden, auch die between() und die from()-Methoden kann man als Factorymethoden auffassen, sie sind (natürlich) allesamt statisch.

Duration
Methode	Eigenschaft
of(long amount, TemporalUnit unit)	Obtains a Duration representing an amount in the specified unit. TemporalUnit wird durch die Enumklasse ChronoUnit realisiert.
ofNanos(long nanos)	Obtains a Duration representing a number of nanoseconds.
ofMillis(long millis)	Obtains a Duration representing a number of milliseconds.
ofMinutes(long minutes)	Obtains a Duration representing a number of standard minutes.
ofSeconds(long seconds)	Obtains a Duration representing a number of seconds.
ofSeconds(long seconds, long nanoAdjustment)	Obtains a Duration representing a number of seconds and an adjustment in nanoseconds.
ofHours(long hours)	Obtains a Duration representing a number of standard hours.
ofDays(long days)	Obtains a Duration representing a number of standard 24 hour days.
parse(CharSequence text)	Obtains a Duration from a text string such as PnDTnHnMn.nS.
between(Temporal startInclusive, Temporal endExclusive)	Obtains a Duration representing the duration between two temporal objects. Ein Temporal ist eine beliebige Date- oder Time- oder DateTimeklasse.
from(TemporalAmount amount)	Obtains an instance of Duration from a temporal amount. Ein TemporalAmount ist eine Duration oder eine Period.

Beispiel zu den ofXxx()-Methoden

Duration sixtysixNanos = Duration.ofNanos(66);
Duration fiftythreeMillis = Duration.ofMillis(53);
Duration twelveSeconds = Duration.ofSeconds(-12);
Duration fiveMinutes = Duration.ofMinutes(-5);
Duration threeHours = Duration.ofHours(3);
Duration twoDays = Duration.ofDays(2);

System.out.println("sixtysixNanos    = " + sixtysixNanos);
System.out.println("fiftythreeMillis = " + fiftythreeMillis);
System.out.println("twelveSeconds    = " + twelveSeconds);
System.out.println("fiveMinutes      = " + fiveMinutes);
System.out.println("threeHours       = " + threeHours);
System.out.println("twoDays          = " + twoDays);

Die Ausgabe

sixtysixNanos    = PT0.000000066S
fiftythreeMillis = PT0.053S
twelveSeconds    = PT-12S
fiveMinutes      = PT-5M
threeHours       = PT3H
twoDays          = PT48H

Wie man sieht können die Zeitangaben auch negativ sein. Aus der Ausgabe im UTC-Format kann man vermuten, daß bei einer Eingabe von Tagen intern mit Stunden gerechnet wird.

Beispiele zur of()-Methode

Hier sieht man, daß nicht alle von ChronoUnit gelieferten Konstanten verwendet werden können.

Duration dur1 = Duration.of(13, ChronoUnit.NANOS);
System.out.println(dur1); // PT0.000000013S

Duration dur2 = Duration.of(31, ChronoUnit.MICROS);
System.out.println(dur2); // PT0.000031S

Duration dur3 = Duration.of(223, ChronoUnit.MILLIS);
System.out.println(dur3); // PT0.223S

Duration dur4 = Duration.of(4, ChronoUnit.SECONDS);
System.out.println(dur4); // PT4S

Duration dur5 = Duration.of(5, ChronoUnit.MINUTES);
System.out.println(dur5); // PT5M

Duration dur6 = Duration.of(6, ChronoUnit.HOURS);
System.out.println(dur6); // PT6H

Duration dur7 = Duration.of(7, ChronoUnit.HALF_DAYS);
System.out.println(dur7); // PT84H

Duration dur8 = Duration.of(8, ChronoUnit.DAYS);
System.out.println(dur8); // PT192H

Der Versuch größere Einheiten zu verwenden führt zu der folgenden Exception:
java.time.temporal.UnsupportedTemporalTypeException: Unit must not have an estimated duration

Beispiele zur parse()-Methode

Die parse-Methode birgt einige Überraschungen.

Duration dur1 = Duration.parse("PT72H");
System.out.println(dur1.getSeconds()); // 259200
System.out.println(dur1.getNano()); // 0

Duration dur1a = Duration.parse("P3D");
System.out.println(dur1a); // PT72H

Während getSeconds() die Zeitdauer in Sekunden umgerechnet liefert, liefert getNano() nur den Anteil der Nanosekunden - und der ist 0.
Die Eingabe eine Formats mit Tagen wird in Stunden umgerechnet.

Duration dur2 = Duration.parse("P2W3D");

Der Versuch größere Einheiten als Tage zu verwenden mißlingt:
java.time.format.DateTimeParseException: Text cannot be parsed to a duration
Dies ist Konzept. Für größere Einheiten ist Period zuständig.

Die get()-Methoden

getNano() liefert den Anteil der Nanosekunden, getSeconds() die gesamte Zeitdauer in Sekunden. Interessanter (und überraschend) ist das Verhalten von get(TemporalUnit).

Duration dur = Duration.parse("PT72H");

//System.out.println(dur1.get(ChronoUnit.DAYS));
//java.time.temporal.UnsupportedTemporalTypeException: Unsupported Unit: Days

//System.out.println(dur1.get(ChronoUnit.HOURS));
//java.time.temporal.UnsupportedTemporalTypeException: Unsupported Unit: Hours

//System.out.println(dur1.get(ChronoUnit.MINUTES));
//java.time.temporal.UnsupportedTemporalTypeException: Unsupported Unit: Minutes

System.out.println(dur1.get(ChronoUnit.SECONDS));  // 259200  OK

Hier stellt sich heraus, daß nur zwei Konstanten aus ChronoUnit verwendet werden können: ChronoUnit.SECONDS und ChronoUnit.NANOS

System.out.println(dur1.get(ChronoUnit.NANOS));  // 0  !!

Wieder wird hier nur der Anteil der Nanosekunden geliefert und nicht umgerechnet, ein wenig mißverständlich ist da die Bezeichung ChronoUnit.NANOS schon...

Die getUnits()-Methode

Mit dieser Methode erhält man einen Hinweis, welche Einheiten aus ChronoUnit verwendet werden können.

System.out.println(dur.getUnits());  // [Seconds, Nanos]

Die Ausgabe ist hier aber kein Bereich, sondern sagt, daß nur diese beiden Einheiten verwendet werden können. das entspricht genau den beiden Methoden getNano() und getSeconds().

Die toXxx()-Methoden

Diese Methoden rechnen tatsächlich die Zeitdauer in die angegebene Einheit um.

Duration dur = Duration.parse("PT3D");
System.out.println(dur.toNanos());   // 259200 000 000 000
System.out.println(dur.toMillis());  // 259200 000
System.out.println(dur.toMinutes()); // 4320
System.out.println(dur.toHours());   // 72
System.out.println(dur.toDays());    // 3

Die from()-Methode

Die from-Methode macht, wenn möglich eine Kopie der übergebenen Zeitdauer.

Duration dur = Duration.parse("PT3D");
Duration from = Duration.from(dur);
System.out.println(from);    // PT72H

Period per = Period.parse("P2W");
System.out.println(per);    // P14D
Duration from2 = Duration.from(per);
//java.time.temporal.UnsupportedTemporalTypeException: Unit must not have an estimated duration