001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.i18n;
029
030import java.util.Locale;
031
032/**
033 * Utility interface for generating localized messages for internal OpenCms operations.<p>
034 *
035 * Every OpenCms core packages should provide one class implementing this interface.
036 * This class should be called <code>Messages</code> and be a subclass of
037 * <code>{@link org.opencms.i18n.A_CmsMessageBundle}</code>. Moreover, the implementation
038 * should contain a <code>public static CmsMessageBundle#get()</code> method, that returns
039 * an instance of the class. Also the implementation should contain public static members
040 * for all available localized keys.<p>
041 *
042 * How to use localization in the OpenCms core:<p>
043 *
044 * There are 3 main ulitiliy classes that deal with localization. These are<ul>
045 *
046 * <li>{@link I_CmsMessageBundle} (all classes that implement this interface):
047 * These classes describe a pointer to a resource bundle, but without providing a {@link java.util.Locale}.
048 * So this is like a list of valid keys that can be localized, without the actual localization.</li>
049 *
050 * <li>{@link org.opencms.i18n.CmsMessages}: This is a fully localized resource bundle,
051 * with a list of keys and a {@link java.util.Locale} to localize these keys. If you have a {@link I_CmsMessageBundle},
052 * you can use {@link I_CmsMessageBundle#getBundleName()} to initialize a {@link org.opencms.i18n.CmsMessages} instance
053 * using {@link org.opencms.i18n.CmsMessages#CmsMessages(String, Locale)}.</li>
054 *
055 * <li>{@link org.opencms.i18n.CmsMessageContainer}: In some circumstances, you do not have a {@link java.util.Locale},
056 * but you want to generate a message that contains certain parameters anyway. For example, in the deeper layers of the
057 * OpenCms core an issue may be generated, but you do not have a full user context available. The {@link org.opencms.i18n.CmsMessageContainer}
058 * contains a reference to a {@link I_CmsMessageBundle}, plus the name of the key to use in the bundle, plus a list of
059 * (optional) parameters. This container is then passed "upwards" in the core until the GUI layer (usually the Workplace)
060 * is reached.</li>
061 *
062 * <li>{@link org.opencms.i18n.CmsMultiMessages}: This is a convenience class that contains a set
063 * of {@link org.opencms.i18n.CmsMessages}. A key lookup is automatically done in all the {@link org.opencms.i18n.CmsMessages}
064 * instances contained in the multi message instance, and the first match is returned.</li>
065 * </ul>
066 *
067 * @since 6.0.0
068 */
069public interface I_CmsMessageBundle {
070
071    /**
072     * Creates a message container for this package with the given arguments.<p>
073     *
074     * Convenience method for a message with no arguments.<p>
075     *
076     * @param key the message key to use
077     * @return a message container for this package with the given arguments
078     */
079    CmsMessageContainer container(String key);
080
081    /**
082     * Creates a message container for this package with the given arguments.<p>
083     *
084     * Convenience method for a message with one argument.<p>
085     *
086     * @param key the message key to use
087     * @param arg0 the message argument
088     * @return a message container for this package with the given arguments
089     */
090    CmsMessageContainer container(String key, Object arg0);
091
092    /**
093     * Creates a message container for this package with the given arguments.<p>
094     *
095     * Convenience method for a message with two arguments.<p>
096     *
097     * @param key the message key to use
098     * @param arg0 the first message argument
099     * @param arg1 the second message argument
100     * @return a message container for this package with the given arguments
101     */
102    CmsMessageContainer container(String key, Object arg0, Object arg1);
103
104    /**
105     * Creates a message container for this package with the given arguments.<p>
106     *
107     * Convenience method for a message with three arguments.<p>
108     *
109     * @param key the message key to use
110     * @param arg0 the first message argument
111     * @param arg1 the second message argument
112     * @param arg2 the third message argument
113     *
114     * @return a message container for this package with the given arguments
115     */
116    CmsMessageContainer container(String key, Object arg0, Object arg1, Object arg2);
117
118    /**
119     * Creates a message container for this package with the given arguments.<p>
120     *
121     * @param key the message key to use
122     * @param args the message arguments to use
123     * @return a message container for this package with the given arguments
124     */
125    CmsMessageContainer container(String key, Object[] args);
126
127    /**
128     * Returns the localized message bundle wrapped in this instance initialized with the OpenCms default locale.<p>
129     *
130     * This should be used only for logging and system output, not for generating GUI messages that the
131     * user can see. In this case, use {@link #getBundle(Locale)}.<p>
132     *
133     * @return the localized message bundle wrapped in this instance initialized with the OpenCms default locale
134     */
135    CmsMessages getBundle();
136
137    /**
138     * Returns the localized message bundle wrapped in this instance initialized with the provided locale.<p>
139     *
140     * @param locale the locale to use
141     *
142     * @return the localized message bundle wrapped in this instance initialized with the provided locale
143     */
144    CmsMessages getBundle(Locale locale);
145
146    /**
147     * Returns the bundle name for this OpenCms package.<p>
148     *
149     * @return the bundle name for this OpenCms package
150     */
151    String getBundleName();
152}