Conheça a biblioteca Java Joda-Time

� muito comum a manipula��o de datas na linguagem Java, pois este artif�cio faz-se necess�rio em quase todos os tipos de sistemas. � percept�vel que as classes que trabalham com Data, do Java 8 pra tr�s, possuem poucos recursos e para realizar tarefas simples acaba sendo uma grande dor de cabe�a.

Neste artigo veremos uma biblioteca muito conhecida e utilizada quando tratamos de Data no Java: a Joda-Time. Esta biblioteca oferece in�meros recursos que possibilitam tornar tarefas antes complexas em simples, � o velho ditado: �Porque reinventar a roda se ela j� foi inventada?�.

Usaremos a IDE Eclipse para teste das nossas aplica��es e importaremos a biblioteca joda-time-2.7.jar no classpath do nosso projeto para que seja poss�vel usar as classes oferecidas pela mesma. Este arquivo jar pode ser encontrado na op��o c�digo fonte deste artigo.

Joda-Time

A primeira pergunta a se fazer �: Porque eu deveria usar o Joda-Time? Porque n�o continuar usando as pr�prias classes oferecidas pelo Java? Vejamos:

A produtividade aumentar� muito com o uso de uma biblioteca que lhe forne�a resultados simples para processos que antes eram considerados complexos.
Proporciona melhor performance do que a classe Calendar, usualmente utilizada para fins de manipula��o de datas. Isso ocorre devido ao m�nimo de c�lculo realizado no acesso de algum campo.
Possui vasta comunidade e documenta��o para auxiliar-lhe em d�vidas ou problemas que possam ocorrer.
C�lculos de Time Zone s�o atualizados v�rias vezes por ano, para garantir consist�ncia dos dados. Estes s�o atualizados a partir de http://www.iana.org/time-zones
Possui m�todos mais simples do que a classe Calendar.
� Open-source, isso significa que qualquer um pode estudar seu c�digo fonte e contribuir se achar relevante.

Para usar o Joda-Time em seu projeto basta adicionar o jar da se��o de downloads no classpath do seu projeto, ou caso voc� use Maven voc� poder� adicionar as linhas da Listagem 1 no seu pom.xml

Listagem 1. Adicionando joda-time no Maven


  <dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.7</version>
  </dependency>

Estudaremos neste artigo o uso de cinco classes frequentemente utilizadas: Instant, DateTime, LocalDate, LocalTime, LocalDateTime.

DateTime

A primeira classe que devemos aprender � a DateTime, que trata-se de uma substitui��o da classe Calendar nativa do Java.

Esta � classe � imut�vel e possui uma grande variedade de construtores. Um destes construtores recebe um Object, o que possibilita uma enorme variedade de argumentos, vejamos:

Date, do JDK.
Calendar, do JDK.
String, no formato ISO8601.
Long, em milissegundos.
Qualquer uma das classes mencionadas acima (Instant, DateTime, LocalDate, LocalTime e LocalDateTime).

Veja como � pr�tico o uso do joda-time, j� que ele consegue entender que queremos converter o nosso Date (JDK) para um DateTime do joda-time, como mostra a Listagem 2.

Listagem 2. Convertendo java.util.Date para DateTime do Joda-Time


  java.util.Date juDate = new Date();
    DateTime dt = new DateTime(juDate);

Quando conseguimos capturar o objeto DateTime, j� podemos come�ar a utilizar seus m�todos, assim como mostra a Listagem 3.

Listagem 3. Usando DateTime pela primeira vez


    java.util.Date juDate = new Date();
    DateTime dt = new DateTime(juDate);
    int month = dt.getMonthOfYear();
    int year = dt.getYear();

O que temos nessa listagem � a cria��o do nosso objeto DateTime a partir de um java.util.Date. Depois capturamos o m�s e o ano da data que foi passada. Para o Joda-Time, Janeiro � representando pelo inteiro 1 e dezembro pelo inteiro 12.

Logo no in�cio falamos que a classe DateTime � imut�vel, mas o que significa isto? Significa que ap�s a sua cria��o ela n�o pode ser alterada, assim como a classe String. Se voc� criar uma DateTime passando a um java.util.Date, voc� poder� manipular este retornando novos valores mas n�o alterando o valor interno. Vejamos como funciona na Listagem 4.

Listagem 4. DateTime � imut�vel


      java.util.Date juDate = new Date();
     DateTime dt = new DateTime(juDate);
    DateTime year2000 = dt.withYear(2000);
    DateTime twoHoursLater = dt.plusHours(2);

Quando chamamos o m�todo withYear(), o Joda-Time ir� usar a data configurada para criar uma nova data com o ano 2000, e o mesmo � feito no plusHours(). Ele usa a data configurada (sem mud�-la) e cria uma nova data adicionando mais duas horas. � por esse motivo que quando chamamos ambos os m�todos atribu�mos a um novo objeto DateTime. Isso nos garante integridade a informa��o que foi repassada, pois a qualquer momento podemos recuperar a data original sem nenhuma altera��o.

O Joda-Time possui uma classe chamada Property, que � respons�vel disponibilizar m�todos importantes para campos que gostar�amos de manipular. Vejamos um exemplo na Listagem 5.

Listagem 5. Usando a classe Property para manipular campos


  DateTime dt = new DateTime();
               String monthName = dt.monthOfYear().getAsText();
               String frenchShortName = dt.monthOfYear().getAsShortText(Locale.FRENCH);
               boolean isLeapYear = dt.year().isLeap();
               DateTime rounded = dt.dayOfMonth().roundFloorCopy();
               System.out.println(frenchShortName);

O que temos acima � o uso da classe Property para nos auxiliar na manipula��o dos dados. Logo na primeira linha usamos o getAsText() para retornar o nome do m�s por extenso e n�o apenas um inteiro, como seria o normal. Logo em seguida retornamos o mesmo conte�do da linha anterior por�m em franc�s. Em isLeap() verificamos se o ano � bissexto e, por �ltimo, o roundFloorCopy() arredonda o valor para �baixo�. Veja um exemplo para demonstrar seu uso na Listagem 6.

Listagem 6. Exemplo roundFloorCopy()


  import org.joda.time.DateTime;
   
  public class JodaTimeMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               DateTime dt = new DateTime();
               DateTime rounded = dt.dayOfMonth().roundFloorCopy();
               System.out.println("Antes: "+dt.toString());
               System.out.println("Depois: "+rounded.toString());
         }
   
  }
   
  Sa�da:
  Antes: 2015-01-14T20:32:38.344-03:00
  Depois: 2015-01-14T00:00:00.000-03:00

O que podemos concluir com a Listagem 6 � que o roundFloorCopy() cria uma nova data, baseada na data original, arredondando-a para um valor inferior. Isso � percept�vel quando olhamos a sa�da da Listagem 6, pois a data antes do arredondamento � maior (em horas) do que a data gerada depois do roundFloorCopy().

Instant

No Joda-Time, a classe Instant representa exatamente um instante no tempo contando em milissegundos desde 01/01/1970 00:00, ou seja, se hoje for 14/01/2015 20:44, quantos milissegundos h� desde a data citada como inicial? A resposta disto ser� o instante exato em que estamos.

A classe Instant � usada pelo DateTime, por exemplo, quando voc� usar o m�todo getYear() para retornar o ano, assim ele faz uma convers�o interna de milissegundos para o que voc� deseja. Se voc� olhar a estrutura hier�rquica das classes date-time do joda-time, ir� perceber que elas implementam direta ou indiretamente a interface ReadableInstant, o que garante o retorno de milissegundos desde 01/01/1970 00:00 como citamos anteriormente. Vejamos um exemplo na Listagem 7.

Listagem 7. Entendendo o Instant


  import org.joda.time.DateTime;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               DateTime dt = new DateTime();
               System.out.println(dt.getYear());
         }
   
  }
   
  Visualizando dentro do dt.getYear():
   
  /**
       * Get the year field value.
       *
       * @return the year
       */
      public int getYear() {
          return getChronology().year().get(getMillis());
      }

Perceba que, na verdade, o retorno do ano s� � poss�vel, pois temos o instante em milissegundos, retornado atrav�s do m�todo getMillis().

O Joda-Time suporta m�ltiplos tipos de calend�rios, assim como o JDK. A diferen�a � que no JDK esses outros tipos de calend�rios devem ser uma subclasse da classe Calendar, enquanto que a estrat�gia do joda-time � um pouco diferente, trabalhando com uma arquitetura de �calend�rios plug�veis�. A classe Chronology permite o uso de oito tipos de calend�rios distintos, sendo eles: Buddhist, Coptic, Ethiopic, Gregorian-Julian cutover, Gregorian, Islamic, ISO e Julian.

No JDK, para cada um dos calend�rios citados voc� teria que chamar uma nova classe estendendo a classe Calendar, implementando o calend�rio que voc� deseja, um tanto quanto trabalhoso. No caso do Joda-Time, voc� usa a classe Chronology para retornar o calend�rio desejado, como podemos ver no exemplo da Listagem 8.

Listagem 8. Retornando calend�rio Coptic com Chronology


  import org.joda.time.Chronology;
  import org.joda.time.DateTime;
  import org.joda.time.DateTimeZone;
  import org.joda.time.chrono.CopticChronology;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               DateTimeZone zone = DateTimeZone.forID("Europe/London");
               Chronology coptic = CopticChronology.getInstance(zone);
   
               
               DateTime dt = new DateTime(coptic);
   
               int year = dt.getYear();   
               int month = dt.getMonthOfYear();
               System.out.println(year);
               System.out.println(month);
         }
   
  }

Antes de voc� questionar, o m�s e o ano retornado n�o est�o errados, pois trata-se de outro calend�rio com outras datas. N�s, brasileiros, usamos o calend�rio gregoriano (Gregorian Calendar) representado pela classe GregorianCalendar.

Perceba que para usar o calend�rio Coptic apenas retornamos a inst�ncia do CopticChronology e podemos trabalhar com ele como um Chronology, sem se preocupar com o tipo de calend�rio, usando os mesmos m�todos que usar�amos para outros calend�rios.

LocalDate, LocalTime e LocalDateTime

Diferente do DateTime, que � a forma mais completa de representar uma data, com ano, m�s, dia, horas, minutos, segundos e time-zone, o LocalDate, LocalTime e LocalDateTime representam a mesma data com informa��es ausentes, ou seja, de uma forma mais simplista, mas o objetivo final � o mesmo: representar uma data.

O LocalDate representa uma data sem considerar horas, minutos, segundos e o time-zone. Nas listagens abaixo veremos as tr�s classes e sempre a sa�da comparada de um DateTime com a classe referenciada, para que voc� leitor possa ter uma melhor visualiza��o da diferen�a.

Listagem 9. Usando LocalDate


  import org.joda.time.DateTime;
  import org.joda.time.LocalDate;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               LocalDate ld = new LocalDate();
               System.out.println("LocalDate: "+ld.toString());
               
               DateTime dt = new DateTime();
               System.out.println("DateTime: "+dt.toString());;
         }
   
  }
  Resultado:
  LocalDate: 2015-01-14
  DateTime: 2015-01-14T21:17:39.028-03:00

Perceba na Listagem 9 que o LocalDate retorna apenas ano, m�s e dia.

O LocalTime retorna apenas as horas, minutos, segundos e milissegundos contidos na data, sem considerar o time-zone, como mostra a Listagem 10.

Listagem 10. Usando LocalTime


  import org.joda.time.DateTime;
  import org.joda.time.LocalTime;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               LocalTime ld = new LocalTime();
               System.out.println("LocalTime: "+ld.toString());
               
               DateTime dt = new DateTime();
               System.out.println("DateTime: "+dt.toString());;
         }
   
  }
   
  Resultado:
   
  LocalTime: 21:19:20.481
  DateTime: 2015-01-14T21:19:20.543-03:00

O LocalTime retornou 21 horas, 19 minutos, 20 segundo e 481 milissegundos. O DateTime possui os milissegundos diferentes porque foi executado alguns milissegundos depois do LocalTime, isso � quest�o apenas de desempenho do processador.

O LocalDateTime retorna o ano, m�s e dia, juntamente com as horas, minutos, segundos e milissegundos, por�m sem o time-zone, e essa � a grande diferen�a do LocalDateTime e do Datetime, o TIMEZONE. Veja um exemplo na Listagem 11.

Listagem 11. Usando LocalDateTime


  import org.joda.time.DateTime;
  import org.joda.time.LocalDateTime;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               LocalDateTime ld = new LocalDateTime();
               System.out.println("LocalDateTime: "+ld.toString());
               
               DateTime dt = new DateTime();
               System.out.println("DateTime: "+dt.toString());;
         }
   
  }
   
  Resultado:
  LocalDateTime: 2015-01-14T21:22:29.537
  DateTime: 2015-01-14T21:22:29.655-03:00

O que voc� pode perceber de diferen�a � que o DateTime possui o n�mero �-03:00� no final, que simboliza o TimeZone que est� configurado para nosso sistema.

Podemos fazer aqui uma mistura de conceitos, usando o DateTime dentro de um dos exemplos apresentados acima, extraindo assim apenas a informa��es que desejamos mostrar ao usu�rio. Assim, temos o novo exemplo na Listagem 12.

Listagem 12. Usando DateTime com LocalDate, LocalDateTime e LocalTime


  import org.joda.time.DateTime;
  import org.joda.time.LocalDate;
  import org.joda.time.LocalDateTime;
  import org.joda.time.LocalTime;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               DateTime dt = new DateTime();
               System.out.println("Data completa com timezone: "+dt.toString());
               
               LocalDateTime ldt = new LocalDateTime(dt);
               System.out.println("Data completa sem timezone: "+ldt.toString());
               
               LocalDate ld = new LocalDate(dt);
               System.out.println("Apenas data: "+ld.toString());
               
               LocalTime lt = new LocalTime(dt);
               System.out.println("Apenas horas, minutos, segundos e milissegundos: "+lt.toString());
   
         }
   
  }
   
  Resultado:
   
  Data completa com timezone: 2015-01-14T21:26:48.940-03:00
  Data completa sem timezone: 2015-01-14T21:26:48.940
  Apenas data: 2015-01-14
  Apenas horas, minutos, segundos e milissegundos: 21:26:48.940

Duration

A classe Duration tem um conceito bem simples, mas muito �til, pois ela � capaz de medir a dura��o entre determinados per�odos atrav�s do Instant, ou seja, em milissegundos. Como sabemos, o tempo em milissegundos pode ser convertido para qualquer tipo de data (ano, m�s, dia e etc.), consequentemente conseguimos capturar a dura��o entre dias entre determinadas datas, por exemplo.

A f�rmula � a seguinte: instant + duration = instant. Isso significa que dado um instante qualquer (em milissegundos) mais uma dura��o qualquer (em milissegundos) resulta em um novo instante. Com base na f�rmula acima voc� consegue ver outras f�rmulas, por exemplo: como saberemos a dura��o entre dois instantes distintos? A resposta � Duration = instant1 � instant2.

Listagem 13. Usando Duration para retornar quantidade de dias


  import org.joda.time.DateTime;
  import org.joda.time.Duration;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               DateTime start = new DateTime(2015, 01, 10, 0, 0, 0, 0);
               DateTime end = new DateTime(2015, 01, 15, 0, 0, 0, 0);
   
               Duration dur = new Duration(start, end);
   
               System.out.println(dur.getStandardDays());
               
   
         }
   
  }
  Resultado: 5

Na Listagem 13 n�s estamos criando dois DateTime: um em 10/01/2015 e outro em 15/01/2015, ambos est�o sendo passados para o construtor da classe Duration como sendo in�cio e fim, respectivamente. Quando chamamos o getStandardDays() estamos solicitando a quantidade de dias que h� entre essas duas datas, e o resultado obviamente n�o poderia ser diferente de 5.

Formatando a data

O Joda-Time ainda tr�s consigo v�rios recursos al�m dos citados acima, e um deles muito poderoso � a formata��o de datas no padr�o desejado. No JDK voc� teria que usar uma classe como a SimpleDateFormat para converter sua data para o formato desejado, mas no joda-time voc� apenas precisa configurar como suas datas dever�o sair e ao chamar o m�todo toString() do DateTime o formato desejado ser� usado.

Listagem 14. Usando DateTimeFormat


  import org.joda.time.LocalDate;
  import org.joda.time.format.DateTimeFormat;
  import org.joda.time.format.DateTimeFormatter;
   
   
  public class JodaMain {
   
         /**
          * @param args
          */
         public static void main(String[] args) {
               LocalDate date = LocalDate.now();
               DateTimeFormatter fmt = DateTimeFormat.forPattern("d MMMM, yyyy");
               String str = date.toString(fmt);
               System.out.println(str);
               
   
         }
   
  }
   
  Resultado:
   
  14 Janeiro, 2015

Com a classe DateTimeFormat basta chamar o m�todo forPattern() passando o padr�o desejado e usar o objeto DateTimeFormatter sempre que for chamar o toString() da classe respectiva, em nosso caso um LocalDate.

Extras

O Joda-time conta tamb�m com outras funcionalidades e n�o apenas relacionadas a Data, este artigo teve foco do �carro-chefe� desta biblioteca, que � a manipula��o de datas, mas com o passar dos anos e a evolu��o desta, foram surgindo novas funcionalidades tamb�m interessantes. Veja algumas:

Joda Money: prov� a manipula��o de valores monet�rios, o que muitas vezes torna-se uma dor de cabe�a quando trabalhamos com sistema que exigem uma moeda espec�fica.
Joda Beans: proveem diversas funcionalidades as propriedades dos beans no Java, tais como valida��o atrav�s de anota��o.
Joda Convert: � um pequeno m�dulo capaz de realizar convers�es entre Objetos e Strings.

Estudamos neste artigo as principais classes no joda-time, com exemplos de manipula��o e qual o objetivo delas. Vale ressaltar que existem muitas outras, mas estas s�o as mais utilizadas e com este conhecimento voc� est� totalmente apto a us�-la.

Tecnologias:

Confira outros conte�dos:

Introdu��o ao JDBC

Novidades do Java

Teste unit�rio com JUnit

Assista grátis a nossa aula inaugural

Perguntas frequentes

Quem somos?

Por que a programação se tornou a profissão mais promissora da atualidade?

Como faço para começar a estudar?

Em quanto tempo de estudo vou me tornar um programador?

Sim, você pode se tornar um programador e não precisa ter diploma de curso superior!

O que eu irei aprender estudando pela DevMedia?

Principais diferenciais da DevMedia

Qual o investimento financeiro que preciso fazer para me tornar um programador?

Como funciona a forma de pagamento da DevMedia?

Por Ronaldo Em 2015

Nossos casos de sucesso

Leonardo Carlos

Eu sabia pouqu�ssimas coisas de programa��o antes de come�ar a estudar com voc�s, fui me especializando em v�rias �reas e ferramentas que tinham na plataforma, e com essa bagagem consegui um est�gio logo no in�cio do meu primeiro per�odo na faculdade.

Lucas Rodrigues

Estudo aqui na Dev desde o meio do ano passado! Nesse per�odo a Dev me ajudou a crescer muito aqui no trampo.
Fui o primeiro desenvolvedor contratado pela minha empresa. Hoje eu lidero um time de desenvolvimento!
Minha meta � continuar estudando e praticando para ser um Full-Stack Dev!

Her�clito J�nior

Economizei 3 meses para assinar a plataforma e sendo sincero valeu muito a pena, pois a plataforma � bem intuitiva e muuuuito did�tica a metodologia de ensino. Sinto que estou EVOLUINDO a cada dia. Muito obrigado!

Julio Cablen

Nossa! Plataforma maravilhosa. To amando o curso de desenvolvimento front-end, tinha coisas que eu ainda n�o tinha visto. A did�tica � do jeito que qualquer pessoa consegue aprender. S�rio, to apaixonado, adorando demais.

Joelberth Sena

Adquiri o curso de voc�s e logo percebi que s�o os melhores do Brasil. � um passo a passo incr�vel. S� n�o aprende quem n�o quer. Foi o melhor investimento da minha vida!

Felipe Nunes

Foi um dos melhores investimentos que j� fiz na vida e tenho aprendido bastante com a plataforma. Voc�s est�o fazendo parte da minha jornada nesse mundo da programa��o, irei assinar meu contrato como programador gra�as a plataforma.

Wanderson Oliveira

Comprei a assinatura tem uma semana, aprendi mais do que 4 meses estudando outros cursos. Exerc�cios pr�ticos que n�o tem como n�o aprender, est�o de parab�ns!

Jos� Lucas

Obrigado DevMedia, nunca presenciei uma plataforma de ensino t�o presente na vida acad�mica de seus alunos, parab�ns!

Eduardo Dorneles

Aprendi React na plataforma da DevMedia h� cerca de 1 ano e meio... Hoje estou h� 1 ano empregado trabalhando 100% com React!

Adauto Junior

J� fiz alguns cursos na �rea e nenhum � t�o bom quanto o de voc�s. Estou aprendendo muito, muito obrigado por existirem. Est�o de parab�ns... Espero um dia conseguir um emprego na �rea.

Ver todos os casos de sucesso

Conhe�a a biblioteca Java Joda-Time

Veja neste artigo como usar a biblioteca Joda-Time com seus principais recursos para manipula��o de datas em Java.