001 /*
002 * SPDX-License-Identifier: Apache-2.0
003 *
004 * Copyright 2008-2017 the original author or authors.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 package griffon.core.i18n;
019
020 import javax.annotation.Nonnull;
021 import javax.annotation.Nullable;
022 import java.util.List;
023 import java.util.Locale;
024 import java.util.Map;
025 import java.util.ResourceBundle;
026
027 /**
028 * Interface for resolving messages, with support for the parameterization and internationalization of such messages.
029 *
030 * @author Andres Almiray
031 * @author Alexander Klein
032 * @since 2.0.0
033 */
034 public interface MessageSource {
035 /**
036 * "@["
037 */
038 String REF_KEY_START = "@[";
039
040 /**
041 * "]"
042 */
043 String REF_KEY_END = "]";
044
045 /**
046 * Try to resolve the message.
047 *
048 * @param key Key to lookup, such as 'log4j.appenders.console'
049 * @return The resolved message at the given key for the default locale
050 * @throws NoSuchMessageException if no message is found
051 */
052 @Nonnull
053 String getMessage(@Nonnull String key) throws NoSuchMessageException;
054
055 /**
056 * Try to resolve the message.
057 *
058 * @param key Key to lookup, such as 'log4j.appenders.console'
059 * @param locale Locale in which to lookup
060 * @return The resolved message at the given key for the given locale
061 * @throws NoSuchMessageException if no message is found
062 */
063 @Nonnull
064 String getMessage(@Nonnull String key, @Nonnull Locale locale) throws NoSuchMessageException;
065
066 /**
067 * Try to resolve the message.
068 *
069 * @param key Key to lookup, such as 'log4j.appenders.console'
070 * @param args Arguments that will be filled in for params within the message (params look like "{0}" within a
071 * message, but this might differ between implementations), or null if none.
072 * @return The resolved message at the given key for the default locale
073 * @throws NoSuchMessageException if no message is found
074 */
075 @Nonnull
076 String getMessage(@Nonnull String key, @Nonnull Object[] args) throws NoSuchMessageException;
077
078 /**
079 * Try to resolve the message.
080 *
081 * @param key Key to lookup, such as 'log4j.appenders.console'
082 * @param args Arguments that will be filled in for params within the message (params look like "{0}" within a
083 * message, but this might differ between implementations), or null if none.
084 * @param locale Locale in which to lookup
085 * @return The resolved message at the given key for the given locale
086 * @throws NoSuchMessageException if no message is found
087 */
088 @Nonnull
089 String getMessage(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale) throws NoSuchMessageException;
090
091 /**
092 * Try to resolve the message.
093 *
094 * @param key Key to lookup, such as 'log4j.appenders.console'
095 * @param args Arguments that will be filled in for params within the message (params look like "{0}" within a
096 * message, but this might differ between implementations), or null if none.
097 * @return The resolved message at the given key for the default locale
098 * @throws NoSuchMessageException if no message is found
099 */
100 @Nonnull
101 String getMessage(@Nonnull String key, @Nonnull List<?> args) throws NoSuchMessageException;
102
103 /**
104 * Try to resolve the message.
105 *
106 * @param key Key to lookup, such as 'log4j.appenders.console'
107 * @param args Arguments that will be filled in for params within the message (params look like "{0}" within a
108 * message, but this might differ between implementations), or null if none.
109 * @param locale Locale in which to lookup
110 * @return The resolved message at the given key for the given locale
111 * @throws NoSuchMessageException if no message is found
112 */
113 @Nonnull
114 String getMessage(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale) throws NoSuchMessageException;
115
116 /**
117 * Try to resolve the message. Return default message if no message was found.
118 *
119 * @param key Key to lookup, such as 'log4j.appenders.console'
120 * @param defaultMessage Message to return if the lookup fails
121 * @return The resolved message at the given key for the default locale
122 */
123 @Nullable
124 String getMessage(@Nonnull String key, @Nullable String defaultMessage);
125
126 /**
127 * Try to resolve the message. Return default message if no message was found.
128 *
129 * @param key Key to lookup, such as 'log4j.appenders.console'
130 * @param locale Locale in which to lookup
131 * @param defaultMessage Message to return if the lookup fails
132 * @return The resolved message at the given key for the given locale
133 */
134 @Nullable
135 String getMessage(@Nonnull String key, @Nonnull Locale locale, @Nullable String defaultMessage);
136
137 /**
138 * Try to resolve the message. Return default message if no message was found.
139 *
140 * @param key Key to lookup, such as 'log4j.appenders.console'
141 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
142 * within a message, but this might differ between implementations), or null if none.
143 * @param defaultMessage Message to return if the lookup fails
144 * @return The resolved message at the given key for the default locale
145 */
146 @Nullable
147 String getMessage(@Nonnull String key, @Nonnull Object[] args, @Nullable String defaultMessage);
148
149 /**
150 * Try to resolve the message. Return default message if no message was found.
151 *
152 * @param key Key to lookup, such as 'log4j.appenders.console'
153 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
154 * within a message, but this might differ between implementations), or null if none.
155 * @param locale Locale in which to lookup
156 * @param defaultMessage Message to return if the lookup fails
157 * @return The resolved message at the given key for the given locale
158 */
159 @Nullable
160 String getMessage(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale, @Nullable String defaultMessage);
161
162 /**
163 * Try to resolve the message. Return default message if no message was found.
164 *
165 * @param key Key to lookup, such as 'log4j.appenders.console'
166 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
167 * within a message, but this might differ between implementations), or null if none.
168 * @param defaultMessage Message to return if the lookup fails
169 * @return The resolved message at the given key for the default locale
170 */
171 @Nullable
172 String getMessage(@Nonnull String key, @Nonnull List<?> args, @Nullable String defaultMessage);
173
174 /**
175 * Try to resolve the message. Return default message if no message was found.
176 *
177 * @param key Key to lookup, such as 'log4j.appenders.console'
178 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
179 * within a message, but this might differ between implementations), or null if none.
180 * @param locale Locale in which to lookup
181 * @param defaultMessage Message to return if the lookup fails
182 * @return The resolved message at the given key for the given locale
183 */
184 @Nullable
185 String getMessage(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale, @Nullable String defaultMessage);
186
187 /**
188 * Try to resolve the message.
189 *
190 * @param key Key to lookup, such as 'log4j.appenders.console'
191 * @param args Arguments that will be filled in for params within the message (params look like "{:key}"
192 * within a message, but this might differ between implementations), or null if none.
193 * @return The resolved message at the given key for the default locale
194 * @throws NoSuchMessageException if no message is found
195 */
196 @Nonnull
197 String getMessage(@Nonnull String key, @Nonnull Map<String, Object> args) throws NoSuchMessageException;
198
199 /**
200 * Try to resolve the message.
201 *
202 * @param key Key to lookup, such as 'log4j.appenders.console'
203 * @param args Arguments that will be filled in for params within the message (params look like "{:key}"
204 * within a message, but this might differ between implementations), or null if none.
205 * @param locale Locale in which to lookup
206 * @return The resolved message at the given key for the given locale
207 * @throws NoSuchMessageException if no message is found
208 */
209 @Nonnull
210 String getMessage(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale) throws NoSuchMessageException;
211
212 /**
213 * Try to resolve the message. Return default message if no message was found.
214 *
215 * @param key Key to lookup, such as 'log4j.appenders.console'
216 * @param args Arguments that will be filled in for params within the message (params look like "{:key}"
217 * within a message, but this might differ between implementations), or null if none.
218 * @param defaultMessage Message to return if the lookup fails
219 * @return The resolved message at the given key for the default locale
220 */
221 @Nullable
222 String getMessage(@Nonnull String key, @Nonnull Map<String, Object> args, @Nullable String defaultMessage);
223
224 /**
225 * Try to resolve the message. Return default message if no message was found.
226 *
227 * @param key Key to lookup, such as 'log4j.appenders.console'
228 * @param args Arguments that will be filled in for params within the message (params look like "{:key}"
229 * within a message, but this might differ between implementations), or null if none.
230 * @param locale Locale in which to lookup
231 * @param defaultMessage Message to return if the lookup fails
232 * @return The resolved message at the given key for the given locale
233 */
234 @Nullable
235 String getMessage(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale, @Nullable String defaultMessage);
236
237 /**
238 * <p>Resolve a message given a key and a Locale.</p>
239 * <p>
240 * This method should use the default Locale if the locale argument is null. The {@code key} argument may refer to
241 * another key if the resolved value results in a {@code CharSequence} that begins with "@[" and ends with "]". In this
242 * case the method will use the enclosed value as the next key to be resolved. For example, given the following key/value
243 * definitions
244 * <p/>
245 * <pre>
246 * some.key = Hello {0}
247 * other.key = @[some.key]
248 * </pre>
249 * <p/>
250 * Evaluating the keys results in
251 * <p/>
252 * <pre>
253 * assert resolveMessageValue('some.key', Locale.default) == 'Hello {0}'
254 * assert resolveMessageValue('other.key', Locale.default) == 'Hello {0}'
255 * </pre>
256 * <p/>
257 * </p>
258 *
259 * @param key Key to lookup, such as 'log4j.appenders.console'
260 * @param locale Locale in which to lookup
261 * @return the resolved message value at the given key for the given locale
262 * @throws NoSuchMessageException if no message is found
263 */
264 @Nonnull
265 Object resolveMessageValue(@Nonnull String key, @Nonnull Locale locale) throws NoSuchMessageException;
266
267 /**
268 * Formats the given message using supplied args to substitute placeholders.
269 *
270 * @param message The message following a predefined format.
271 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
272 * within a message, but this might differ between implementations), or null if none.
273 * @return the formatted message with all matching placeholders with their substituted values.
274 */
275 @Nonnull
276 String formatMessage(@Nonnull String message, @Nonnull List<?> args);
277
278 /**
279 * Formats the given message using supplied args to substitute placeholders.
280 *
281 * @param message The message following a predefined format.
282 * @param args Arguments that will be filled in for params within the message (params look like "{0}"
283 * within a message, but this might differ between implementations), or null if none.
284 * @return the formatted message with all matching placeholders with their substituted values.
285 */
286 @Nonnull
287 String formatMessage(@Nonnull String message, @Nonnull Object[] args);
288
289 /**
290 * Formats the given message using supplied args to substitute placeholders.
291 *
292 * @param message The message following a predefined format.
293 * @param args Arguments that will be filled in for params within the message (params look like "{:key}"
294 * within a message, but this might differ between implementations), or null if none.
295 * @return the formatted message with all matching placeholders with their substituted values.
296 */
297 @Nonnull
298 String formatMessage(@Nonnull String message, @Nonnull Map<String, Object> args);
299
300 /**
301 * Offers a view of this {@code MessageSource} as a {@code ResourceBundle}.
302 *
303 * @return a {@code ResourceBundle} containing the keys this {@code MessageSource}
304 * can resolve.
305 */
306 @Nonnull
307 ResourceBundle asResourceBundle();
308 }
|