A classe Calendar no Java é uma classe abstrata que fornece a estrutura necessária para converter um instante de tempo específico em um conjunto de campos de calendário, como YEAR, MONTH, DAY_OF_MONTH, HOUR, entre outros. Além da conversão, ela permite a manipulação desses campos para realizar cálculos de datas, como determinar a data da próxima semana.

O ponto de partida para representar o tempo é um valor em milissegundos que corresponde ao deslocamento a partir da "Epoch" (a Era padrão), definida como 1º de janeiro de 1970 00:00:00.000 GMT (Calendário Gregoriano). Sendo uma classe abstrata, o Calendar não pode ser instanciado diretamente com a palavra-chave new. Em vez disso, utiliza-se métodos de fábrica estáticos.

Para obter uma instância pronta para uso, geralmente recorre-se ao método getInstance. Este método retorna um objeto Calendar cujos campos já foram inicializados com a data e hora atual do sistema, considerando o fuso horário e a localidade padrão (Locale).

Abaixo, apresentamos uma representação simplificada da estrutura interna da classe, ilustrando como os dados são gerenciados:

public abstract class Agenda implements Serializable, Cloneable, Comparable<java.util.Calendar> {

    protected long tempoMilis;

    public int get(int campo) {
        finalizar();
        return recuperarInterno(campo);
    }

    public static Calendar getInstance() {
        return criarCalendario(TimeZone.getDefault(), Locale.getDefault(Locale.Category.FORMAT));
    }

    public final Date obterData() {
        return new Date(getTempoEmMilis());
    }

    public long getTempoEmMilis() {
        if (!tempoDefinido) {
            recalcularTempo();
        }
        return tempoMilis;
    }
}

Leitura de Campos Temporais

O método get(int field) é utilizado para extrair informações específicas do objeto Calendar. O código a seguir demonstra como recuperar componentes individuais da data atual, como ano, mês, dia e hora, além de informações relativas à semana e ao dia do ano:

Calendar dataAtual = Calendar.getInstance();

int ano = dataAtual.get(Calendar.YEAR);
int mes = dataAtual.get(Calendar.MONTH);
int dia = dataAtual.get(Calendar.DATE);
int hora = dataAtual.get(Calendar.HOUR);
int minuto = dataAtual.get(Calendar.MINUTE);
int segundo = dataAtual.get(Calendar.SECOND);

System.out.println("Data formatada: " + ano + "-" + (mes + 1) + "-" + dia + " " + hora + ":" + minuto + ":" + segundo);

int semanaAno = dataAtual.get(Calendar.WEEK_OF_YEAR);
int diaAno = dataAtual.get(Calendar.DAY_OF_YEAR);
System.out.println("Semana do Ano: " + semanaAno + " | Dia do Ano: " + diaAno);

int semanaMes = dataAtual.get(Calendar.WEEK_OF_MONTH);
int diaMes = dataAtual.get(Calendar.DAY_OF_MONTH);
System.out.println("Semana do Mês: " + semanaMes + " | Dia do Mês: " + diaMes);

int diaSemana = dataAtual.get(Calendar.DAY_OF_WEEK);
int diaSemanaMes = dataAtual.get(Calendar.DAY_OF_WEEK_IN_MONTH);

Modificação de Campos Temporais

Para definir valores específicos para ano, mês, dia, hora, minuto e segundo, utiliza-se o método sobrecarregado set. Este método é útil para retroceder ou avançar a data para um momento determinado. O exemplo abaixo configura uma data histórica específica e a exibe formatada:

Calendar configuracaoData = Calendar.getInstance();
configuracaoData.set(1995, Calendar.MAY, 15, 08, 30, 00);

Data dataDefinida = configuracaoData.getTime();
System.out.println("Objeto Date: " + dataDefinida);

FormatoData formatter = DateFormat.getDateTimeInstance();
String dataFormatada = formatter.format(dataDefinida);
System.out.println("Data Formatada: " + dataFormatada);