Guia para a classe Java Clock

1. Visão geral

Neste tutorial, vamoslook into the Java Clock class from the java.time package. Explicaremos o que é a classeClock e como podemos usá-la.

2. A classeClock

Clock foi adicionado ao Java 8 e fornece acesso a um instante no tempo usando o melhor relógio do sistema disponível e para ser usado como um provedor de tempo que pode ser efetivamente criado para fins de teste.

A data e a hora atuais dependem do fuso horário e, para aplicativos globalizados, é necessário um provedor de horário para garantir que a data e a hora sejam criadas com o fuso horário correto.

Esta classe nos ajuda a testar se nossas alterações de código funcionam com fusos horários diferentes ou - ao usar um relógio fixo - que a hora não afeta nosso código.

A classeClock é abstrata, portanto, não podemos criar uma instância dela. Os seguintes métodos de fábrica podem ser usados:

offset(Clock, Duration) – retorna um relógio que é compensado peloDuration especificado. O principal caso de uso para isso é simular a execução no futuro ou no passado
systemUTC() – retorna um relógio que representa o fuso horário UTC
fixed(Instant, ZoneId) – sempre retorna o mesmoInstant. O principal caso de uso para isso é o teste, em que o relógio fixo garante que os testes não dependam do relógio atual

Vamos dar uma olhada na maioria dos métodos disponíveis na classeClock.

2.1. instant()

Este método retorna um instante que representa o instante atual definido pelo relógio:

Clock clock = Clock.systemDefaultZone();
Instant instant = clock.instant();
System.out.println(instant);

vai produzir:

2018-04-07T03:59:35.555Z

2.2. systemUTC()

Este método retorna um objetoClock que representa o instante atual na zona UTC:

Clock clock = Clock.systemUTC();
System.out.println("UTC time :: " + clock.instant());

vai produzir:

UTC time :: 2018-04-04T17:40:12.353Z

2.3. system()

Este método estático retorna o objetoClock para o fuso horário identificado pelo id de fuso horário fornecido:

Clock clock = Clock.system(ZoneId.of("Asia/Calcutta"));
System.out.println(clock.instant());

vai produzir:

2018-04-04T18:00:31.376Z

2.4. systemDefaultZone()

Este método estático retorna um objetoClock representando o instante atual e usando o fuso horário padrão do sistema em que está sendo executado:

Clock clock = Clock.systemDefaultZone();
System.out.println(clock);

As linhas acima produzem o seguinte resultado (supondo que nosso fuso horário padrão seja "Ásia / Calcutá"):

SystemClock[Asia/Calcutta]

Podemos obter o mesmo comportamento passandoZoneId.systemDefault():

Clock clock = Clock.system(ZoneId.systemDefault());

2.5. millis()

Este método retorna o instante atual do relógio em milissegundos. É fornecidoto allow the use of the clock in high-performance use cases where the creation of an object would be unacceptable. Este método pode ser usado em lugares onde, de outra forma, teríamos usadoSystem.currentTimeInMillis():

Clock clock = Clock.systemDefaultZone();
System.out.println(clock.millis());

vai produzir:

1523104441258

2.6. offset()

Este método estático retorna um instante do relógio base especificado com a duração especificada adicionada.

Se a duração for negativa, o instante do relógio resultante será anterior ao relógio de base fornecido.

Using offset, we can get instants in the past and future of the given base clock. Se passarmos uma duração zero, obteremos o mesmo relógio que o relógio base dado:

Clock baseClock = Clock.systemDefaultZone();

// result clock will be later than baseClock
Clock clock = Clock.offset(baseClock, Duration.ofHours(72));
System.out.println(clock5.instant());

// result clock will be same as baseClock                           
clock = Clock.offset(baseClock, Duration.ZERO);
System.out.println(clock.instant());

// result clock will be earlier than baseClock            
clock = Clock.offset(baseClock, Duration.ofHours(-72));
System.out.println(clock.instant());

vai produzir:

2018-04-10T13:24:07.347Z
2018-04-07T13:24:07.348Z
2018-04-04T13:24:07.348Z

2.7. tick()

Este método estático retorna instantes do relógio especificadorounded to the nearest occurrence of the specified duration. A duração do relógio especificada deve ser positiva:

Clock clockDefaultZone = Clock.systemDefaultZone();
Clock clocktick = Clock.tick(clockDefaultZone, Duration.ofSeconds(30));

System.out.println("Clock Default Zone: " + clockDefaultZone.instant());
System.out.println("Clock tick: " + clocktick.instant());

vai produzir:

Clock Default Zone: 2018-04-07T16:42:05.473Z
Clock tick: 2018-04-07T16:42:00Z

2.8. tickSeconds()

Esse método estático retorna o instante atual atual em segundos inteiros para o fuso horário especificado. Este relógio sempre terá o camponano-of-second definido como zero:

ZoneId zoneId = ZoneId.of("Asia/Calcutta");
Clock clock = Clock.tickSeconds(zoneId);
System.out.println(clock.instant());

vai produzir:

2018-04-07T17:40:23Z

O mesmo pode ser alcançado usandotick():

Clock clock = Clock.tick(Clock.system(ZoneId.of("Asia/Calcutta")), Duration.ofSeconds(1));

2.9. tickMinutes()

Esse método estático retorna o relógio instantâneo em minutos inteiros para o fuso horário especificado. Este relógio sempre terá os camposnano-of-second esecond-of-minute definidos para zero:

ZoneId zoneId = ZoneId.of("Asia/Calcutta");
Clock clock = Clock.tickMinutes(zoneId);
System.out.println(clock.instant());

vai produzir:

2018-04-07T17:26:00Z

O mesmo pode ser alcançado usandotick():

Clock clock = Clock.tick(Clock.system(ZoneId.of("Asia/Calcutta")), Duration.ofMinutes(1));

2.10. withZone()

Este método retorna uma cópia deste relógio com um fuso horário diferente.

Se tivermos uma instância de relógio para um fuso horário específico, podemos fazer uma cópia desse relógio para fuso horário diferente:

ZoneId zoneSingapore = ZoneId.of("Asia/Singapore");  
Clock clockSingapore = Clock.system(zoneSingapore); 
System.out.println(clockSingapore.instant());

ZoneId zoneCalcutta = ZoneId.of("Asia/Calcutta");
Clock clockCalcutta = clockSingapore.withZone(zoneCalcutta);
System.out.println(clockCalcutta.instant());

vai produzir:

2018-04-07T17:55:43.035Z
2018-04-07T17:55:43.035Z

2.11. getZone()

Este método retorna o fuso horário dosClock fornecidos.

Clock clock = Clock.systemDefaultZone();
ZoneId zone = clock.getZone();
System.out.println(zone.getId());

vai produzir:

Asia/Calcutta

2.12. fixo()

Este método retorna um relógio quealways returns the same instant. O principal caso de uso desse método está nos testes, nos quais o relógio fixo garante que os testes não dependam do relógio atual.

Clock fixedClock = Clock.fixed(Instant.parse("2018-04-29T10:15:30.00Z"),
ZoneId.of("Asia/Calcutta"));
System.out.println(fixedClock);

vai produzir:

FixedClock[2018-04-29T10:15:30Z,Asia/Calcutta]

3. Conclusão

Neste artigo, mergulhamos na classe JavaClock e nas diferentes maneiras de usá-la com os métodos disponíveis.

Como sempre, os exemplos de código estão disponíveisover on GitHub.

TOC

Guia para a classe Java Clock