1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_resource_XResourceBundle_idl__
28#define __com_sun_star_resource_XResourceBundle_idl__
29
30#ifndef __com_sun_star_container_XNameAccess_idl__
31#include <com/sun/star/container/XNameAccess.idl>
32#endif
33
34#ifndef __com_sun_star_lang_Locale_idl__
35#include <com/sun/star/lang/Locale.idl>
36#endif
37
38
39//=============================================================================
40
41module com { module sun { module star { module resource {
42
43//=============================================================================
44/** Resource bundles contain locale-specific objects.
45
46	<p>When your program needs a locale-specific resource, such as
47	<code>String</code> for example, your program can load it from the
48	resource bundle that is appropriate for the current user's locale. In
49	this way, you can write program code that is largely independent of
50	the user's locale, which isolates most, if not all, of the
51	locale-specific information in resource bundles.
52
53	<p>This allows you to write programs that can:
54
55	<UL type=SQUARE>
56
57	<LI> be easily localized, or translated, into different
58	languages.
59
60	<LI> handle multiple locales at once.
61
62	<LI> be easily modified, later, to support even more locales.
63
64	</UL>
65
66	<P> One resource bundle is, conceptually, a set of related services
67	that supports <code>XResourceBundle</code>. Each related service of
68	<code>XResourceBundle</code> has the same base name plus an
69	additional component that identifies its locale. For example, suppose
70	your resource bundle is named <code>MyResources</code>. The first
71	service you are likely to implement is the default resource bundle,
72	which has the same name as its family--<code>MyResources</code>. You
73	can also provide as many related locale-specific services as you need.
74
75	For example, perhaps you would provide a German one named
76	<code>MyResources_de</code>.
77
78	<P>
79	Each related implementation of <code>XResourceBundle</code> contains
80	the same items, but the items have been translated for the locale
81	represented by that <code>XResourceBundle</code> implementation. For
82	example, both <code>MyResources</code> and <code>MyResources_de</code>
83	may have a <code>String</code> that is used on a button for
84	confirming operations. In <code>MyResources</code> the
85	<code>String</code> may contain <code>OK</code> and in
86	<code>MyResources_de</code> it may contain <code>Gut</code>.
87
88	<P>
89	If there are different resources for different countries, you
90	can make specializations: for example, <code>MyResources_de_CH</code>
91	is the German language (de) in Switzerland (CH). If you only want to
92	modify some of the resources in the specialization, you can do so.
93
94	<P>
95	When your program needs a locale-specific object, it loads
96
97	the <code>XResourceBundle</code> implementation using the
98	<type>XResourceBundleLoader</type> service:
99
100	<listing>
101	XResourceBundle myResources = xLoader.getBundle("MyResources", currentLocale);
102	</listing>
103
104	<p>The first argument specifies the family name of the resource
105	bundle that contains the object in question. The second argument
106	indicates the desired locale. <code>getBundle</code> uses these two
107	arguments to construct the name of the <code>ResourceBundle</code>
108	subclass it should load according to the following specifications.
109
110	<P>The resource bundle lookup searches for services with various
111	suffixes on the basis of (1) the desired locale and (2) the current
112	default locale as returned by Locale.getDefault(), and (3) the root
113	resource bundle (baseclass), in the following order from lower-level
114	(more specific) to parent-level (less specific):
115	<p> baseclass + "_" + language1 + "_" + country1 + "_" + variant1
116	<BR> baseclass + "_" + language1 + "_" + country1
117	<BR> baseclass + "_" + language1
118	<BR> baseclass + "_" + language2 + "_" + country2 + "_" + variant2
119	<BR> baseclass + "_" + language2 + "_" + country2
120	<BR> baseclass + "_" + language2
121	<BR> baseclass
122
123	<P> For example, if the current default locale is <TT>en_US</TT>, the
124	locale that the caller is interested in is <TT>fr_CH</TT>, and the
125	resource bundle name is <TT>MyResources</TT>; resource bundle lookup
126	will search for the following services, in order:
127	<BR> <TT>MyResources_fr_CH
128	<BR> MyResources_fr
129	<BR> MyResources_en_US
130	<BR> MyResources_en
131	<BR> MyResources</TT>
132
133	<P> The result of the lookup is a service, but that service may be
134	backed by a property file on disk. If a lookup fails,
135	<code>getBundle()</code> throws a
136	<code>MissingResourceException</code>.
137
138	<P> The base service <strong>must</strong> be fully qualified (for
139	example, <code>myPackage::MyResources</code>, not just
140	<code>MyResources</code>).
141
142	<P> Resource bundles contain key/value pairs. The keys uniquely
143	identify a locale-specific object in the bundle. Here is an
144	example of a <code>XResourceBundle</code> implementation that contains
145	two key/value pairs:
146
147	<listing>
148	class MyResource extends com.sun.star.resource.XResourceBundle
149	{
150		// some queryInterface stuff
151		// ...
152		public final Object getDirectElement(String key)
153		{
154			if (key.equals("okKey")) return "Ok";
155			if (key.equals("cancelKey")) return "Cancel";
156			return null;
157		}
158	}
159	</listing>
160
161	<p>Keys are always <code>String</code>s. In this example, the keys
162	are <code>OkKey</code> and <code>CancelKey</code>. In the above
163	example, the values are also <code>String</code>s--<code>OK</code>
164	and <code>Cancel</code>--but they do not have to be. The values can
165	be any type of object.
166
167	<P> You retrieve an object from resource bundle using the appropriate
168	get method. Because <code>OkKey</code> and <code>CancelKey</code>
169	are both strings, you use <code>getByName</code> to retrieve them:
170
171	<listing>
172	button1 = new Button(myResourceBundle.getByName("OkKey").getString());
173	button2 = new Button(myResourceBundle.getByName("CancelKey").getString());
174	</listing>
175
176	<p>The get methods all require the key as an argument and return
177	the object if found. If the object is not found, the get methods
178	throw a <type scope="com::sun::star::container">NoSuchElementException</type>.
179
180	<P> <STRONG>NOTE:</STRONG> You should always supply a base service
181	with no suffixes. This will be the class of "last resort" if a
182	locale is requested that does not exist. In fact, you must provide
183	<I>all</I> of the services in any given inheritance chain for which
184	you provide a resource.  For example, if you provide
185	<TT>MyResources_fr_BE</TT>, you must provide <I>both</I>
186	<TT>MyResources</TT> <I>and</I> <TT>MyResources_fr</TT>, or the
187	resource bundle lookup will not work right.
188
189	<P>You do not have to restrict yourself to using a single family of
190	<code>ResourceBundle</code>s. For example, you could have a set of
191	bundles for exception messages, <code>ExceptionResources</code>
192	(<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...),
193	and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>,
194	<code>WidgetResources_de</code>, ...); breaking up the resources however you like.
195
196	@see		MissingResourceException
197	@see         Locale
198	@version     0.1 26 May 1999
199	@author      Mark Davis
200	@author      Markus Meyer
201	@deprecated	draft
202*/
203published interface XResourceBundle: com::sun::star::container::XNameAccess
204{
205	//-------------------------------------------------------------------------
206    /** contains the parent bundle of this bundle.
207
208		<p>The parent bundle is searched by the method
209		<method scope="com::sun::star::container">XNameAccess::getByName</method>
210		when this bundle does not contain a particular resource.
211     */
212    [attribute] XResourceBundle Parent;
213
214	//-------------------------------------------------------------------------
215	/** @returns
216		the locale for this resource bundle.
217
218		<p>This function can be used to determine whether the
219		resource bundle that is returned really corresponds to the
220		requested locale or is a fallback.
221
222	*/
223	com::sun::star::lang::Locale getLocale();
224
225	//-------------------------------------------------------------------------
226	/** @returns
227		an object from a resource bundle or NULL if no resource
228		exists.
229
230		<p>It does not look in the parents.
231
232		@param key
233			specifies the element.
234	*/
235	any getDirectElement( [in] string key );
236
237};
238
239//=============================================================================
240
241}; }; }; };
242
243#endif
244