Java Legacy Calendar-Klasse | W3Docs Learn Java

java.util.Calendar ist die zweite Hälfte des Legacy-Datums-/Zeitpaares. Während java.util.Date lediglich ein Wrapper um einen long-Wert von Epochenmillisekunden ist, weiß Calendar, auf welches Jahr, Monat und Tag dieser Millisekunden-Wert fällt. Die Klasse wurde in Java 1.1 eingeführt, um die Kalenderarithmetik aus Date herauszulösen — deshalb sind die meisten Feldzugriffsmethoden von Date als veraltet markiert.

In modernem Code sollte man java.time bevorzugen. Aber Calendar taucht noch immer auf: in alten Code-Pfaden, in Bibliotheken, die vor Java 8 geschrieben wurden, und in JDBC-Treibern, die noch nicht aktualisiert wurden. Man muss es lesen, überbrücken und weitermachen. Diese Seite erklärt, wie man ein Calendar-Objekt erstellt, seine Felder sicher ausliest (Achtung: nullbasierte Monate), Kalenderarithmetik durchführt und — am wichtigsten — es zur modernen API überbrückt.

Calendar ist abstrakt

Calendar selbst ist eine abstrakte Klasse. Man ruft nie new Calendar(...) auf. Eine Instanz erhält man über die Factory-Methode:

Calendar cal = Calendar.getInstance();

Dies gibt eine konkrete Unterklasse zurück — fast immer GregorianCalendar — vorbelegt mit der aktuellen Zeit, der Standard-Zeitzone und dem Standard-Locale. Man kann bei Bedarf auch explizit angeben:

Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("UTC"), Locale.US);

GregorianCalendar hat auch öffentliche Konstruktoren, aber die Factory-Methode ist die Konvention.

Feldkonstanten

Calendar stellt alles über Integer-Feldkonstanten und ein generisches get(int field) bereit:

Feld	Bedeutung	Bereich
`Calendar.YEAR`	Jahr	vollständiges Jahr, z. B. 2026
`Calendar.MONTH`	Monat	0–11 (Januar = 0)
`Calendar.DAY_OF_MONTH`	Tag des Monats	1–31
`Calendar.DAY_OF_WEEK`	Wochentag	1–7 (Sonntag = 1)
`Calendar.HOUR_OF_DAY`	Stunde	0–23
`Calendar.MINUTE`	Minute	0–59
`Calendar.SECOND`	Sekunde	0–59
`Calendar.MILLISECOND`	Millisekunde	0–999

Zwei Fallen stecken in dieser Tabelle: MONTH ist nullbasiert (Calendar.JANUARY == 0) und DAY_OF_WEEK beginnt mit Sonntag. Off-by-one-Fehler in Legacy-Code lassen sich fast immer auf diese Punkte zurückführen.

Setzen und Arithmetik

set nimmt ein Feld und einen Wert entgegen; add führt kalendergestützte Arithmetik durch, bei der Überläufe in größere Felder übertragen werden:

Calendar cal = Calendar.getInstance();
cal.set(2026, Calendar.MAY, 29);   // Y, M, D — month is zero-based
cal.add(Calendar.DAY_OF_MONTH, 5); // → 2026-06-03

roll macht dasselbe feldweise, überträgt jedoch nicht in größere Felder — roll(DAY_OF_MONTH, 5) am 30. Mai ergibt den 4. Mai, nicht den 4. Juni. Das ist selten das Gewünschte.

Calendar-Instanzen sind veränderlich, daher bedeutet das Übergeben einer Instanz an eine Methode, dass man ein direktes Handle weitergibt. Vor der Weitergabe klonen, genauso wie bei einem Date.

Die Brücke zu java.time

Der eigentliche Grund, Calendar heute anzufassen, ist, es hinter sich zu lassen. Zwei Methoden ermöglichen das:

Instant when = cal.toInstant();
ZoneId  zone = cal.getTimeZone().toZoneId();
ZonedDateTime zdt = when.atZone(zone);

Von ZonedDateTime aus steht die gesamte moderne API zur Verfügung. In die andere Richtung:

Calendar cal = GregorianCalendar.from(zdt); // Java 8+

GregorianCalendar.from(ZonedDateTime) ist die unterstützte Konvertierung. Den Umweg über Date sollte man vermeiden.

Ausgearbeitetes Beispiel

Das folgende Beispiel zeigt die zwei Dinge, die man mit Calendar im echten Code tun wird: Felder von einer Legacy-Instanz auslesen und zur java.time-API überbrücken, um alles Nichttriviale zu erledigen.

java— editable, runs on the server

import java.util.*;
import java.time.*;

public class CalendarDemo {
  public static void main(String[] args) {
      // Build a Calendar the legacy way
      Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("Europe/Berlin"));
      cal.set(2026, Calendar.MAY, 29, 14, 30, 0);
      cal.set(Calendar.MILLISECOND, 0);

// Read fields — note the zero-based month
      System.out.println("year   = " + cal.get(Calendar.YEAR));
      System.out.println("month  = " + cal.get(Calendar.MONTH));        // 4, not 5
      System.out.println("day    = " + cal.get(Calendar.DAY_OF_MONTH));
      System.out.println("hour   = " + cal.get(Calendar.HOUR_OF_DAY));

// Calendar-aware arithmetic
      cal.add(Calendar.MONTH, 1);
      System.out.println("plus 1 month: " + cal.getTime());

// Bridge to java.time and do the same thing cleanly
      ZonedDateTime zdt = cal.toInstant().atZone(cal.getTimeZone().toZoneId());
      ZonedDateTime later = zdt.plusMonths(2);
      System.out.println("modern: " + later);

// Round-trip back to Calendar if you must hand it back to legacy code
      Calendar handBack = GregorianCalendar.from(later);
      System.out.println("handed back: " + handBack.getTime());
  }
}

Was man dem Ergebnis entnehmen kann:

Calendar.MONTH für Mai gibt 4 aus. Nullbasierte Monate sind die häufigste Fehlerquelle in Legacy-Datumscode.
getInstance(TimeZone) bindet die Instanz an eine Zeitzone — anders als Date, das keine hat.
add(MONTH, 1) berücksichtigt die Monatslänge; man erhält den richtigen Tag im nächsten Monat, auch wenn Monate nicht alle 30 Tage haben.
cal.toInstant().atZone(cal.getTimeZone().toZoneId()) ist die einzeilige Brücke zu java.time.
GregorianCalendar.from(ZonedDateTime) ermöglicht es, ein Calendar-Objekt an eine alte API zurückzugeben, ohne die Zeitzone zu verlieren.

Was kommt als Nächstes

Damit schließt Teil 14 — Datum und Uhrzeit. Als Nächstes folgt Teil 15, Multithreading und Nebenläufigkeit, beginnend mit Multithreading in Java — das Modell, das jede andere API in diesem Buch geprägt hat.

Übung

Ein Calendar, der auf den 29. Mai 2026 gesetzt ist, gibt cal.get(Calendar.MONTH) zurück. Welcher Wert wird ausgegeben?

4 — Calendar-Monate sind nullbasiert, daher ist Mai Index 4.5 — Calendar-Monate entsprechen der menschlichen Zählung, Mai ist 5.'MAY' — get(MONTH) gibt den Monatsnamen als String zurück.Eine IllegalStateException — MONTH ist kein gültiges Feld für Calendar.