001    /*
002     * Created on 25/11/2005 by Eduardo Piva - eduardo@gwe.com.br
003     *
004     */
005    package org.trails.i18n;
006    
007    import java.util.Locale;
008    
009    import org.trails.descriptor.IClassDescriptor;
010    import org.trails.descriptor.IDescriptor;
011    
012    /**
013     * Interface used to imlement i18n in Trails pages and components.
014     */
015    public interface TrailsMessageSource
016    {
017    
018            Object[] EMPTY_ARGUMENTS = new Object[]{};
019    
020            /**
021             * Return a internationalized message.
022             *
023             * @param key Key used to locate the message.
024             * @return Localized message. Return null if message not found.
025             */
026            public String getMessage(String key);
027    
028            /**
029             * Return a internationalized message specifing arguments to format this message.
030             *
031             * @param key  Key used to locate the message.
032             * @param args Arguments to format the message.
033             * @return Localized message. Return null of message not found.
034             */
035            public String getMessage(String key, Object[] args);
036    
037            /**
038             * Same as getMessage(String key), but it will return a default value instead of null if message not found.
039             *
040             * @param defaultMessage Default message to return if message not found.
041             */
042            public String getMessageWithDefaultValue(String key, String defaultMessage);
043    
044            /**
045             * Same as getMessage(String key, Object[] args), but will return a default value instead of null if message not
046             * found.
047             *
048             * @param defaultMessage Default message to return if message not found.
049             */
050            public String getMessageWithDefaultValue(String key, Object[] args, String defaultMessage);
051    
052            /**
053             * Given a IDescriptor, this method select an i18n message for the descriptor. If no i18n message is found, a
054             * defaultMessage is used instead.
055             *
056             * @param clazz                   Class description.
057             * @param defaultDisplayName default displayName to return if no i18n message is found.
058             * @return
059             */
060            public String getDisplayName(IDescriptor clazz, String defaultDisplayName);
061    
062            /**
063             * Given a IClassDescriptor and a Locale, this method select an i18n message for the class in the plural name
064             *
065             * @param clazz                   Class description
066             * @param defaultDisplayName default displayName to return if no i18n message is found.
067             * @return
068             */
069            public String getPluralDislayName(IClassDescriptor clazz, String defaultDisplayName);
070    
071    
072            /**
073             * Return a internationalized message.
074             * <p/>
075             * Sometimes it makes sense to force a Locale, but don't overuse this method.
076             *
077             * @param key   Key used to locate the message.
078             * @param locale Locale used to locate message.
079             * @return Localized message. Return null if message not found.
080             */
081            public String getMessage(String key, Locale locale);
082    
083            /**
084             * Return a internationalized message specifing arguments to format this message.
085             * <p/>
086             * Sometimes it makes sense to force a Locale, but don't overuse this method.
087             *
088             * @param key   Key used to locate the message.
089             * @param args   Arguments to format the message.
090             * @param locale Locale used to locate message.
091             * @return Localized message. Return null of message not found.
092             */
093            public String getMessage(String key, Object[] args, Locale locale);
094    
095            public String getMessageWithDefaultValue(String key, Locale locale, String defaultMessage);
096            public String getMessageWithDefaultValue(String key, Object[] args, Locale locale, String defaultMessage);
097    }