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.resources;
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
026 /**
027 * Interface for resolving resources, with support for the parameterization and internationalization of such resources.
028 *
029 * @author Andres Almiray
030 * @author Alexander Klein
031 * @since 2.0.0
032 */
033 public interface ResourceResolver {
034 /**
035 * "@["
036 */
037 String REF_KEY_START = "@[";
038
039 /**
040 * "]"
041 */
042 String REF_KEY_END = "]";
043
044 /**
045 * Try to resolve the resource.
046 *
047 * @param key Key to lookup, such as 'sample.SampleModel.icon'
048 * @return The resolved resource at the given key for the default locale
049 * @throws NoSuchResourceException if no resource is found
050 */
051 @Nonnull
052 Object resolveResource(@Nonnull String key) throws NoSuchResourceException;
053
054 /**
055 * Try to resolve the resource.
056 *
057 * @param key Key to lookup, such as 'sample.SampleModel.icon'
058 * @param locale Locale in which to lookup
059 * @return The resolved resource at the given key for the given locale
060 * @throws NoSuchResourceException if no resource is found
061 */
062 @Nonnull
063 Object resolveResource(@Nonnull String key, @Nonnull Locale locale) throws NoSuchResourceException;
064
065 /**
066 * Try to resolve the resource.
067 *
068 * @param key Key to lookup, such as 'sample.SampleModel.icon'
069 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
070 * resource, but this might differ between implementations), or null if none.
071 * @return The resolved resource at the given key for the default locale
072 * @throws NoSuchResourceException if no resource is found
073 */
074 @Nonnull
075 Object resolveResource(@Nonnull String key, @Nonnull Object[] args) throws NoSuchResourceException;
076
077 /**
078 * Try to resolve the resource.
079 *
080 * @param key Key to lookup, such as 'sample.SampleModel.icon'
081 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
082 * resource, but this might differ between implementations), or null if none.
083 * @param locale Locale in which to lookup
084 * @return The resolved resource at the given key for the given locale
085 * @throws NoSuchResourceException if no resource is found
086 */
087 @Nonnull
088 Object resolveResource(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale) throws NoSuchResourceException;
089
090 /**
091 * Try to resolve the resource.
092 *
093 * @param key Key to lookup, such as 'sample.SampleModel.icon'
094 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
095 * resource, but this might differ between implementations), or null if none.
096 * @return The resolved resource at the given key for the default locale
097 * @throws NoSuchResourceException if no resource is found
098 */
099 @Nonnull
100 Object resolveResource(@Nonnull String key, @Nonnull List<?> args) throws NoSuchResourceException;
101
102 /**
103 * Try to resolve the resource.
104 *
105 * @param key Key to lookup, such as 'sample.SampleModel.icon'
106 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
107 * resource, but this might differ between implementations), or null if none.
108 * @param locale Locale in which to lookup
109 * @return The resolved resource at the given key for the given locale
110 * @throws NoSuchResourceException if no resource is found
111 */
112 @Nonnull
113 Object resolveResource(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale) throws NoSuchResourceException;
114
115 /**
116 * Try to resolve the resource. Return default resource if no resource was found.
117 *
118 * @param key Key to lookup, such as 'sample.SampleModel.icon'
119 * @param defaultValue Message to return if the lookup fails
120 * @return The resolved resource at the given key for the default locale
121 */
122 @Nullable
123 Object resolveResource(@Nonnull String key, @Nullable Object defaultValue);
124
125 /**
126 * Try to resolve the resource. Return default resource if no resource was found.
127 *
128 * @param key Key to lookup, such as 'sample.SampleModel.icon'
129 * @param locale Locale in which to lookup
130 * @param defaultValue Message to return if the lookup fails
131 * @return The resolved resource at the given key for the given locale
132 */
133 @Nullable
134 Object resolveResource(@Nonnull String key, @Nonnull Locale locale, @Nullable Object defaultValue);
135
136 /**
137 * Try to resolve the resource. Return default resource if no resource was found.
138 *
139 * @param key Key to lookup, such as 'sample.SampleModel.icon'
140 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
141 * within a resource, but this might differ between implementations), or null if none.
142 * @param defaultValue Message to return if the lookup fails
143 * @return The resolved resource at the given key for the default locale
144 */
145 @Nullable
146 Object resolveResource(@Nonnull String key, @Nonnull Object[] args, @Nullable Object defaultValue);
147
148 /**
149 * Try to resolve the resource. Return default resource if no resource was found.
150 *
151 * @param key Key to lookup, such as 'sample.SampleModel.icon'
152 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
153 * within a resource, but this might differ between implementations), or null if none.
154 * @param locale Locale in which to lookup
155 * @param defaultValue Message to return if the lookup fails
156 * @return The resolved resource at the given key for the given locale
157 */
158 @Nullable
159 Object resolveResource(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale, @Nullable Object defaultValue);
160
161 /**
162 * Try to resolve the resource. Return default resource if no resource was found.
163 *
164 * @param key Key to lookup, such as 'sample.SampleModel.icon'
165 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
166 * within a resource, but this might differ between implementations), or null if none.
167 * @param defaultValue Message to return if the lookup fails
168 * @return The resolved resource at the given key for the default locale
169 */
170 @Nullable
171 Object resolveResource(@Nonnull String key, @Nonnull List<?> args, @Nullable Object defaultValue);
172
173 /**
174 * Try to resolve the resource. Return default resource if no resource was found.
175 *
176 * @param key Key to lookup, such as 'sample.SampleModel.icon'
177 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
178 * within a resource, but this might differ between implementations), or null if none.
179 * @param locale Locale in which to lookup
180 * @param defaultValue Message to return if the lookup fails
181 * @return The resolved resource at the given key for the given locale
182 */
183 @Nullable
184 Object resolveResource(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale, @Nullable Object defaultValue);
185
186 /**
187 * Try to resolve the resource.
188 *
189 * @param key Key to lookup, such as 'sample.SampleModel.icon'
190 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
191 * within a resource, but this might differ between implementations), or null if none.
192 * @return The resolved resource at the given key for the default locale
193 * @throws NoSuchResourceException if no resource is found
194 */
195 @Nonnull
196 Object resolveResource(@Nonnull String key, @Nonnull Map<String, Object> args) throws NoSuchResourceException;
197
198 /**
199 * Try to resolve the resource.
200 *
201 * @param key Key to lookup, such as 'sample.SampleModel.icon'
202 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
203 * within a resource, but this might differ between implementations), or null if none.
204 * @param locale Locale in which to lookup
205 * @return The resolved resource at the given key for the given locale
206 * @throws NoSuchResourceException if no resource is found
207 */
208 @Nonnull
209 Object resolveResource(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale) throws NoSuchResourceException;
210
211 /**
212 * Try to resolve the resource. Return default resource if no resource was found.
213 *
214 * @param key Key to lookup, such as 'sample.SampleModel.icon'
215 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
216 * within a resource, but this might differ between implementations), or null if none.
217 * @param defaultValue Message to return if the lookup fails
218 * @return The resolved resource at the given key for the default locale
219 */
220 @Nullable
221 Object resolveResource(@Nonnull String key, @Nonnull Map<String, Object> args, @Nullable Object defaultValue);
222
223 /**
224 * Try to resolve the resource. Return default resource if no resource was found.
225 *
226 * @param key Key to lookup, such as 'sample.SampleModel.icon'
227 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
228 * within a resource, but this might differ between implementations), or null if none.
229 * @param locale Locale in which to lookup
230 * @param defaultValue Message to return if the lookup fails
231 * @return The resolved resource at the given key for the given locale
232 */
233 @Nullable
234 Object resolveResource(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale, @Nullable Object defaultValue);
235
236 /**
237 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
238 *
239 * @param key Key to lookup, such as 'sample.SampleModel.icon'
240 * @param type the type to be returned
241 * @return The resolved resource at the given key for the default locale
242 * @throws NoSuchResourceException if no resource is found
243 * @since 2.5.0
244 */
245 @Nonnull
246 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Class<T> type) throws NoSuchResourceException;
247
248 /**
249 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
250 *
251 * @param key Key to lookup, such as 'sample.SampleModel.icon'
252 * @param locale Locale in which to lookup
253 * @param type the type to be returned
254 * @return The resolved resource at the given key for the given locale
255 * @throws NoSuchResourceException if no resource is found
256 * @since 2.5.0
257 */
258 @Nonnull
259 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Locale locale, @Nonnull Class<T> type) throws NoSuchResourceException;
260
261 /**
262 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
263 *
264 * @param key Key to lookup, such as 'sample.SampleModel.icon'
265 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
266 * resource, but this might differ between implementations), or null if none.
267 * @param type the type to be returned
268 * @return The resolved resource at the given key for the default locale
269 * @throws NoSuchResourceException if no resource is found
270 * @since 2.5.0
271 */
272 @Nonnull
273 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Object[] args, @Nonnull Class<T> type) throws NoSuchResourceException;
274
275 /**
276 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
277 *
278 * @param key Key to lookup, such as 'sample.SampleModel.icon'
279 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
280 * resource, but this might differ between implementations), or null if none.
281 * @param locale Locale in which to lookup
282 * @param type the type to be returned
283 * @return The resolved resource at the given key for the given locale
284 * @throws NoSuchResourceException if no resource is found
285 * @since 2.5.0
286 */
287 @Nonnull
288 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale, @Nonnull Class<T> type) throws NoSuchResourceException;
289
290 /**
291 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
292 *
293 * @param key Key to lookup, such as 'sample.SampleModel.icon'
294 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
295 * resource, but this might differ between implementations), or null if none.
296 * @param type the type to be returned
297 * @return The resolved resource at the given key for the default locale
298 * @throws NoSuchResourceException if no resource is found
299 * @since 2.5.0
300 */
301 @Nonnull
302 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull List<?> args, @Nonnull Class<T> type) throws NoSuchResourceException;
303
304 /**
305 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
306 *
307 * @param key Key to lookup, such as 'sample.SampleModel.icon'
308 * @param args Arguments that will be filled in for params within the resource (params look like "{0}" within a
309 * resource, but this might differ between implementations), or null if none.
310 * @param locale Locale in which to lookup
311 * @param type the type to be returned
312 * @return The resolved resource at the given key for the given locale
313 * @throws NoSuchResourceException if no resource is found
314 * @since 2.5.0
315 */
316 @Nonnull
317 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale, @Nonnull Class<T> type) throws NoSuchResourceException;
318
319 /**
320 * Try to resolve the resource. Returns default value if no resource was found.
321 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
322 *
323 * @param key Key to lookup, such as 'sample.SampleModel.icon'
324 * @param defaultValue Message to return if the lookup fails
325 * @param type the type to be returned
326 * @return The resolved resource at the given key for the default locale
327 * @since 2.5.0
328 */
329 @Nullable
330 <T> T resolveResourceConverted(@Nonnull String key, @Nullable T defaultValue, @Nonnull Class<T> type);
331
332 /**
333 * Try to resolve the resource. Returns default value if no resource was found.
334 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
335 *
336 * @param key Key to lookup, such as 'sample.SampleModel.icon'
337 * @param locale Locale in which to lookup
338 * @param defaultValue Message to return if the lookup fails
339 * @param type the type to be returned
340 * @return The resolved resource at the given key for the given locale
341 * @since 2.5.0
342 */
343 @Nullable
344 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Locale locale, @Nullable T defaultValue, @Nonnull Class<T> type);
345
346 /**
347 * Try to resolve the resource. Returns default value if no resource was found.
348 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
349 *
350 * @param key Key to lookup, such as 'sample.SampleModel.icon'
351 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
352 * within a resource, but this might differ between implementations), or null if none.
353 * @param defaultValue Message to return if the lookup fails
354 * @param type the type to be returned
355 * @return The resolved resource at the given key for the default locale
356 * @since 2.5.0
357 */
358 @Nullable
359 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Object[] args, @Nullable T defaultValue, @Nonnull Class<T> type);
360
361 /**
362 * Try to resolve the resource. Returns default value if no resource was found.
363 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
364 *
365 * @param key Key to lookup, such as 'sample.SampleModel.icon'
366 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
367 * within a resource, but this might differ between implementations), or null if none.
368 * @param locale Locale in which to lookup
369 * @param defaultValue Message to return if the lookup fails
370 * @param type the type to be returned
371 * @return The resolved resource at the given key for the given locale
372 * @since 2.5.0
373 */
374 @Nullable
375 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Object[] args, @Nonnull Locale locale, @Nullable T defaultValue, @Nonnull Class<T> type);
376
377 /**
378 * Try to resolve the resource. Returns default value if no resource was found.
379 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
380 *
381 * @param key Key to lookup, such as 'sample.SampleModel.icon'
382 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
383 * within a resource, but this might differ between implementations), or null if none.
384 * @param defaultValue Message to return if the lookup fails
385 * @param type the type to be returned
386 * @return The resolved resource at the given key for the default locale
387 * @since 2.5.0
388 */
389 @Nullable
390 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull List<?> args, @Nullable T defaultValue, @Nonnull Class<T> type);
391
392 /**
393 * Try to resolve the resource. Returns default value if no resource was found.
394 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
395 *
396 * @param key Key to lookup, such as 'sample.SampleModel.icon'
397 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
398 * within a resource, but this might differ between implementations), or null if none.
399 * @param locale Locale in which to lookup
400 * @param defaultValue Message to return if the lookup fails
401 * @param type the type to be returned
402 * @return The resolved resource at the given key for the given locale
403 * @since 2.5.0
404 */
405 @Nullable
406 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull List<?> args, @Nonnull Locale locale, @Nullable T defaultValue, @Nonnull Class<T> type);
407
408 /**
409 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
410 *
411 * @param key Key to lookup, such as 'sample.SampleModel.icon'
412 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
413 * within a resource, but this might differ between implementations), or null if none.
414 * @param type the type to be returned
415 * @return The resolved resource at the given key for the default locale
416 * @throws NoSuchResourceException if no resource is found
417 * @since 2.5.0
418 */
419 @Nonnull
420 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Class<T> type) throws NoSuchResourceException;
421
422 /**
423 * Try to resolve the resource. The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
424 *
425 * @param key Key to lookup, such as 'sample.SampleModel.icon'
426 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
427 * within a resource, but this might differ between implementations), or null if none.
428 * @param locale Locale in which to lookup
429 * @param type the type to be returned
430 * @return The resolved resource at the given key for the given locale
431 * @throws NoSuchResourceException if no resource is found
432 * @since 2.5.0
433 */
434 @Nonnull
435 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale, @Nonnull Class<T> type) throws NoSuchResourceException;
436
437 /**
438 * Try to resolve the resource. Returns default value if no resource was found.
439 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
440 *
441 * @param key Key to lookup, such as 'sample.SampleModel.icon'
442 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
443 * within a resource, but this might differ between implementations), or null if none.
444 * @param defaultValue Message to return if the lookup fails
445 * @param type the type to be returned
446 * @return The resolved resource at the given key for the default locale
447 * @since 2.5.0
448 */
449 @Nullable
450 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Map<String, Object> args, @Nullable T defaultValue, @Nonnull Class<T> type);
451
452 /**
453 * Try to resolve the resource. Returns default value if no resource was found.
454 * The value is converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
455 *
456 * @param key Key to lookup, such as 'sample.SampleModel.icon'
457 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
458 * within a resource, but this might differ between implementations), or null if none.
459 * @param locale Locale in which to lookup
460 * @param defaultValue Message to return if the lookup fails
461 * @param type the type to be returned
462 * @return The resolved resource at the given key for the given locale
463 * @since 2.5.0
464 */
465 @Nullable
466 <T> T resolveResourceConverted(@Nonnull String key, @Nonnull Map<String, Object> args, @Nonnull Locale locale, @Nullable T defaultValue, @Nonnull Class<T> type);
467
468 /**
469 * <p>Resolve a resource given a key and a Locale.</p>
470 * <p>
471 * This method should use the default Locale if the locale argument is null. The {@code key} argument may refer to
472 * another key if the resolved value results in a {@code CharSequence} that begins with "@[" and ends with "]". In this
473 * case the method will use the enclosed value as the next key to be resolved. For example, given the following key/value
474 * definitions
475 * <p/>
476 * <pre>
477 * some.key = Hello {0}
478 * other.key = @[some.key]
479 * </pre>
480 * <p/>
481 * Evaluating the keys results in
482 * <p/>
483 * <pre>
484 * assert resolveResourceValue('some.key', Locale.default) == 'Hello {0}'
485 * assert resolveResourceValue('other.key', Locale.default) == 'Hello {0}'
486 * </pre>
487 * <p/>
488 * </p>
489 *
490 * @param key Key to lookup, such as 'sample.SampleModel.icon'
491 * @param locale Locale in which to lookup
492 * @return the resolved resource value at the given key for the given locale
493 * @throws NoSuchResourceException if no message is found
494 */
495 @Nonnull
496 Object resolveResourceValue(@Nonnull String key, @Nonnull Locale locale) throws NoSuchResourceException;
497
498 /**
499 * Formats the given resource using supplied args to substitute placeholders.
500 *
501 * @param resource The resource following a predefined format.
502 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
503 * within a resource, but this might differ between implementations), or null if none.
504 * @return the formatted resource with all matching placeholders with their substituted values.
505 */
506 @Nonnull
507 String formatResource(@Nonnull String resource, @Nonnull List<?> args);
508
509 /**
510 * Formats the given resource using supplied args to substitute placeholders.
511 *
512 * @param resource The resource following a predefined format.
513 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
514 * within a resource, but this might differ between implementations), or null if none.
515 * @return the formatted resource with all matching placeholders with their substituted values.
516 */
517 @Nonnull
518 String formatResource(@Nonnull String resource, @Nonnull Object[] args);
519
520 /**
521 * Formats the given resource using supplied args to substitute placeholders.
522 *
523 * @param resource The resource following a predefined format.
524 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
525 * within a resource, but this might differ between implementations), or null if none.
526 * @return the formatted resource with all matching placeholders with their substituted values.
527 */
528 @Nonnull
529 String formatResource(@Nonnull String resource, @Nonnull Map<String, Object> args);
530 }
|