Guía de java.util.GregorianCalendar

Programación

1. Introducción

En este tutorial, vamos a echar un vistazo rápido a la clase GregorianCalendar .

2. Calendario Gregoriano

GregorianCalendar es una implementación concreta de la clase abstracta java.util.Calendar . No es sorprendente que el calendario gregoriano sea el calendario civil más utilizado en el mundo.

2.1. Obtener una instancia

Hay dos opciones disponibles para obtener una instancia de GregorianCalendar: Calendar.getInstance () y usar uno de los constructores.

El uso del método de fábrica estático Calendar.getInstance () no es un enfoque recomendado, ya que devolverá una instancia subjetiva a la configuración regional predeterminada.

Puede devolver un BuddhistCalendar para Thai o JapaneseImperialCalendar para Japón. No saber el tipo de instancia que se devuelve puede dar lugar a una 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; }

Usando uno de los siete constructores sobrecargados, podemos inicializar el objeto Calendario con la fecha y hora predeterminadas dependiendo de la ubicación de nuestro sistema operativo o podemos especificar una combinación de fecha, hora, ubicación y zona horaria.

Entendamos los diferentes constructores mediante los cuales se puede crear una instancia de un objeto GregorianCalendar .

El constructor predeterminado inicializará el calendario con la fecha y hora actuales en la zona horaria y la configuración regional del sistema operativo:

new GregorianCalendar();

Podemos especificar el año, mes, dayOfMonth, hourOfDay, minuto y segundo para la zona horaria predeterminada con la configuración regional predeterminada:

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

Tenga en cuenta que no tenemos que especificar hourOfDay, minute y second, ya que hay otros constructores sin estos parámetros.

Podemos pasar la zona horaria como parámetro para crear un calendario en esta zona horaria con la configuración regional predeterminada:

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

Podemos pasar la configuración regional como parámetro para crear un calendario en esta configuración regional con la zona horaria predeterminada:

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

Finalmente, podemos pasar tanto la zona horaria como la configuración regional como parámetros:

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

2.2. Nuevos métodos con Java 8

Con Java 8, se han introducido nuevos métodos en GregorianCalendar.

El método from () obtiene una instancia de GregorianCalendar con la configuración regional predeterminada de un objeto ZonedDateTime.

Usando getCalendarType () podemos obtener el tipo de instancia de calendario. Los tipos de calendario disponibles son 'gregory', 'budista' y 'japonés'.

Podemos usar esto, por ejemplo, para asegurarnos de que tenemos un calendario de cierto tipo antes de continuar con la lógica de nuestra aplicación:

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

Al llamar a toZonedDateTime () podemos convertir el objeto de calendario en un objeto ZonedDateTime que representa el mismo punto en la línea de tiempo que este GregorianCalendar.

2.3. Modificar fechas

Los campos del calendario se pueden modificar utilizando los métodos add () , roll () y set () .

El método add () nos permite agregar tiempo al calendario en una unidad específica basada en el conjunto de reglas internas del calendario:

@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); }

También podemos usar el método add () para restar tiempo del objeto de calendario:

@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); }

La ejecución del método add () fuerza un recálculo inmediato de los milisegundos del calendario y todos los campos.

Tenga en cuenta que el uso de add () también puede cambiar los campos de calendario superiores (MES en este caso).

El método roll () agrega una cantidad firmada al campo de calendario especificado sin cambiar los campos más grandes. Un campo más grande representa una unidad de tiempo más grande. Por ejemplo, DAY_OF_MONTH es mayor que HOUR.

Veamos un ejemplo de cómo acumular meses.

En este caso, YEAR siendo un campo más grande no se incrementará:

@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); }

Del mismo modo, podemos acumular meses:

@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); }

Podemos establecer directamente un campo de calendario en un valor especificado usando el método set () . El valor de tiempo del calendario en milisegundos no se volverá a calcular hasta que se realice la siguiente llamada a get () , getTime () , add () o roll () .

Por lo tanto, múltiples llamadas a set () no activan cálculos innecesarios.

Veamos un ejemplo que establecerá el campo del mes en 3 (es decir, abril):

@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. Trabajar con XMLGregorianCalendar

JAXB permite mapear clases Java a representaciones XML. El tipo javax.xml.datatype.XMLGregorianCalendar puede ayudar a mapear los tipos de esquemas XSD básicos como xsd: date , xsd: time y xsd: dateTime .

Echemos un vistazo a un ejemplo para convertir del tipo GregorianCalendar al tipo XMLGregorianCalendar :

@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

En este artículo, exploramos ciertos aspectos de GregorianCalendar .

Como siempre, el código de muestra está disponible en GitHub.