View Javadoc

1   /*
2    *
3    * ====================================================================
4    *
5    * Copyright 2004 The Apache Software Foundation 
6    *
7    * Licensed under the Apache License, Version 2.0 (the "License");
8    * you may not use this file except in compliance with the License.
9    * You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   *
19   */
20  package org.apache.commons.i18n;
21  
22  import java.text.MessageFormat;
23  import java.util.ArrayList;
24  import java.util.Iterator;
25  import java.util.List;
26  import java.util.Locale;
27  import java.util.Map;
28  
29  /***
30   * The <code>MessageManager</code> provides methods for retrieving localized
31   * messages and adding custom message providers. This class should not be called
32   * directly for other purposes than registering a custom {@link MessageProvider}
33   * or retrieving information about available message entries.
34   * <p>
35   * To access localized messages a subclass of the {@link LocalizedBundle}class
36   * such as <code>LocalizedText </code> should be used:
37   * <p>
38   * <code>LocalizedText welcome = new LocalizedText("welcome"); // Using the
39   * default locale System.out.println(welcome.getText()); // Using some other
40   * locale System.out.println(welcome.getText(Locale.GERMAN));</code>
41   * <p>
42   * <code>You can call {@link
43   * MessageManager#getText(String,String,Object[],Locale) getText} directly,
44   * but if you do so, you have to ensure that the given entry key really exists
45   * and to deal with the MessageNotFound exception that will be thrown if you
46   * try to access a not existing entry.</code>
47   * 
48   * @author Daniel Florey
49   */
50  public class MessageManager {
51      private static List messageProviders = new ArrayList();
52  
53      static {
54          messageProviders.add(new XMLMessageProvider());
55          messageProviders.add(new ResourceBundleMessageProvider());
56      }
57  
58      /***
59       * Add a custom <code>{@link MessageProvider}</code> to the
60       * <code>MessageManager</code>. It will be incorporated in later calls of
61       * the {@link MessageManager#getText(String,String,Object[],Locale) getText}
62       * or {@link #getEntries(String,Locale) getEntries}methods.
63       * 
64       * @param messageProvider
65       *            The <code>MessageProvider</code> to be added.
66       */
67      public static void addMessageProvider(MessageProvider messageProvider) {
68          messageProviders.add(messageProvider);
69      }
70  
71      /***
72       * Iterates over all registered message providers in order to find the given
73       * entry in the requested message bundle.
74       * 
75       * @param id
76       *            The identifier that will be used to retrieve the message
77       *            bundle
78       * @param entry
79       *            The desired message entry
80       * @param arguments
81       *            The dynamic parts of the message that will be evaluated using
82       *            the standard java text formatting abilities.
83       * @param locale
84       *            The locale in which the message will be printed
85       * @exception MessageNotFoundException
86       *                Will be thrown if no message bundle can be found for the
87       *                given id or if the desired message entry is missing in the
88       *                retrieved bundle
89       * @return The localized text
90       */
91      public static String getText(String id, String entry, Object[] arguments,
92              Locale locale) throws MessageNotFoundException {
93          MessageNotFoundException exception = null;
94          for (Iterator i = messageProviders.iterator(); i.hasNext();) {
95              try {
96                  String text = ((MessageProvider) i.next()).getText(id, entry,
97                          locale);
98                  return MessageFormat.format(text, arguments);
99              } catch (MessageNotFoundException e) {
100                 exception = e;
101             }
102         }
103         throw exception;
104     }
105 
106     /***
107      * Iterates over all registered message providers in order to find the given
108      * entry in the requested message bundle.
109      * 
110      * @param id
111      *            The identifier that will be used to retrieve the message
112      *            bundle
113      * @param entry
114      *            The desired message entry
115      * @param arguments
116      *            The dynamic parts of the message that will be evaluated using
117      *            the standard java text formatting abilities.
118      * @param locale
119      *            The locale in which the message will be printed
120      * @param defaultText
121      *            If no message bundle or message entry could be found for the
122      *            specified parameters, the default text will be returned.
123      * @return The localized text or the default text if the message could not
124      *         be found
125      */
126     public static String getText(String id, String entry, Object[] arguments,
127             Locale locale, String defaultText) {
128         try {
129             String text = getText(id, entry, arguments, locale);
130             return MessageFormat.format(text, arguments);
131         } catch (MessageNotFoundException e) {
132             return defaultText;
133         }
134     }
135 
136     /***
137      * Returns a map containing all available message entries for the given
138      * locale. The map contains keys of type {@link String}containing the keys
139      * of the available message entries and values of type {@link String}
140      * containing the localized message entries.
141      */
142     public static Map getEntries(String id, Locale locale)
143             throws MessageNotFoundException {
144         MessageNotFoundException exception = null;
145         for (Iterator i = messageProviders.iterator(); i.hasNext();) {
146             try {
147                 Map entries = ((MessageProvider) i.next()).getEntries(id,
148                         locale);
149                 return entries;
150             } catch (MessageNotFoundException e) {
151                 exception = e;
152             }
153         }
154         throw exception;
155     }
156 }