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