Guide to java.util.GregorianCalendar

1. Introduction

In this tutorial, we’re going to take a quick peek at the GregorianCalendar class.

2. GregorianCalendar

GregorianCalendar is a concrete implementation of the abstract class java.util.Calendar. Not surprisingly, the Gregorian Calendar is the most widely used civil calendar in the world. 

2.1. Getting an Instance

There are two options available to get an instance of GregorianCalendar: Calendar.getInstance() and using one of the constructors.

Using the static factory method Calendar.getInstance() isn’t a recommended approach as it will return an instance subjective to the default locale.

It might return a BuddhistCalendar for Thai or JapaneseImperialCalendar for Japan. Not knowing the type of the instance being returned may lead to a ClassCastException:

@Test(expected = ClassCastException.class)
public void test_Class_Cast_Exception() {
    TimeZone tz = TimeZone.getTimeZone("GMT+9:00");
    Locale loc = new Locale("ja", "JP", "JP");
    Calendar calendar = Calendar.getInstance(loc);
    GregorianCalendar gc = (GregorianCalendar) calendar;
}

Using one of the seven overloaded constructors we can initialize the Calendar object either with the default date and time depending on the locale of our operating system or we can specify a combination of date, time, locale and time zone.

Let’s understand the different constructors by which a GregorianCalendar object can be instantiated.

The default constructor will initialize the calendar with the current date and time in the time zone and locale of the operating system:

new GregorianCalendar();

We can specify the year, month, dayOfMonth, hourOfDay, minute, and second for the default time zone with the default locale:

new GregorianCalendar(2018, 6, 27, 16, 16, 47);

Note that we don’t have to specify hourOfDay, minute and second as there are other constructors without these parameters.

We can pass the time zone as a parameter to create a calendar in this time zone with the default locale:

new GregorianCalendar(TimeZone.getTimeZone("GMT+5:30"));

We can pass the locale as a parameter to create a calendar in this locale with the default time zone:

new GregorianCalendar(new Locale("en", "IN"));

Finally, we can pass both the time zone and locale as parameters:

new GregorianCalendar(TimeZone.getTimeZone("GMT+5:30"), new Locale("en", "IN"));

2.2. New Methods With Java 8

With Java 8, new methods have been introduced to GregorianCalendar.

The from() method gets an instance of GregorianCalendar with the default locale from a ZonedDateTime object.

Using getCalendarType() we can get the type of the calendar instance. The available calendar types are ‘gregory’, ‘buddhist’ and ‘japanese’.

We can use this, for example, to make sure we have a calendar of a certain type before moving on with our application logic:

@Test
public void test_Calendar_Return_Type_Valid() {
    Calendar calendar = Calendar.getInstance();
    assert ("gregory".equals(calendar.getCalendarType()));
}

Calling toZonedDateTime() we can convert the calendar object into a ZonedDateTime object that represents the same point on the timeline as this GregorianCalendar.

2.3. Modifying Dates

The calendar fields can be modified using the methods add(), roll() and set().

The add() method allows us to add time to the calendar in a specified unit based on the calendar’s internal ruleset:

@Test
public void test_whenAddOneDay_thenMonthIsChanged() {
    int finalDay1 = 1;
    int finalMonthJul = 6; 
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 5, 30);
    calendarExpected.add(Calendar.DATE, 1);
    System.out.println(calendarExpected.getTime());
 
    assertEquals(calendarExpected.get(Calendar.DATE), finalDay1);
    assertEquals(calendarExpected.get(Calendar.MONTH), finalMonthJul);
}

We can also use the add() method to subtract time from the calendar object:

@Test
public void test_whenSubtractOneDay_thenMonthIsChanged() {
    int finalDay31 = 31;
    int finalMonthMay = 4; 
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 5, 1);
    calendarExpected.add(Calendar.DATE, -1);

    assertEquals(calendarExpected.get(Calendar.DATE), finalDay31);
    assertEquals(calendarExpected.get(Calendar.MONTH), finalMonthMay);
}

Execution of the add() method forces an immediate re-computation of the calendar’s milliseconds and all fields.

Note that using add() may also change the higher calendar fields (MONTH in this case).

The roll() method adds a signed amount to the specified calendar field without changing the larger fields. A larger field represents a larger unit of time. For example, DAY_OF_MONTH is larger than HOUR.

Let’s see an example of how to roll up months.

In this case, YEAR being a larger field will not be incremented:

@Test
public void test_whenRollUpOneMonth_thenYearIsUnchanged() {
    int rolledUpMonthJuly = 7, orginalYear2018 = 2018;
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 6, 28);
    calendarExpected.roll(Calendar.MONTH, 1);
 
    assertEquals(calendarExpected.get(Calendar.MONTH), rolledUpMonthJuly);
    assertEquals(calendarExpected.get(Calendar.YEAR), orginalYear2018);
}

Similarly, we can roll down months:

@Test
public void test_whenRollDownOneMonth_thenYearIsUnchanged() {
    int rolledDownMonthJune = 5, orginalYear2018 = 2018;
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 6, 28);
    calendarExpected.roll(Calendar.MONTH, -1);
 
    assertEquals(calendarExpected.get(Calendar.MONTH), rolledDownMonthJune);
    assertEquals(calendarExpected.get(Calendar.YEAR), orginalYear2018);
}

We can directly set a calendar field to a specified value using the set() method. The calendar’s time value in milliseconds will not recomputed until the next call to get(), getTime(), add() or roll() is made.

Thus, multiple calls to set() don’t trigger unnecessary computations.

Let’s see an example which will set the month field to 3 (i.e. April):

@Test
public void test_setMonth() {
    GregorianCalendarExample calendarDemo = new GregorianCalendarExample();
    GregorianCalendar calendarActual = new GregorianCalendar(2018, 6, 28);
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 6, 28);
    calendarExpected.set(Calendar.MONTH, 3);
    Date expectedDate = calendarExpected.getTime();

    assertEquals(expectedDate, calendarDemo.setMonth(calendarActual, 3));
}

2.4. Working With XMLGregorianCalendar

JAXB allows mapping Java classes to XML representations. The  javax.xml.datatype.XMLGregorianCalendar type can help in mapping the basic XSD schema types such as xsd:date, xsd:time and xsd:dateTime.

Let’s have a look at an example to convert from GregorianCalendar type into the XMLGregorianCalendar type:

@Test
public void test_toXMLGregorianCalendar() throws Exception {
    GregorianCalendarExample calendarDemo = new GregorianCalendarExample();
    DatatypeFactory datatypeFactory = DatatypeFactory.newInstance();
    GregorianCalendar calendarActual = new GregorianCalendar(2018, 6, 28);
    GregorianCalendar calendarExpected = new GregorianCalendar(2018, 6, 28);
    XMLGregorianCalendar expectedXMLGregorianCalendar = datatypeFactory
      .newXMLGregorianCalendar(calendarExpected);
 
    assertEquals(
      expectedXMLGregorianCalendar, 
      alendarDemo.toXMLGregorianCalendar(calendarActual));
}

Once the calendar object has been translated into XML format, it can be used in any use cases that require a date to be serialized, like messaging or web service calls.

Let’s see an example on how to convert from XMLGregorianCalendar type back into GregorianCalendar:

@Test
public void test_toDate() throws DatatypeConfigurationException {
    GregorianCalendar calendarActual = new GregorianCalendar(2018, 6, 28);
    DatatypeFactory datatypeFactory = DatatypeFactory.newInstance();
    XMLGregorianCalendar expectedXMLGregorianCalendar = datatypeFactory
      .newXMLGregorianCalendar(calendarActual);
    expectedXMLGregorianCalendar.toGregorianCalendar().getTime();
    assertEquals(
      calendarActual.getTime(), 
      expectedXMLGregorianCalendar.toGregorianCalendar().getTime() );
}

2.5. Comparing Dates

We can use the Calendar classes’ compareTo() method to compare dates. The result will be positive if the base date is in the future and negative if the base data is in the past of the date we compare it to:

@Test
public void test_Compare_Date_FirstDate_Greater_SecondDate() {
    GregorianCalendar firstDate = new GregorianCalendar(2018, 6, 28);
    GregorianCalendar secondDate = new GregorianCalendar(2018, 5, 28);
    assertTrue(1 == firstDate.compareTo(secondDate));
}

@Test
public void test_Compare_Date_FirstDate_Smaller_SecondDate() {
    GregorianCalendar firstDate = new GregorianCalendar(2018, 5, 28);
    GregorianCalendar secondDate = new GregorianCalendar(2018, 6, 28);
    assertTrue(-1 == firstDate.compareTo(secondDate));
}

@Test
public void test_Compare_Date_Both_Dates_Equal() {
    GregorianCalendar firstDate = new GregorianCalendar(2018, 6, 28);
    GregorianCalendar secondDate = new GregorianCalendar(2018, 6, 28);
    assertTrue(0 == firstDate.compareTo(secondDate));
}

2.6. Formatting Dates

We can convert GregorianCalendar into a specific format by using a combination of ZonedDateTime and DateTimeFormatter to get the desired output:

@Test
public void test_dateFormatdMMMuuuu() {
    String expectedDate = new GregorianCalendar(2018, 6, 28).toZonedDateTime()
      .format(DateTimeFormatter.ofPattern("d MMM uuuu"));
    assertEquals("28 Jul 2018", expectedDate);
}

2.7. Getting Information About the Calendar

GregorianCalendar provides several get methods which can be used to fetch different calendar attributes. Let’s look at the different options we have:

• getActualMaximum(int field) – returns the maximum value for the specified calendar field taking into consideration the current time values. The following example will return value 30 for the DAY_OF_MONTH field because June has 30 days:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(30 == calendar.getActualMaximum(calendar.DAY_OF_MONTH));

• getActualMinimum(int field) – returns the minimum value for the specified calendar field taking into consideration the current time values:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(1 == calendar.getActualMinimum(calendar.DAY_OF_MONTH));

• getGreatestMinimum(int field) – returns the highest minimum value for the given calendar field:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(1 == calendar.getGreatestMinimum(calendar.DAY_OF_MONTH));

• getLeastMaximum(int field) – Returns the lowest maximum value for the given calendar field. For the DAY_OF_MONTH field this is 28, because February may have only 28 days:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(28 == calendar.getLeastMaximum(calendar.DAY_OF_MONTH));

• getMaximum(int field) – returns the maximum value for the given calendar field:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(31 == calendar.getMaximum(calendar.DAY_OF_MONTH));

• getMinimum(int field) – returns the minimum value for the given calendar field:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(1 == calendar.getMinimum(calendar.DAY_OF_MONTH));

• getWeekYear() – returns the year of the week represented by this GregorianCalendar:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(2018 == calendar.getWeekYear());

• getWeeksInWeekYear() – returns the number of weeks in the week year for the calendar year:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(52 == calendar.getWeeksInWeekYear());

• isLeapYear() – returns true if the year is a leap year:

  GregorianCalendar calendar = new GregorianCalendar(2018 , 5, 28);
  assertTrue(false == calendar.isLeapYear(calendar.YEAR));

3. Conclusion

In this article, we explored certain aspects of GregorianCalendar.