Ръководство за java.util.GregorianCalendar

1. Въведение

В този урок ще разгледаме набързо класа GregorianCalendar .

2. GregorianCalendar

GregorianCalendar е конкретна реализация на абстрактния клас java.util.Calendar . Не е изненадващо, че Григорианският календар е най-често използваният граждански календар в света.

2.1. Получаване на инстанция

Налични са две опции за получаване на екземпляр на GregorianCalendar: Calendar.getInstance () и използване на един от конструкторите.

Използването на статичния фабричен метод Calendar.getInstance () не е препоръчителен подход, тъй като ще върне субективен екземпляр към локала по подразбиране.

Може да върне будистки календар за тайландски или японски имперски календар за Япония. Непознаването на типа на връщания екземпляр може да доведе до 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; }

Използвайки един от седемте претоварени конструктора, можем да инициализираме обекта Календар или с датата и часа по подразбиране в зависимост от локала на нашата операционна система, или можем да посочим комбинация от дата, час, локал и часова зона.

Нека разберем различните конструктори, чрез които обект GregorianCalendar може да бъде създаден.

Конструкторът по подразбиране ще инициализира календара с текущата дата и час в часовата зона и локала на операционната система:

new GregorianCalendar();

Можем да посочим година, месец, dayOfMonth, hourOfDay, минута и секунда за часовата зона по подразбиране с локала по подразбиране:

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

Имайте предвид, че не е необходимо да посочваме hourOfDay, минута и секунда, тъй като има други конструктори без тези параметри.

Можем да предадем часовата зона като параметър, за да създадем календар в тази часова зона с локал по подразбиране:

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

Можем да предадем локала като параметър, за да създадем календар в този локал с часовата зона по подразбиране:

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

И накрая, можем да предадем и часовата зона, и локала като параметри:

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

2.2. Нови методи с Java 8

С Java 8 в GregorianCalendar са въведени нови методи .

Методът from () получава екземпляр на GregorianCalendar с локал по подразбиране от обект ZonedDateTime.

Използвайки getCalendarType (), можем да получим типа на екземпляра на календара. Наличните типове календари са „григорий“, „будистки“ и „японски“.

Можем да използваме това, например, за да сме сигурни, че имаме календар от определен тип, преди да продължим с нашата логика на приложението:

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

Повикване toZonedDateTime () можем да конвертирате календарната обекта в ZonedDateTime обект , който представлява една и съща точка на времевата линия, тъй като това григориански календар.

2.3. Промяна на датите

Полетата на календара могат да бъдат модифицирани с помощта на методите add () , roll () и set () .

Методът add () ни позволява да добавяме време към календара в определена единица въз основа на вътрешния набор от правила на календара:

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

Също така можем да използваме метода add () , за да извадим времето от обекта на календара:

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

Изпълнението на метода add () налага незабавно повторно изчисляване на милисекундите на календара и всички полета.

Имайте предвид, че използването на add () може също да промени по-високите полета на календара (MONTH в този случай).

Методът roll () добавя подписана сума към посоченото поле на календара, без да променя по-големите полета. По-голямото поле представлява по-голяма единица време. Например DAY_OF_MONTH е по-голям от HOUR.

Нека да видим пример как да навиваме месеци.

В този случай YEAR като по-голямо поле няма да бъде увеличено:

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

По същия начин можем да превъртаме месеци:

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

Можем директно да зададем поле за календар на определена стойност, използвайки метода set () . Стойността на времето в календара в милисекунди няма да бъде преизчислена, докато не бъде направено следващото повикване за get () , getTime () , add () или roll () .

По този начин многократните извиквания на set () не задействат ненужни изчисления.

Нека видим пример, който ще зададе полето месец на 3 (т.е. април):

@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. Работа с XMLGregorianCalendar

JAXB позволява съпоставяне на Java класове с XML представления. Типът javax.xml.datatype.XMLGregorianCalendar може да помогне при картографирането на основните типове XSD схеми като xsd: date , xsd: time и xsd: dateTime .

Нека да разгледаме пример за преобразуване от тип GregorianCalendar в тип 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

В тази статия разгледахме някои аспекти на GregorianCalendar .

Както винаги, примерният код е достъпен в GitHub.