org.embulk.util.timestamp

Class TimestampFormatter

java.lang.Object

org.embulk.util.timestamp.TimestampFormatter

public abstract class TimestampFormatter
extends Object

Formatter for parsing a date-time text into Instant, and for formatting Instant.

The formatter is built with a predefined format pattern, and used for parsing a date-time String, and formatting Instant. Patterns include the Ruby style, the Java style, and the legacy Embulk style ("legacy non-prefixed").

The Ruby style works like Ruby's Time.strptime and Time#strftime. A Ruby-style pattern follows a prefix "ruby:", or built with builderWithRuby(String). For example:

 TimestampFormatter formatter1 = TimestampFormatter.builder("ruby:%Y-%m-%d %H:%M:%S %Z").build();
 Instant instant1 = formatter1.parse("2019-02-28 12:34:56 +09:00");
 System.out.println(instant1);  // => "2019-02-28T03:34:56Z"

 String formatted1 = formatter1.format(Instant.ofEpochSecond(1009110896));
 System.out.println(formatted1);  // => "2017-12-23 12:34:56 UTC"

 // Same as formatter1 without "ruby:".
 TimestampFormatter formatter2 = TimestampFormatter.builderWithRuby("%Y-%m-%d %H:%M:%S %Z").build();

The Java style works like DateTimeFormatter. A Java-style pattern follows a prefix "java:", or built with builderWithJava(String). For example:

 TimestampFormatter formatter3 = TimestampFormatter.builder("java:uuuu-MM-dd HH:mm:ss XXXXX").build();
 Instant instant3 = formatter3.parse("2019-02-28 12:34:56 +09:00");
 System.out.println(instant3);  // => "2019-02-28T03:34:56Z"

 String formatted3 = formatter3.format(Instant.ofEpochSecond(1009110896));
 System.out.println(formatted3);  // => "2017-12-23 12:34:56 UTC"

 // Same as formatter3 without "java:".
 TimestampFormatter formatter4 = TimestampFormatter.builderWithJava("uuuu-MM-dd HH:mm:ss XXXXX").build();

The legacy Embulk style is here for backward compatibility, but it has some problems in timezones, especially around daylight saving time. A legacy Embulk-style pattern does not have any prefix, and must be built with builder(String, boolean) with isLegacyEnabled = true. For example:

 TimestampFormatter formatter5 = TimestampFormatter.builder("%Y-%m-%d %H:%M:%S %Z", true).build();
 Instant instant5 = formatter5.parse("2019-02-28 12:34:56 +09:00");
 System.out.println(instant5);  // => "2019-02-28T03:34:56Z"

 String formatted5 = formatter5.format(Instant.ofEpochSecond(1009110896));
 System.out.println(formatted5);  // => "2017-12-23 12:34:56 UTC"

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TimestampFormatter.Builder Builds a TimestampFormatter instance with configurations.

Method Summary

Modifier and Type	Method and Description
static TimestampFormatter.Builder	builder(String pattern) Creates a TimestampFormatter.Builder from a matching pattern.
static TimestampFormatter.Builder	builder(String pattern, boolean isLegacyEnabled) Creates a TimestampFormatter.Builder from a matching pattern.
static TimestampFormatter.Builder	builderWithJava(String pattern) Creates a TimestampFormatter.Builder from a Java-style matching pattern.
static TimestampFormatter.Builder	builderWithRuby(String pattern) Creates a TimestampFormatter.Builder from a Ruby-style matching pattern.
abstract String	format(Instant instant) Formats Instant with the default timezone of this formatter into String.
abstract Instant	parse(String text) Parses a date-time text into Instant.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

builder

public static TimestampFormatter.Builder builder(String pattern)

Creates a TimestampFormatter.Builder from a matching pattern.

It can create only for a prefixed matching pattern. If a legacy non-prefixed pattern is required, call builder(String, boolean) with isLegacyEnabled = true.

Parameters:

pattern - the matching pattern, which must start from "ruby:" or "java:"

Returns:

the TimestampFormatter.Builder created

builder

public static TimestampFormatter.Builder builder(String pattern,
                                                 boolean isLegacyEnabled)

Creates a TimestampFormatter.Builder from a matching pattern.

Parameters:

pattern - the matching pattern, which may start from "ruby:" or "java:"

isLegacyEnabled - true if a legacy non-prefixed pattern is required

Returns:

the TimestampFormatter.Builder created

builderWithJava

public static TimestampFormatter.Builder builderWithJava(String pattern)

Creates a TimestampFormatter.Builder from a Java-style matching pattern.

It builds a Java-style TimestampFormatter without the prefix "java:".

Parameters:

pattern - the matching pattern, which is Java-style without the prefix "java:"

Returns:

the TimestampFormatter.Builder created

builderWithRuby

public static TimestampFormatter.Builder builderWithRuby(String pattern)

Creates a TimestampFormatter.Builder from a Ruby-style matching pattern.

It builds a Ruby-style TimestampFormatter without the prefix "ruby:".

Parameters:

pattern - the matching pattern, which is Ruby-style without the prefix "ruby:"

Returns:

the TimestampFormatter.Builder created

format

public abstract String format(Instant instant)

Formats Instant with the default timezone of this formatter into String.

Parameters:

instant - the Instant object to format, not null

Returns:

the formatted string, not null

Throws:

NullPointerException - if instant is null

DateTimeException - if an error occurs during formatting

parse

public abstract Instant parse(String text)

Parses a date-time text into Instant.

Parameters:

text - the text to parse, not null nor empty

Returns:

the parsed instantaneous point on the time-line, Instant, not null

Throws:

DateTimeParseException - if unable to parse the requested result