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