KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > context > support > AbstractMessageSource


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.context.support;
18
19 import java.text.MessageFormat JavaDoc;
20 import java.util.ArrayList JavaDoc;
21 import java.util.HashMap JavaDoc;
22 import java.util.List JavaDoc;
23 import java.util.Locale JavaDoc;
24 import java.util.Map JavaDoc;
25
26 import org.apache.commons.logging.Log;
27 import org.apache.commons.logging.LogFactory;
28
29 import org.springframework.context.HierarchicalMessageSource;
30 import org.springframework.context.MessageSource;
31 import org.springframework.context.MessageSourceResolvable;
32 import org.springframework.context.NoSuchMessageException;
33 import org.springframework.util.ObjectUtils;
34
35 /**
36  * Abstract implementation of the HierarchicalMessageSource interface,
37  * implementing common handling of message variants, making it easy
38  * to implement a specific strategy for a concrete MessageSource.
39  *
40  * <p>Subclasses must implement the abstract <code>resolveCode</code>
41  * method. For efficient resolution of messages without arguments, the
42  * <code>resolveCodeWithoutArguments</code> method should be overridden
43  * as well, resolving messages without a MessageFormat being involved.
44  *
45  * <p><b>Note:</b> By default, message texts are only parsed through
46  * MessageFormat if arguments have been passed in for the message. In case
47  * of no arguments, message texts will be returned as-is. As a consequence,
48  * you should only use MessageFormat escaping for messages with actual
49  * arguments, and keep all other messages unescaped. If you prefer to
50  * escape all messages, set the "alwaysUseMessageFormat" flag to "true".
51  *
52  * <p>Supports not only MessageSourceResolvables as primary messages
53  * but also resolution of message arguments that are in turn
54  * MessageSourceResolvables themselves.
55  *
56  * <p>This class does not implement caching of messages per code, thus
57  * subclasses can dynamically change messages over time. Subclasses are
58  * encouraged to cache their messages in a modification-aware fashion,
59  * allowing for hot deployment of updated messages.
60  *
61  * @author Juergen Hoeller
62  * @author Rod Johnson
63  * @see #resolveCode(String, java.util.Locale)
64  * @see #resolveCodeWithoutArguments(String, java.util.Locale)
65  * @see #setAlwaysUseMessageFormat
66  * @see java.text.MessageFormat
67  */
68 public abstract class AbstractMessageSource implements HierarchicalMessageSource {
69
70     /** Logger available to subclasses */
71     protected final Log logger = LogFactory.getLog(getClass());
72
73     private MessageSource parentMessageSource;
74
75     private boolean useCodeAsDefaultMessage = false;
76
77     private boolean alwaysUseMessageFormat = false;
78
79     /**
80      * Cache to hold already generated MessageFormats per message.
81      * Used for passed-in default messages. MessageFormats for resolved
82      * codes are cached on a specific basis in subclasses.
83      */
84     private final Map JavaDoc cachedMessageFormats = new HashMap JavaDoc();
85
86
87     public void setParentMessageSource(MessageSource parent) {
88         this.parentMessageSource = parent;
89     }
90
91     public MessageSource getParentMessageSource() {
92         return parentMessageSource;
93     }
94
95     /**
96      * Set whether to use the message code as default message instead of
97      * throwing a NoSuchMessageException. Useful for development and debugging.
98      * Default is "false".
99      * <p>Note: In case of a MessageSourceResolvable with multiple codes
100      * (like a FieldError) and a MessageSource that has a parent MessageSource,
101      * do <i>not</i> activate "useCodeAsDefaultMessage" in the <i>parent</i>:
102      * Else, you'll get the first code returned as message by the parent,
103      * without attempts to check further codes.
104      * <p>To be able to work with "useCodeAsDefaultMessage" turned on in the parent,
105      * AbstractMessageSource and AbstractApplicationContext contain special checks
106      * to delegate to the internal <code>getMessageInternal</code> method if available.
107      * In general, it is recommended to just use "useCodeAsDefaultMessage" during
108      * development and not rely on it in production in the first place, though.
109      * @see #getMessage(String, Object[], Locale)
110      * @see #getMessageInternal
111      * @see org.springframework.validation.FieldError
112      */
113     public void setUseCodeAsDefaultMessage(boolean useCodeAsDefaultMessage) {
114         this.useCodeAsDefaultMessage = useCodeAsDefaultMessage;
115     }
116
117     /**
118      * Return whether to use the message code as default message instead of
119      * throwing a NoSuchMessageException. Useful for development and debugging.
120      * Default is "false".
121      * <p>Alternatively, consider overriding the <code>getDefaultMessage</code>
122      * method to return a custom fallback message for an unresolvable code.
123      * @see #getDefaultMessage(String)
124      */
125     protected boolean isUseCodeAsDefaultMessage() {
126         return useCodeAsDefaultMessage;
127     }
128
129     /**
130      * Set whether to always apply the MessageFormat rules, parsing even
131      * messages without arguments.
132      * <p>Default is "false": Messages without arguments are by default
133      * returned as-is, without parsing them through MessageFormat.
134      * Set this to "true" to enforce MessageFormat for all messages,
135      * expecting all message texts to be written with MessageFormat escaping.
136      * <p>For example, MessageFormat expects a single quote to be escaped
137      * as "''". If your message texts are all written with such escaping,
138      * even when not defining argument placeholders, you need to set this
139      * flag to "true". Else, only message texts with actual arguments
140      * are supposed to be written with MessageFormat escaping.
141      * @see java.text.MessageFormat
142      */
143     public void setAlwaysUseMessageFormat(boolean alwaysUseMessageFormat) {
144         this.alwaysUseMessageFormat = alwaysUseMessageFormat;
145     }
146
147     /**
148      * Return whether to always apply the MessageFormat rules, parsing even
149      * messages without arguments.
150      */
151     protected boolean isAlwaysUseMessageFormat() {
152         return alwaysUseMessageFormat;
153     }
154
155
156     public final String JavaDoc getMessage(String JavaDoc code, Object JavaDoc[] args, String JavaDoc defaultMessage, Locale JavaDoc locale) {
157         String JavaDoc msg = getMessageInternal(code, args, locale);
158         if (msg != null) {
159             return msg;
160         }
161         if (defaultMessage == null) {
162             String JavaDoc fallback = getDefaultMessage(code);
163             if (fallback != null) {
164                 return fallback;
165             }
166         }
167         return renderDefaultMessage(defaultMessage, args, locale);
168     }
169
170     public final String JavaDoc getMessage(String JavaDoc code, Object JavaDoc[] args, Locale JavaDoc locale) throws NoSuchMessageException {
171         String JavaDoc msg = getMessageInternal(code, args, locale);
172         if (msg != null) {
173             return msg;
174         }
175         String JavaDoc fallback = getDefaultMessage(code);
176         if (fallback != null) {
177             return fallback;
178         }
179         throw new NoSuchMessageException(code, locale);
180     }
181
182     public final String JavaDoc getMessage(MessageSourceResolvable resolvable, Locale JavaDoc locale)
183             throws NoSuchMessageException {
184
185         String JavaDoc[] codes = resolvable.getCodes();
186         if (codes == null) {
187             codes = new String JavaDoc[0];
188         }
189         for (int i = 0; i < codes.length; i++) {
190             String JavaDoc msg = getMessageInternal(codes[i], resolvable.getArguments(), locale);
191             if (msg != null) {
192                 return msg;
193             }
194         }
195         if (resolvable.getDefaultMessage() != null) {
196             return renderDefaultMessage(resolvable.getDefaultMessage(), resolvable.getArguments(), locale);
197         }
198         if (codes.length > 0) {
199             String JavaDoc fallback = getDefaultMessage(codes[0]);
200             if (fallback != null) {
201                 return fallback;
202             }
203         }
204         throw new NoSuchMessageException(codes.length > 0 ? codes[codes.length - 1] : null, locale);
205     }
206
207
208     /**
209      * Resolve the given code and arguments as message in the given Locale,
210      * returning null if not found. Does <i>not</i> fall back to the code
211      * as default message. Invoked by getMessage methods.
212      * @param code the code to lookup up, such as 'calculator.noRateSet'
213      * @param args array of arguments that will be filled in for params
214      * within the message
215      * @param locale the Locale in which to do the lookup
216      * @return the resolved message, or <code>null</code> if not found
217      * @see #getMessage(String, Object[], String, Locale)
218      * @see #getMessage(String, Object[], Locale)
219      * @see #getMessage(MessageSourceResolvable, Locale)
220      * @see #setUseCodeAsDefaultMessage
221      */
222     protected String JavaDoc getMessageInternal(String JavaDoc code, Object JavaDoc[] args, Locale JavaDoc locale) {
223         if (code == null) {
224             return null;
225         }
226         if (locale == null) {
227             locale = Locale.getDefault();
228         }
229         Object JavaDoc[] argsToUse = args;
230
231         if (!isAlwaysUseMessageFormat() && ObjectUtils.isEmpty(args)) {
232             // Optimized resolution: no arguments to apply,
233 // therefore no MessageFormat needs to be involved.
234 // Note that the default implementation still uses MessageFormat;
235 // this can be overridden in specific subclasses.
236 String JavaDoc message = resolveCodeWithoutArguments(code, locale);
237             if (message != null) {
238                 return message;
239             }
240         }
241
242         else {
243             // Resolve arguments eagerly, for the case where the message
244 // is defined in a parent MessageSource but resolvable arguments
245 // are defined in the child MessageSource.
246 argsToUse = resolveArguments(args, locale);
247
248             MessageFormat JavaDoc messageFormat = resolveCode(code, locale);
249             if (messageFormat != null) {
250                 synchronized (messageFormat) {
251                     return messageFormat.format(argsToUse);
252                 }
253             }
254         }
255
256         // Not found -> check parent, if any.
257 return getMessageFromParent(code, argsToUse, locale);
258     }
259
260     /**
261      * Try to retrieve the given message from the parent MessageSource, if any.
262      * @param code the code to lookup up, such as 'calculator.noRateSet'
263      * @param args array of arguments that will be filled in for params
264      * within the message
265      * @param locale the Locale in which to do the lookup
266      * @return the resolved message, or <code>null</code> if not found
267      * @see #getParentMessageSource()
268      */
269     protected String JavaDoc getMessageFromParent(String JavaDoc code, Object JavaDoc[] args, Locale JavaDoc locale) {
270         MessageSource parent = getParentMessageSource();
271         if (parent != null) {
272             if (parent instanceof AbstractMessageSource) {
273                 // Call internal method to avoid getting the default code back
274 // in case of "useCodeAsDefaultMessage" being activated.
275 return ((AbstractMessageSource) parent).getMessageInternal(code, args, locale);
276             }
277             else {
278                 // Check parent MessageSource, returning null if not found there.
279 return parent.getMessage(code, args, null, locale);
280             }
281         }
282         // Not found in parent either.
283 return null;
284     }
285
286     /**
287      * Return a fallback default message for the given code, if any.
288      * <p>Default is to return the code itself if "useCodeAsDefaultMessage"
289      * is activated, or return no fallback else. In case of no fallback,
290      * the caller will usually receive a NoSuchMessageException from
291      * <code>getMessage</code>.
292      * @param code the message code that we couldn't resolve
293      * and that we didn't receive an explicit default message for
294      * @return the default message to use, or <code>null</code> if none
295      * @see #setUseCodeAsDefaultMessage
296      */
297     protected String JavaDoc getDefaultMessage(String JavaDoc code) {
298         if (isUseCodeAsDefaultMessage()) {
299             return code;
300         }
301         return null;
302     }
303
304
305     /**
306      * Render the given default message String. The default message is
307      * passed in as specified by the caller and can be rendered into
308      * a fully formatted default message shown to the user.
309      * <p>Default implementation passes the String to <code>formatMessage</code>,
310      * resolving any argument placeholders found in them. Subclasses may override
311      * this method to plug in custom processing of default messages.
312      * @param defaultMessage the passed-in default message String
313      * @param args array of arguments that will be filled in for params within
314      * the message, or <code>null</code> if none.
315      * @param locale the Locale used for formatting
316      * @return the rendered default message (with resolved arguments)
317      * @see #formatMessage(String, Object[], java.util.Locale)
318      */
319     protected String JavaDoc renderDefaultMessage(String JavaDoc defaultMessage, Object JavaDoc[] args, Locale JavaDoc locale) {
320         return formatMessage(defaultMessage, args, locale);
321     }
322
323     /**
324      * Format the given message String, using cached MessageFormats.
325      * By default invoked for passed-in default messages, to resolve
326      * any argument placeholders found in them.
327      * @param msg the message to format
328      * @param args array of arguments that will be filled in for params within
329      * the message, or <code>null</code> if none.
330      * @param locale the Locale used for formatting
331      * @return the formatted message (with resolved arguments)
332      */
333     protected String JavaDoc formatMessage(String JavaDoc msg, Object JavaDoc[] args, Locale JavaDoc locale) {
334         if (msg == null || (!this.alwaysUseMessageFormat && (args == null || args.length == 0))) {
335             return msg;
336         }
337         MessageFormat JavaDoc messageFormat = null;
338         synchronized (this.cachedMessageFormats) {
339             messageFormat = (MessageFormat JavaDoc) this.cachedMessageFormats.get(msg);
340             if (messageFormat == null) {
341                 messageFormat = createMessageFormat(msg, locale);
342                 this.cachedMessageFormats.put(msg, messageFormat);
343             }
344         }
345         synchronized (messageFormat) {
346             return messageFormat.format(resolveArguments(args, locale));
347         }
348     }
349
350     /**
351      * Create a MessageFormat for the given message and Locale.
352      * <p>This implementation creates an empty MessageFormat first,
353      * populating it with Locale and pattern afterwards, to stay
354      * compatible with J2SE 1.3.
355      * @param msg the message to create a MessageFormat for
356      * @param locale the Locale to create a MessageFormat for
357      * @return the MessageFormat instance
358      */
359     protected MessageFormat JavaDoc createMessageFormat(String JavaDoc msg, Locale JavaDoc locale) {
360         if (logger.isDebugEnabled()) {
361             logger.debug("Creating MessageFormat for pattern [" + msg + "] and locale '" + locale + "'");
362         }
363         MessageFormat JavaDoc messageFormat = new MessageFormat JavaDoc("");
364         messageFormat.setLocale(locale);
365         if (msg != null) {
366             messageFormat.applyPattern(msg);
367         }
368         return messageFormat;
369     }
370
371
372     /**
373      * Search through the given array of objects, find any
374      * MessageSourceResolvable objects and resolve them.
375      * <p>Allows for messages to have MessageSourceResolvables as arguments.
376      * @param args array of arguments for a message
377      * @param locale the locale to resolve through
378      * @return an array of arguments with any MessageSourceResolvables resolved
379      */
380     protected Object JavaDoc[] resolveArguments(Object JavaDoc[] args, Locale JavaDoc locale) {
381         if (args == null) {
382             return new Object JavaDoc[0];
383         }
384         List JavaDoc resolvedArgs = new ArrayList JavaDoc(args.length);
385         for (int i = 0; i < args.length; i++) {
386             if (args[i] instanceof MessageSourceResolvable) {
387                 resolvedArgs.add(getMessage((MessageSourceResolvable) args[i], locale));
388             }
389             else {
390                 resolvedArgs.add(args[i]);
391             }
392         }
393         return resolvedArgs.toArray(new Object JavaDoc[resolvedArgs.size()]);
394     }
395
396     /**
397      * Subclasses can override this method to resolve a message without
398      * arguments in an optimized fashion, that is, to resolve a message
399      * without involving a MessageFormat.
400      * <p>The default implementation <i>does</i> use MessageFormat,
401      * through delegating to the <code>resolveCode</code> method.
402      * Subclasses are encouraged to replace this with optimized resolution.
403      * <p>Unfortunately, <code>java.text.MessageFormat</code> is not
404      * implemented in an efficient fashion. In particular, it does not
405      * detect that a message pattern doesn't contain argument placeholders
406      * in the first place. Therefore, it's advisable to circumvent
407      * MessageFormat completely for messages without arguments.
408      * @param code the code of the message to resolve
409      * @param locale the Locale to resolve the code for
410      * (subclasses are encouraged to support internationalization)
411      * @return the message String, or <code>null</code> if not found
412      * @see #resolveCode
413      * @see java.text.MessageFormat
414      */
415     protected String JavaDoc resolveCodeWithoutArguments(String JavaDoc code, Locale JavaDoc locale) {
416         MessageFormat JavaDoc messageFormat = resolveCode(code, locale);
417         if (messageFormat != null) {
418             synchronized (messageFormat) {
419                 return messageFormat.format(new Object JavaDoc[0]);
420             }
421         }
422         return null;
423     }
424
425     /**
426      * Subclasses must implement this method to resolve a message.
427      * <p>Returns a MessageFormat instance rather than a message String,
428      * to allow for appropriate caching of MessageFormats in subclasses.
429      * <p><b>Subclasses are encouraged to provide optimized resolution
430      * for messages without arguments, not involving MessageFormat.</b>
431      * See <code>resolveCodeWithoutArguments</code> javadoc for details.
432      * @param code the code of the message to resolve
433      * @param locale the Locale to resolve the code for
434      * (subclasses are encouraged to support internationalization)
435      * @return the MessageFormat for the message, or <code>null</code> if not found
436      * @see #resolveCodeWithoutArguments(String, java.util.Locale)
437      */
438     protected abstract MessageFormat JavaDoc resolveCode(String JavaDoc code, Locale JavaDoc locale);
439
440 }
441
Popular Tags