001 /*
002 * $Id: Messages.java 354330 2005-12-06 06:05:19Z niallp $
003 * $Revision: 354330 $
004 * $Date: 2005-12-06 06:05:19 +0000 (Tue, 06 Dec 2005) $
005 *
006 * ====================================================================
007 *
008 * Copyright 2003-2005 The Apache Software Foundation
009 *
010 * Licensed under the Apache License, Version 2.0 (the "License");
011 * you may not use this file except in compliance with the License.
012 * You may obtain a copy of the License at
013 *
014 * http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing, software
017 * distributed under the License is distributed on an "AS IS" BASIS,
018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019 * See the License for the specific language governing permissions and
020 * limitations under the License.
021 *
022 */
023
024 package org.apache.commons.resources;
025
026 import java.io.Serializable;
027 import java.text.MessageFormat;
028 import java.util.Locale;
029
030 import org.apache.commons.logging.Log;
031 import org.apache.commons.logging.LogFactory;
032 import org.apache.commons.resources.impl.ResourceBundleResourcesFactory;
033
034 /**
035 * <p>Wrapper around any {@link Resources} object that performs message
036 * string lookups from the {@link Resources} instance, and parameter
037 * replacement via <code>java.text.MessageFormat</code>. For convenience,
038 * the same functionality is also available via static methods that accept
039 * a {@link Resources} parameter.</p>
040 *
041 * <p>Calls to <code>getMessage()</code> variants without a <code>Locale</code>
042 * argument are presumed to be requesting a message string in the default
043 * <code>Locale</code> for this JVM.</p>
044 *
045 * <p>When a <code>getString()</code> call to the underlying {@link Resources}
046 * instance fails or returns null, a suitable error message String will be
047 * returned.</p>
048 */
049 public class Messages implements Serializable {
050
051
052 // ----------------------------------------------------------- Constructors
053
054
055 /**
056 * <p>Construct a {@link Messages} instance that wraps the specified
057 * {@link Resources} instance.</p>
058 *
059 * @param resources The {@link Resources} instance from which
060 * message strings are to be retrieved
061 */
062 public Messages(Resources resources) {
063
064 this.resources = resources;
065
066 }
067
068
069 // ----------------------------------------------------- Instance Variables
070
071
072 /**
073 * <p>The {@link Resources} instance that we are wrapping.</p>
074 */
075 private Resources resources = null;
076
077
078 // ------------------------------------------------------------- Properties
079
080
081 /**
082 * <p>Return the {@link Resources} instance that we are wrapping.</p>
083 *
084 * @return The wrapped resources.
085 */
086 public Resources getResources() {
087
088 return (this.resources);
089
090 }
091
092
093 // --------------------------------------------------------- Public Methods
094
095
096 /**
097 * <p>Return a text message for the specified key, for the default
098 * <code>Locale</code>.</p>
099 *
100 * @param key Message key to retrieve
101 * @return The text message for the specified key.
102 */
103 public String getMessage(String key) {
104
105 return (getMessage(resources, key));
106
107 }
108
109
110 /**
111 * <p>Return a text message for the specified key, for the specified
112 * <code>Locale</code>.</p>
113 *
114 * @param locale <code>Locale</code> for which to retrieve the message
115 * @param key Message key to retrieve
116 * @return The text message for the specified key and locale.
117 */
118 public String getMessage(Locale locale, String key) {
119
120 return (getMessage(resources, locale, key));
121
122 }
123
124
125 /**
126 * <p>Return a text message for the specified key, for the default
127 * <code>Locale</code>, with parametric replacement.</p>
128 *
129 * @param key Message key to retrieve
130 * @param args Array of replacement values
131 * @return The text message with parametric replacement.
132 */
133 public String getMessage(String key, Object[] args) {
134 return getMessage(resources, key, args);
135 }
136
137
138 /**
139 * <p>Return a text message for the specified key, for the specified
140 * <code>Locale</code>, with parametric replacement.</p>
141 *
142 * @param locale <code>Locale</code> for which to retrieve the message
143 * @param key Message key to retrieve
144 * @param args Array of replacement values
145 * @return The text message for a spcified locale with parametric replacement.
146 */
147 public String getMessage(Locale locale, String key, Object[] args) {
148 return getMessage(resources, locale, key, args);
149 }
150
151
152 /**
153 * <p>Return a text message for the specified key, for the default
154 * <code>Locale</code>, with parametric replacement.</p>
155 *
156 * @param key Message key to retrieve
157 * @param arg0 Individual parameter replacement value
158 * @return The text message with parametric replacement.
159 */
160 public String getMessage(String key, Object arg0) {
161
162 return (getMessage(resources, key, arg0));
163
164 }
165
166
167 /**
168 * <p>Return a text message for the specified key, for the specified
169 * <code>Locale</code>, with parametric replacement.</p>
170 *
171 * @param locale <code>Locale</code> for which to retrieve the message
172 * @param key Message key to retrieve
173 * @param arg0 Individual parameter replacement value
174 * @return The text message for a spcified locale with parametric replacement.
175 */
176 public String getMessage(Locale locale, String key, Object arg0) {
177
178 return (getMessage(resources, locale, key, arg0));
179
180 }
181
182
183 // ------------------------------------------------------- Static Variables
184
185
186 /**
187 * <p>The {@link org.apache.commons.resources.ResourcesFactory} that will be used by the
188 * <code>getMessages()</code> method.</p>
189 */
190 private static ResourcesFactory factory = null;
191
192
193 // --------------------------------------------------------- Static Methods
194
195 /**
196 * <p>Set the {@link org.apache.commons.resources.ResourcesFactory} that
197 * will be used by the <code>getMessages()</code> method.</p>
198 *
199 * @param factory ResourcesFactory instance to set.
200 */
201 public static void setFactory(ResourcesFactory factory) {
202 Messages.factory = factory;
203 }
204
205 /**
206 * <p>Return a text message for the specified key, for the default
207 * <code>Locale</code>.</p>
208 *
209 * @param resources {@link Resources} instance to retrieve the message from
210 * @param key Message key to retrieve
211 * @return The text message.
212 */
213 public static String getMessage(Resources resources, String key) {
214
215 return (getMessage(resources, (Locale) null, key));
216
217 }
218
219
220 /**
221 * <p>Return a text message for the specified key, for the specified
222 * <code>Locale</code>.</p>
223 *
224 * @param resources {@link Resources} instance to retrieve the message from
225 * @param locale <code>Locale</code> for which to retrieve the message
226 * @param key Message key to retrieve
227 * @return The text message.
228 */
229 public static String getMessage(
230 Resources resources,
231 Locale locale,
232 String key) {
233
234 String message = null;
235 try {
236 message = resources.getString(key, locale);
237 } catch (ResourcesException e) {
238 Log log = LogFactory.getLog(Messages.class);
239 if (log.isDebugEnabled()) {
240 log.debug("Failed retrieving message for key: '" + key + "'.", e);
241 }
242 }
243
244 if (message == null && !resources.isReturnNull()) {
245 message = "???" + key + "???";
246 }
247
248 return message;
249 }
250
251
252 /**
253 * <p>Return a text message for the specified key, for the default
254 * <code>Locale</code>, with parametric replacement.</p>
255 *
256 * @param resources {@link Resources} instance to retrieve the message from
257 * @param key Message key to retrieve
258 * @param args Array of replacement values
259 * @return The text message.
260 */
261 public static String getMessage(
262 Resources resources,
263 String key,
264 Object[] args) {
265
266 return getMessage(resources, (Locale) null, key, args);
267 }
268
269
270 /**
271 * <p>Return a text message for the specified key, for the specified
272 * <code>Locale</code>, with parametric replacement.</p>
273 *
274 * @param resources {@link Resources} instance to retrieve the message from
275 * @param locale <code>Locale</code> for which to retrieve the message
276 * @param key Message key to retrieve
277 * @param args Array of replacement values
278 * @return The text message.
279 */
280 public static String getMessage(
281 Resources resources,
282 Locale locale,
283 String key,
284 Object[] args) {
285
286 // TODO - Cache MessageFormat instances?
287 String message = getMessage(resources, locale, key);
288 MessageFormat format = new MessageFormat(message);
289 return (format.format(args));
290 }
291
292
293 /**
294 * <p>Return a text message for the specified key, for the default
295 * <code>Locale</code>, with parametric replacement.</p>
296 *
297 * @param resources {@link Resources} instance to retrieve the message from
298 * @param key Message key to retrieve
299 * @param arg0 Individual parameter replacement value
300 * @return The text message.
301 */
302 public static String getMessage(Resources resources,
303 String key, Object arg0) {
304
305 return (getMessage(resources, (Locale) null, key, arg0));
306
307 }
308
309 /**
310 * <p>Return a text message for the specified key, for the specified
311 * <code>Locale</code>, with parametric replacement.</p>
312 *
313 * @param resources {@link Resources} instance to retrieve the message from
314 * @param locale <code>Locale</code> for which to retrieve the message
315 * @param key Message key to retrieve
316 * @param arg0 Individual parameter replacement value
317 * @return The text message.
318 */
319 public static String getMessage(
320 Resources resources,
321 Locale locale,
322 String key,
323 Object arg0) {
324
325 return getMessage(resources, locale, key, new Object[] { arg0 });
326 }
327
328 /**
329 * <p>Convenience factory method to create a {@link Messages} instance
330 * that wraps a {@link Resources} instance that contains message resources
331 * for the specified properties file. It is expected that the resources
332 * for each package will be in properties files that are nested in the
333 * package directory, with names like <code>LocalStrings.properties</code>
334 * for the default messages, and names like
335 * <code>LocalStrings_en_US.properties</code> for messages localized to
336 * a particular <code>Locale</code>.</p>
337 *
338 * @param name Package + file name of the properties file for which
339 * local message resources are desired (ie. org.apache.commons.resources.LocalStrings).
340 * @return The text messages.
341 */
342 public static Messages getMessages(String name) {
343
344 if (factory == null) {
345 factory = new ResourceBundleResourcesFactory();
346 }
347
348 try {
349 Resources resources = factory.getResources(name);
350 return (new Messages(resources));
351
352 } catch (ResourcesException e) {
353 return (null);
354 }
355
356 }
357
358
359 }