001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.i18n;
020
021import java.text.MessageFormat;
022import java.util.Locale;
023import java.util.MissingResourceException;
024import java.util.ResourceBundle;
025
026
027/**
028 *  Manages all internationalization in JSPWiki.
029 *
030 *  @since 2.6
031 */
032public interface InternationalizationManager {
033
034    /** The name of the ResourceBundle which contains any and all JSPWiki core resource strings.  It's value is {@value}. */
035    String CORE_BUNDLE = "CoreResources";
036    
037    /** The name of the ResourceBundle which contains any and all JSPWiki default templates resource strings.  It's value is {@value}. */
038    String DEF_TEMPLATE = "templates.default";
039    // public static final String JSPWIKI_BUNDLE = "jspwiki";
040    // public static final String PLUGINS_BUNDLE = "plugins";
041
042    /**
043     *  Returns a String from the CORE_BUNDLE using English as the default locale.
044     *
045     *  @param key Key to find
046     *  @return The English string
047     *  @throws MissingResourceException If there is no such key
048     */
049    default String get( final String key ) throws MissingResourceException {
050        return get( CORE_BUNDLE, Locale.ENGLISH, key );
051    }
052    
053    /**
054     *  Finds a resource bundle.
055     *
056     *  @param bundle The ResourceBundle to find.  Must exist.
057     *  @param locale The Locale to use.  Set to null to get the default locale.
058     *  @return A localized string
059     *  @throws MissingResourceException If the key cannot be located at all, even from the default locale.
060     */
061    default ResourceBundle getBundle( final String bundle, Locale locale ) throws MissingResourceException {
062        if( locale == null ) {
063            locale = Locale.getDefault();
064        }
065
066        return ResourceBundle.getBundle( bundle, locale );
067    }
068
069    /**
070     *  If you are too lazy to open your own bundle, use this method to get a string simply from a bundle.
071     *
072     *  @param bundle Which bundle the string is in
073     *  @param locale Locale to use - null for default
074     *  @param key    Which key to use.
075     *  @return A localized string (or from the default language, if not found)
076     *  @throws MissingResourceException If the key cannot be located at all, even from the default locale.
077     */
078    default String get( final String bundle, final Locale locale, final String key ) throws MissingResourceException {
079        return getBundle( bundle, locale ).getString( key );
080    }
081
082    /**
083     *  Obtain a parameterized String from the bundle.
084     *
085     *  @param bundle Which bundle the string is in
086     *  @param locale Locale to use - null for default
087     *  @param key    Which key to use.
088     *  @param args parameters to insert in the String.
089     *  @return A localized string (or from the default language, if not found)
090     *  @throws MissingResourceException If the key cannot be located at all, even from the default locale.
091     */
092    default String get( final String bundle, final Locale locale, final String key, final Object... args ) throws MissingResourceException {
093        final MessageFormat mf = new MessageFormat( get( bundle, locale, key ), locale );
094        return mf.format( args );
095    }
096
097}