Overview

DateTime
is the most commonly class in Joda-Time to represent date and time.

This article is a How-To guide on accessing the various features provided by
DateTime
as listed below:

1. Instantiate DateTime
2. Get DateTime for current instant
3. Get sub-elements of DateTime (e.g. year, month, hours, etc.)
4. Perform arithmetic operations on DateTime like addition and substraction
5. Update sub-elements of DateTime
6. Get DateTime from String representation
7. Compare two DateTime instances
8. Convert DateTime to other representations like Milliseconds, JDK date, MutableDateTime, LocalDateTime and String
9. Handling DateTime Exceptions

Instantiate DateTime

Instantiate DateTime using the various constructors which include date fields, time fields, timezone and chronology.

---

Get DateTime for current instant

Joda-Time provides a convenience method
DateTime.now()
to get the DateTime for current instant.

---

Get sub-elements of DateTime (e.g. year, month, hours, etc.)

DateTime API provides a number of methods to access sub-elements of date and time like year, month, day, hour, minute, second, etc.

---

Perform arithmetic operations on DateTime like addition and substraction

DateTime provides methods to add or subtract sub-elements from a DateTime.

The output of the above program is shown below. The changed sub-element after the arithmetic operations are underlined for emphasis.

---

Update sub-elements of DateTime

DateTime is immutable. However it is often useful from programming perspective to modify sub-elements of (e.g. year, month, hour, etc.) date and time. Note however that a new instance of DateTime is returned after making the desired modifications as the original instance in immutable.

There are two ways to modify sub-elements of DateTime:

1. Convenience Methods: DateTime class has numerous convenience methods that enable us to update the value of sub-elements of a given DateTime.
2. Using DateTimeFieldType: DateTime.withField() can be used in conjunction with methods defined in DateTimeFieldType to modify DateTime.

The output of the above program is shown below. The changed sub-element after the modifying the DateTime are underlined for emphasis.

---

Get DateTime from String representation

DateTime.parse()
method can be used to convert String representation of date and time to DateTime.

In the example below, String representations for both date and date-time are used to get DateTime instance.

---

Compare two DateTime instances

There are three ways to compare two DateTime instances:

1. Using convenience methods line DateTime.isBefore(),DateTime.isAfter() and DateTime.isEqual()
2. Using DateTime.compareTo() method.
   The return integer follows the contract mentioned in Comparable interface
3. Using DateTimeComparator. This is discussed in detail here.

This example demonstrates the usage of point 1 and 2 mentioned above.

---

Convert DateTime to other representations like Milliseconds, JDK date, MutableDateTime, LocalDateTime and String

This example demonstrates how to convert DateTime to other representations.

---

Handling DateTime Exceptions

If an illegal value for a DateTime field is passed then and
IllegalFieldValueException
is thrown.

To start, click on the next arrow. If you find anything missing in the tutorials then please drop in your comments.