I_CmsMessageBundle


1   /*
2    * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/i18n/I_CmsMessageBundle.java,v $
3    * Date   : $Date: 2006/03/27 14:53:01 $
4    * Version: $Revision: 1.7 $
5    *
6    * This library is part of OpenCms -
7    * the Open Source Content Mananagement System
8    *
9    * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10   *
11   * This library is free software; you can redistribute it and/or
12   * modify it under the terms of the GNU Lesser General Public
13   * License as published by the Free Software Foundation; either
14   * version 2.1 of the License, or (at your option) any later version.
15   *
16   * This library is distributed in the hope that it will be useful,
17   * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19   * Lesser General Public License for more details.
20   *
21   * For further information about Alkacon Software GmbH, please see the
22   * company website: http://www.alkacon.com
23   *
24   * For further information about OpenCms, please see the
25   * project website: http://www.opencms.org
26   * 
27   * You should have received a copy of the GNU Lesser General Public
28   * License along with this library; if not, write to the Free Software
29   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
30   */
31  
32  package org.opencms.i18n;
33  
34  import java.util.Locale  ;
35  
36  /**
37   * Utility interface for generating localized messages for internal OpenCms operations.<p>
38   * 
39   * Every OpenCms core packages should provide one class implementing this interface.
40   * This class should be called <code>Messages</code> and be a subclass of 
41   * <code>{@link org.opencms.i18n.A_CmsMessageBundle}</code>. Moreover, the implementation 
42   * should contain a <code>public static CmsMessageBundle#get()</code> method, that returns 
43   * an instance of the class. Also the implementation should contain public static members
44   * for all available localized keys.<p>
45   * 
46   * How to use localization in the OpenCms core:<p>
47   * 
48   * There are 3 main ulitiliy classes that deal with localization. These are<ul>
49   * 
50   * <li>{@link I_CmsMessageBundle} (all classes that implement this interface):
51   * These classes describe a pointer to a resource bundle, but without providing a {@link java.util.Locale}.
52   * So this is like a list of valid keys that can be localized, without the actual localization.</li>
53   * 
54   * <li>{@link org.opencms.i18n.CmsMessages}: This is a fully localized resource bundle, 
55   * with a list of keys and a {@link java.util.Locale} to localize these keys. If you have a {@link I_CmsMessageBundle},
56   * you can use {@link I_CmsMessageBundle#getBundleName()} to initialize a {@link org.opencms.i18n.CmsMessages} instance
57   * using {@link org.opencms.i18n.CmsMessages#CmsMessages(String, Locale)}.</li>
58   * 
59   * <li>{@link org.opencms.i18n.CmsMessageContainer}: In some circumstances, you do not have a {@link java.util.Locale},
60   * but you want to generate a message that contains certain parameters anyway. For example, in the deeper layers of the
61   * OpenCms core an issue may be generated, but you do not have a full user context available. The {@link org.opencms.i18n.CmsMessageContainer}
62   * contains a reference to a {@link I_CmsMessageBundle}, plus the name of the key to use in the bundle, plus a list of 
63   * (optional) parameters. This container is then passed "upwards" in the core until the GUI layer (usually the Workplace)
64   * is reached.</li>
65   * 
66   * <li>{@link org.opencms.i18n.CmsMultiMessages}: This is a convenience class that contains a set 
67   * of {@link org.opencms.i18n.CmsMessages}. A key lookup is automatically done in all the {@link org.opencms.i18n.CmsMessages} 
68   * instances contained in the multi message instance, and the first match is returned.</li>
69   * </ul>
70   * 
71   * @author Alexander Kandzior 
72   * 
73   * @version $Revision: 1.7 $ 
74   * 
75   * @since 6.0.0 
76   */
77  public interface I_CmsMessageBundle {
78  
79      /**
80       * Creates a message container for this package with the given arguments.<p>
81       * 
82       * Convenience method for a message with no arguments.<p>
83       * 
84       * @param key the message key to use
85       * @return a message container for this package with the given arguments
86       */
87      CmsMessageContainer container(String   key);
88  
89      /**
90       * Creates a message container for this package with the given arguments.<p>
91       * 
92       * Convenience method for a message with one argument.<p>
93       * 
94       * @param key the message key to use
95       * @param arg0 the message argument
96       * @return a message container for this package with the given arguments
97       */
98      CmsMessageContainer container(String   key, Object   arg0);
99  
100     /**
101      * Creates a message container for this package with the given arguments.<p>
102      * 
103      * Convenience method for a message with two arguments.<p>
104      * 
105      * @param key the message key to use
106      * @param arg0 the first message argument
107      * @param arg1 the second message argument
108      * @return a message container for this package with the given arguments
109      */
110     CmsMessageContainer container(String   key, Object   arg0, Object   arg1);
111 
112     /**
113      * Creates a message container for this package with the given arguments.<p>
114      * 
115      * Convenience method for a message with three arguments.<p>
116      * 
117      * @param key the message key to use
118      * @param arg0 the first message argument
119      * @param arg1 the second message argument
120      * @param arg2 the third message argument
121      * 
122      * @return a message container for this package with the given arguments
123      */
124     CmsMessageContainer container(String   key, Object   arg0, Object   arg1, Object   arg2);
125 
126     /**
127      * Creates a message container for this package with the given arguments.<p>
128      * 
129      * @param key the message key to use
130      * @param args the message arguments to use
131      * @return a message container for this package with the given arguments
132      */
133     CmsMessageContainer container(String   key, Object  [] args);
134 
135     /** 
136      * Returns the localized message bundle wrapped in this instance initialized with the OpenCms default locale.<p> 
137      * 
138      * This should be used only for logging and system output, not for generating GUI messages that the
139      * user can see. In this case, use {@link #getBundle(Locale)}.<p> 
140      * 
141      * @return the localized message bundle wrapped in this instance initialized with the OpenCms default locale
142      */
143     CmsMessages getBundle();
144 
145     /** 
146      * Returns the localized message bundle wrapped in this instance initialized with the provided locale.<p> 
147      * 
148      * @param locale the locale to use
149      * 
150      * @return the localized message bundle wrapped in this instance initialized with the provided locale
151      */
152     CmsMessages getBundle(Locale   locale);
153 
154     /**
155      * Returns the bundle name for this OpenCms package.<p>
156      * 
157      * @return the bundle name for this OpenCms package
158      */
159     String   getBundleName();
160 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags