dflorey 2005/01/02 06:08:12 Modified: i18n/src/java/org/apache/commons/i18n MessageManager.java Log: Some javadoc testings Revision Changes Path 1.7 +132 -63 jakarta-commons-sandbox/i18n/src/java/org/apache/commons/i18n/MessageManager.java Index: MessageManager.java =================================================================== RCS file: /home/cvs/jakarta-commons-sandbox/i18n/src/java/org/apache/commons/i18n/MessageManager.java,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- MessageManager.java 2 Jan 2005 13:33:39 -0000 1.6 +++ MessageManager.java 2 Jan 2005 14:08:12 -0000 1.7 @@ -1,22 +1,22 @@ /* -* -* ==================================================================== -* -* Copyright 2004 The Apache Software Foundation -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -* -*/ + * + * ==================================================================== + * + * Copyright 2004 The Apache Software Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ package org.apache.commons.i18n; import java.text.MessageFormat; @@ -27,61 +27,130 @@ import java.util.Map; /** + * The <code>MessageManager</code> provides methods for retrieving localized + * messages and adding custom message providers. This class should not be called + * directly for other purposes than registering a custom [EMAIL PROTECTED] + * or retrieving information about available message entries. + * <p> + * To access localized messages a subclass of the [EMAIL PROTECTED] LocalizedBundle}class + * such as <code>LocalizedText </code> should be used: + * <p> + * <code>LocalizedText welcome = new LocalizedText("welcome"); // Using the + * default locale System.out.println(welcome.getText()); // Using some other + * locale System.out.println(welcome.getText(Locale.GERMAN));</code> + * <p> + * <code>You can call [EMAIL PROTECTED] + * MessageManager#getText(String,String,Object[],Locale) getText} directly, + * but if you do so, you have to ensure that the given entry key really exists + * and to deal with the MessageNotFound exception that will be thrown if you + * try to access a not existing entry.</code> * * @author Daniel Florey */ public class MessageManager { private static List messageProviders = new ArrayList(); - + static { - messageProviders.add(new XMLMessageProvider()); - messageProviders.add(new ResourceBundleMessageProvider()); + messageProviders.add(new XMLMessageProvider()); + messageProviders.add(new ResourceBundleMessageProvider()); } - + /** - * Add a custom <code>[EMAIL PROTECTED] MessageProvider}</code> to the - * <code>MessageManager</code>. It will be incorporated in later calls of the - * [EMAIL PROTECTED] MessageManager#getText(String,String,Object[]) getText} or [EMAIL PROTECTED] - * #getEntries(String,Locale) getEntries} methods. - * - * @param messageProvider The <code>MessageProvider</code> to be added. - */ -public static void addMessageProvider(MessageProvider messageProvider) { - messageProviders.add(messageProvider); + * Add a custom <code>[EMAIL PROTECTED] MessageProvider}</code> to the + * <code>MessageManager</code>. It will be incorporated in later calls of + * the [EMAIL PROTECTED] MessageManager#getText(String,String,Object[],Locale) getText} + * or [EMAIL PROTECTED] #getEntries(String,Locale) getEntries}methods. + * + * @param messageProvider + * The <code>MessageProvider</code> to be added. + */ + public static void addMessageProvider(MessageProvider messageProvider) { + messageProviders.add(messageProvider); } - - public static String getText(String id, String entry, Object[] arguments, Locale locale) throws MessageNotFoundException { - MessageNotFoundException exception = null; - for ( Iterator i = messageProviders.iterator(); i.hasNext(); ) { - try { - String text =((MessageProvider)i.next()).getText(id, entry, locale); - return MessageFormat.format(text, arguments); - } catch ( MessageNotFoundException e ) { - exception = e; - } - } - throw exception; + + /** + * Iterates over all registered message providers in order to find the given + * entry in the requested message bundle. + * + * @param id + * The identifier that will be used to retrieve the message + * bundle + * @param entry + * The desired message entry + * @param arguments + * The dynamic parts of the message that will be evaluated using + * the standard java text formatting abilities. + * @param locale + * The locale in which the message will be printed + * @exception MessageNotFoundException + * Will be thrown if no message bundle can be found for the + * given id or if the desired message entry is missing in the + * retrieved bundle + * @return The localized text + */ + public static String getText(String id, String entry, Object[] arguments, + Locale locale) throws MessageNotFoundException { + MessageNotFoundException exception = null; + for (Iterator i = messageProviders.iterator(); i.hasNext();) { + try { + String text = ((MessageProvider) i.next()).getText(id, entry, + locale); + return MessageFormat.format(text, arguments); + } catch (MessageNotFoundException e) { + exception = e; + } + } + throw exception; } - public static String getText(String id, String entry, Object[] arguments, Locale locale, String defaultText) { - try { - String text = getText(id, entry, arguments, locale); - return MessageFormat.format(text, arguments); - } catch ( MessageNotFoundException e ) { - return defaultText; - } + /** + * Iterates over all registered message providers in order to find the given + * entry in the requested message bundle. + * + * @param id + * The identifier that will be used to retrieve the message + * bundle + * @param entry + * The desired message entry + * @param arguments + * The dynamic parts of the message that will be evaluated using + * the standard java text formatting abilities. + * @param locale + * The locale in which the message will be printed + * @param defaultText + * If no message bundle or message entry could be found for the + * specified parameters, the default text will be returned. + * @return The localized text or the default text if the message could not + * be found + */ + public static String getText(String id, String entry, Object[] arguments, + Locale locale, String defaultText) { + try { + String text = getText(id, entry, arguments, locale); + return MessageFormat.format(text, arguments); + } catch (MessageNotFoundException e) { + return defaultText; + } } - - public static Map getEntries(String id, Locale locale) throws MessageNotFoundException { - MessageNotFoundException exception = null; - for ( Iterator i = messageProviders.iterator(); i.hasNext(); ) { - try { - Map entries =((MessageProvider)i.next()).getEntries(id, locale); - return entries; - } catch ( MessageNotFoundException e ) { - exception = e; - } - } - throw exception; + + /** + * Returns a map containing all available message entries for the given + * locale. The map contains keys of type [EMAIL PROTECTED] String}containing the keys + * of the available message entries and values of type [EMAIL PROTECTED] String} + * containing the localized message entries. + */ + public static Map getEntries(String id, Locale locale) + throws MessageNotFoundException { + MessageNotFoundException exception = null; + for (Iterator i = messageProviders.iterator(); i.hasNext();) { + try { + Map entries = ((MessageProvider) i.next()).getEntries(id, + locale); + return entries; + } catch (MessageNotFoundException e) { + exception = e; + } + } + throw exception; } -} +} \ No newline at end of file
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
