1.1 --- a/openide.util/src/org/openide/util/NbBundle.java Wed Jun 01 17:41:57 2005 +0000
1.2 +++ b/openide.util/src/org/openide/util/NbBundle.java Fri Jun 03 01:07:03 2005 +0000
1.3 @@ -10,6 +10,7 @@
1.4 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
1.5 * Microsystems, Inc. All Rights Reserved.
1.6 */
1.7 +
1.8 package org.openide.util;
1.9
1.10 import org.openide.ErrorManager;
1.11 @@ -38,7 +39,6 @@
1.12 import java.util.WeakHashMap;
1.13 import java.util.jar.Attributes;
1.14
1.15 -
1.16 /** Convenience class permitting easy loading of localized resources of various sorts.
1.17 * Extends the functionality of the default Java resource support, and interacts
1.18 * better with class loaders in a multiple-loader system.
1.19 @@ -51,10 +51,9 @@
1.20 * // Might also look in /com/mycom/Bundle_de.properties, etc.
1.21 * }
1.22 * </pre></code>
1.23 -*
1.24 -* @author Petr Hamernik, Jaroslav Tulach, Jesse Glick
1.25 */
1.26 public class NbBundle extends Object {
1.27 +
1.28 private static final boolean USE_DEBUG_LOADER = Boolean.getBoolean("org.openide.util.NbBundle.DEBUG"); // NOI18N
1.29 private static String brandingToken = null;
1.30
1.31 @@ -88,6 +87,11 @@
1.32 /** Set the current branding token.
1.33 * The permitted format, as a regular expression:
1.34 * <pre>/^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)*$/</pre>
1.35 + * <p class="nonnormative">
1.36 + * This is normally only called by NetBeans startup code and unit tests.
1.37 + * Currently the branding may be specified by passing the <code>--branding</code>
1.38 + * command-line option to the launcher.
1.39 + * </p>
1.40 * @param bt the new branding, or <code>null</code> to clear
1.41 * @throws IllegalArgumentException if in an incorrect format
1.42 */
1.43 @@ -96,9 +100,10 @@
1.44 brandingToken = bt;
1.45 }
1.46
1.47 - /** Get a localized file in the default locale with the default class loader.
1.48 + /**
1.49 + * Get a localized and/or branded file in the default locale with the default class loader.
1.50 * <p>Note that use of this call is similar to using the URL protocol <code>nbresloc</code>
1.51 - * (which is in fact implemented using the fuller form of the method).
1.52 + * (which may in fact be implemented using the fuller form of the method).
1.53 * <p>The extension may be null, in which case no final dot will be appended.
1.54 * If it is the empty string, the resource will end in a dot.
1.55 * @param baseName base name of file, as dot-separated path (e.g. <code>some.dir.File</code>)
1.56 @@ -114,7 +119,8 @@
1.57 return getLocalizedFile(baseName, ext, Locale.getDefault(), getLoader());
1.58 }
1.59
1.60 - /** Get a localized file with the default class loader.
1.61 + /**
1.62 + * Get a localized and/or branded file with the default class loader.
1.63 * @param baseName base name of file, as dot-separated path (e.g. <code>some.dir.File</code>)
1.64 * @param ext extension of file (or <code>null</code>)
1.65 * @param locale locale of file
1.66 @@ -129,7 +135,8 @@
1.67 return getLocalizedFile(baseName, ext, locale, getLoader());
1.68 }
1.69
1.70 - /** Get a localized file.
1.71 + /**
1.72 + * Get a localized and/or branded file.
1.73 * @param baseName base name of file, as dot-separated path (e.g. <code>some.dir.File</code>)
1.74 * @param ext extension of file (or <code>null</code>)
1.75 * @param locale locale of file
1.76 @@ -230,7 +237,8 @@
1.77 }
1.78 }
1.79
1.80 - /** Find a localized value for a given key and locale.
1.81 + /**
1.82 + * Find a localized and/or branded value for a given key and locale.
1.83 * Scans through a map to find
1.84 * the most localized match possible. For example:
1.85 * <p><code><PRE>
1.86 @@ -276,7 +284,8 @@
1.87 return null;
1.88 }
1.89
1.90 - /** Find a localized value for a given key in the default system locale.
1.91 + /**
1.92 + * Find a localized and/or branded value for a given key in the default system locale.
1.93 *
1.94 * @param table mapping from localized strings to objects
1.95 * @param key the key to look for
1.96 @@ -287,7 +296,8 @@
1.97 return getLocalizedValue(table, key, Locale.getDefault());
1.98 }
1.99
1.100 - /** Find a localized value in a JAR manifest.
1.101 + /**
1.102 + * Find a localized and/or branded value in a JAR manifest.
1.103 * @param attr the manifest attributes
1.104 * @param key the key to look for (case-insensitive)
1.105 * @param locale the locale to use
1.106 @@ -297,7 +307,8 @@
1.107 return (String) getLocalizedValue(attr2Map(attr), key.toString().toLowerCase(Locale.US), locale);
1.108 }
1.109
1.110 - /** Find a localized value in a JAR manifest in the default system locale.
1.111 + /**
1.112 + * Find a localized and/or branded value in a JAR manifest in the default system locale.
1.113 * @param attr the manifest attributes
1.114 * @param key the key to look for (case-insensitive)
1.115 * @return the value if found, else <code>null</code>
1.116 @@ -320,7 +331,7 @@
1.117 // ---- LOADING RESOURCE BUNDLES ----
1.118
1.119 /**
1.120 - * Get a resource bundle with the default class loader and locale.
1.121 + * Get a resource bundle with the default class loader and locale/branding.
1.122 * <strong>Caution:</strong> {@link #getBundle(Class)} is generally
1.123 * safer when used from a module as this method relies on the module's
1.124 * classloader to currently be part of the system classloader. The
1.125 @@ -338,7 +349,7 @@
1.126 }
1.127
1.128 /** Get a resource bundle in the same package as the provided class,
1.129 - * with the default locale and the class' own classloader.
1.130 + * with the default locale/branding and the class' own classloader.
1.131 * This is the usual style of invocation.
1.132 *
1.133 * @param clazz the class to take the package name from
1.134 @@ -368,9 +379,9 @@
1.135 }
1.136
1.137 /**
1.138 - * Get a resource bundle with the default class loader.
1.139 + * Get a resource bundle with the default class loader and branding.
1.140 * @param baseName bundle basename
1.141 - * @param locale the locale to use
1.142 + * @param locale the locale to use (but still uses {@link #getBranding default branding})
1.143 * @return the resource bundle
1.144 * @exception MissingResourceException if the bundle does not exist
1.145 */
1.146 @@ -381,7 +392,7 @@
1.147
1.148 /** Get a resource bundle the hard way.
1.149 * @param baseName bundle basename
1.150 - * @param locale the locale to use
1.151 + * @param locale the locale to use (but still uses {@link #getBranding default branding})
1.152 * @param loader the class loader to use
1.153 * @return the resource bundle
1.154 * @exception MissingResourceException if the bundle does not exist
1.155 @@ -592,7 +603,8 @@
1.156 // Helper methods to simplify localization of messages
1.157 //
1.158
1.159 - /** Finds a localized string in a bundle.
1.160 + /**
1.161 + * Finds a localized and/or branded string in a bundle.
1.162 * @param clazz the class to use to locate the bundle
1.163 * @param resName name of the resource to look for
1.164 * @return the string associated with the resource
1.165 @@ -603,7 +615,8 @@
1.166 return getBundle(clazz).getString(resName);
1.167 }
1.168
1.169 - /** Finds a localized string in a bundle and formats the message
1.170 + /**
1.171 + * Finds a localized and/or branded string in a bundle and formats the message
1.172 * by passing requested parameters.
1.173 *
1.174 * @param clazz the class to use to locate the bundle
1.175 @@ -618,7 +631,8 @@
1.176 return getMessage(clazz, resName, new Object[] { param1 });
1.177 }
1.178
1.179 - /** Finds a localized string in a bundle and formats the message
1.180 + /**
1.181 + * Finds a localized and/or branded string in a bundle and formats the message
1.182 * by passing requested parameters.
1.183 *
1.184 * @param clazz the class to use to locate the bundle
1.185 @@ -634,7 +648,8 @@
1.186 return getMessage(clazz, resName, new Object[] { param1, param2 });
1.187 }
1.188
1.189 - /** Finds a localized string in a bundle and formats the message
1.190 + /**
1.191 + * Finds a localized and/or branded string in a bundle and formats the message
1.192 * by passing requested parameters.
1.193 *
1.194 * @param clazz the class to use to locate the bundle
1.195 @@ -651,7 +666,8 @@
1.196 return getMessage(clazz, resName, new Object[] { param1, param2, param3 });
1.197 }
1.198
1.199 - /** Finds a localized string in a bundle and formats the message
1.200 + /**
1.201 + * Finds a localized and/or branded string in a bundle and formats the message
1.202 * by passing requested parameters.
1.203 *
1.204 * @param clazz the class to use to locate the bundle
1.205 @@ -676,10 +692,12 @@
1.206 return (c != null) ? c : ClassLoader.getSystemClassLoader();
1.207 }
1.208
1.209 - /** Get a list of all suffixes used to search for localized resources.
1.210 + /**
1.211 + * Get a list of all suffixes used to search for localized/branded resources.
1.212 * Based on the default locale and branding, returns the list of suffixes
1.213 * which various <code>NbBundle</code> methods use as the search order.
1.214 - * For example, you might get a sequence such as:
1.215 + * For example, when {@link #getBranding} returns <code>branding</code>
1.216 + * and the default locale is German, you might get a sequence such as:
1.217 * <ol>
1.218 * <li><samp>"_branding_de"</samp>
1.219 * <li><samp>"_branding"</samp>