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