Table Of Contents
Overview
Before plunging into the details of Joda-Time, it is important to clarify the key concepts related to date and time. This article details out the the concepts related to date and time with respect to Joda-Time API.
Note: This article is based on ISO 8601 Calendar System.
Date Concepts
Calendar
: A system of reckoning dates. Examples of Calendar systems are ISO 8601, Gregorian, Islamic, Buddhist, Coptic, etc.
Date
: The basic element of a Calendar system is a date. e.g. 1st of February, 2003. It typically consists of three sub-elements:
- Day of Month: In this example, the day of month is 1
- Month of Year: In this example, the month of year is February
- Year: In this example, the year is 2003
Day
: The Day can be evaluated in three ways:
- Day Of Month: The number of days since the begining of current month.
e.g. In the case of 1st of February, 2003, the day of month is 1 - Day Of Week: The number of days since the begining of week. Monday is the 1st day, Tuesday is 2nd day and so on till Sunday which is the 7th day.
e.g. In case of 1st of February, 2003, the day of Week is 1 i.e. Saturday - Day Of Year: The number of days since the begining of the calendar year starting from 1st of January.
e.g. In case of 1st of February, 2003, the day of Year is 32.
Year
: Year can be evaluated in following four ways:
- Calendar Year: Most commonly used representation of year (typically using four digits).
e.g. In case of 1st of February, 2003, the year is 2003.Note: Calendar year can be zero or negative in which case it represents a year in BC (Before Christ) Era.
- Week Year: A year in which all the weeks are whole weeks. It means that any week in a week year does not transition between years. It also implies that the begining of a week year may not start with 1st of January and that the last day of a week year may not end with 31st of December.
The first week of the week year is the week that contains 1st of January. The last of week of the week year is the 52nd week from the first week in week year.It is important to note that a given date may belong to a different calendar year and week year.
e.g. For the calendar year 2014, the 1st week of weekyear is shown below. This week year starts on 30th of December 2013.
Hence, in this example. the date 30th of December belongs to the calendar year 2013 but it belongs to week year 2014.
As another example. For the calendar
year 2014, the 52nd week of weekyear is shown below. This week year ends on 28th of December 2014.
- Year Of Century: It the number of years from the start of the century (which is typically the last two digits of the calendar year). See Century for further details.
e.g. For the date 1st of February, 2013, the year of century is 13.
e.g. For the date 4th of September 1967, the year of century is 67 - Year Of Era: The number of years from the begining of the era (see Era for further details.
Typically, for all calendar years belonging to AD (Anno Domini) Era, the calendar year value and year of era value is the same.
e.g. For the date, 1st of February, 2003, the year of era is 2003.However, for the BC (Before Christ) Era, it is important to note that the calendar year 0000 corresponds to 1BC, the calendar year -0001 corresponds to 2BC, the calendar year -0002 corresponds to 3BC and so on.
- Week Of Week Year: The week number in a week year in which the given date belongs.
See the related concept of Week Year.
e.g.The date 3rd of January 2014 belongs the first week of week year 2014.
The date 15th of January 2014 belongs to the 3rd week of week year 2014.
Century Of Era
: The century of the era to which the given date belongs (see
Era
for more details).
-
Typically it is the first two digits of the 4 digit representation of the Calendar Year (see
Year for more details).
e.g. for the date 2nd of March 2015, the century of era is 20 (which is the first two digits of 2015).
Era
: The ISO 8601 Calendar System is divided into two eras:
- BC (Before Christ): The calendar years 0000, -0001, -0002, -0003, … fall under the BC era
- AD (Anno Domini): The calendar years 0001,0002,0003, … fall under the AD era
Typically it is the first two digits of the 4 digit representation of the Calendar Year (see
Year
for more details).
e.g. for the date 2nd of March 2015, the century of era is 20 (which is the first two digits of 2015).
Epoch
: Epoch is a reference date. With respect to computing, it is the time kept internally by a computer system. Of particular importance is the Java Epoch which starts on midnight of 1st Of January 1970.
Time Concepts
-
It is convenient from a practical standpoint for areas with close commercial or social purposes to keep the same time. Hence TimeZone provides a way to demarcate a geographic region, typically along longitudes, boundaries of countries or thier states, so that all locations within that region share the same time.
The standard for calculating TimeZones is called
Coordinated Universal Time (UTC) (see
here
The earth’s surface is partitioned into 24 regions in which standard time is kept as shown below.
-
it is the amount of time that is added or subtracted from UTC (a.k.a Coordinated Time Zone) to get the actual time in a region.
e.g. The Eastern standard time in US and Canada is typically 5 hours behind UTC
e.g. The Indian standard time is typically 5 hours and 30 minutes ahead of UTC.
Clock Convention
: There are two conventions in dividing the day into hours:
- 12-hour Clock: A convention in which the 24 hours of the day are divided into two periods each consisting of 12 hours each:
- AM (Ante Meridiem): This period consists of hours between midnight and noon.
e.g. 5:00 A.M. means 5 hours past midnight (a.k.a. 5 in the morning) - PM (Ante Meridiem): This period consists of hours between noon and midnight.
e.g. 5:00 P.M. means 5 hours past noon (a.k.a. 5 in the evening)
A 12 hour clock starts from 0 hours, 0 minutes and 0 seconds to 11 hrs, 59 minutes and 59 seconds.
- AM (Ante Meridiem): This period consists of hours between midnight and noon.
- 24-hour Clock: A convention in which the hours in day are calculated from midnight to midnight. A day is divided into 24 hours. This convention is used in the ISO 8601 standard.
e.g. 07:00 implies 7 A.M (a.k.a 7 in the morning)
e.g. 18:00 implies 6 P.M (a.k.a 6 in the evening)A 24 hour clock starts from 0 hours, 0 minutes and 0 seconds to 23 hrs, 59 minutes and 59 seconds.
-
It represents the number of hour from the start of the day based on 24 hour clock.
e.g. 05:00 implies 5 A.M (a.k.a 5 in the morning)
e.g. 18:00 implies 6 P.M (a.k.a 6 in the evening)
Minute
: Minute can be calculated in the following two ways:
- Minute of Hour: It describes the number of minutes passed since the start of the current hour.
e.g. If the time is 07:45, it implies that 45 minutes have passed since the start of the 7th hour. - Minute of Day: It describes the number of minutes passed since the start of the current day.
e.g. If the time is 07:45, it implies that 465 minutes have passed since the start of the current day.
Second
: Second can be calculated in the following two ways:
- Second of Minute: It describes the number of secondss passed since the start of the current minute.
e.g. If the time is 07:45:30, it implies that 30 seconds have passed since the start of the 45th minute of the 7th hour. - Second of Day: It describes the number of seconds passed since the start of the current day.
e.g. If the time is 07:45:30, it implies that 27930 ((7*60*60) + (45*60) +30)seconds have passed since the start of the current day.
Milli-Second (a.k.a millis)
: Milli-Second can be calculated in the following three ways:
- Millis of Second: It describes the number of mill-secondss passed since the start of the current second.
e.g. If the time is 07:45:30:15, it implies that 15 milli-seconds have passed since the start of the 30th second of 45th minute of 7th hour. - Millis of Day: It describes the number of mill-seconds passed since the start of the current day.
e.g. If the time is 07:45:30:15, it implies that 27930015 ((7*60*60*1000) + (45*60*1000) + (30*1000) + 15)milli-seconds have passed since the start of the current day. - Millis: It describes the number of mill-seconds passed since the start of the 1st Of January 1970 which corresponds to Java Epoch (see Epoch for further details).
e.g. If the date-time is 2014:01:06T07:45:30:15, it implies that 1396750530015 milli-seconds have passed since the start of 1st Of January 1970.
Joda-Time Specific Concepts
The following sections elaborate the key concepts with specific interpretation in Joda-Time API which are listed here for sake of completeness:
To start, click on the next arrow. If you find anything missing in the tutorials then please drop in your comments.