001 /*
002 * Copyright 2008-2015 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 * <p>Resolve a resource given a key and a Locale.</p>
236 * <p>
237 * This method should use the default Locale if the locale argument is null. The {@code key} argument may refer to
238 * another key if the resolved value results in a {@code CharSequence} that begins with "@[" and ends with "]". In this
239 * case the method will use the enclosed value as the next key to be resolved. For example, given the following key/value
240 * definitions
241 * <p/>
242 * <pre>
243 * some.key = Hello {0}
244 * other.key = @[some.key]
245 * </pre>
246 * <p/>
247 * Evaluating the keys results in
248 * <p/>
249 * <pre>
250 * assert resolveResourceValue('some.key', Locale.default) == 'Hello {0}'
251 * assert resolveResourceValue('other.key', Locale.default) == 'Hello {0}'
252 * </pre>
253 * <p/>
254 * </p>
255 *
256 * @param key Key to lookup, such as 'sample.SampleModel.icon'
257 * @param locale Locale in which to lookup
258 * @return the resolved resource value at the given key for the given locale
259 * @throws NoSuchResourceException if no message is found
260 */
261 @Nonnull
262 Object resolveResourceValue(@Nonnull String key, @Nonnull Locale locale) throws NoSuchResourceException;
263
264 /**
265 * Formats the given resource using supplied args to substitute placeholders.
266 *
267 * @param resource The resource following a predefined format.
268 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
269 * within a resource, but this might differ between implementations), or null if none.
270 * @return the formatted resource with all matching placeholders with their substituted values.
271 */
272 @Nonnull
273 String formatResource(@Nonnull String resource, @Nonnull List<?> args);
274
275 /**
276 * Formats the given resource using supplied args to substitute placeholders.
277 *
278 * @param resource The resource following a predefined format.
279 * @param args Arguments that will be filled in for params within the resource (params look like "{0}"
280 * within a resource, but this might differ between implementations), or null if none.
281 * @return the formatted resource with all matching placeholders with their substituted values.
282 */
283 @Nonnull
284 String formatResource(@Nonnull String resource, @Nonnull Object[] args);
285
286 /**
287 * Formats the given resource using supplied args to substitute placeholders.
288 *
289 * @param resource The resource following a predefined format.
290 * @param args Arguments that will be filled in for params within the resource (params look like "{:key}"
291 * within a resource, but this might differ between implementations), or null if none.
292 * @return the formatted resource with all matching placeholders with their substituted values.
293 */
294 @Nonnull
295 String formatResource(@Nonnull String resource, @Nonnull Map<String, Object> args);
296 }
|