Support free tutorials

vogella training Training Books

Java Date, Calendar and Time API - Tutorial

Lars Vogel

Version 1.1


Java Date and Time API

This article explains the API for using Calendar, Date and Time in Java and how to format the output of a date.

Table of Contents

1. Overview
2. Format date
3. Working with Dates and Calendars
3.1. Calendar
3.2. Date and Date Conversion
4. About this website
4.1. Donate to support free tutorials
4.2. Questions and discussion
4.3. License for this tutorial and its code
5. Links and Literature

1. Overview

The Java language provides direct support for time-based objects. This article gives a few examples how this API can be used.

The java.util.Date and the java.util.Calendar classes provide access to storing and manipulating dates.

It is recommended to use Calendar if possible. Existing API may required that you convert from Date to Calendar and vice versa.

2. Format date

To format a date, you can use the SimpleDateFormat class. The following snippet gives several example for its usage.

// use dd/MM/yy as format

DateFormat df1 = new SimpleDateFormat("dd/MM/yy");
String formattedDate1 = df1.format(new Date());

// or use yyyy/MM/dd as format

DateFormat df2 = new SimpleDateFormat("yyyy/MM/dd");
String formattedDate2 = df2.format(theDate); 

3. Working with Dates and Calendars

3.1. Calendar

The java.util.Calendar class is an abstract encapsulation of the Date object.

Calendar provides getter and setter for the date fields.

public final int get(int field)
public final void set(int field, int value) 

Table 1. Calendar field access

Field Explanation
Calendar.YEAR Identifies the year
Calendar.MONTH Identifies the month
Calendar.DAY_OF_MONTH Identifies the day
Calendar.HOUR Identifies the hour
Calendar.MINUTE Identifies the minute
Calendar.SECOND Identifies the second


The Calendar.MONTH starts with 0. So December is 11.

Create a new Java project called JavaIntroCalendar. Create the following class for testing.

package test;

import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.GregorianCalendar;

public class CalendarTest {
  public static void main(String[] args) {
    // constructor allows to set year, month and date
    Calendar cal1 = new GregorianCalendar(2008, 01, 01);
    // constructor could also be empty
    // calendar cal2 = new GregorianCalendar();
    // change the month
    cal1.set(Calendar.MONTH, Calendar.MAY);

    System.out.println("Year: " + cal1.get(Calendar.YEAR));
    System.out.println("Month: " + (cal1.get(Calendar.MONTH) + 1));
    System.out.println("Days: " + cal1.get(Calendar.DAY_OF_MONTH));

    // format the output with leading zeros for days and month
    SimpleDateFormat date_format = new SimpleDateFormat("yyyyMMdd");


3.2. Date and Date Conversion

Use the following commands to convert to a Date from various formats.

package conversion;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;

public class ConversionExamplesDate {

  // convert from String to date
  private void stringToDate() {
    try {
      Date date1;
      date1 = new SimpleDateFormat("MM/dd/yy").parse("05/18/05");
      Date date2 = new SimpleDateFormat("MM/dd/yyyy").parse("05/18/2007");
    } catch (ParseException e) {

  // convert from millisecs to a String with a defined format
  private void calcDate(long millisecs) {
    SimpleDateFormat date_format = new SimpleDateFormat("MMM dd,yyyy HH:mm");
    Date resultdate = new Date(millisecs);
  private void writeActualDate(){
    Calendar cal = new GregorianCalendar();
    Date creationDate = cal.getTime();
    SimpleDateFormat date_format = new SimpleDateFormat("MMM dd,yyyy HH:mm");

  public static void main(String[] args) {
    ConversionExamplesDate convert = new ConversionExamplesDate();

4. About this website

4.1. Donate to support free tutorials

Please consider a contribution Support free tutorials if this article helped you. It will help to maintain our content and our Open Source activities.

4.2. Questions and discussion

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

4.3. License for this tutorial and its code

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

5. Links and Literature

Not yet listed