Interface SemanticDateTimeFormatter


  • @ProviderType
    public interface SemanticDateTimeFormatter
    Provides services that allow to convert different date and time representations.

    Following representations are supported:

    • Original - any Calendar object or date/time-related String representation; may have any timezone setting and also unnormalized fields (see description of the semantic representation below for more information about normalization).
    • Semantic - normalized representations of an original Calendar object or date/time-related or String representation. For the date sub-type, the time is guaranteed to be 00:00:00.000 and the semantic Calendar object to be in the UTC timezone. For the time sub-type, the date is guaranteed to be set to 1970-01-01 and the semantic Calendar object to be in the UTC timezone.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      @Nullable String format​(@NotNull Calendar value, @NotNull String semanticType)
      Gets a string representation of the specified Calendar value for the given semantic type.
      @NotNull String map​(@NotNull String value, @NotNull String semanticType)
      Maps an original String representation to a suitable semantic String representation.
      @Nullable Calendar map​(@NotNull Calendar value, @NotNull String semanticType)
      Maps an original Calendar object to a semantic Calendar object.
      @Nullable Calendar parse​(@NotNull String value, @NotNull String semanticType)
      Parses a String value to a semantic Calendar object.
    • Method Detail

      • parse

        @Nullable
        @Nullable Calendar parse​(@NotNull
                                 @NotNull String value,
                                 @NotNull
                                 @NotNull String semanticType)
        Parses a String value to a semantic Calendar object.

        The format supported for strings is [HH:mm[:ss]][yyyy-MM-dd['T'HH:mm:ss[.SSS][XXX]], which basically resembles ISO-8601.

        Parameters:
        value - The string to parse
        semanticType - The semantic type to map value to; supported values are: SemanticDataType.DATE, SemanticDataType.TIME and SemanticDataType.DATETIME
        Returns:
        The semantic Calendar object that matches the parsed string; null if the string doesn't contain a valid date
      • format

        @Nullable
        @Nullable String format​(@NotNull
                                @NotNull Calendar value,
                                @NotNull
                                @NotNull String semanticType)
        Gets a string representation of the specified Calendar value for the given semantic type.

        The string representation will be hh:mm:ss[.n...] (nanosecond portion is optional) for the time semantic type and yyyy-mm-dd for date. The string representation for the datetime semantic type will be formatted as an ISO-8601-compliant string.

        Parameters:
        value - The Calendar object to create a string representation for
        semanticType - the semantic type for the string representation
        Returns:
        The string representation
      • map

        @NotNull
        @NotNull String map​(@NotNull
                            @NotNull String value,
                            @NotNull
                            @NotNull String semanticType)
        Maps an original String representation to a suitable semantic String representation.

        The format supported for the returned value is [HH:mm[:ss]][yyyy-MM-dd['T'HH:mm:ss[.SSS][XXX]], which basically resembles ISO-8601.

        Parameters:
        value - The string to map
        semanticType - The semantic type
        Returns:
        The semantic string