    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}