offapi/com/sun/star/resource/XResourceBundle.idl

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