1 package org.apache.turbine.services.localization;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.time.ZoneId;
23 import java.time.format.DateTimeFormatter;
24 import java.time.temporal.TemporalAccessor;
25 import java.util.Locale;
26
27 public interface DateTimeFormatterInterface {
28
29 /**
30 * Property tag for the date format that is to be used for the web
31 * application. "tool.dateTool.format"
32 */
33 final String DATE_TIME_FORMAT_KEY = "datetime.format";
34
35 final String DATE_TIME_ZONEID_KEY = "datetime.zoneId";
36
37 final String USE_TURBINE_LOCALE_KEY = "datetime.use.turbine.locale";
38
39 final String USE_REQUEST_LOCALE_KEY = "tool.use.request.locale";
40
41 /** Default date format. find supported formats in {@link DateTimeFormatterService} */
42 final String DATE_TIME_FORMAT_DEFAULT = "MM/dd/yyyy";
43
44 DateTimeFormatter getDefaultFormat();
45
46 String getFormatPattern();
47
48 /**
49 * Formats the given datetime as a String with the #{@link DateTimeFormatterService#getDefaultFormat()}.
50 * using the default date format.
51 *
52 * @param temporalAccessor {@link TemporalAccessor to format
53 * @return String value of the date
54 */
55 <T extends TemporalAccessor> String format(T temporalAccessor);
56
57 /**
58 * Formats the given date as a String.
59 *
60 * @param temporalAccessor TimeDate date to format
61 * @param dateFormatString format string to use. See {@link DateTimeFormatter}
62 * for details.
63 * @return String value of the date
64 */
65 <T extends TemporalAccessor> String format(T temporalAccessor, String dateFormatString);
66
67 /**
68 * Formats the given date as a String.
69 *
70 * @param temporalAccessor TimeDate date to format
71 * @param dateFormatString format string to use. See {@link DateTimeFormatter}
72 * for details.
73 * @param locale used to loclize the format
74 * @return String value of the date
75 */
76 <T extends TemporalAccessor> String format(T temporalAccessor, String dateFormatString, Locale locale);
77
78 /**
79 * Formats the given date as a String.
80 *
81 * @param temporalAccessor TimeDate date to format
82 * @param dateFormatString format string to use. See {@link DateTimeFormatter}
83 * for details.
84 * @param locale the {@link Locale}
85 * @param zoneId the {@link ZoneId}
86 * @return String value of the date
87 */
88 <T extends TemporalAccessor> String format(T temporalAccessor, String dateFormatString, Locale locale, ZoneId zoneId);
89
90 /**
91 * Maps from an incoming format to an outgoing format {@link DateTimeFormatter}.
92 * @param src the formatted datetime
93 * @param outgoingFormat the outgoingFormat pattern, {@link DateTimeFormatter}
94 * @param locale Locale, if needed for outgoing formatting, no default.
95 * @param incomingFormat the incming format pattern {@link DateTimeFormatter}, optional, default is {@link #getDefaultFormat()}.
96 * @return the newly mapped
97 */
98 String map(String src, String outgoingFormat, Locale locale, String incomingFormat);
99
100 /**
101 * Uses as incoming format {@link #getDefaultFormat()} and no locale.
102 * @param src the text, which will be parsed using the incomingFormat.
103 * @param outgoingFormat the outgoing formatter, which will format.
104 * @param locale The locale, if not null which will outgoingFormat use, {@link DateTimeFormatter#withLocale(Locale)}.
105 * @param incomingFormat the incoming formatter, which will be parsed.
106 * @return the formatted string
107 *
108 */
109 String map(String src, DateTimeFormatter outgoingFormat, Locale locale,
110 DateTimeFormatter incomingFormat);
111
112 /**
113 * Uses as outgoing {@link DateTimeFormatter} {@link #getDefaultFormat()} and no locale.
114 *
115 * @param src the datetime formatted string
116 * @param outgoingFormat the format of this string
117 * @return the date time formatted
118 */
119 String mapTo(String src, DateTimeFormatter outgoingFormat);
120
121 /**
122 * @param src the datetime formatted string
123 * @param incomingFormat the format to which this incoming string should be formatted.
124 *
125 * @return the newly formatted date time string
126 */
127 String mapFrom(String src, DateTimeFormatter incomingFormat);
128
129 /**
130 * Uses as incoming {@link DateTimeFormatter} {@link #getDefaultFormat()}.
131 *
132 * @param src the datetime formatted string
133 * @param outgoingFormat the format to which this string should be formatted.
134 * @param locale The locale, if not null,the incomingFormat will use.
135 *
136 * @return the newly formatted date time string
137 */
138 String map(String src, DateTimeFormatter outgoingFormat, Locale locale);
139
140 ZoneId getZoneId();
141 }