Sunday, April 17, 2022

Java Tutorial: Handling Date&Time

Chapters

Overview

Prior to java8, java.util.Date and java.sql.Date are widely used classes for handling date and time. In java 8 and above, classes in java.time are recommended to be used for handling date&time.

java.util.Date class is not recommended anymore due to lots of issues like implementing coordinated universal time(UTC). Although the Date class is intended to reflect coordinated universal time (UTC), it may not do so exactly, depending on the host environment of the Java Virtual Machine.

Nearly all modern operating systems assume that 1 day = 24 × 60 × 60 = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second". Prior to java 8, Joda-Time was used as an alternative for handling date & time.

java.util.Date and java.sql.Date

java.util.Date is a mutable class that represents a specific instant in time, with millisecond precision since the 1st of January 1970 00:00:00 GMT(the epoch time). Since java 8, several constructors and methods of this class have been deprecated. However, there are few constructors and methods left that we can use.

To instantiate a java.util.Date instance, we can use two constructors: Date() and Date(long date). This example demonstrates these two constructors.
import java.util.Date;

public class SampleClass{

  public static void main(String[] args){
    Date currentDate = new Date();
    Date specificDate = new Date(1332416372111L);
    Date epoch = new Date(0);
    
    System.out.println(currentDate);
    System.out.println(specificDate);
    System.out.println(epoch);
  }
}

Result(may vary)
Mon Mar 21 04:37:24 CST 2022
Thu Mar 22 19:39:32 CST 2012
Thu Jan 01 00:00:00 CST 1970
Date() constructor creates a Date instance with the current date&time of our machine. Date(long date) creates a Date instance with date&time extracted from the given timestamp. To compare to Date objects, we can use equals method. We can also check if a Date object is before or after another Date object by invoking before and after methods. Take a look at this example.
import java.util.Date;

public class SampleClass{

  public static void main(String[] args){
    Date currentDate = new Date();
    Date specificDate = new Date(1332416372111L);
    Date specificDate2 = new Date(1332416372111L);
    
    System.out.println(currentDate.after(specificDate));
    System.out.println(specificDate.before(currentDate));
    System.out.println(specificDate.equals(specificDate2));
  }
}

Result
true
true
true
For formatting date values in Date objects, use DateFormat and SimpleDateFormat classes. I explained them in this article. Here's an example of formatting date using SimpleDateFormat.
import java.text.SimpleDateFormat;
import java.util.Date;

public class SampleClass{

  public static void main(String[] args){
    String pattern = "MM/dd/yyyy hh:mm:ss a";
    Date date = new Date(1332416372111L);
    
    SimpleDateFormat sdf =
    new SimpleDateFormat(pattern);
    
    String result = sdf.format(date);
    System.out.println("Unformatted");
    System.out.println(date);
    System.out.println("Formatted");
    System.out.println(result);
  }
}

Result
Unformatted
Thu Mar 22 19:39:32 CST 2012
Formatted
03/22/2012 07:39:32 PM
java.sql.Date is a thin wrapper around a millisecond value that allows JDBC to identify the instance of this class as an SQL DATE value. A milliseconds value represents the number of milliseconds that have passed since January 1, 1970 00:00:00.00 GMT.

Instance of this class must be "normalized" or in other words the hours, minutes, seconds, and milliseconds must be set to zero. java.sql.Date is a subclass of java.util.Date.

Since java 8, several constructors and methods of this class have been deprecated. However, there are few constructors and methods left that we can use. Take a look at this example.
import java.sql.Date;

public class SampleClass{

  public static void main(String[] args){
    Date date1 = new Date(0);
    Date date2 = new Date(0);
    
    System.out.println(date1);
    System.out.println(date1.after(date2));
    System.out.println(date2.before(date1));
    System.out.println(date1.equals(date2));
  }
}

Result
1970-01-01
false
false
true
Date(long date) Constructs a Date object using the given milliseconds time value or timestamp. before method returns true if the Date object that invokes the method precedes the given Date object. Otherwise, returns false. after method is the opposite of before method. equals returns true if both Date objects are equal. Otherwise, returns false.

For formatting date values in Date objects, use DateFormat and SimpleDateFormat classes. I explained them in this article.

To support SQL data types related to time like SQL TIME and SQL TIMESTAMP, use Time and Timestamp classes. Time is a thin wrapper around the java.util.Date class that allows the JDBC API to identify this as an SQL TIME value. Timestamp is a thin wrapper around java.util.Date that allows the JDBC API to identify this as an SQL TIMESTAMP value.

In the description above, we can say that java.util.Date should be used for handling date&time in our program whereas java.sql.Date should be used as a wrapper for date values when dealing with databases.

Calendar Class

Calendar class is an abstract class that provides methods for converting between a specific instant in time and a set of calendar fields such as YEAR, MONTH, DAY_OF_MONTH, HOUR, and so on, and for manipulating the calendar fields, such as getting the date of the next week.

An instant in time can be represented by a millisecond value that is an offset from the Epoch, January 1, 1970 00:00:00.00 GMT (Gregorian). The class also provides additional fields and methods for implementing a concrete calendar system. Those fields and methods are defined as protected.

Since java 8, most setter and getter methods of java.util.Date and java.sql.Date are deprecated. However, java introduces Calendar class. This class has getter and setter methods that interact with date attributes like days, months, time, etc.

To instantiate an object related to Calendar object, we use the getInstance method. This method is a static method has for overloaded form.
getInstance()
getInstance(Locale aLocale)
getInstance(TimeZone zone)
getInstance(TimeZone zone, Locale aLocale)
This example demonstrates Calendar class.
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    
    System.out.println("System's Default Locale");
    System.out.println(Locale.getDefault());
    System.out.println("System's Default TimeZone");
    System.out.println(TimeZone.getDefault().getID());
    System.out.println();
    
    System.out.println("Available Calendar Types");
    for(String s : calendar.getAvailableCalendarTypes())
      System.out.println(s);
    System.out.println();
    
    System.out.println("Calendar Type: " + 
    calendar.getCalendarType());
    System.out.println("Calendar object instance" +
    " of GregorianCalendar?");
    System.out.println(calendar instanceof GregorianCalendar);
    System.out.println();
    
    Date date1 = calendar.getTime();
    System.out.println("getTime: " + date1);
    long timestamp = calendar.getTimeInMillis();
    Date date2 = new Date(timestamp);
    System.out.println("getTimeInMillis: " + date2);
    System.out.println();
    
  }
}

Result(may vary)
System's Default Locale
en_US
System's Default TimeZone
Asia/Taipei

Available Calendar Types
gregory
buddhist
japanese

Calendar Type: gregory
Calendar Object instance of GregorialCalendar?
true

getTime: Wed Mar 23 17:23:51 CST 2022
getTimeInMillis: Wed Mar 23 17:23:51 CST 2022
First off, I invoke getInstance() method. This method returns a Calendar object with default time zone and locale. In my system, the default locale "en-US" which is synonymous with Locale.US. My system's default timezone is "Asia/Taipei". Take note that getInstance() is inconsistent because every system may have different default locale, timezone and calendar type.

To create a Calendar with consistent locale and timezone, use getInstance(TimeZone zone, Locale aLocale) method and set the locale and timezone that you like. If you just want a consistent locale, use getInstance(Locale aLocale) method. If you just want a consistent timezone, use getInstance(TimeZone zone).

To get system's default locale, use Locale.getDefault() method. To get system's default timezone, use TimeZone.getDefault() method. To get the String representation of a timezone in TimeZone object, use getID() method.

getAvailableCalendarTypes method returns a Set<String> object that contains calendar type names. In the example above, there are three available calendar types: gregory, buddhist and japanese. The default calendar type is "gregory" which stands for "Gregorian". To use other calendar types, instantiate a Calendar object using Calendar.Builder.

For basic instantiation, call Calendar.Builder.setCalendarType(String type) method and then build the Calendar by calling build method. For example, Calendar c = Calendar.Builder.setCalendarType("japanese").build()

getCalendarType returns the type of a Calendar object. In the example above, the calendar type is "gregory". Notice that the Calendar object in the example is an instance of GregorianCalendar. GregorianCalendar is a concrete implementation of Calendar provides the standard calendar system used by most of the world, which is the Gregorian Calendar. We will discuss that class later.

getTime method returns a java.util.Date object where the date&time of the Calendar object is wrapped into. getTimeInMillis method returns the Calendar object's date&time in milliseconds. We can use this methods to convert Calendar object's date&time to java.util.Date or java.sql.Date.

To convert java.util.Date or java.sql.Date date&time to Calendar, use setTime(java.util.Date date). To convert a timestamp(millis) to Calendar, use setTimeInMillis method.

Displaying Date&Time Field Names/Values

To diplay Calendar field numerical value, we use get method. To display Calendar field name, use getDisplayName method. To display all fields of a Calendar field, use getDisplayNames method. Take note that not all Calendar fields have names and fields. This example demonstrates methods that are mentioned above.
import java.util.Calendar;
import java.util.Locale;
import java.util.Map;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
  
    System.out.println("Days");
    for(Map.Entry entry : calendar.getDisplayNames(
                          Calendar.DAY_OF_WEEK,
                          Calendar.LONG_FORMAT,
                          Locale.US).entrySet())
      System.out.println(entry.getKey() + " | " +
                         entry.getValue());
    System.out.println();
    
    System.out.println("First Day of Week: " +
    calendar.getFirstDayOfWeek());
    System.out.println("Day of Week(Plain): " + 
    calendar.get(Calendar.DAY_OF_WEEK));
    System.out.println("Day of Week(Short Format, US): " + 
    calendar.getDisplayName(Calendar.DAY_OF_WEEK,
                            Calendar.SHORT_FORMAT,
                            Locale.US));
    System.out.println("Day of Week(Short Format, France): " + 
    calendar.getDisplayName(Calendar.DAY_OF_WEEK,
                 Calendar.SHORT_FORMAT,
                 Locale.FRANCE));
    System.out.println("Day of Week(Long Format, US): " + 
    calendar.getDisplayName(Calendar.DAY_OF_WEEK,
                            Calendar.LONG_FORMAT,
                            Locale.US));
  }
}

Result(may vary)
Days
Monday | 2
Thursday | 5
Friday | 6
Sunday | 1
Wednesday | 4
Tuesday | 3
Saturday | 7

First Day of Week: 1
Day of Week(Plain): 4
Day of Week(Short Format, US): Wed
Day of Week(Short Format, France): mer.
Day of Week(Long Format, US): Wednesday
getDisplayNames returns a Map object that contains fields of a field. In the example above, Calendar.DAY_OF_WEEK has 7 fields that represent days. Field with a numerical value of 1 is the first day of a week. First day of a week is locale-dependent. For example, in France, first day of a week is CALENDAR.MONDAY. In US, the first day of a week is CALENDAR.SUNDAY

getDisplayNames(int field, int style, Locale locale) has three parameters. field is a Calendar field with fields. Take note that most Calendar fields have a numerical(int) identifiers that are compatible with particular methods. For example, the numerical identifier of Calendar.DAY_OF_WEEK is compatible with getDisplayNames method. It's also compatible with getDisplayName method.

CALENDAR.SUNDAY is not compatible with getDisplayNames because it doesn't have its own fields. It's not also compatible with getDisplayName because it doesn't have display name. Its display name is in Calendar.DAY_OF_WEEK. getDisplayNames and getDisplayName return null or an exception if the numerical identifier of a field is not compatible with them.

style is the format of the extracted field data. There are different types of field formatting that we can use. You can refer to Calendar.ALL_STYLES field to see all available styles. locale is the specific locale of you choosing.

getDisplayName is similar to getDisplayNames and has the same parameters. Although, getDisplayName extracts display names of a field. For example, getDisplayName extracts the display name of the current day of a week from Calendar.DAY_OF_WEEK.

If a Calendar field contains a numerical value, use get method. In the example above, get method extracts the numerical identifier of Calendar.WEDNESDAY which is 4. This number is the current numerical value of Calendar.DAY_OF_WEEK.

Don't be confused with numerical value and numerical identifier. Numerical value is a representation of something whereas numerical identifier is an identifier to identify a Calendar field. For example, the numerical value of Calendar.DAY_OF_MONTH represents current day of our Calendar object.

To clarify further, take a look at this example.
System.out.println("identifier: "+Calendar.DAY_OF_WEEK); //7
System.out.println("value: "+Calendar.get(Calendar.DAY_OF_WEEK)); //4
Assume that these codes are part of the codebase in the example above. The first println returns 7. This number is the numerical identifier. The second println returns 4. This number is the numerical value.

getFirstDayOfWeek returns the numerical identifier of the first day of a week. In the example above, this method returns 4 which is the numerical identifier of Calendar.WEDNESDAY.

If you wanna change the first day of a week, use setFirstDayOfWeek(int value) method. The value parameter should be one of the numerical identifier of fields of Calendar.DAY_OF_WEEK. For example:
setFirstDayOfWeek(Calendar.MONDAY)

Take note that changing the first day of a week may affect the week count of Calendar class.

Date&Time Fields

Calendar class has lots of fields that we can use to obtain information regarding date&time. This example demonstrates obtaining information from some Calendar fields.
import java.util.Calendar;
import java.util.Locale;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
  
    System.out.println("Month: " +
    calendar.getDisplayName(Calendar.MONTH, 
                            Calendar.LONG_FORMAT,
                            Locale.US));
    System.out.println("Day: " +
    calendar.get(Calendar.DAY_OF_MONTH));
    System.out.println("Year: " +
    calendar.get(Calendar.YEAR));
    System.out.println("Hour(24-hour format): " +
    calendar.get(Calendar.HOUR_OF_DAY));
    System.out.println("Hour(12-hour format): " +
    calendar.get(Calendar.HOUR));
    System.out.println("Minutes: " +
    calendar.get(Calendar.MINUTE));
    System.out.println("Seconds: " +
    calendar.get(Calendar.SECOND));
    System.out.println("AM_PM: " +
    calendar.getDisplayName(Calendar.AM_PM,
                            Calendar.SHORT_FORMAT,
                            Locale.US));
    System.out.println();
    
    //If isWeekDateSupported method returns false,
    //your Calendar object doesn't support 
    //week dates and week-related fields may not
    //work as intended
    System.out.println("Week Date Supported? " +
    calendar.isWeekDateSupported());
    
    System.out.println("Week Year: " + 
    calendar.getWeekYear());
    System.out.println("Minimal Days in First Week: " + 
    calendar.getMinimalDaysInFirstWeek());
    System.out.println("Weeks in Week Year: " + 
    calendar.getWeeksInWeekYear());
    System.out.println("Week of Month: " + 
    calendar.get(Calendar.WEEK_OF_MONTH));
    System.out.println("Week of Year: " + 
    calendar.get(Calendar.WEEK_OF_YEAR));
  }
}

Result(may vary)
Month: March
Day: 23
Year: 2022
Hour(24-hour format): 17
Hour(12-hour format): 5
Minutes: 34
Seconds: 31
AM_PM: PM

Week Date Supported? true
Week Year: 2022
Minimal Days in First Week: 1
Weeks in Week Year: 53
Week of Month: 4
Week of Year: 13
In the specified date&time in a Calendar object, Calendar.MONTH holds month. Calendar.DAY_OF_MONTH holds day in the month Calendar.YEAR holds year. Calendar.HOUR_OF_DAY holds hours in 24-hour format. Calendar.HOUR holds hours in 12-hour format. Calendar.MINUTE holds minutes. Calendar.SECOND holds seconds. Calendar.AM_PM holds AM or PM value.

Calendar.WEEK_OF_YEAR holds the week number in a year where Calendar.DAY_OF_MONTH belongs. In the example above, day 23 of March is in week 13 of year 2022. Calendar.WEEK_OF_MONTH holds the week number in a month where Calendar.DAY_OF_MONTH belongs.

In the example above, day 23 of March is in week 4 of March 2022. getWeeksInWeekYear returns the total number of weeks in a year. In the example above, year 2022 has a total of 53 weeks.

Take note that WEEK_OF_YEAR, DAY_OF_MONTH, WEEK_OF_MONTH and the return value of getWeeksInWeekYear are affected by minimal days in first week. Minimal days are minimum days required for a first week to be part of next month. Take a look at this example.
import java.util.GregorianCalendar;
import java.util.Calendar;
import java.util.Locale;

public class SampleClass{

  public static void main(String[] args){
    GregorianCalendar calendar1 =
    new GregorianCalendar(1998, Calendar.JANUARY, 1);
    calendar1.setFirstDayOfWeek(Calendar.MONDAY);
    calendar1.setMinimalDaysInFirstWeek(4);
    System.out.println("Output #1");
    System.out.println("Week Year: " + 
    calendar1.getWeekYear());
    System.out.println();
    
    calendar1.setFirstDayOfWeek(Calendar.SUNDAY);
    System.out.println("Output #2");
    System.out.println("Week Year: " + 
    calendar1.getWeekYear());
    System.out.println();
    
    calendar1.setFirstDayOfWeek(Calendar.TUESDAY);
    System.out.println("Output #3");
    System.out.println("Week Year: " + 
    calendar1.getWeekYear());
    System.out.println();
    
  }
}

Result
Output #1
Week Year: 1998

Output #2
Week Year: 1997

Output #3
Week Year: 1998
First off, getWeekYear returns the year where the week belongs. In the example above, minimal days in first week is set to 4 and first day of week is set to Calendar.MONDAY. getWeekYear returns 1998 because the week where jan 1 belongs is part of 1998. This week starts from first day of week which is monday. Monday in this week is dec 29.

If we count days from the first day of next month(jan 1) up to the day before the first day of week, those days are the minimal days. So, jan 1 is thursday, jan 2 is friday, jan 3 is saturday and jan 4 is sunday. Those days sum up to 4 which is the value that we assign to setMinimalDaysInFirstWeek. Thus, we can say that the week starting from monday, dec 29, 1997 to sunday, jan 4, 1998 is part of 1998.

In Output #2, the returned week year is 1997 because I changed the first day of week to sunday. If we count days from the first day of next month(jan 1) up to the day before the first day of week, the total minimal days is less than 4. Thus, we can say that the week starting from sunday, dec 28, 1997 to saturday, jan 3, 1998 is part of 1997.

In Output #3, the returned week year is 1998 because I changed the first day of week to tuesday. If we count days from the first day of next month(jan 1) up to the day before the first day of week, the total minimal days is greater than 4. Thus, we can say that the week starting from tuesday, dec 30, 1997 to monday, jan 5, 1998 is part of 1998.

In ISO 8601 standard, the default first day of week is monday and the default minimal days in first week is 4. To see the effect of minimal days in other week-related fields, take a look at this example.
import java.util.GregorianCalendar;
import java.util.Calendar;
import java.util.Locale;

public class SampleClass{

  public static void main(String[] args){
    GregorianCalendar calendar1 =
    new GregorianCalendar(1998, Calendar.JANUARY, 1);
    calendar1.setFirstDayOfWeek(Calendar.MONDAY);
    calendar1.setMinimalDaysInFirstWeek(4);
    System.out.println("Output #1");
    System.out.println("Week Year: " + 
    calendar1.getWeekYear());
    System.out.println("Week of Year: " + 
    calendar1.get(Calendar.WEEK_OF_YEAR));
    System.out.println("Week of Month: " + 
    calendar1.get(Calendar.WEEK_OF_MONTH));
    System.out.println();
    
    calendar1.setFirstDayOfWeek(Calendar.SUNDAY);
    System.out.println("Output #2");
    System.out.println("Week Year: " + 
    calendar1.getWeekYear());
    System.out.println("Week of Year: " + 
    calendar1.get(Calendar.WEEK_OF_YEAR));
    System.out.println("Week of Month: " + 
    calendar1.get(Calendar.WEEK_OF_MONTH));
    System.out.println();
    
  }
}

Result
Output #1
Week Year: 1998
Week of Year: 1
Week of Month: 1

Output #2
Week Year: 1997
Week of Year: 53
Week of Month: 0
In the result above, Output #1 indicates that the week is part of 1998. Output #2 indicates that the week is part of 1997. If you're wondering why week of month in Output #2 is 0, a zero week of month means that the week where the specified day belongs is part of previous month. Thus, we can say that the week where jan 1, 1998 belongs is part of december 1997.

add(), set() and roll() Methods

add, set and roll methods are essentials method in Calendar class. Let's start with set method. set method has multiple forms and I'm gonna demonstrate two of them:
set(int field, int value)
set(int year, int month, int date)
We can set a value to a particular Calendar field by using the first one. If we want to set year, month and day by invoking set method once, use the second form. This example demonstrates set method.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    System.out.println(calendar.getTime());
    calendar.set(Calendar.YEAR, 1994);
    System.out.println(calendar.getTime());
    calendar.set(2012, Calendar.SEPTEMBER, 1);
    System.out.println(calendar.getTime());
  }
}

Result(may vary)
Sat Mar 26 20:22:24 CST 2022
Sat Mar 26 20:22:24 CST 1994
Sat Sep 01 20:22:24 CST 2012
Take note that calling set method alone doesn't recompute time value in milliseconds until the next call to get, getTime, getTimeInMillis, add, or roll method is made.

Example: Consider a GregorianCalendar originally set to August 31, 1999. Calling set(Calendar.MONTH, Calendar.SEPTEMBER) sets the date to September 31, 1999. This is a temporary internal representation that resolves to October 1, 1999 if getTime()is then called.

However, a call to set(Calendar.DAY_OF_MONTH, 30) before the call to getTime() sets the date to September 30, 1999, since no recomputation occurs after set() itself. To check if a Calendar field has been set or will be changed, call isSet method.

If you wanna set time, use these overloaded forms of set method.
set(int year, int month, int date, int hourOfDay, int minute)
set(int year, int month, int date, int hourOfDay, int minute, int second)

add(f, delta) adds delta to field f. Unlike set method, this method recomputes and adjusts date&time values if it's invoked. This example demonstrates add method.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    calendar.set(2010, Calendar.JANUARY, 31);
    System.out.println(calendar.getTime());
    calendar.add(Calendar.MONTH, 13);
    System.out.println(calendar.getTime());
  }
}

Result(may vary)
Mon Jan 31 08:59:15 CST 2010
Wed Feb 28 08:59:15 CST 2011
In the example above, the original date is Jan 13, 2010 then, I added additional 13 months to Calendar.MONTH field. The date was changed to Feb and as you can see, the day was adjusted from 31 to 28. This adjustment was necessary because maximum day(no leap year) of February in Gregorian Calendar is day 28. Also, the year was changed to 2011.

roll method is just like add except for the adjustments. Unlike add, roll method doesn't adjust larger field. Larger field represents a larger unit of time than the given field. Smaller field represents a smaller unit of time than the given field. This example demonstrates roll method.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    calendar.set(2010, Calendar.JANUARY, 31);
    System.out.println(calendar.getTime());
    calendar.roll(Calendar.MONTH, 15);
    System.out.println(calendar.getTime());
  }
}

Result(may vary)
Sun Jan 31 09:26:08 CST 2010
Fri Apr 30 09:26:08 CST 2010
In the example above, the original date is Jan 31, 2010. We can see from the result that the day is adjusted to 30 and the day of week is changed to Fri. However, the year stays the same. Year doesn't change because Calendar.YEAR field is larger than Calendar.MONTH. Calendar.DAY_OF_MONTH field is smaller than Calendar.MONTH.

Just remember this general time diagram to easily determine which field is smaller and larger.
MILLISECOND < SECOND < MINUTE < HOUR < DAY_OF_MONTH < MONTH < YEAR
In the diagram above, MILLISECOND is the smallest unit of time and YEAR is the largest unit of time. Take note that week-related fields like DAY_OF_WEEK can be a given value for set, add and roll. Take a look at this example.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    calendar.setFirstDayOfWeek(Calendar.SUNDAY);
    calendar.set(2010, Calendar.DECEMBER, 31);
    System.out.println(calendar.getTime());
    calendar.roll(Calendar.DAY_OF_WEEK, 1);
    System.out.println(calendar.getTime());
    
    calendar.set(2010, Calendar.DECEMBER, 31);
    calendar.setFirstDayOfWeek(Calendar.SUNDAY);
    calendar.roll(Calendar.DAY_OF_WEEK, 2);
    System.out.println(calendar.getTime());
  }
}

Result(may vary)
Fri Dec 31 10:18:35 CST 2010
Sat Jan 01 10:18:35 CST 2011
Sun Dec 26 10:18:35 CST 2010
In the third println, the date rolled back to Dec 26. This happened because when roll is used with DAY_OF_WEEK, changes revolve within the boundary of week. In the example above, first day of week starts at sunday which is Dec 26. Dec 26, 2010(Sunday) to Jan 01, 2011(Saturday) is the week where the given date(Dec 31, 2010) belongs.

In the second println, the date didn't roll back because the new date is in the boundary of the week. In the third println, the date rolled back to Dec 26 because the new date(Jan 02, 2011) would have been out of the boundary of the week.

A more detailed explanation about set, add and roll methods can be found in the documentation.

getActualMinimum() getActualMaximum() Methods

getActualMinimum and getActualMaximum methods return the minimum and maximum value that the specified calendar field could have, given the time value of this Calendar. The default implementation of this method uses an iterative algorithm to determine the actual minimum value for the calendar field.

Subclasses should, if possible, override this with a more efficient implementation. For getActualMinimum, getMinimum is simply returned in many cases. This example demonstrates these two methods.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    calendar.set(2022, Calendar.FEBRUARY, 1);
    System.out.println("Max Day of Month: " + 
    calendar.getActualMaximum(Calendar.DAY_OF_MONTH));
    calendar.set(2012, Calendar.FEBRUARY, 1);
    System.out.println("Max Day of Month: " + 
    calendar.getActualMaximum(Calendar.DAY_OF_MONTH));
    System.out.println("Min Week of Month: " + 
    calendar.getActualMinimum(Calendar.WEEK_OF_MONTH));
  }
}

Result(may vary)
Max Day of Month: 28
Max Day of Month: 29
Min Week of Month: 0
setWeekDate() Method

This method sets the date of this Calendar with the given date specifiers - week year, week of year, and day of week. Unlike the set method, all of the calendar fields and time values are calculated upon return. This example demonstrates this method.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    Calendar calendar = Calendar.getInstance();
    System.out.println(calendar.getTime());
    if(calendar.isWeekDateSupported()){
      calendar.setWeekDate(2022, 40, Calendar.FRIDAY);
      System.out.println(calendar.getTime());
    }
    else System.out.println("Week Dates not Supported!");
  }
}

Result(may vary)
Mon Mar 28 20:20:59 CST 2022
Fri Sep 30 20:20:59 CST 2022
If your Calendar object doesn't support week dates, setWeekDate may not work properly or may throw UnsupportedOperationException.

Lenient and Non-Lenient Modes

Calendar has two modes for interpreting the calendar fields, lenient and non-lenient. When a Calendar is in lenient mode, it accepts a wider range of calendar field values than it produces. When a Calendar recomputes calendar field values for return by get(), all of the calendar fields are normalized. For example, a lenient GregorianCalendar interprets MONTH == JANUARY, DAY_OF_MONTH == 32 as February 1.

When a Calendar is in non-lenient mode, it throws an exception if there is any inconsistency in its calendar fields. For example, a GregorianCalendar always produces DAY_OF_MONTH values between 1 and the length of the month. For example, A non-lenient GregorianCalendar throws an exception upon calculating its time or calendar field values if any out-of-range field value has been set.

This example demonstrates lenient and non-lenient modes.
import java.util.Calendar;
import java.util.GregorianCalendar;

public class SampleClass{

  public static void main(String[] args){
    GregorianCalendar calendar =
    new GregorianCalendar(2010, Calendar.JANUARY, 1);
    
    System.out.println("Lenient? " + 
    calendar.isLenient());
    
    calendar.set(Calendar.DAY_OF_MONTH, 32);
    System.out.println(calendar.getTime());
    
    calendar = new GregorianCalendar(
               2010, Calendar.JANUARY, 1);
    calendar.setLenient(false);
    calendar.set(Calendar.DAY_OF_MONTH, 32);
    System.out.println(calendar.getTime());
  }
}

Result
Lenient? true
Mon Feb 01 00:00:00 CST 2010
...IllegalArgumentException...
isLenient methods returns true if a Calendar object is lenient. Otherwise, returns false. setLenient sets the Calendar object to lenient or non-lenient mode.

Comparing Dates

Calendar class has methods that can be used to make a comparison between dates. Take a look at this example.
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
   Calendar calendar1 = Calendar.getInstance();
   calendar1.clear();
   calendar1.set(1994, Calendar.SEPTEMBER, 1);
   Calendar calendar2 = Calendar.getInstance();
   calendar2.clear();
   calendar2.set(1994, Calendar.SEPTEMBER, 1);
   
   System.out.println(calendar1.after(calendar2));
   System.out.println(calendar2.before(calendar1));
   System.out.println();
   calendar1.setLenient(false);
   System.out.println(calendar1.compareTo(calendar2));
   System.out.println(calendar1.equals(calendar2));
  }
}

Result
false
false

0
false
clear method resets date and time of this calendar(calendar1) to Calendar-specific defaults. For example, the default date and time is January 1, 1970 00:00:00(also called Unix time or Epoch time). This method also sets isSet boolean flag to false for all the calendar fields, and the date and time calculations will treat the fields as if they had never been set.

If you wanna reset a single Calendar field, you can use clear(int field) method. This method set isSet boolean flag to false for the specific Calendar field. This method may reset the Calendar field to its Calendar-specific default value.

after method returns true if the date and time of Calendar object that calls the method is after the date and time of the given Calendar object. Otherwise, returns false. before method is the opposite of after method.

compareTo method returns 0 if the millisecond representation of both dates are equals. Otherwise, returns a non-zero integer. compareTo returns a negative integer if the millisecond(offset from epoch) of the given date is greater than the millisecond(offset from epoch) of the other date. Returns a positive integer if the millisecond of the given date is less than the millisecond of the other date.

equals method compares millisecond(offset from epoch) and some parameters of two Calendar objects. The Calendar parameters are the values represented by the isLenient, getFirstDayOfWeek, getMinimalDaysInFirstWeek and getTimeZone methods. If there is any difference in those parameters between the two Calendars, this method returns false.

GregorianCalendar Class

GregorianCalendar is a concrete subclass of Calendar and provides the standard calendar system used by most of the world. This class implements proleptic Gregorian and Julian calendars.

That is, dates are computed by extrapolating the current rules indefinitely far backward and forward in time. As a result,
GregorianCalendar
may be used for all years to generate meaningful and consistent results.

However, dates obtained using GregorianCalendar are historically accurate only from March 1, 4 AD onward, when modern Julian calendar rules were adopted. Before this date, leap year rules were applied irregularly, and before 45 BC the Julian calendar did not even exist.

Unlike Calendar class, this class has constructors that can set date and time individually. Take a look at this example.
import java.util.Calendar;
import java.util.GregorianCalendar;

public class SampleClass{

  public static void main(String[] args){
    GregorianCalendar gc = 
    new GregorianCalendar(2012, Calendar.FEBRUARY, 1);
    
    System.out.println("Actual Max: "+
    gc.getActualMaximum(Calendar.DAY_OF_MONTH));
    System.out.println("Max: "+
    gc.getMaximum(Calendar.DAY_OF_MONTH));
    System.out.println("Least Max: "+
    gc.getLeastMaximum(Calendar.DAY_OF_MONTH));
    System.out.println();
    
    System.out.println("Actual Min: "+
    gc.getActualMinimum(Calendar.DAY_OF_MONTH));
    System.out.println("Min: "+
    gc.getMinimum(Calendar.DAY_OF_MONTH));
    System.out.println("Greatest Min: "+
    gc.getGreatestMinimum(Calendar.DAY_OF_MONTH));
    System.out.println();
    
    System.out.println("Is 2012 a leap year? " +
    gc.isLeapYear(2012));
    System.out.println("Cutover Date: " + 
    gc.getGregorianChange());
  }
}

Result(may vary)
Actual Max: 29
Max: 31
Least Max: 28

Actual Min: 1
Min: 1
Greatest Min: 1

Is 2012 a leap year? true
Cutover Date: Fri Oct 15 00:00:00 CST 1582
GregorianCalendar(int year, int month, int dayOfMonth) constructs a GregorianCalendar with the given date set in the default time zone with the default locale. If you want to instantiate a GregorianCalendar with time set individally, use these two constructors.
GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay, int minute)
GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay, int minute, int second)

getActualMaximum returns the maximum value of a field in a specific date of the Calendar instance. If a year is leap year, the max day of month value that getActualMaximum can get in February is 29. In the example above, 2012 is a leap year. Thus, getActualMaximum returns 29.

getMaximum returns the maximum value of a field based on the maximum value that get method can get in any possible time value. The maximum day of month in Gregorian Calendar is 31. Thus, the maximum value that get method can get is 31.

getLeastMaximum returns the smallest max value that getActualMaximum can get in any possible time value. If a year is not leap year, the max day of month value that getActualMaximum can get in February is 28.

getActualMinimum returns the minimum value of a field in a specific date of the Calendar instance. getMinimum returns the minimum value of a field based on the minimum value that get method can get in any possible time value. getGreatestMinimum returns the highest min value that getActualMinimum can get in any possible time value.

These maximum and minimum related methods may be affected by the current values of the getFirstDayOfWeek, getMinimalDaysInFirstWeek, getGregorianChange and getTimeZone methods.

isLeapYear method returns true if the given year is a leap year. Otherwise, returns false.

getGregorianChange gets the Gregorian Calendar change date which is also called as the cutover date. This is the point when the switch from Julian dates to Gregorian dates occurred. Default is October 15, 1582 (Gregorian). Previous to this, dates will be in the Julian calendar. You can set your own cutover date by calling setGregorianChange(Date date) method.

You might ask what's the difference between Julian and Gregorian Calendar. The only difference between the Gregorian and the Julian calendar is the leap year rule. The Julian calendar specifies leap years every four years, whereas the Gregorian calendar specifies leap years every four years but omits century years which are not divisible by 400.

For example, In Gregorian Calendar, year 1600 and 2000 are leap years because they're divisible by 400. Year 1700, 1800 and 1900 are not leap years because they're not divisible by 400.

TimeZone Class

TimeZone is an abstract class that represents a time zone offset, and also figures out daylight savings. A time zone is an area that observes a uniform standard time for legal, commercial and social purposes.

To obtain the time zone where java platform is running, use the getDefault static method. If we want to obtain a time zone via ID name, use getTimeZone(String ID) static method. If you're using Calendar class, you can call getTimeZone() method. This example demonstrates TimeZone class and some of its methods.
import java.util.TimeZone;
import java.util.Calendar;

public class SampleClass{

  public static void main(String[] args){
    //get system's default time zone
    TimeZone tz = TimeZone.getDefault();
    
    System.out.println("My Default TimeZone ID");
    System.out.println(tz.getID());
    System.out.println("Display Name(Long Format)");
    System.out.println(
    tz.getDisplayName(false, TimeZone.LONG));
    System.out.println("Daylight Saving Time?");
    System.out.println(tz.observesDaylightTime());
    System.out.println("Offset from UTC+-00:00");
    long millis = Calendar.getInstance().getTimeInMillis();
    System.out.println("Millis: "+ tz.getOffset(millis));
    double hour = tz.getOffset(millis) / 1000 / 60 / 60;
    System.out.println("Hour: " + hour);
    System.out.println();
  }
}

Result(may vary)
My Default TimeZone ID
Asia/Taipei
Display Name(Long Format)
Taipe Standard Time
Daylight Saving Time?
false
Offset UTC+-00:00
Millis: 28800000
Hour: 8.0
getID method returns the ID name of a time zone. We can use ID names in getTimeZone(String ID). getDisplayName(boolean daylight, int style) returns the display name of a time zone. daylight is a boolean type that determines that if true, the returned display name is daylight savings even the specified time zone doesn't follow daylight saving time. If false, standard display name is returned.

display is the format of the display name. We can use TimeZone.SHORT or TimeZone.LONG for formatting time zones. getDisplayName has multiple forms. Look at them in the documentation.

observesDaylightTime method returns true if the specified time zone follows daylight saving time. Otherwise, returns false.

getOffset returns the offset of this time zone from UTC(UTC+-00:00) at the specified date. If Daylight Saving Time is in effect at the specified date, the offset value is adjusted with the amount of daylight saving.

This method returns a historically correct offset value if an underlying TimeZone implementation subclass supports historical Daylight Saving Time schedule and GMT offset changes. Take note that UTC is effectively a successor to Greenwich Mean Time.

This method returns the offset in milliseconds which can be converted to hour which one of the numbers that we see in this UTC/GMT time zone format:
UTC+-Hours:Minutes or GMT+-Hours:Minutes
Examples: UTC+08:00, GMT-10:00

If you're using Calendar class, a time offset from UTC is stored in Calendar.ZONE_OFFSET and Calendar.DST_OFFSET. Calendar.ZONE_OFFSET holds the raw offset. This offset is a time offset without adjustments due to Daylight Saving Time. Calendar.DST_OFFSET is a time offset with adjustments due to Daylight Saving Time.

SimpleTimeZone Class

SimpleTimeZone is a concrete subclass of TimeZone that represents a time zone for use with a Gregorian calendar. The class holds an offset from GMT, called raw offset, and start and end rules for a daylight saving time schedule.

Since it only holds single values for each, it cannot handle historical changes in the offset from GMT and the daylight saving schedule, except that the setStartYear method can specify the year when the daylight saving time schedule starts in effect.

This example demonstrates SimpleTimeZone and how to schedule daylight saving time.
import java.util.SimpleTimeZone;
import java.util.Calendar;
import java.util.GregorianCalendar;

public class SampleClass{

  public static void main(String[] args){
   SimpleTimeZone stz = 
   new SimpleTimeZone(1*60*60*1000, "Europe/Paris",
                      Calendar.APRIL, 1, -Calendar.SUNDAY,
                      3600000, SimpleTimeZone.UTC_TIME,
                      Calendar.OCTOBER, -1, Calendar.SUNDAY,
                      3600000, SimpleTimeZone.UTC_TIME,
                      3600000);
   stz.setStartYear(2021);
   System.out.println("Is SimpleTimeZone instance DST? " +
   stz.observesDaylightTime());
   
   System.out.println("Daylight Savings: " +
   stz.getDSTSavings());
   System.out.println("Raw Offset: " + 
   stz.getRawOffset());
   
   GregorianCalendar gc = new GregorianCalendar(
   2021, Calendar.APRIL, 4, 3, 0);
   gc.setTimeZone(stz);
   System.out.println("Is April 4, 2021 03:00 in DST? "+
   stz.inDaylightTime(gc.getTime()));
   System.out.println();
   
   System.out.println("Get time zone of gc");
   System.out.println("Time zone ID: "+
   gc.getTimeZone().getID());
 }
}

Result

Is SimpleTimeZone instance DST? true
Daylight Savings: 3600000
Raw Offset: 3600000
Is April 4, 2021 03:00 in DST? true

Get time zone of gc
Time zone ID: Europe/Paris
First off, let's examine this SimpleTimeZone constructor:
SimpleTimeZone(int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int startTimeMode, int endMonth, int endDay, int endDayOfWeek, int endTime, int endTimeMode, int dstSavings)
rawOffset is the offset from UTC/GMT time. ID is the ID name that we want to assign to our time zone.

startMonth, startDay, startDayOfWeek, startTime and startTimeMode are parameters for the start-rule of our scheduled daylight saving time.

endMonth, endDay, endDayOfWeek, endTime and endTimeMode are parameters for the end-rule of our scheduled daylight saving time.

startTime is the time where our scheduled daylight saving time starts. endTime is the time where our scheduled daylight saving time ends.

dstSavings is the saved daylight time per day in daylight saving time.

Month, day and day-of-week have different combinations that have different effects in the start-rule and end-rule of daylight saving time. You can read the combinations in the documentation.

In the example above, this combination in the start-rule:
Calendar.APRIL, 1, -Calendar.SUNDAY
means first Sunday in April. Therefore, the daylight saving time of stz starts on the first Sunday in April. Next, this combination in the end-rule:
Calendar.OCTOBER, -1, Calendar.SUNDAY means last Sunday in October. Therefore, the daylight saving time of stz ends on the last Sunday in October.

Next, let's talk about time mode. startTimeMode is the time mode for the start-rule. endTimeMode is the time mode for the end-rule. There are three time modes: WALL_TIME, STANDARD_TIME and UTC_TIME. startTimeMode and endTimeMode are applied to the startTime and endTime, respectively.

WALL_TIME represents local time with daylight time applied to the end-rule.
STANDARD_TIME represents local time without daylight time applied to start-rule and end-rule.
UTC_TIME represents Universal Time(UTC+-00:00) and doesn't apply daylight time to start-rule and end-rule.

For example, In the example above, the local time is UTC+01:00(1*60*60*1000 or 3600000 millis or one hour offset). Then, the start-rule of SimpleTimeZone instance in the example above is set to first sunday of April 2021. starting time is 3600000 millis or 1:00am in UTC time(24-hour format).

The returned value of inDaylightTime method is true. This means that April 4, 2021 03:00 is in the daylight saving time of stz. Make sure that gc Calendar time zone is stz. Otherwise, you may get a different result. Use setTimeZone method to set time zone to a Calendar instance, GregorianCalendar in this case.

setStartYear sets the daylight saving time starting year. inDaylightTime returns true if the given date and time is in the daylight saving time(DST) of the SimpleTimeZone that invokes the method. Otherwise, returns false. Now, let's discuss why April 4, 2021 03:00 is in the daylight saving time of stz.

First off, Start time is 1:00am(3600000 millis) in UTC time. Then, we convert that start time to our local time which is UTC+1(UTC+01:00). Thus, the starting time in UTC+1 is 2:00am. Then, we move the time forward by an hour because we assign 1 hour or 3600000 millis to dstSavings parameter. Now, DST starts at sunday, April 4, 2021 03:00am in UTC+1 DST.

Now, for the end-rule, end time is 1:00am(3600000 millis) in UTC time. Then, we convert that end time to our local time which is UTC+1(UTC+01:00). Thus, the end time in UTC+1 is 2:00am. Then, we move the time backward by an hour because we assign 1 hour or 3600000 millis to dstSavings parameter. Now, DST ends at sunday, October 31, 2021 01:00am in UTC+1 time.

If we change the endTimeMode to STANDARD_TIME, DST ends at sunday, October 31, 2021 00:00am in UTC+1 time. The result is different because we use a different type of time mode. STANDARD_TIME uses the given local time which is UTC+1 in this case. That's why ending time is 01:00am UTC+1 standard time, move backward by an hour and DST ends at 00:00am.

If we change the endTimeMode to WALL_TIME, DST ends at saturday, October 30, 2021 23:00pm in UTC+1 time. The result is different because we use a different type of time mode. WALL_TIME when applied to end-rule, uses local time with daylight time adjustment.

That's why ending time is 01:00am UTC+1 DST, convert ending time back to standard UTC+1 which 00:00am UTC+1, move time backward by an hour and DST ends at 23:00pm.

Now, to test if our DST schedule is working, take a look at this example.
import java.util.SimpleTimeZone;
import java.util.TimeZone;
import java.util.Calendar;
import java.util.GregorianCalendar;

public class SampleClass{
 
  public static void main(String[] args){
    SimpleTimeZone stz =
    new SimpleTimeZone(1*60*60*1000, "Europe/Paris",
                       Calendar.APRIL, 1, -Calendar.SUNDAY,
                       3600000, SimpleTimeZone.UTC_TIME,
                       Calendar.OCTOBER, -1, Calendar.SUNDAY,
                       3600000, SimpleTimeZone.UTC_TIME,
                       3600000);
    stz.setStartYear(2021);
    
    GregorianCalendar gc = new GregorianCalendar(
    2021, Calendar.APRIL, 4, 1, 50);
    gc.setTimeZone(stz);
    TimeZone.setDefault(stz);
    
    System.out.println(gc.getTime());
    gc.add(Calendar.MINUTE, 30);
    System.out.println(gc.getTime());
  }
}

Result
Sun Apr 4 01:50:00 CET 2021
Sun Apr 4 03:20:00 CEST 2021
In the example above, we see that once the time reached 2:00am, an hour was added to the time and the timezone changed from CET(Central European Time) to CEST(Central European Summer Time).

Don't forget to set your program's default timezone to the timezone we created. Use TimeZone.setDefault method to set our program's default timezone. This ensures that other date-time related classes like java.util.Date follow the timezone we created.

If you want to use SimpleTimeZone rules in ZonedDateTime in java.time package, we can convert SimpleTimeZone to ZoneId by calling toZoneId() method.

Aside from the SimpleTimeZone constructor that I demonstrated in the example above, SimpleTimeZone has three more constructors. These constructors:
SimpleTimeZone(int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int endMonth, int endDay, int endDayOfWeek, int endTime)

SimpleTimeZone(int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int endMonth, int endDay, int endDayOfWeek, int endTime, int dstSavings)
Uses WALL_TIME as default time mode for startTime and endTime.

This constructor:
SimpleTimeZone(int rawOffset, String ID)
Doesn't have daylight time schedule. However, we can use setStartRule and setEndRule methods to set a start-rule and end-rule if we want to assign new DST schedule to SimpleTimeZone instance.

Month, day and day-of-week combinations that I explained above is applicable here. Take note that these methods(and their overloaded forms) use WALL_TIME as default time mode.

Next, let's discuss the methods that I used in the example above. observesDaylightTime returns true if a TimeZone instance observes DST. Otherwise, returns false. getRawOffset returns the offset of a time zone from UTC. This method doesn't include the effect of DST.

If you want to get offset from UTC with DST adjustment, use getOffset method. To set raw offset, use setRawOffset method. More information can be found in the documentation.

java.time Package

The classes defined in java.time package represent the principle date-time concepts, including instants, durations, dates, times, time-zones and periods. They are based on the ISO calendar system, which is the de facto world calendar following the proleptic Gregorian rules. All the classes are immutable and thread-safe.

This API is new and improved alternative to old date-and-time-related classes like java.util.Date. Since java 8, this API is recommended to be used for handling date and time.

In this topic, I'm gonna be discussing classes that are commonly used and follow ISO-8601 calendar system such as LocalDate, LocalTime, LocalDateTime and ZonedDateTime. If you want to use a calendar other than ISO calendar system, you should read the classes and documentation in java.time.chrono package.

Classes like Month, DayOfWeek, Year, YearMonth and MonthDay are also classes that follow ISO-8601 although they store single-value or partial date/time information compared to the classes mentioned above.

All the instances of the classes mentioned above are called temporal objects because those classes implement Temporal or its superinterface which is the TemporalAccessor. Also, the classes mentioned above are immutable and thread-safe.

If you want to extend this API like adding different computations of date and time, you should read the classes and documentation in java.time.temporal package.

To quantify date, use Period class. To quantify time, use Duration class.

Instant, LocalDate, LocalTime, LocalDateTime, OffsetTime, OffsetDateTime and ZonedDateTime Classes

We can access and obtain date and time from these classes: Instant, LocalDate, LocalTime, OffsetTime, LocalDateTime, OffsetDateTime and ZonedDateTime.

To format the values of these date-related classes, use DateTimeFormatter. I already discuss this class in this blogpost.

Getting Date/Time Information

To get the time in our system clock, we invoke now method. Take a look at this example.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    Instant instant = Instant.now();
    System.out.println("Instant: " + instant);
    LocalDate locDate = LocalDate.now();
    System.out.println("Local Date: " + locDate);
    LocalTime locTime = LocalTime.now();
    System.out.println("Local Time: " + locTime);
    OffsetTime offsetTime = OffsetTime.now();
    System.out.println("Offset Time: " + offsetTime);
    LocalDateTime ldt = LocalDateTime.now();
    System.out.println("Local Date Time: " + ldt);
    OffsetDateTime odt = OffsetDateTime.now();
    System.out.println("Offset Date Time: " + odt);
    ZonedDateTime zdt = ZonedDateTime.now();
    System.out.println("Zoned Date Time: " + zdt);
  }
}

Result(may vary)
Instant: 2022-04-04T22:14:03.767119900Z
Local Date: 2022-04-05
Local Time: 06:41:03.792119900
Offset Time: 06:41:03.792119900+08:00
Local Date Time: 2022-04-05T06:41:03.792119900
Offset Date Time: 2022-04-05T06:41:03.792119900+08:00
Zone Date Time:
2022-04-05T06:41:03.792119900+08:00[Asia/Taipei]
Instant stores date and time(UTC+0). "T" stands for time and it separates date and time. "Z" stands for "Zulu" time which is another term for UTC time. LocalDate stores date without time. LocalTime stores time without date. OffsetTime stores time with offset from UTC.

LocalDateTime stores date and time. Time is adjusted based on the offset where the time is extracted. OffsetDateTime stores date and time with the offset from UTC. ZonedDateTime stores date and time with offset from UTC and ID of a time zone. Also, ZonedDateTime observes daylight saving time based on the rules of its ZoneRules that resides in its ZoneId.

Where possible, applications should use LocalDate, LocalTime and LocalDateTime to better model the domain. For example, a birthday should be stored in a code LocalDate. Bear in mind that any use of a time-zone, such as 'Europe/Paris', adds considerable complexity to a calculation.

Many applications can be written only using LocalDate, LocalTime and Instant, with the time-zone added at the user interface (UI) layer. For example, you get your system's date/time using ZonedDateTime. Then, display your system's time zone ID by calling getZone() which returns a ZoneId instance. If you wanna get offset only, call getOffset() which returns a ZoneOffset instance.

Then, call toLocalDate() that returns a LocalDate instance with the date of our ZonedDateTime instance. With this, we can compare dates easily without including time.

The offset-based date-time types OffsetTime and OffsetDateTime, are intended primarily for use with network protocols and database access. For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but they can store an offset like '+02:00'.

Next, let's discuss how to get specific part of a date like month, day, year etc. This example demonstrates getter methods that get specific part of a date.
import java.time.*;
import java.time.temporal.ChronoField;

public class SampleClass{

  public static void main(String[] args){
    
    ZonedDateTime zdt = ZonedDateTime.now();
    
    LocalDate ld = zdt.toLocalDate();
    //These getter methods can be found in
    //LocalDate, LocalDateTime, OffsetDateTime
    //and ZonedDateTime
    System.out.println("Day of Month: " +
    ld.getDayOfMonth());
    System.out.println("Day of Week: " +
    ld.getDayOfWeek());
    System.out.println("Day of Year: " +
    ld.getDayOfYear());
    System.out.println("Month: " +
    ld.getMonth() + " | " + ld.getMonthValue());
    System.out.println("Year: " + ld.getYear());
    System.out.println();
    
    //These getter methods can be found in
    //LocalTime, LocalDateTime, OffsetTime,
    //OffsetDateTime and ZonedDateTime
    LocalTime lt = zdt.toLocalTime();
    System.out.println("Hour: " + lt.getHour());
    System.out.println("Minutes: " + 
    lt.getMinute());
    System.out.println("Seconds: " +
    lt.getSecond());
    System.out.println("Nano-of-Second: " +
    lt.getNano());
    System.out.println();
    
    //This getter method can be found in
    //OffsetTime, OffsetDateTime and 
    //ZonedDateTime
    System.out.println("Offset: " + 
    zdt.getOffset());
    
    //This getter method can be found in
    //ZonedDateTime
    System.out.println("Zone ID: " +
    zdt.getZone());
    System.out.println();
    
    //These getter methods can be found in
    //LocalDate
    System.out.println("Length of Month: "+
    ld.lengthOfMonth());
    System.out.println("Length of Year: "+
    ld.lengthOfYear());
    System.out.println("Is leap year? "+
    ld.isLeapYear());
    System.out.println("Era: "+
    ld.getEra());
    System.out.println();
    
    //These getter methods can be found in
    //LocalTime
    System.out.println("Nanoseconds of Day: " +
    lt.toNanoOfDay());
    System.out.println("Seconds of Day: " +
    lt.toSecondOfDay());
    System.out.println();
    
    //get(TemporalField field) method
    //can be found in every temporal
    //implementations highlighted in this topic
    if(zdt.isSupported(ChronoField.AMPM_OF_DAY))
      System.out.println("AM/PM of day: " +
      zdt.get(ChronoField.AMPM_OF_DAY));
  }
}

Result
Day of Month: 7
Day of Week: THURSDAY
Day of Year: 97
Month: APRIL | 4
Year: 2022

Hour: 10
Minutes: 42
Seconds: 31
Nano-of-Second: 432663400

Offset: +08:00
Zone ID: Asia/Taipei

Length of Month: 30
Length of Year: 365
Is leap year? false
Era: CE

Nanoseconds of Day:
38551432663400
Seconds of Day: 38551

AM/PM of Day: 0
getDayOfMonth() returns the day of the month, getDayOfWeek() returns a DayOfWeek enum that stores the day of the week and getDayOfYear() returns the day of the year.

getMonth() returns a Month enum that denotes the month. getMonthValue() returns the numerical representation of the month. In ISO calendar system, A value of 1 represents January. A value of 12 represents December. In the example above, the value 4 represents April. getYear() returns the year.

getHour() returns hour, getMinute() returns minutes and getSecond() returns seconds. getNano() returns nano-of-second or a fraction of a second in nanoseconds. getOffset() returns a ZoneOffset instance that stores the offset from UTC. getZone() returns a ZoneID instance that stores the ID of the time zone.

lengthOfMonth() returns the total number of days in a month. In the example above, the total number of days in March 2022 is 30. lengthOfYear() returns the total number of days in a year. In the example above, the total number of days in 2022 is 365. isLeapYear() returns true is a year is a leap year. Otherwise, returns false. getEra() returns an IsoEra instance which holds the current era of the specified date.

toNanoOfDay() returns the elapsed time in a day in nanoseconds. toSecondOfDay() returns the elapsed time in a day in seconds. get(TemporalField field) gets the value of the specified field from this date as an int.

In the example above, ChronoField.AMPM_OF_DAY holds a value that determines if this date and time is in AM or PM. If the field returns 0, date and time is AM. if 1, date and time is PM. This method will throw an exception if the given field is not supported by this instance or the value of the given field exceeds the max range of int. If the latter happened, use getLong(TemporalField field).

TemporalField is a field of date-time, such as month-of-year or minute-of-hour. ChronoField is an enum that contains a standard set of fields that are compatible with TemporalField. Other fields that are TemporalField type can be found in IsoFields, WeekFields and JulianFields.

isSupported(TemporalField field) returns true if the given field is supported by the class. In the example above, LocalDate supports ChronoField.AMPM_OF_DAY field that's why isSupported returns true.

Setting Date/Time Information

There are different ways of setting date and time. However, one of the common ways of setting date and time is by using of method. Take a look at this example.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    //of(int year, int month, int dayOfMonth)
    LocalDate ld = LocalDate.of(2020, 5, 30);
    System.out.println("LocalDate: " + ld);
    
    //of(int hour, int minute)
    LocalTime lt = LocalTime.of(10, 45);
    System.out.println("LocalTime: " + lt);
    
    //of(LocalTime time, ZoneOffset offset)
    OffsetTime ot = 
    OffsetTime.of(LocalTime.of(20, 30),
                  ZoneOffset.of("+10:00"));
    System.out.println("OffsetTime: " + ot);
    
    //of(LocalDate date, LocalTime time)
    LocalDateTime ldt = 
    LocalDateTime.of(LocalDate.of(2015, 1, 15),
                     LocalTime.of(10, 10));
    System.out.println("LocalDateTime: " + ldt);
    
    //of(LocalDateTime dateTime, ZoneOffset offset)
    OffsetDateTime odt = 
    OffsetDateTime.of(ldt,
                      ZoneOffset.of("+08:00"));
    System.out.println("OffsetDateTime: " + odt);
    
    //of(LocalDateTime localDateTime, ZoneId zone)
    ZonedDateTime zdt = 
    ZonedDateTime.of(ldt,
                     ZoneId.of("Asia/Taipei"));
    System.out.println("ZonedDateTime: " + zdt);
  }
}

Result
LocalDate: 2020-05-30
LocalTime: 10:45
OffsetTime: 20:30+10:00
LocalDateTime: 2015-01-15T10:00+08:00
ZonedDateTime: 2015-01-15T10:00+08:00[Asia/Taipei]
Take note that of method has overloaded forms and each overloaded form may be unique to each temporal implementation.

Parsing Date/Time

If we want to parse a text to a temporal object, we use parse method. This method can be seen from every temporal implementations highlighted in this topic. This method has two forms:
parse(CharSequence text)
parse(CharSequence text, DateTimeFormatter formatter)
This example demonstrates parse(CharSequence text)
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    
    LocalDate ld = LocalDate.parse("2010-10-20");
    System.out.println("LocalDate: " + ld);
    
    ZonedDateTime zdt = 
    ZonedDateTime.parse(
    "2007-12-03T10:15:30+01:00[Europe/Paris]");
    System.out.println("ZonedDateTime: " + zdt);
  }
}

Result
LocalDate: 2010-10-20
ZonedDateTime: 
2007-12-03T10:15:30+01:00[Europe/Paris]
Take note that an ISO format must be followed when the first overloaded form of parse is used. For example, parse(CharSequence text) in LocalDate follows DateTimeFormatter.ISO_LOCAL_DATE. in ZonedDateTime, first overloaded form of parse follows DateTimeFormatter.ISO_ZONED_DATE_TIME. More information about formatting can be found in the DateTimeFormatter.

Adding/Subtracting Date/Time

To subtract or add date or time to a temporal implementations highligted in this topic, we use methods with minus or plus prefix. This example demonstrates some of those methods.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
  
    LocalDate ld = LocalDate.of(2020, 5, 20);
    //These methods can be found in LocalDate,
    //LocalDateTime, OffsetDateTime and
    //ZonedDateTime
    ld = ld.plusDays(1);
    ld = ld.plusMonths(1);
    ld = ld.plusYears(1);
    System.out.println("Date(plus): " + ld);
    
    ld = ld.minusDays(1);
    ld = ld.minusMonths(1);
    ld = ld.minusYears(1);
    System.out.println("Date(minus): " + ld);
    
    LocalTime lt = LocalTime.of(10, 45, 15);
    //These methods can be found in LocalTime,
    //LocalDateTime, OffsetTime, OffsetDateTime
    //and ZonedDateTime
    lt = lt.plusHours(1);
    lt = lt.plusMinutes(5);
    lt = lt.plusSeconds(15);
    System.out.println("Time(plus): " + lt);
    
    lt = lt.minusHours(1);
    lt = lt.minusMinutes(5);
    lt = lt.minusSeconds(15);
    System.out.println("Time(minus): " + lt);
    
  }
}

Result
Date(plus): 2021-06-21
Date(minus): 2020-05-20
Time(plus): 11:50:30
Time(minus): 10:45:15
The methods demonstrated above are easy to understand. Now, let's discuss plus and minus methods. These methods can found in every date-time-related classes highlighted in this topic and both of them have two overloaded forms:
plus(long amountToAdd, TemporalUnit unit)
plus(TemporalAmount amountToAdd)
minus(long amountToSubtract, TemporalUnit unit)
minus(TemporalAmount amountToSubtract)
This example demonstrates plus and minus methods.
import java.time.*;
import java.time.temporal.ChronoUnit;

public class SampleClass{

  public static void main(String[] args){
    LocalDate ld = LocalDate.of(2020, 5, 20);
    
    //plus(long amountToAdd, TemporalUnit unit)
    if(ld.isSupported(ChronoUnit.DAYS))
      ld = ld.plus(5, ChronoUnit.DAYS);
    else System.out.println("DAYS not supported!");
    
    //plus(TemporalAmount amountToAdd)
    ld = ld.plus(Period.ofYears(1));
    System.out.println("LocalDate: " + ld);
    
    LocalTime lt = LocalTime.of(16, 30);
    
    //minus(long amountToSubtract, TemporalUnit unit)
    if(lt.isSupported(ChronoUnit.MINUTES))
      lt = lt.minus(15, ChronoUnit.MINUTES);
      
    //minus(TemporalAmount amountToSubtract)
    lt = lt.minus(Duration.ofHours(1));
    System.out.println("LocalTime: " + lt);
  }
}

Result
LocalDate: 2021-05-25
LocalTime: 15:15
TemporalUnit A unit of date-time, such as Days or Hours. ChronoUnit is an enum that contains a standard set of fields that are compatible with TemporalUnit. Other fields that are TemporalUnit type can be found in IsoFields.

isSupported(TemporalUnit unit) returns true if the given field is supported by the class. In the example above, LocalDate supports ChronoUnit.DAYS field that's why isSupported returns true.

TemporalAmount is a framework-level interface defining an amount of time, such as "6 hours", "8 days" or "2 years and 3 months". This interface has two concrete implementations: Duration and Period.

Period is just like LocalDate. However, Period follows a different format and can be used to store single-value date information like months, years, days, etc.

Duration is just like LocalTime. However, Duration follows a different format and can be used to store single-value time information like hours, minutes, seconds, etc.

Modifying Date/Time

To modify date and time in temporal objects, we use with or methods with 'with' prefix. Take note that the methods throw an exception if the given value is not in the range of the specified field. This example demonstrates some of those methods.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    
    LocalDate ld = LocalDate.of(2015, 6, 15);
    //These methods can be found in LocalDate,
    //LocalDateTime, OffsetDateTime and
    //ZonedDateTime
    ld = ld.withDayOfMonth(5);
    ld = ld.withMonth(4);
    ld = ld.withYear(2020);
    System.out.println("LocalDate: " + ld);
    
    LocalTime lt = LocalTime.of(10, 15, 10);
    //These methods can be found in LocalTime,
    //OffsetTime, OffsetDateTime and
    //ZonedDateTime
    lt = lt.withHour(2);
    lt = lt.withMinute(5);
    lt = lt.withSecond(15);
    System.out.println("LocalTime: " + lt);
    System.out.println();
    
    OffsetTime ot = 
    OffsetTime.of(lt, ZoneOffset.of("+02:00"));
    System.out.println("Original: " + ot);
    //These methods can be found in OffsetTime,
    //OffsetDateTime
    ot = ot.withOffsetSameInstant(
    ZoneOffset.of("+03:00"));
    System.out.println("withOffsetSameInstant: " +
    ot);
    ot = ot.withOffsetSameLocal(
    ZoneOffset.of("+04:00"));
    System.out.println("withOffsetSameLocal: " +
    ot);
    System.out.println();
    
    ZonedDateTime zdt = ZonedDateTime.of(
    ld, lt, ZoneId.of("Europe/Paris"));
    System.out.println("Original: " + zdt);
    //These methods can be found in
    //ZonedDateTime
    zdt = zdt.withZoneSameInstant(ZoneId.of("Asia/Taipei"));
    System.out.println("withZoneSameInstant: " +
    zdt);
    zdt = zdt.withZoneSameLocal(ZoneId.of("Europe/Paris"));
    System.out.println("withZoneSameLocal: " +
    zdt);
  }
}

Result
LocalDate: 2020-04-05
LocalTime: 02:05:15

Original: 02:05:15+02:00
withZoneSameInstant
03:03:15+03:00
03:03:15+04:00

Original: 
2020-04-05T02:05:15+02:00[Europe/Paris]
withZoneSameInstant
2020-04-05T02:08:15+08:00[Asia/Taipei]
withZoneSameLocal
2020-04-05T02:08:15+02:00[Europe/Paris]
withDayOfMonth, withMonth and withYear create new instances with the given day of month, month and year. withHour, withMinute and withSecond create new instances with the given hour, minutes and seconds.

withOffsetSameInstant creates a new instance with the given offset. Time will adjust based on the previous and new offset. withOffsetSameLocal creates a new instance with the given offset. The time won't be adjusted.

withZoneSameInstant creates a new instance with the given ZoneId and its offset. Time will adjust based on the rules and offset of the previous ZoneId to rules and offset of the new ZoneId. withZoneSameLocal creates a new instance with the given ZoneId and its offset from UTC. Time won't be adjusted.

Take note that ZoneId has rules that are defined by ZoneRules. ZonedDateTime follows the rules of ZoneId. "Europe/Paris" ZoneId has rules that follow daylight saving time. Thus, any ZonedDateTime that uses "Europe/Paris" Zone ID observes daylight saving time.

There are three methods with 'with' prefix that I wanna discuss. withEarlierOffsetAtOverlap, withLaterOffsetAtOverlap and withFixedOffsetZone can be found in ZonedDateTime. Take a look at this example.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    ZonedDateTime zdt = 
    ZonedDateTime.of(
    LocalDateTime.of(2022, 10, 30, 2, 0),
    ZoneId.of("Europe/Paris"));
    
    ZonedDateTime fixedOffsetZone = 
    zdt.withFixedOffsetZone();
    fixedOffsetZone = 
    fixedOffsetZone.plusHours(1);
    System.out.println("Fixed: " + 
    fixedOffsetZone);
    
    System.out.println();
    System.out.println("Original: " + zdt);
    zdt = zdt.plusHours(1);
    System.out.println("Plus 1hr: " + zdt);
    System.out.println();
    
    zdt = zdt.withEarlierOffsetAtOverlap();
    System.out.println("Early Overlap: " + zdt);
    zdt = zdt.withLaterOffsetAtOverlap();
    System.out.println("Later Overlap: " + zdt);
  }
}

Result
Fixed: 2022-10-30T03:00+02:00

Original: 2022-10-30T02:00+02:00[Europe/Paris]
Plus 1hr: 2022-10-30T02:00+01:00[Europe/Paris]

Early Overlap: 2022-10-30T02:00+02:00[Europe/Paris]
Later Overlap: 2022-10-30T02:00+01:00[Europe/Paris]
In the example above, we can see that the time in fixedOffsetZone variable didn't adjust because there's no ZoneId is present in the instance. Thus, no daylight rules to follow. withFixedOffsetZone discards the ZoneId of a ZonedDateTime instance. Making it effectively equivalent to OffsetDateTime.

withLaterOffsetAtOverlap returns a ZonedDateTime with the later valid offset of the ZonedDateTime that invoked this method. withEarlierOffsetAtOverlap returns a ZonedDateTime with the earlier valid offset of the ZonedDateTime that invoked this method.

Overlap happens during transition from daylight saving time to standard time. Gap happens during transition from standard time to daylight saving time. This documentation has a definition about gaps and overlaps.

Next, let's discuss with method. This method can be found in every temporal implementations highlighted in this topic and this method has two forms:
with(TemporalAdjuster adjuster)
with(TemporalField field, long newValue)
This example demonstrates with method and its overloaded forms.
import java.time.*;
import java.time.temporal.TemporalAdjusters;
import java.time.temporal.ChronoField;

public class SampleClass{

  public static void main(String[] args){
    LocalDate ld = LocalDate.of(2020, 5, 20);
    
    //with(TemporalField field, long newValue)
    if(ld.isSupported(ChronoField.YEAR))
      ld.with(ChronoField.YEAR, 2025);
    
    //with(TemporalAdjuster adjuster)
    ld = ld.with(temporal -> 
            temporal.plus(Period.ofMonths(2)));
    ld = ld.with(TemporalAdjusters.lastDayOfMonth());
    
    System.out.println("LocalDate: " + ld);
  }
}

Result
LocalDate: 2020-07-31
TemporalAdjuster is a functional interface used for adjusting a temporal object. You can create your own lambda functions that return Temporal or use the pre-defined functions from TemporalAdjusters.

TemporalField is a field of date-time, such as month-of-year or minute-of-hour. ChronoField is an enum that contains a standard set of fields that are compatible with TemporalField. Other fields that are TemporalField type can be found in IsoFields, WeekFields and JulianFields.

Comparing Date/Time

Use equals method to compare date and time of two temporal objects with the same type. This method can be found in every temporal implementations highlighted in this topic. Take a look at this example.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
  
    LocalDate ld1 = LocalDate.of(2020, 5, 20);
    LocalDate ld2 = LocalDate.of(2020, 5, 20);
    LocalDate ld3 = LocalDate.of(2015, 5, 20);
    System.out.println("ld1 is equal to ld2? "
                       + ld1.equals(ld2));
    System.out.println("ld1 is equal to ld3? "
                       + ld1.equals(ld3));
  }
}

Result
ld1 is equal to ld2? true
ld1 is equal to ld3? false
take note that equals method works differently in every temporal objects. For example, in LocalDate, only date is being compared. In LocalTime, only time is compared. In LocalDateTime, date and time are used for comparing two instances. In ZonedDateTime, date, time and ZoneId are used for comparing two instances.

Querying Date/Time

a temporal object can be queried to extract information from it. To do that, we use the query method which can be found in every temporal implementations highlighted in this topic. Take a look at this example.
import java.time.*;
import java.time.temporal.TemporalQueries;
import java.time.chrono.Chronology;
import java.time.chrono.IsoChronology;

public class SampleClass{

  public static void main(String[] args){
  
    ZonedDateTime zdt = 
    ZonedDateTime.of(
    LocalDate.of(10, 5, 20),
    LocalTime.of(10, 15),
    ZoneId.of("Europe/Paris"));
    
    Chronology ch = 
    zdt.query(TemporalQueries.chronology());
    System.out.println("Chronology: " + ch);
    boolean isChrono = ch instanceof IsoChronology;
    System.out.println("is IsoChronology? " +
                       isChrono);
    
    //Quarter Year: standard calendar divides
    //months in a year in a quarter: Q1, Q2, Q3, Q4
    //January, February, and March (Q1) April, 
    //May, and June (Q2)
    //July, August, and September (Q3)
    //October, November and December (Q4)
    int quarterYear = zdt.query(temporal ->
    {
      LocalDate ld = LocalDate.from(temporal);
      return (ld.getMonthValue() / 3) + 1;
    });
    System.out.println("Quarter Year: " + 
                       quarterYear);
    
  }
}

Result
Chronology: ISO
is IsoChronology? true
Quarter Year: 2
TemporalQuery is a functional interface used for querying a temporal object. We can create our own lambda functions for TemporalQuery. Additionally, we can use pre-defined functions in TemporalQueries.

Chronology is an interface that defines a calendar system, used to organize and identify dates. Java supports different types of calendars and those calendars implement this interface. Most of the time, the default calendar system used by java platforms is the ISO calendar system. IsoChronology defines the rules of the ISO calendar system.

LocalDate.from extracts date-related information from the given temporal object and returns LocalDate instance with the extracted information.

Duration and Period Classes

Duration and Period implement TemporalAmount that is used as a parameter of methods such as plus, minus and with.

Duration class models a quantity or amount of time in terms of seconds and nanoseconds. Period class models a quantity or amount of time in terms of years, months and days. This example demonstrates some methods of Duration and Period.
import java.time.*;

public class SampleClass{

  public static void main(String[] args){
    Duration hours = Duration.parse("P2DT10H10M5S");
    Duration minutes = Duration.ofMinutes(30);
    Duration seconds = Duration.ofSeconds(15);
    
    hours = hours.plusMinutes(30);
    System.out.println("Duration1: " + 
    hours);
    minutes = minutes.plusMinutes(15);
    System.out.println("Duration2: " + 
    minutes);
    seconds = seconds.plusSeconds(15);
    System.out.println("Duration3: " + 
    seconds);
    System.out.println();
    
    System.out.println("toHoursPart: " + 
    hours.toHoursPart());
    System.out.println("toMinutesPart: " + 
    hours.toMinutesPart());
    System.out.println("toMinutes: " + 
    hours.toMinutes());
    System.out.println();
    
    Period date = Period.parse("P2022Y5M15D");
    Period months = Period.ofMonths(5);
    Period years = Period.ofYears(5);
    
    System.out.println("Period1: " + date);
    System.out.println("Period2: " + months);
    System.out.println("Period3: " + years);
    System.out.println();
    
    System.out.println("getYears: " + 
    date.getYears());
    System.out.println("getMonths: " + 
    date.getMonths());
    System.out.println("getDays: " + 
    date.getDays());
    System.out.println();
    
    Period date2 = Period.parse("P2022Y15M10D");
    System.out.println("Not normalized: " + date2);
    date2 = date2.normalized();
    System.out.println("Normalized: " + date2);
  }
}

Result
Duration1: PT58H40M5S
Duration2: PT45M
Duration3: PT30S

toHoursPart: 10
toMinutesPart: 40
toMinutes: 3520

Period1: 2022Y5M15D
Period2: P5M
Period3: P5Y

getYears: 2022
getMonths: 5
getDays: 15

Not normalized: P2022Y15M10D
Normalized: P2023Y3M10D
If you read several topics before this topic, you will notice that Duration and Period have similarities with the classes I've discussed previously. Duration.ofMinutes creates a Duration instance with the given minutes. Duration.ofSeconds creates a Duration instance with the given seconds. Duration.parse obtains a Duration from a text that follows particular textual formats such as PnDTnHnMn.nS. More information about Duration.parse formats can be found here.

Notice that the format P2022Y5M15D I put in Duration.parse is not equivalent to the output of System.out.println("Duration1: " + hours);. That's because Duration.toString formats the output String into particular formats such as PT8H6M12.345S. More information about Duration.toString formats can be found here.

toHoursPart method extracts the hours part in a Duration object. toMinutesPart method extracts the minutes part in a Duration object.toMinutes gets the number of minutes in this Duration object. plusMinutes creates a Duration object with the added minutes. plusSeconds creates a Duration object with the added seconds.

Period.ofMonths creates a Period instance with the given months. Period.ofYears creates a Period instance with the given seconds. Period.getYears returns the extracted years from the Period instance. Period.getMonths returns the extracted months from the Period instance. Period.getDays returns the extracted days from the Period instance.

Period.parse obtains a Period from a text that follows particular textual formats such as PnYnMnD. More information about Period.parse formats can be found here.

Period.normalized method returns a copy of this Period object with the years and months normalized. This normalizes the years and months units, leaving the days unit unchanged. The months unit is adjusted to have an absolute value less than 12, with the years unit being adjusted to compensate. For example, a period of "1 Year and 15 months" will be normalized to "2 years and 3 months".

Thursday, March 17, 2022

Java Tutorial: Reflection

Chapters

Overview

Reflection is a feature in the Java programming language. It allows an executing Java program to examine or "introspect" upon itself, and manipulate internal properties of the program. For example, it's possible for a Java class to obtain the names of all its members and display them.

The ability to examine and manipulate a Java class from within itself may not sound like very much, but in other programming languages this feature simply doesn't exist. For example, there is no way in a Pascal, C, or C++ program to obtain information about the functions defined within that program.

One tangible use of reflection is in JavaBeans, where software components can be manipulated visually via a builder tool. The tool uses reflection to obtain the properties of Java components (classes) as they are dynamically loaded.

Reflection is powerful, but should not be used indiscriminately. If it is possible to perform an operation without using reflection, then it is preferable to avoid using it. In this tutorial, I'm gonna demonstrate some essential methods of java.lang.Class and some essential classes of java.lang.reflect package like Field, Method and Constructor.

Retrieving Class Object

The entry point for all reflection operations is java.lang.Class. With the exception of java.lang.reflect.ReflectPermission, none of the classes in java.lang.reflect have public constructors. Most Class objects refer to .class files of classes.

If there's an available instance and it's related to Object, we can use getClass method. This example demonstrates getClass method.
public class SampleClass{

  public static void main(String[] args){
    String str = "String";
    
    Class<?> classObj = str.getClass();
    System.out.println(classObj);
    
  }
}

Result 
class java.lang.String
If there's no available instance, we can use the .class instance. This syntax requires name of type followed by ".class". This feature is also the easiest way of getting Class object for primitive types. This example demonstrates .class syntax.
public class SampleClass{

  public static void main(String[] args){
    
    Class<?> classObj = boolean.class;
    System.out.println(classObj);
    classObj = String.class;
    System.out.println(classObj);
  }
}

Result
boolean
class java.lang.String
when .class syntax is used with primitive type. It returns a Class object that corresponds to the primitive type.

Another way of getting Class object is using Class.forName method. This static method verifies the fully-qualified class name in its argument. If the Class name is available, this method will return the corresponding Class object. This method has multiple forms. Also, this method can't be used with primitive type.

getName method returns the Class name of a Class object. This example demonstrates Class.forName(String className) method.
public class SampleClass{

  public static void main(String[] args){
    Class<?> classObj = Class.forName("java.lang.String");
    System.out.println(classObj.getName());
  }
}
For wrapper classes like Integer, Boolean and others; we can use the TYPE fields. Each wrapper class has TYPE field that returns a Class object of the specified wrapper class. This example demonstrates TYPE fields.
public class SampleClass{

  public static void main(String[] args){
    
    Class<?> classObj = Boolean.TYPE;
    System.out.println(classObj.getName());
  }
}

Result
boolean
There are other methods from the Class class that we can use to get nested Class objects. Although, these methods are not static. Thus, we need to have a Class object first. This example demonstrates getSuperClass, getClasses and getClasses methods.
public class SampleClass{

  public static void main(String[] args){
    Class<?> classObj = javax.swing.JButton.class;
    System.out.println("Super Class");
    System.out.println(classObj.getSuperclass().getName());
    System.out.println();
    
    Class<?>[] classes = Character.class.getClasses();
    System.out.println("Classes");
    for(Class<?> c : classes)
      System.out.println(c.getName());
    System.out.println();
    
    System.out.println("Declared Classes");
    for(Class<?> c : Character.class.getDeclaredClasses()){
      System.out.println(c.getName());
    }
    
  }
}

Result
Super Class
class javax.swing.AbstractButton

Classes
class java.lang.Character$UnicodeBlock
class java.lang.Character$UnicodeScript
class java.lang.Character$Subset

Declared Classes
class java.lang.Character$CharacterCache
class java.lang.Character$UnicodeBlock
class java.lang.Character$UnicodeScript
class java.lang.Character$Subset
getSuperclass method returns superclass of the given class. In the example above, javax.swing.JButton is the given class and getSuperclass method returns javax.swing.AbstractButton which is the superclass of JButton.

getClasses method returns returns all the public classes, interfaces, and enums that are members of the class including inherited members. getDeclaredClasses returns all public and non-public classes, interfaces, and enums.

In the example above, CharacterCache is a private class in Character class. It's included in the result of getDeclaredClasses method but not included in the result of getClasses method.

To get declaring class, we use getDeclaringClass method. This example demonstrate that method.
import java.lang.reflect.*;

public class SampleClass{

  public static void main(String[] args) 
                     throws NoSuchFieldException{
    //Field class stores reflected information
    //regarding the specified field in a class
    Field f = System.class.getField("out");
    
    Class<?> classObj = f.getDeclaringClass();
    System.out.println(classObj.getName());
  }
}

Result
java.lang.System
out is a standard output stream in java and it's declared in the System class in java.lang package. Anonymous class is not considered as "declared" in a class. Although, we can still get the class where an anonymous class resides by invoking getEnclosingClass method. Take a look at this example.
public class SampleClass{
  static Object o = new Object(){};
  
  public static void main(String[] args){
    Class<?> classObj = o.getClass().getDeclaringClass();
    System.out.println(classObj);
    classObj = o.getClass().getEnclosingClass();
    System.out.println(classObj);
  }
}

Result
null
class SampleClass

Accessing Fields

A field is a class, interface, or enum with an associated value. Methods in the Field class can retrieve information about the field, such as its name, type, modifiers, and annotations.

This example demonstrates retrieving name, type, modifiers and annotations of a field.
import java.lang.reflect.*;
import java.lang.annotation.Annotation;

public class SampleClass{
  
  @Deprecated
  public static java.util.ArrayList<String> arlist;
  
  public static void main(String[] args)
                     throws NoSuchFieldException{
    //getField method returns a Field object where
    //information about the given field is stored.
    Field field = SampleClass.class.getField("arlist");
    System.out.println("Name: " + field.getName());
    System.out.println();
    
    Class<?> type = field.getType();
    System.out.println("Type: " + type.getName());
    System.out.println();
    
    Type genericType = field.getGenericType();
    System.out.println("Generic Type: " + genericType);
    System.out.println();
    
    int modifiers = field.getModifiers();
    System.out.println("Modifiers: " + modifiers);
    System.out.println("Public field? " + 
    Modifier.isPublic(modifiers));
    System.out.println("Static field? " + 
    Modifier.isStatic(modifiers));
    System.out.println();
    
    System.out.println("Annotations");
    System.out.println(field.getAnnotation(Deprecated.class));
    System.out.println(
    field.getAnnotation(SuppressWarnings.class));
    
  }
}

Result
Name: arList

Type: java.util.ArrayList

Generic Type: java.util.ArrayList<java.lang.String>

Modifiers: 9
Public field? true
Static field? true

Annotations
@java.lang.Deprecated(forRemoval=false, since="")
null
getName method in Field class returns the name of the field. getType method in Field class returns a Class object that stores the type of the field. getGenericType method returns a Type object that represents a generic type of the field if it's present in the Signature attribute of the Class object.Otherwise, this method will rollback to getType method. getModifiers returns an integer value that represents one or more modifiers.

Modifier class provides static methods and constants to decode class and member access modifiers. The sets of modifiers are represented as integers with distinct bit positions representing different modifiers. Bits that represent modifiers can be computed by using the OR(|) operator.

For example, Modifier.PUBLIC is represented by integer value of 8. Modifier.STATIC is represented by integer value of 1. 8|1 = 9. getAnnotation method returns an Annotation or one of its subclasses that holds the specified annotation if such annotation is applied to the field. Otherwise, the method returns null. Note that any annotation returned by this method is a declaration annotation. Also, getAnnotation only returns annotation with RetentionPolicy.RUNTIME.

Getting and Setting Field Values

We can get and set field values by using Field's getter and setter methods. This example demonstrates getting and setting field values via reflection.
import java.lang.reflect.*;

public class SampleClass{
  public static int num = 5;
  public String str = "String";
  
  public static void main(String[] args)
                     throws NoSuchFieldException,
                            IllegalAccessException{
    Field primitive = SampleClass.class.getField("num");
    int value = primitive.getInt(primitive);
    System.out.println("Integer Original Value: " + value);
    System.out.println();
    
    Field object = SampleClass.class.getField("str");
    SampleClass sc = new SampleClass();
    
    String s = (String)object.get(sc);
    System.out.println("String Original Value: " + s);
    System.out.println();
    
    System.out.println("Setting values...");
    System.out.println();
    
    primitive.setInt(primitive, 10);
    value = primitive.getInt(primitive);
    System.out.println("Integer Current Value: " + value);
    System.out.println();
    
    object.set(sc, new String("MyString"));
    s = (String)object.get(sc);
    System.out.println("String Current Value: " + s);
    System.out.println();
  }
}

Result
Integer Original Value: 5

String Original Value: String

Setting Values...

Integer Current Value: 10

String Current Value: MyString
Use get(Object obj) method when getting object-type fields. obj parameter is the given field which value will be returned by the method. For primitive-type fields, It's preferrable to use get methods that correspond to the type of the field.

In the example above, primitive variable is an int primitive. Thus, I used getInt method. If we use the regular get method with a primitive field, the return value will be wrapped into the corresponding wrapper class.

If we're getting a value from a non-static field, we need to instantiate the class where the field resides and then we can get the value of the field.

Use set(Object obj, Object value) method when setting object-type values. For primitive-type values, It's preferrable to use set methods that correspond to the type of the field.

If we're setting a value to a non-static field, we need to instantiate the class where the field resides and then we can set the value to the field.

If we wanna get/set private field value, we need to invoke getDeclaredField method instead of getField method. getDeclaredField method returns public and non-public declared(but not inherited fields) fields in the Class object whereas getField method only returns public fields(including inherited fields). This example demonstrates getting/setting private field value.
import java.lang.reflect.*;

public class SampleClass{
  private static int num = 5;
  
  public static void main(String[] args)
                     throws NoSuchFieldException,
                            IllegalAccessException{
    Field field = SampleClass.class.getDeclaredField("num");
    
    System.out.println("Original Value: " + field.getInt(field));
    field.setInt(field, 10);
    System.out.println("Current Value: " + field.getInt(field));
  }
}
To get all public fields in a class, use getFields method. To get all public and non-public fields, use getDeclaredFields method. Read their descriptions in the documentation. To know more about Field class, you can read this documentation.

If you're having a problem accessing fields. You may try to check the accessibility of a field by invoking canAccess(Object obj) method. If it returns false, we need to set the accessiblity of the field to true by invoking setAccessible(boolean flag) method. Here's an example:
SampleClass sc = new SampleClass(); Field field = sc.getClass().getField("field");
if(!field.canAccess(sc)) field.setAccessible(true); System.out.println(field.getInt(sc));

Accessing Methods

A method declaration includes the name, modifiers, parameters, return type, and list of throwable exceptions. The java.lang.reflect.Method class provides a way to obtain this information. This example demonstrates retrieving name, return type, modifiers, parameters and annotations of a method.
import java.lang.reflect.*;
import java.lang.annotation.Annotation;

public class SampleClass{
  
  @Deprecated
  public static <T extends String>
  String message(T msg1, T msg2)
         throws NullPointerException{
    return msg1.concat(msg2);
  }
  
  public static void main(String[] args){
    Method[] methods = SampleClass.class.getMethods();
    
    for(Method m : methods){
      if(!m.getName().equals("message"))
         continue;
      System.out.println("Name: " + m.getName());
      System.out.println();
      
      System.out.println("Annotations");
      for(Annotation a : m.getDeclaredAnnotations())
        System.out.println(a);
      System.out.println();
      int modifiers = m.getModifiers();
      
      System.out.println("Modifiers: "+modifiers);
      System.out.println("Is public? " + 
      Modifier.isPublic(modifiers));
      System.out.println("Is static? " + 
      Modifier.isStatic(modifiers));
      System.out.println();
      
      System.out.println("Parameter Count: " + 
      m.getParameterCount());
      System.out.println("Parameter Types");
      for(Class<?> param : m.getParameterTypes())
        System.out.println(param.getTypeName());
      System.out.println("Type Parameters");
      for(TypeVariable tv : m.getTypeParameters())
        System.out.println(tv.getName());
      System.out.println();
      
      System.out.println("Return Type: " + 
      m.getReturnType().getName());
      System.out.println();
      
      System.out.println("Exceptions");
      for(Class<?> exp : m.getExceptionTypes())
        System.out.println(exp.getName());
      
    }
  }
}

Result
Name: message

Annotations
@java.lang.Deprecated(forRemoval=false, since="")

Modifiers: 9
Is public? true
Is static? true

Parameter Count: 2
Parameter Types
java.lang.String
java.lang.String
Type Parameters
T

Return Type: java.lang.String

Exceptions
java.lang.NullPointerException
getMethods returns all methods including inherited methods. If you wanna only access declared method in a class, use getDeclaredMethods method. getName method in Method class returns the name of the method.

getDeclaredAnnotations method returns annotations that are directly present on this element. This method ignores inherited annotations. If you wanna include inherited annotations, use getAnnotations method.

getModifiers returns an integer value that represents one or more modifiers. Modifier class provides static methods and constants to decode class and member access modifiers. The sets of modifiers are represented as integers with distinct bit positions representing different modifiers. Bits that represent modifiers can be computed by using the OR(|) operator.

For example, Modifier.PUBLIC is represented by integer value of 8. Modifier.STATIC is represented by integer value of 1. 8|1 = 9. getParameterCount method returns the total number of parameters in a method.

m.getParameterTypes returns types of method parameters that are wrapped into Class objects. getTypeParameters method returns type parameters in a method that are wrapped into TypeVariable interface.

getReturnType method returns the return type of a method wrapped into a Class object. getExceptionTypes returns exceptions thrown in a method.

To get parameter names and other information regarding parameters, we can use the getParameters method. This method returns parameter information wrapped into a Parameter object. This example demonstrates getParameters method.
import java.lang.reflect.*;

public class SampleClass{
  
  public void message(String str, int num){
    System.out.println(str);
    System.out.println(num);
  }
  
  public static void main(String[] args){
    
    for(Method m : SampleClass.class.getMethods()){
      if(!m.getName().equals("message"))
        continue;
      System.out.println("Method Name: " + m.getName());
      for(Parameter param : m.getParameters()){
        System.out.println("Param Name: " + param.getName());
        System.out.println("Param Type: " + 
        param.getType().getName());
      }
    }
  }
}

Result
Method name: message
Param Name: arg0
Param Type: java.lang.String
Param Name: arg1
Param Type: int
In the result above, the names that we get are different from the parameter names in our source code. That's because .class files do not store formal parameter names by default. According to oracle:

However, .class files do not store formal parameter names by default. This is because many tools that produce and consume class files may not expect the larger static and dynamic footprint of .class files that contain parameter names. In particular, these tools would have to handle larger .class files, and the Java Virtual Machine (JVM) would use more memory. In addition, some parameter names, such as secret or password, may expose information about security-sensitive methods.

To store formal parameter names in a particular .class file, and thus enable the Reflection API to retrieve formal parameter names, compile the source file with the -parameters option to the javac compiler.


If we compile our source code above with -parameters flag like this:
javac SampleClass.java -parameters
The result is going to be:
Method name: message
Param Name: str
Param Type: java.lang.String
Param Name: num
Param Type: int

The "arg0" and "arg1" that we see in the result above are synthesized parameter names of the form argN, where N is the index of the parameter in the descriptor of the method which declares the parameter.

Another way of getting method is invoking getMethod method. This example demonstrates getMethod.
import java.lang.reflect.*;

public class SampleClass{
  
  public void meth(String msg){
    System.out.println(msg);
  }
  
  public static void main(String[] args)
                throws NoSuchMethodException{
    Method m = 
    SampleClass.class.getMethod("meth", String.class);
    System.out.println("Method Name: " + m.getName());
  }
}

Result: Method Name: meth
getMethod(String name, Class<?>... parameterTypes) has two parameters. name parameter is the name of the method that we are looking for. parameterTypes is used to determine the number and types of parameters of the method that we're looking for. getMethod can obtain a public method(inherited or declared in the specified class).

If you wanna access a non-public method, use getDeclaredMethod method. Unlike getMethod, getDeclaredMethod can obtain a non-public method(declared in the specified class only).

Invoking Method

We can invoke a method via reflection by using invoke method. This example demonstrates invoke method.
import java.lang.reflect.*;

public class SampleClass{
  
  String invokeMe(String msg1, String msg2){
    System.out.println("invokeMe Method!");
    System.out.println("message1: " + msg1);
    System.out.println("message2: " + msg2);
    return msg1+msg2;
  }
  
  static void noParam(){
    System.out.println("noParam Method!");
  }
  
  public static void main(String[] args)
                throws IllegalAccessException,
                       InvocationTargetException{
    for(Method m : SampleClass.class.getDeclaredMethods()){
      if(m.getName().equals("noParam")){
        System.out.println("Invoke noParam");
        Object o = m.invoke(m);
        System.out.println("return value");
        System.out.println(o);
        System.out.println();
      }
      else if(m.getName().equals("invokeMe")){
        System.out.println("Invoke invokeMe");
        Object o = m.invoke(new SampleClass(),
                            "Hello","Everyone");
        System.out.println("return value");
        System.out.println(o);
        System.out.println();
      }
    }
      
  }
}

Result
Invoke noParam
noParam Method!
return value
null

Invoke invokeMe
invokeMe Method!
message1: Hello
message2: Everyone
return value
HelloEveryone
invoke(Object obj, Object... args) has two parameters. obj parameter is the object where the method we're going to invoke resides. args parameter is a varargs that accepts objects as method arguments. Number of arguments in args parameter must match the number of arguments in the method.

If you're having a problem accessing methods. You may try to set the accessibility of a method by invoking canAccess(Object obj) method. If it returns false, we need to set the accessiblity of the method to true by invoking setAccessible(boolean flag) method. Here's an example:
SampleClass sc = new SampleClass();
Method[] m = sc.getClass().getDeclaredMethods()
if(m.length != 0){ if(!m[0].canAccess(sc)) m[0].setAccessible(true); m[0].invoke(sc); }
Accessing Constructors

A constructor is used in the creation of an object that is an instance of a class. Typically it performs operations required to initialize the class before methods are invoked or fields are accessed. Constructors are never inherited.

Similar to methods, reflection provides APIs to discover and retrieve the constructors of a class and obtain declaration information such as the modifiers, parameters, annotations, and thrown exceptions.The java.lang.reflect.Constructor class provides a way to obtain this information.

This example demonstrates obtaining information regarding constructors such as modifiers, parameters, annotations and thrown exceptions.
import java.lang.reflect.*;
import java.lang.annotation.Annotation;

public class SampleClass{
  
  @Deprecated
  public SampleClass(String s1, Integer i1)
               throws IllegalStateException{
  }
  
  public static void main(String[] args){
    for(Constructor c : SampleClass.class.getConstructors()){
      System.out.println("Name: " + c.getName());
      System.out.println();
      
      System.out.println("Parameters");
      for(Parameter p : c.getParameters()){
        System.out.println("Param Name: " + p.getName());
        System.out.println("Param Type: " + 
        p.getType().getName());
      }
      System.out.println();
      
      System.out.println("Modifiers");
      System.out.println(c.getModifiers());
      System.out.println();
      
      System.out.println("Exceptions");
      for(Class<?> ex : c.getExceptionTypes())
        System.out.println(ex.getName());
      System.out.println();
      
      System.out.println("Annotations");
      for(Annotation a : c.getDeclaredAnnotations())
        System.out.println(a);
    }
  }
}

Result
Name: SampleClass

Parameters
Param Name: arg0
Param Type: java.lang.String
Param Name: arg1
Param Type: java.lang.Integer

Modifiers
1

Exceptions
java.lang.IllegalStateException

Annotations
@java.lang.Deprecated(forRemoval=false, since="")
getConstructors returns all public constructors in a class. If you wanna obtain non-public constructors, use getDeclaredConstructors method. getName method in Constructor class returns the name of the constructor. Other methods that I used here like getParameters, getExceptionTypes, etc. are explained in the "Accessing Methods" and "Invoking Methods" topics. You should read those topic first before reading this topic.

Another way of getting class's constructor is to use getConstructor method. This example demonstrates getConstructor method.
import java.lang.reflect.*;

public class SampleClass{
  String str;
  
  public SampleClass(String str){
    this.str = str;
  }
  
  public static void main(String[] args)
                throws NoSuchMethodException{
    Constructor c = 
    SampleClass.class.getConstructor(String.class);
    
    System.out.println("Parameters");
      for(Parameter p : c.getParameters()){
        System.out.println("Param Name: " + p.getName());
        System.out.println("Param Type: " + 
        p.getType().getName());
      }
  }
}

Result
Parameters
Param Name: args0
Param Type: java.lang.String
getConstructor(Class<?>... parameterType) has a varargs parameter that is used to identify specific constructor that we wanna access. In the example ebove, I put String.class as argument. Meaning, I'm looking for a constructor in SampleClass with only a String stype parameter.

Creating New Instance

We can instantiate an object of a class via reflection by using newInstance(Object... initargs) method. This method invokes a constructor that has the same parameter signature as the parameters in the method. This example demonstrates newInstance method.
import java.lang.reflect.*;

public class SampleClass{
  private String str;
  private int num;
  
  SampleClass(String str, int num){
    this.str = str;
    this.num = num;
  }
  
  void display(){
    System.out.println(str + " | " + num);
  }
  
  public static void main(String[] args)
                throws InstantiationException,
                       IllegalAccessException,
                       InvocationTargetException{
    
    Constructor[] cons = 
    SampleClass.class.getDeclaredConstructors();
    
    SampleClass sc = null;
    if(cons.length != 0){
      sc = (SampleClass)cons[0].newInstance("Hello!",5);
    }
    else throw new NullPointerException();
    sc.display();
  }
}

Result
Hello! | 5
If you're having a problem accessing constructors. You may try to set the accessibility of a constructor by invoking setAccessible(boolean flag) method. Here's an example:
Constructor[] cons =
SampleClass.class.getDeclaredConstructors()
if(cons.length != 0){ cons[0].setAccessible(true); SampleClass sc = cons[0].newInstance("Hello!", 5); sc.display(); }
Accessing Arrays

An array is an object of reference type which contains a fixed number of components of the same type; the length of an array is immutable. Creating an instance of an array requires knowledge of the length and component type. Each component may be a primitive type (such as byte, int, or double), a reference type (such as String or Object), or an array. Multi-dimensional arrays are really just arrays which contain components of array type.

Arrays are implemented in the Java virtual machine. The only methods on arrays are those inherited from Object. The length of an array is not part of its type; arrays have a length field which is accessible via getLength() in java.lang.reflect.Array class.

This example demonstrates creating a new array, getting an array and accessing array elements via reflection.
import java.lang.reflect.*;

public class SampleClass{
  static String[] strArr;
  
  public static void main(String[] args)
                throws NoSuchFieldException,
                       IllegalAccessException{
    Field field = 
    SampleClass.class.getDeclaredField("strArr");
    
    Class<?> type = field.getType();
    if(type.isArray()){
      System.out.println("Array Name: " + 
      field.getName());
      System.out.println("Array Type: " + 
      type.getComponentType());
      
      //create new array
      Object o = 
      Array.newInstance(type.getComponentType(), 3);
      //set elements
      for(int i = 0; i < 3; i++)
        Array.set(o, i, String.valueOf("a"+i));
      //get elements
      System.out.println("Reflection");
      System.out.println("length: " + Array.getLength(o));
      System.out.println("Elements");
      for(int i = 0; i < 3; i++)
        System.out.println(Array.get(o, i));
      System.out.println();
     //assign our newly created array to strArr
     field.set(field,o);
     
     System.out.println("strArr");
     System.out.println("length: " + strArr.length);
     System.out.println("Elements");
     for(String s : strArr)
       System.out.println(s);
     System.out.println();
     
     //get array field
     String[] strArr2 = (String[])field.get(field);
     System.out.println("strArr2");
     System.out.println("length: " + strArr2.length);
     System.out.println("Elements");
     for(String s : strArr2)
       System.out.println(s);
    }
  }
}

Result
Array Name: strArr
Array Type: class java.lang.String
Reflection
length: 3
Elements
a0
a1
a2

strArr
length: 3
Elements
a0
a1
a2

strArr2
length: 3
Elements
a0
a1
a2
isArray() verifies if a type is an array type. Returns true if the type is an array. Otherwise, returns false. getComponentType(interchangeable with componentType method) method returns a Class object with component type of an array. Otherwise, returns null. ComponentType of an array is the type of element that we can put in the array. In the example above, the component type of strArr array is java.lang.String.

If you wanna obtain array type, use getType() method. This method returns array type in this format: braces+L+component-type. Example, [Ljava.lang.String represents a one-dimensional array with java.lang.String as its component type. [[Ljava.lang.String represents a two-dimensional array with java.lang.String as its component type.

newInstance(Class<?> componentType, int length) in set(Object array, int index, Object value) method in Array class creates a new array. componentType is the component type of the array and length is the number of elements in array.

set(Object array, int index, Object value) method in Array class sets a value in a specified index. array parameter is the array where we wanna set a value, index parameter is where the value is going to be placed and value is the value to be placed in the specified index in the specified array.

If you're setting primitive value to a primitive-type array, use the setter methods in Array class that correspond to primitives like setInt, setBoolean and others.

getLength in Array class returns the total length of an array. get(Object array, int index) method retrives a value in an array. array parameter is the array where the value is to be obtained. index parameter is the location of the value to be obtained. If you're getting primitive value from a primitive-type array, use getter methods in Arrayclass that correspond to primitives like getInt, getBoolean and others.

Working on Multi-Dimensional Arrays

Working on multi-dimensional arrays is similar to working on one-dimensional array. Note that multi-dimensional array is just an array inside an array. This example demonstrates creating and accessing multi-dimensional array.
import java.lang.reflect.*;

public class SampleClass{
  
  public static void main(String[] args){
    //2x1 array
    Object o = Array.newInstance(String[].class,2);
    Array.set(o,0,new String[]{"a","b"});
    Array.set(o,1,new String[]{"c","d"});
    
    Object row0 = Array.get(o,0);
    Object row1 = Array.get(o,1);
    
    System.out.println("Row1");
    for(String s : (String[])row0)
      System.out.println(s);
    System.out.println();
    
    System.out.println("Row2");
    for(String s : (String[])row1)
      System.out.println(s);
    System.out.println();
    
  }
}

Result
Row1
a
b

Row2
c
d
Another way of creating multi-dimensional array is by invoking the second form of newInstance method. newInstance(Class<?> componentType, int... dimensions) Creates a new array with the specified component type and dimensions. If componentType represents a non-array class or interface, the new array has dimensions.length dimensions and componentType as its component type.

If componentType represents an array class, the number of dimensions of the new array is equal to the sum of dimensions.length and the number of dimensions of componentType. In this case, the component type of the new array is the component type of componentType.

This example demonstrates the method.
import java.lang.reflect.*;

public class SampleClass{

  public static void main(String[] args){
    //2x2 array
    Object o = Array.newInstance(int.class,2,2);
    
    Object row1 = Array.get(o,0);
    Array.set(row1,0,2);
    Array.set(row1,1,4);
    
    Object row2 = Array.get(o,1);
    Array.set(row2,0,6);
    Array.set(row2,1,8);
    
    System.out.println("Row1");
    for(int i : (int[])row1)
      System.out.println(i);
    System.out.println();
    
    System.out.println("Row2");
    for(int i : (int[])row2)
      System.out.println(i);
    System.out.println();
  }
}
Result
Row1
2
4

Row2
6
8
Another example.
import java.lang.reflect.*;

public class SampleClass{
  public static String[] str =
  new String[1];
  
  public static void main(String[] args)
                throws NoSuchFieldException{
    Field field = SampleClass.class.getField("str");
    //1x2 array
    Object o = Array.newInstance(field.getType(),1,2);
    System.out.println(Array.getLength(o));
    
    Object o1 = Array.get(o,0);
    System.out.println(Array.getLength(o1));
    Array.set(o1,0,new String[]{"a","b","c"});
    Array.set(o1,1,new String[]{"d","e"});
    
    for(String s : (String[])Array.get(o1,0))
      System.out.println(s);
    for(String s : (String[])Array.get(o1,1))
      System.out.println(s);
    
  }
}

Result
1
2
a
b
c
d
e
Accessing Enums

An enum is a language construct that is used to define type-safe enumerations which can be used when a fixed set of named values is desired. All enums implicitly extend java.lang.Enum. Enums may contain one or more enum constants, which define unique instances of the enum type. An enum declaration defines an enum type which is very similar to a class in that it may have members such as fields, methods, and constructors (with some restrictions).

This example demonstrates accessing enums via reflection.
import java.lang.reflect.*;

enum Days{
MONDAY, TUESDAY, WEDNESDAY, 
THURSDAY, FRIDAY, SATURDAY, SUNDAY;

final boolean field1 = false;
final int field2 = 1;
}

public class SampleClass{
  public static Days day = Days.WEDNESDAY;
  
  public static void main(String[] args)
                throws ClassNotFoundException,
                       NoSuchFieldException,
                       IllegalAccessException{
    Class<?> c = Class.forName("Days");
    
    if(c.isEnum()){
      System.out.println("enum name: " + c.getName());
      
      int mod = c.getModifiers();
      System.out.println("Modifiers: " + mod);
      System.out.println("Is public? " + 
      Modifier.isPublic(mod));
      System.out.println("Is static? " + 
      Modifier.isStatic(mod));
      System.out.println("Is final? " + 
      Modifier.isFinal(mod));
      System.out.println();
      
      System.out.println("Constants");
      for(Object o : c.getEnumConstants())
        System.out.println(o);
      System.out.println();
      
      System.out.println("Fields");
      for(Field f : c.getDeclaredFields())
        if(f.isEnumConstant())
          System.out.println("Constant: " + f.getName());
        else
          System.out.println("Field: " + f.getName());
      System.out.println();
      
      Class<?> sc = SampleClass.class;
      Field enumField = sc.getField("day");
      if(enumField.getType().isEnum()){
        System.out.println("Enum field value");
        System.out.println(enumField.get(enumField));
        System.out.println("Set value");
        enumField.set(enumField, Days.SATURDAY);
        System.out.println("Enum field value");
        System.out.println(enumField.get(enumField));
      }
      
    }
  }
}

Result
enum name: Days
Modifiers: 16400
Is public? false
Is static? false
Is final? true

Constants
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY

Fields
Constant: MONDAY
Constant: TUESDAY
Constant: WEDNESDAY
Constant: THURSDAY
Constant: FRIDAY
Constant: SATURDAY
Constant: SUNDAY
Field: field1
Field: field2
Field: $VALUES

Enum field value
WEDNESDAY
Set value
Enum field value
SATURDAY
isEnum method returns true if a Class object is an enum. Otherwise, returns false. getEnumConstants returns enum constants in the order they're declared in source code.

Take note that getDeclaredFields and getFields methods don't guarantee the order of enum constants. use getEnumConstants if enum constants are needed to be ordered.

isEnumConstant in Field class returns true if the field is an enum constants. Otherwise, returns false. We can also get and set fields with enum values by using get and set methods of Field class.

Java Reflection's Nest-Based Access Control Feature

Nest-Based feature is introduced in java 11. This feature links nested classes without creating bridge methods. Instead, this feature creates nest-based attributes in class files to determine the relationship between nested classes. Java adds access controls to java reflection in order to deal with the new feature.

a nest consists of a nest host and nest mates. Typically, nest host is the top-level class and nest mates are classes enclosed within a nest host. This example demonstrates methods that can access nest-based attributes.
import java.util.ArrayList;

public class SampleClass{

  public static void main(String[] args){
    
    Class<?> hostClass = Host.class;
    ArrayList<Class<?>> list =
    new ArrayList<>();
    
    System.out.println
    (hostClass.getName() + 
    " class nest mates/members");
    for(Class<?> c : hostClass.getNestMembers()){
      System.out.println(c.getName());
      list.add(c);
    }
    System.out.println();
    
    for(Class<?> c : list){
      System.out.println("Nest host of " + c.getName());
      System.out.println(c.getNestHost().getName());
      System.out.println
      (c.getName()+" nest mate of " + hostClass.getName());
      System.out.println(c.isNestmateOf(hostClass));
      System.out.println();
    }
  }
}

class Host{
  class ClassA{
    class ClassC{
    }
  }
  
  class ClassB{
  }
}

Host class nest mates/members
Host
Host$ClassB
Host$ClassA
Host$ClassA$ClassC

Nest host of Host
Host nest mate of Host
true

Nest host of Host$ClassB
Host
Host$ClassB nest mate of Host
true

Nest host of Host$ClassA
Host
Host$ClassA nest mate of Host
true

Nest host of Host$ClassA$ClassC
Host
Host$ClassA$ClassC nest mate of Host
true

getNestMembers returns an array of nest mates of a nest host. There are interesting things in the result above. First off, the "root" nest host(Host class) considers itself as its nest mate. This could mean that the nest host can access itself which is pretty normal.

Another interesting thing is that ClassC is a nest mate of Host class. You might ask why ClassA is not the nest host of ClassC. Note that inheritance is different from nest-based feature. Nest-based feature is about links or communication lines, if you will, between nested classes whereas inheritance is about relationships between classes.

That's why ClassC is not nest mate of ClassA even ClassC is a subclass of ClassA. The nest host of ClassC is Host because, in my opinion, ClassC requires to link to Host first and then Host links ClassC to ClassA.

getNestHost returns the nest host of a Class object that invokes this method. isNestmateOf method tests if the Class object that invokes this method is a nest mate of the given Class object in the argument. Returns true if the test is successful. Otherwise, returns false.

If we change the "root" nest host to a subclass of Host class, the result will change. Try changing this line:
Class<?> hostClass = Host.class;
To this:
Class<?> hostClass = ClassA.class;
And the result will be:
ClassA nest mates/members
ClassA

Nest host of ClassA
ClassA nest mate of ClassA
true
In the example above, the nest host and nest mate of ClassA is itself. That's because ClassA is the "root" nest host and "root" host considers itself as its nest host and nest mate. Although, ClassC is still not a nest mate of ClassA because in the class file of ClassC, Host class is the nest host of ClassC.

Troubleshooting

In this chapter, I'm gonna discuss some exceptions that we may encounter when using java reflection and how to avoid them.

Fields

Getter and setter methods of Field class methods throw IllegalArgumentException if an argument can't be referenced to a designated field. This example demonstrates this scenario.
import java.lang.reflect.*;

public class SampleClass{
  public static Integer num;
  
  public static void main(String[] args)
                throws NoSuchFieldException,
                       IllegalAccessException{
    Field f = SampleClass.class.getField("num");
    f.setInt(f,4);
  }
}

Result
IllegalArgumentException...
To avoid this problem, use the appropriate set method for a specific type. Try changing this:
f.setInt(f,4);
To this:
f.set(f, Integer.valueOf(4));
And IllegalArgumentException in the example above will be gone. Integer is an Object. Thus, we should use set method.

Getter and setter methods of Field class support upcasting(widening) but don't support downcasting(narrowing). An exception will be thrown if we try to do downcasting. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{
  public static int num = 0;
  
  public static void main(String[] args)
                        throws Exception{
    Field f = SampleClass.class.getField("num");
    //upcasting works
    f.setShort(f,(short)4);
    System.out.println(SampleClass.num);
    //downcasting doesn't work
    //IllegalArgumentException
    f.setLong(f,2L);
  }
}

Result
4
IllegalArgumentException...
If we try to obtain field from a non-public Field object using getField method, java will throw NoSuchFieldException. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{
  private static Integer num;
  
  public static void main(String[] args)
                throws NoSuchFieldException,
                       IllegalAccessException{
    Field f = SampleClass.class.getField("num");
    f.set(f, Integer.valueOf(4));
  }
}

Result
NoSuchFieldException...
Use getDeclaredField method when accessing non-public fields.

IllegalAccessException may be thrown if an inaccessible private field is being accessed. In java versions prior to java 11, it is recommended to enable field accessibility by invoking setAccessible method. This method accepts a boolean value as an argument. set the argument to true to enable accessibility. Otherwise, set it to false.

IllegalAccessException or IllegalArgumentException may be thrown if a final public or non-public field value is accessed. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{
  public final int num = 4;
  
  public static void main(String[] args)
                throws NoSuchFieldException,
                       IllegalAccessException{
    Field f = SampleClass.class.getField("num");
    f.setInt(f, 4);
    //This will throw an exception too
    //Object o = f.getInt(f);
  }
}

Result
IllegalArgumentException...
Methods

NoSuchMethodException is thrown if we try to look for a method with Non-reifiable parameterized type. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{
  
  public static void main(String[] args)
                throws NoSuchMethodException{
    Class<?> c = 
    new ClassA<String>().getClass();
    Method m = c.getMethod("meth",String.class);
  }
}

class ClassA<T>{
  public void meth(T o){
    System.out.println(o);
  }
}

Result
NoSuchMethodException...
Remember that non-reifiable type like T and the type that is going to replace T which is String will be erased due to type erasure. Instead, T will be replaced with its upper bound which is Object type.

Try changing this:
Method m = c.getMethod("meth",String.class);
To this:
Method m = c.getMethod("meth",Object.class);
And NoSuchMethodException in the example above will be gone.

Reflection follows methods access restriction that is applied to direct invocation of methods. For example, private methods can only be accessed by its enclosing class and that enclosing class members. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{

  public static void main(String[] args)
                throws NoSuchMethodException,
                       IllegalAccessException,
                       InvocationTargetException{
    ClassA<String> ca = new ClassA<>();
    Class<?> c = ca.getClass();
    Method m = c.getDeclaredMethod("meth",Object.class);
    m.invoke(ca,"Hello");
  }
}

class ClassA<T>{
  private void meth(T o){
    System.out.println(o);
  }
}

Result
IllegalAccessException...
meth can't be invoked outside ClassA because meth is a private method. We can use setAccessible method to suppress IllegalAccessException in this situation. Add this line of code before invoking the method:
m.setAccessible(true)
Put it like this:
m.setAccessible(true);
m.invoke(ca,"Hello");
If it succeeds, java will print(without quotes) "Hello" on the console.

invoke method has been retrofitted to be a variable-arity method(method that takes one or more arguments). Although, sometimes, this can cause ambiguity. Take a look at this example.
Source: The Java™ Tutorials

import java.lang.reflect.Method;

public class MethodTroubleToo {
    public void ping() { System.out.format("PONG!%n"); }

    public static void main(String... args) {
	try {
	    MethodTroubleToo mtt = new MethodTroubleToo();
	    Method m = MethodTroubleToo.class.getMethod("ping");

 	    switch(Integer.parseInt(args[0])) {
        
        // works
	    case 0:
  		m.invoke(mtt);
		break;
        
        // works (expect compiler warning)
	    case 1:
 		m.invoke(mtt, null); 
		break;
        
        // IllegalArgumentException
	    case 2:
		Object arg2 = null;
		m.invoke(mtt, arg2);
		break;
        
        // IllegalArgumentException
	    case 3:
		Object arg4 = new Object[0];
		m.invoke(mtt, arg4);           
		break;
        
        // works
	    case 4:
		m.invoke(mtt, new Object[0]);
		break;
        
	    default:
		System.out.format("Test not found%n");
	    }

        // production code should 
        //handle these exceptions more gracefully
	} catch (Exception x) {
	    x.printStackTrace();
	}
    }
}
In the example above, case 0 works fine because it met the right criteria for invoking ping method. case 1 works but it's kinda ambiguous because of the null argument. This case works because we're assigning a null value to a varargs parameter.

When we directly assign a null value to a varargs parameter, the varargs is "ambiguously zero-length". Thus, java doesn't consider a null value as varargs. Moreover, java still thinks something is wrong.

case 2 doesn't work because null is assigned to an Object-type variable. Once we put a variable in the argument-list of a method, this variable will be considered as a regular argument even the value of that variable is null. This explanation is also applicable to case 3.

case 4 works because we're assigning a zero-length array to varargs. Zero-length array is equivalent to zero-length varargs.

An InvocationTargetException wraps all exceptions (checked and unchecked) produced during the invocation of a method. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{

  public float compute(int num){
    System.out.println("Invoke compute method");
    return num/0;
  }
  
  public static void main(String[] args)
                throws NoSuchMethodException,
                       IllegalAccessException,
                       InvocationTargetException{
    Class<?> c = SampleClass.class;
    Method m = c.getMethod("compute", int.class);
    Object f = m.invoke(new SampleClass(),5);
    System.out.println("result: " + f);
  }
}

Result
Invoke compute method
InvocationTargetException...
...
Caused by: java.lang.ArithmeticException: / by zero
...
If an InvocationTargetException is thrown, the method was invoked. Diagnosis of the problem would be the same as if the method was called directly and threw the exception. This exception does not indicate a problem with the reflection package or its usage.

Constructors

Any exception(checked or unchecked) that is thrown during object instantiation using newInstance method will be wrapped into an InvocationTargetException.
import java.lang.reflect.*;

public class SampleClass{
  int num = 0;
  
  public SampleClass(int num){
    this.num = num/0;
  }
  
  public static void main(String[] args)
                throws InstantiationException,
                       NoSuchMethodException,
                       IllegalAccessException,
                       InvocationTargetException{
    Constructor c = 
    SampleClass.class.getConstructor(int.class);
    SampleClass sc = (SampleClass)c.newInstance(5);
  }
}

Result
InvocationTargetException...
...
Caused by: java.lang.ArithmeticException: /by zero
...
If an InvocationTargetException is thrown, the constructor was invoked. Diagnosis of the problem would be the same as if the constructor was called directly and threw the exception. This exception does not indicate a problem with the reflection package or its usage.

Sometimes, we may have problems regarding locating and invoking constructor. This example demonstrates some of the problems that we may encounter.
public class SampleClass{
  
  SampleClass(){
    System.out.println
    ("Constructor with 0 parameters");
  }
  
  SampleClass(Integer num){
    System.out.println("Integer: " + num);
  }
  
  SampleClass(Object obj){
    System.out.println("Object: " + obj);
  }
  
  SampleClass(String str){
    System.out.println("String: " + str);
  }
  
  public static void main(String[] args)
                throws Exception{
    
    Class<?> c = SampleClass.class;
    
    int num = 0;
    switch(num){
      case 0:
      //IllegalArgumentException: wrong 
      //number of arguments
      c.getDeclaredConstructor().
      newInstance("Hello");
      break;
      
      case 1:
      //NoSuchMethodException
      //no constructor with int parameter
      c.getDeclaredConstructor(int.class).
      newInstance(4);
      break;
      
      case 2:
      //Result: Object: Hi
      //Doesn't perform method/constructor
      //resolution
      c.getDeclaredConstructor(Object.class).
      newInstance("Hi");
      break;
      
      default:
      System.err.println("Invalid number!");
      break;
    }
  }
}
In case 0, We looked for a constructor without parameter. Then, we attempted to invoke a constructor with parameter. IllegalArgumentException is thrown because we tried to invoke a constructor that didn't correspond with the constructor that was returned by getConstructor method.

In case 1, we attemped to look for a constructor with int parameter. NoSuchMethodException is thrown because such constructor doesn't exist. Remember that int primitive is different from Integer class. If you expect java to autobox int value and invokes a constructor with Integer parameter, if won't happen because autoboxing doesn't work with reflection.

Try directly invoking the constructor like this:
new SampleClass(4);
and the result will be:
Integer: 4
This example shows one of the differences between invoking constructor directly and invoking constructor via reflection.

In case 2, constructor with Object parameter was invoked. Method/Constructor resolution doesn't work with reflection. Method/Constructor resolution is a mechanism that looks for a method/constructor that is mostly suitable for the given arguments. In the example above, the constructor with String parameter should have been invoked if the Method/Constructor resolution was working with reflection.

Try directly invoking the constructor like this:
new SampleClass("Hi");
and the result will be:
String: Hi
This example shows another difference between invoking constructor directly against invoking constructor via reflection.

Reflection follows constructor access restriction that is applied to direct invocation of constructors. For example, private constructors can only be accessed by its enclosing class and that enclosing class members. Take a look at this example.
public class SampleClass{
  
  public static void main(String[] args)
                        throws Exception{
    ClassA.class.getDeclaredConstructor().
    newInstance();
  }
}

class ClassA{
  private ClassA(){
    System.out.println
    ("ClassA Private Constructor!");
  }
}

Result
IllegalAccessException...
Class constructor can't be invoked outside ClassA because the constructor is a private method. We can use setAccessible method to suppress IllegalAccessException in this situation. Add this line of code before invoking the constructor:
m.setAccessible(true)
Put it like this:
Constructor c = ClassA.class.getConstructor();
c.setAccessible(true);
c.newInstance();
If it succeeds, the message in the constructor will be printed.

Arrays

Just like in Field class, Getter and setter methods of Array class methods throw IllegalArgumentException if an argument can't be placed in a particular array. This example demonstrates an attempt to set an int value to an index in an Integer-type array.
import java.lang.reflect.Array;

public class SampleClass{

  public static void main(String[] args)
                        throws Exception{
    Integer[] arr = new Integer[2];
    Array.setInt(arr,0,4);
  }
}

Result
IllegalArgumentException...
To solve this problem, use the appropriate method for a specific array-type. change this line of codes:
Array.setInt(arr,0,4);
To this:
Array.set(arr,0,Integer.valueOf(4));
And IllegalArgumentException will be gone. Integer is an Object. Thus, we should use set method.

Just like in Field class, Getter and setter methods of Array class support upcasting(widening) but don't support downcasting(narrowing). An exception will be thrown if we try to do downcasting. Take a look at this example.
import java.lang.reflect.Array;

public class SampleClass{

  public static void main(String[] args){
    int[] nums = new int[1];
    //upcasting works
    Array.setShort(nums,0,(short)2);
    System.out.println(nums[0]);
    //downcasting doesn't work
    //IllegalArgumentException
    Array.setLong(nums,0,4L);
  }
}

Result
2
IllegalArgumentException...
In reflection, If we get/set a value of an zero-length array, ArrayIndexOutOfBoundsException will be thrown. Take a look at this example.
import java.lang.reflect.Array;

public class SampleClass{

  public static void main(String[] args){
    int[] nums = new int[0];
    int num = Array.getInt(nums,0);
    System.out.println(num);
  }
}

Result
ArrayIndexOutOfBoundsException...
In common code, this problem occurs in a few cases. In reflection, you may encounter this in several cases. If you encounter ArrayIndexOutOfBoundsException, you may check the length of the array you're accessing by invoking getLength method in order to know if you're dealing with zero-length array or not.

Enums

Instantiation of enum types explicitly is forbidden in common coding and reflection. One of reasons why we can't is to preserve the uniqueness of enums. If we try to explicitly instantiate an enum type in reflection, IllegalArgumentException will be thrown. Take a look at this example.
import java.lang.reflect.*;

public class SampleClass{

  public static void main(String[] args)
                        throws Exception{
    Constructor[] cons = 
    Weekends.class.getDeclaredConstructors();
    
    for(Constructor c : cons){
      System.out.println("Name: " + c.getName());
      c.setAccessible(true);
      c.newInstance();
    }
  }
}

enum Weekends{
  SATURDAY, SUNDAY;
  
  Weekends(){
    System.out.println("Invoking...");
  }
}

Result
Name: Weekends
...IllegalArgumentException...
To avoid this problem, check first if the Class object that you wanna instantiate is an enum type by invoking isEnum method.

Another problem that we may encounter is setting an incompatible enum constant to a enum variable. This will throw IllegalArgumentException. Take a look at this example.
import java.lang.reflect.Field;

enum A1{
  A,B
}

enum A2{
  C,D
}

public class SampleClass{
  private static A1 a1 = A1.A;
  
  public static void main(String[] args)
                        throws Exception{
    Field f = 
    SampleClass.class.getDeclaredField("a1");
    f.set(f,A2.C);
  }
}

Result
IllegalArgumentException...
To avoid this problem, we can check if an enum constant can be assigned to an enum variable by invoking isAssignableFrom method. This method returns true if the given object type can be assigned to the object type in Field object. Otherwise, returns false. Let's modify the example above.
import java.lang.reflect.Field;

enum A1{
  A,B
}

enum A2{
  C,D
}

public class SampleClass{
  private static A1 a1 = A1.A;
  
  public static void main(String[] args)
                        throws Exception{
    Field f = 
    SampleClass.class.getDeclaredField("a1");
    if(A2.class.isAssignableFrom(A1.class))
      f.set(f,A2.C);
    else
      System.out.println("Incompatible!");
  }
}

Result
Incompatible!