MessageSource.java
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 keythrows 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 localethrows 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[] argsthrows 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 localethrows 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<?> argsthrows 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 localethrows 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> argsthrows 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 localethrows 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 localethrows 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 }