001/* ----------------------------------------------------------------------------
002   The Kiwi Toolkit - A Java Class Library
003   Copyright (C) 1998-2004 Mark A. Lindner
004
005   This library is free software; you can redistribute it and/or
006   modify it under the terms of the GNU General Public License as
007   published by the Free Software Foundation; either version 2 of the
008   License, or (at your option) any later version.
009
010   This library is distributed in the hope that it will be useful,
011   but WITHOUT ANY WARRANTY; without even the implied warranty of
012   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013   General Public License for more details.
014
015   You should have received a copy of the GNU General Public License
016   along with this library; if not, write to the Free Software
017   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
018   02111-1307, USA.
019 
020   The author may be contacted at: mark_a_lindner@yahoo.com
021   ----------------------------------------------------------------------------
022   $Log: LocaleData.java,v $
023   Revision 1.9  2004/05/05 21:22:45  markl
024   Comment header updates.
025
026   Revision 1.8  2004/03/10 00:49:20  markl
027   corrected javadoc comment
028
029   Revision 1.7  2003/02/06 07:43:44  markl
030   fixed javadoc typos
031
032   Revision 1.6  2003/01/19 09:42:39  markl
033   Javadoc & comment header updates.
034
035   Revision 1.5  2001/03/18 06:39:47  markl
036   No longer relies on PropertyResourceBundle; added new constructor to
037   construct from Dictionary.
038
039   Revision 1.4  2001/03/12 02:57:41  markl
040   Source code cleanup.
041
042   Revision 1.3  1999/06/28 08:19:19  markl
043   Added another form of getMessage().
044
045   Revision 1.2  1999/04/19 05:31:53  markl
046   New I18N support.
047
048   Revision 1.1  1999/04/18 10:26:12  markl
049   Initial revision
050   ----------------------------------------------------------------------------
051*/
052
053package kiwi.util;
054
055import java.io.*;
056import java.text.*;
057import java.util.*;
058
059/** Locale-specific message bundle. This class serves as a lookup dictionary
060 * for localized messages, and provides some convenience methods for formatting
061 * the messages.
062 *
063 * @author Mark Lindner
064 */
065
066public class LocaleData
067  {
068  /** The default message list delimiter. */
069  public static final String DEFAULT_DELIMITER = ",";
070
071  private final Object unitArray[] = new Object[1];
072  private Dictionary source;
073
074  /** Construct a new <code>LocaleData</code> object from the given input
075   * stream.
076   *
077   * @param instream The stream to read the data from.
078   * @exception java.io.IOException If an error occurred while reading from
079   * the stream.
080   */
081  
082  public LocaleData(InputStream instream) throws IOException
083    {
084    Properties props = new Properties();
085    props.load(instream);
086
087    source = props;
088    }
089
090  /** Construct a new <code>LocaleData</code> object from the given
091   * dictionary.
092   *
093   * @param source A dictionary that contains the key/value pairs.
094   *
095   * @since Kiwi 1.3
096   */
097
098  public LocaleData(Dictionary source)
099    {
100    this.source = source;
101    }
102  
103  /** Get a message for the specified key.
104   *
105   * @param key The key.
106   * @exception kiwi.util.ResourceNotFoundException If the specified key was
107   * not found.
108   * @return A message for the specified key.
109   */
110  
111  public String getMessage(String key) throws ResourceNotFoundException
112    {
113    Object o = source.get(key);
114    if(o == null)
115      throw(new ResourceNotFoundException("Resource not found: " + key));
116    
117    return((String)o);
118    }
119
120  /** Get a message for the specified key, and format the message, substituting
121   * the specified arguments for the message's placeholders. Messages may have
122   * placeholders of the form {n}, where n is a non-negative integer. For
123   * example, the message <tt>"My name is {0}, and I am {1} years old."</tt>
124   * and argument list <code>{ "Joe", new Integer(12) }</code> would be
125   * formatted as <tt>My name is Joe, and I am 12 years old.</tt>
126   *
127   * @param key The key.
128   * @param args An array of arguments for the message.
129   * @exception kiwi.util.ResourceNotFoundException If the specified key was
130   * not found.
131   * @return A formatted message for the specified key.
132   */
133  
134  public String getMessage(String key, Object args[])
135    {
136    return(MessageFormat.format(getMessage(key), args));
137    }
138
139  /** Get a message for the specified key, and format the message, substituting
140   * the specified argument for the message's first placeholder. Messages may
141   * have* placeholders of the form {n}, where n is a non-negative integer. For
142   * example, the message <tt>"My name is {0}"</tt> and argument
143   * <code>"Joe"</code> would be formatted as <tt>My name is Joe.</tt>
144   *
145   * @param key The key.
146   * @param arg A single argument for the message.
147   * @exception kiwi.util.ResourceNotFoundException If the specified key was
148   * not found.
149   * @return A formatted message for the specified key.
150   */
151  
152  public String getMessage(String key, Object arg)
153    {
154    // Reuse a single array so we don't waste heap space.
155    
156    synchronized(unitArray)
157      {
158      unitArray[0] = arg;
159      return(getMessage(key, unitArray));
160      }
161    }
162  
163  /** Get a message list for the specified key. Retrieves a message for the
164   * specified key, and breaks the message on the default delimiter (",")
165   * constructing an array in the process.
166   *
167   * @param key The key.
168   * @exception kiwi.util.ResourceNotFoundException If the specified key was
169   * not found.
170   * @return An array of messages for the specified key.
171   */
172  
173  public String[] getMessageList(String key) throws ResourceNotFoundException
174    {
175    return(getMessageList(key, DEFAULT_DELIMITER));
176    }
177
178  /** Get a message list for the specified key. Retrieves a message for the
179   * specified key, and breaks the message on the specified delimiter
180   * constructing an array in the process.
181   *
182   * @param key The key.
183   * @param delimiter The delimiter to use.
184   * @exception kiwi.util.ResourceNotoundException If the specified key was
185   * not found.
186   * @return An array of messages for the specified key.
187   */
188  
189  public String[] getMessageList(String key, String delimiter)
190    throws ResourceNotFoundException
191    {
192    String msg = getMessage(key);
193    
194    return(StringUtils.split(msg, delimiter));
195    }
196
197  /** Determine if a message is defined for the specified key.
198   *
199   * @param key The key.
200   * @return <code>true</code> if the key exists, and <code>false</code>
201   * otherwise.
202   */
203   
204  public boolean isMessageDefined(String key)
205    {
206    return(source.get(key) != null);
207    }
208  
209  }
210
211/* end of source file */