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