A implementação de referência da JSR 310 (API Date and Time), denominada ThreeTen, foi inserida no JDK 8 Early Access b75 sob o pacote java.time, diferentemente das versões anteriores, em que ficava no pacote javax.time. O rascunho do Javadoc da API também foi disponibilizado.
Todas as classes da API Java Time são imutáveis e thread-safe. Além disso, são baseadas na norma ISO 8601, o calendário internacional segundo as regras Gregorianas. Outros sistemas de calendário também são suportados pelos pacotes java.time.calendar e java.time.temporal. Além das classes para data e hora, a API também fornece classes para relógios, períodos e intervalos de tempo, e enumerações para meses e dias da semana.
Há muitas classes na API Java Time, mas a maioria das aplicações podem iniciar com os seguintes tipos de data/hora:
- Instant
- É um timestamp numérico armazenado com precisão de nanossegundos. Útil para capturar um instante no tempo, similar ao método System.currentTimeMillis(). A classe Instant é a mais próxima em equivalência à classe java.util.Date. Quando impreso, um instante assemelha-se a '2000-12-01T12:30:00.000Z'.
- LocalDate
- Representa uma data sem hora ou fuso horário. Útil, por exemplo, para armazenar datas como a de um aniversário. Quando impressa, uma data assemelha-se a '2000-12-01'.
- LocalTime
- Representa um horário sem data ou fuso horário. Um exemplo de utilização é o armazenamento de horários de lojas. Quando impresso, um horário assemelha-se a '12:30:00.000'.
- LocalDateTime
- Representa uma data e hora sem o fuso horário. A impressão de uma data/hora assemelha-se a '2000-12-01T12:30:00.000'.
- ZonedDateTime
- Representa uma data e hora com o fuso horário. Útil para realizar cálculos que levam em consideração o fuso horário, como 'America/New_York'. A classe ZonedDateTime é a mais próxima em equivalência à classe java.util.GregorianCalendar. A impressão de uma data/hora assemelha-se a '2000-12-01T12:30:00.000-05:00[America/New_York]'.
Sempre que possível, é recomendável utilizar classes mais simples e sem fuso horário para modelar os objetos de domínio, como LocalDate, LocalTime e LocalDateTime. O uso generalizado de fusos horários pode adicionar uma complexidade considerável a uma aplicação. Muitas aplicações podem utilizar classes mais simples e adicionar o fuso horário somente na camada de apresentação.
Outras classes notáveis na API Java Time são:
- Clock
- Um clock fornece acesso ao instante corrente, data e hora, usando um fuso horário. Pode ser utilizado no lugar dos métodos System.currentTimeMillis() e TimeZone.getDefault(). Embora todas as principais classes de data e hora tenham um metódo de fábrica denominado now(), que utiliza o relógio do sistema, o principal objetivo desta abstração é permitir que relógios alternativos sejam injetados, o que simplifica bastante os testes.
- Duration
- Representa uma duração entre dois instantes na linha do tempo, armazenada com a precisão de nanossegundos. Esta classe modela uma duração de tempo sem estar ligada a qualquer instante. O modelo é direcionado, significando que a duração pode ser negativa. Na impressão, uma duração assemelha-se a 'PT3600S'.
- Period
- Representa um período de tempo expresso em unidades que fazem sentido aos humanos, como '1 ano, 2 meses e 3 dias'. O modelo é direcionado, significando que partes individuais do período podem ser negativas. A impressão de um período é semelhante a 'P1Y2M3D'.
- ZoneId
- Representa um identificador de fuso horário (área), como America/New_York.
- ZoneOffset
- Representa a diferença de horário a partir do meridiano de Greenwich/UTC. Como, por exemplo, +02:00.
O pacote java.time.zone fornece suporte a fusos horários, suas regras e as lacunas ou sobreposições na linha do tempo local, causadas tipicamente pelos períodos de Horário de Verão. Há também o pacote java.time.format para impressão e parsing de objetos do tipo data/hora (embora na maioria dos casos os métodos toString() e parse() dessas classes sejam suficientes). O pacote java.time.temporal fornece acesso à data e hora através do uso de campos e unidades, além de classes adicionais para as subpartes mais importantes de uma data, e suporte base para calendários que não atendam aos padrões ISO. Fornece também funcionalidades adicionais para os casos mais avançados.
Os usuários que quiserem testar a nova API Java Time, podem baixar o JDK 8 b75 e utilizar o Javadoc como guia. Se quiserem também uma IDE com suporte ao JDK 8, podem usar a última versão das IDEs IntelliJ IDEA ou Netbeans. Aqueles que estão em busca por tutoriais de terceiros, devem se certificar de que estão olhando os artigos mais recentes, pois a API sofreu muitas mudanças nos últimos anos. Considere também que mudanças nas classes e métodos da API Java Time poderão continuar ocorrendo até que o JDK 8 seja definitivamente lançado. Desenvolvedores interessados em conhecer todas as novas funcionalidades do JDK 8 e também saber quando serão de fato incluídas, podem verificar a lista de funcionalidades e mudanças do JDK.
O InfoQ cobriu o anúncio da JSR 310 no começo de 2007, quando a distribuição da JSR foi originalmente planejada para o JDK 7. O InfoQ também entrevistou Stephen Colebourne, líder da JSR 310, durante a primeira revisão dos rascunhos da JSR em 2010. A última cobertura da JSR 310 pelo InfoQ foi feita em setembro de 2012, quando a JSR foi oficialmente adicionada à lista de funcionalidades do Java 8.