199 *
200 * <p>
201 * The implementation of a {@code ResourceBundle} subclass must be thread-safe
202 * if it's simultaneously used by multiple threads. The default implementations
203 * of the non-abstract methods in this class, and the methods in the direct
204 * known concrete subclasses {@code ListResourceBundle} and
205 * {@code PropertyResourceBundle} are thread-safe.
206 *
207 * <h3><a id="bundleprovider">Resource Bundles in Named Modules</a></h3>
208 *
209 * When resource bundles are deployed in named modules, the following
210 * module-specific requirements and restrictions are applied.
211 *
212 * <ul>
213 * <li>Code in a named module that calls {@link #getBundle(String, Locale)}
214 * will locate resource bundles in the caller's module (<em>caller module</em>).</li>
215 * <li>If resource bundles are deployed in named modules separate from
216 * the caller module, those resource bundles need to be loaded from service
217 * providers of {@link ResourceBundleProvider}. The caller module must declare
218 * "{@code uses}" and the service interface name is the concatenation of the
219 * package name of the base name, string "(@code .spi.}, the simple class
220 * name of the base name, and the string "{@code Provider}". The
221 * <em>bundle provider modules</em> containing resource bundles must
222 * declare "{@code provides}" with the service interface name and
223 * its implementation class name. For example, if the base name is
224 * "{@code com.example.app.MyResources}", the caller module must declare
225 * "{@code uses com.example.app.spi.MyResourcesProvider;}" and a module containing resource
226 * bundles must declare "{@code provides com.example.app.spi.MyResourcesProvider
227 * with com.example.app.internal.MyResourcesProviderImpl;}"
228 * where {@code com.example.app.internal.MyResourcesProviderImpl} is an
229 * implementation class of {@code com.example.app.spi.MyResourcesProvider}.</li>
230 * <li>If you want to use non-standard formats in named modules, such as XML,
231 * {@link ResourceBundleProvider} needs to be used.</li>
232 * <li>The {@code getBundle} method with a {@code ClassLoader} may not be able to
233 * find resource bundles using the given {@code ClassLoader} in named modules.
234 * The {@code getBundle} method with a {@code Module} can be used, instead.</li>
235 * <li>{@code ResourceBundle.Control} is <em>not</em> supported in named modules.
236 * If the {@code getBundle} method with a {@code ResourceBundle.Control} is called
237 * in a named module, the method will throw an {@code UnsupportedOperationException}.
238 * Any service providers of {@link ResourceBundleControlProvider} are ignored in
239 * named modules.
240 * </li>
241 * </ul>
242 *
243 * <h3><a id="RBP_support">ResourceBundleProvider Service Providers</a></h3>
244 *
245 * The {@code getBundle} factory methods load service providers of
246 * {@link ResourceBundleProvider}, if available, using {@link ServiceLoader}.
247 * The service type is designated by {@code package name + ".spi." + simple name +"Provider"}. For
248 * example, if the base name is "{@code com.example.app.MyResources}", the service
249 * type is {@code com.example.app.spi.MyResourcesProvider}.
250 * <p>
251 * In named modules, the loaded service providers for the given base name are
252 * used to load resource bundles. If no service provider is available, or if
253 * none of the service providers returns a resource bundle and the caller module
254 * doesn't have its own service provider, the {@code getBundle} factory method
255 * searches for resource bundles that are local in the caller module and that
256 * are visible to the class loader of the caller module. The resource bundle
257 * formats for local module searching are "java.class" and "java.properties".
258 *
259 * <h3>ResourceBundle.Control</h3>
260 *
261 * The {@link ResourceBundle.Control} class provides information necessary
262 * to perform the bundle loading process by the <code>getBundle</code>
263 * factory methods that take a <code>ResourceBundle.Control</code>
264 * instance. You can implement your own subclass in order to enable
265 * non-standard resource bundle formats, change the search strategy, or
266 * define caching parameters. Refer to the descriptions of the class and the
267 * {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}
907 */
908 @CallerSensitive
909 public static final ResourceBundle getBundle(String baseName,
910 Locale locale)
911 {
912 Class<?> caller = Reflection.getCallerClass();
913 return getBundleImpl(baseName, locale,
914 caller, getDefaultControl(caller, baseName));
915 }
916
917 /**
918 * Gets a resource bundle using the specified base name and the default locale
919 * on behalf of the specified module. This method is equivalent to calling
920 * <blockquote>
921 * <code>getBundle(baseName, Locale.getDefault(), module)</code>
922 * </blockquote>
923 *
924 * <p> Resource bundles in named modules may be encapsulated. When
925 * the resource bundle is loaded from a provider, the caller module
926 * must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
927 * to declare that the module uses implementations of {@code "baseName"Provider}.
928 * When the resource bundle is loaded from the specified module, it is
929 * subject to the encapsulation rules specified by
930 * {@link Module#getResourceAsStream Module.getResourceAsStream}.
931 *
932 * @param baseName the base name of the resource bundle,
933 * a fully qualified class name
934 * @param module the module for which the resource bundle is searched
935 * @throws NullPointerException
936 * if {@code baseName} or {@code module} is {@code null}
937 * @throws SecurityException
938 * if a security manager exists and the caller is not the specified
939 * module and doesn't have {@code RuntimePermission("getClassLoader")}
940 * @throws MissingResourceException
941 * if no resource bundle for the specified base name can be found in the
942 * specified module
943 * @return a resource bundle for the given base name and the default locale
944 * @since 9
945 * @spec JPMS
946 * @see ResourceBundleProvider
947 */
948 @CallerSensitive
949 public static ResourceBundle getBundle(String baseName, Module module) {
950 return getBundleFromModule(Reflection.getCallerClass(), module, baseName,
951 Locale.getDefault(),
952 getDefaultControl(module, baseName));
953 }
954
955 /**
956 * Gets a resource bundle using the specified base name and locale
957 * on behalf of the specified module.
958 *
959 * <p> Resource bundles in named modules may be encapsulated. When
960 * the resource bundle is loaded from a provider, the caller module
961 * must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
962 * to declare that the module uses implementations of {@code "baseName"Provider}.
963 * When the resource bundle is loaded from the specified module, it is
964 * subject to the encapsulation rules specified by
965 * {@link Module#getResourceAsStream Module.getResourceAsStream}.
966 *
967 * <p>
968 * If the given {@code module} is a named module, this method will
969 * load the service providers for {@link java.util.spi.ResourceBundleProvider}
970 * and also resource bundles that are local in the given module or that
971 * are visible to the class loader of the given module (refer to the
972 * <a href="#bundleprovider">Resource Bundles in Named Modules</a> section
973 * for details).
974 *
975 * <p>
976 * If the given {@code module} is an unnamed module, then this method is
977 * equivalent to calling {@link #getBundle(String, Locale, ClassLoader)
978 * getBundle(baseName, targetLocale, module.getClassLoader()} to load
979 * resource bundles that are visible to the class loader of the given
980 * unnamed module. Custom {@link java.util.spi.ResourceBundleControlProvider}
981 * implementations, if present, will only be invoked if the specified
982 * module is an unnamed module.
983 *
984 * @param baseName the base name of the resource bundle,
985 * a fully qualified class name
986 * @param targetLocale the locale for which a resource bundle is desired
987 * @param module the module for which the resource bundle is searched
988 * @throws NullPointerException
989 * if {@code baseName}, {@code targetLocale}, or {@code module} is
990 * {@code null}
991 * @throws SecurityException
992 * if a security manager exists and the caller is not the specified
993 * module and doesn't have {@code RuntimePermission("getClassLoader")}
994 * @throws MissingResourceException
995 * if no resource bundle for the specified base name and locale can
1054 }
1055
1056 /**
1057 * Gets a resource bundle using the specified base name, locale, and class
1058 * loader.
1059 *
1060 * <p>This method behaves the same as calling
1061 * {@link #getBundle(String, Locale, ClassLoader, Control)} passing a
1062 * default instance of {@link Control} unless another {@link Control} is
1063 * provided with the {@link ResourceBundleControlProvider} SPI. Refer to the
1064 * description of <a href="#modify_default_behavior">modifying the default
1065 * behavior</a>.
1066 *
1067 * <p><a id="default_behavior">The following describes the default
1068 * behavior</a>.
1069 *
1070 * <p>
1071 * Resource bundles in a named module are private to that module. If
1072 * the caller is in a named module, this method will find resource bundles
1073 * from the service providers of {@link java.util.spi.ResourceBundleProvider}
1074 * and also find resource bundles that are in the caller's module or
1075 * that are visible to the given class loader.
1076 * If the caller is in a named module and the given {@code loader} is
1077 * different than the caller's class loader, or if the caller is not in
1078 * a named module, this method will not find resource bundles from named
1079 * modules.
1080 *
1081 * <p><code>getBundle</code> uses the base name, the specified locale, and
1082 * the default locale (obtained from {@link java.util.Locale#getDefault()
1083 * Locale.getDefault}) to generate a sequence of <a
1084 * id="candidates"><em>candidate bundle names</em></a>. If the specified
1085 * locale's language, script, country, and variant are all empty strings,
1086 * then the base name is the only candidate bundle name. Otherwise, a list
1087 * of candidate locales is generated from the attribute values of the
1088 * specified locale (language, script, country and variant) and appended to
1089 * the base name. Typically, this will look like the following:
1090 *
1091 * <pre>
1092 * baseName + "_" + language + "_" + script + "_" + country + "_" + variant
1093 * baseName + "_" + language + "_" + script + "_" + country
1094 * baseName + "_" + language + "_" + script
1095 * baseName + "_" + language + "_" + country + "_" + variant
|
199 *
200 * <p>
201 * The implementation of a {@code ResourceBundle} subclass must be thread-safe
202 * if it's simultaneously used by multiple threads. The default implementations
203 * of the non-abstract methods in this class, and the methods in the direct
204 * known concrete subclasses {@code ListResourceBundle} and
205 * {@code PropertyResourceBundle} are thread-safe.
206 *
207 * <h3><a id="bundleprovider">Resource Bundles in Named Modules</a></h3>
208 *
209 * When resource bundles are deployed in named modules, the following
210 * module-specific requirements and restrictions are applied.
211 *
212 * <ul>
213 * <li>Code in a named module that calls {@link #getBundle(String, Locale)}
214 * will locate resource bundles in the caller's module (<em>caller module</em>).</li>
215 * <li>If resource bundles are deployed in named modules separate from
216 * the caller module, those resource bundles need to be loaded from service
217 * providers of {@link ResourceBundleProvider}. The caller module must declare
218 * "{@code uses}" and the service interface name is the concatenation of the
219 * package name of the base name, string "{@code .spi.}", the simple class
220 * name of the base name, and the string "{@code Provider}". The
221 * <em>bundle provider modules</em> containing resource bundles must
222 * declare "{@code provides}" with the service interface name and
223 * its implementation class name. For example, if the base name is
224 * "{@code com.example.app.MyResources}", the caller module must declare
225 * "{@code uses com.example.app.spi.MyResourcesProvider;}" and a module containing resource
226 * bundles must declare "{@code provides com.example.app.spi.MyResourcesProvider
227 * with com.example.app.internal.MyResourcesProviderImpl;}"
228 * where {@code com.example.app.internal.MyResourcesProviderImpl} is an
229 * implementation class of {@code com.example.app.spi.MyResourcesProvider}.</li>
230 * <li>If you want to use non-standard formats in named modules, such as XML,
231 * {@link ResourceBundleProvider} needs to be used.</li>
232 * <li>The {@code getBundle} method with a {@code ClassLoader} may not be able to
233 * find resource bundles using the given {@code ClassLoader} in named modules.
234 * The {@code getBundle} method with a {@code Module} can be used, instead.</li>
235 * <li>{@code ResourceBundle.Control} is <em>not</em> supported in named modules.
236 * If the {@code getBundle} method with a {@code ResourceBundle.Control} is called
237 * in a named module, the method will throw an {@code UnsupportedOperationException}.
238 * Any service providers of {@link ResourceBundleControlProvider} are ignored in
239 * named modules.
240 * </li>
241 * </ul>
242 *
243 * <h3><a id="RBP_support">ResourceBundleProvider Service Providers</a></h3>
244 *
245 * The {@code getBundle} factory methods load service providers of
246 * {@link ResourceBundleProvider}, if available, using {@link ServiceLoader}.
247 * The service type is designated by
248 * {@code <package name> + ".spi." + <simple name> + "Provider"}. For
249 * example, if the base name is "{@code com.example.app.MyResources}", the service
250 * type is {@code com.example.app.spi.MyResourcesProvider}.
251 * <p>
252 * In named modules, the loaded service providers for the given base name are
253 * used to load resource bundles. If no service provider is available, or if
254 * none of the service providers returns a resource bundle and the caller module
255 * doesn't have its own service provider, the {@code getBundle} factory method
256 * searches for resource bundles that are local in the caller module and that
257 * are visible to the class loader of the caller module. The resource bundle
258 * formats for local module searching are "java.class" and "java.properties".
259 *
260 * <h3>ResourceBundle.Control</h3>
261 *
262 * The {@link ResourceBundle.Control} class provides information necessary
263 * to perform the bundle loading process by the <code>getBundle</code>
264 * factory methods that take a <code>ResourceBundle.Control</code>
265 * instance. You can implement your own subclass in order to enable
266 * non-standard resource bundle formats, change the search strategy, or
267 * define caching parameters. Refer to the descriptions of the class and the
268 * {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}
908 */
909 @CallerSensitive
910 public static final ResourceBundle getBundle(String baseName,
911 Locale locale)
912 {
913 Class<?> caller = Reflection.getCallerClass();
914 return getBundleImpl(baseName, locale,
915 caller, getDefaultControl(caller, baseName));
916 }
917
918 /**
919 * Gets a resource bundle using the specified base name and the default locale
920 * on behalf of the specified module. This method is equivalent to calling
921 * <blockquote>
922 * <code>getBundle(baseName, Locale.getDefault(), module)</code>
923 * </blockquote>
924 *
925 * <p> Resource bundles in named modules may be encapsulated. When
926 * the resource bundle is loaded from a provider, the caller module
927 * must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
928 * to declare that the module uses implementations of
929 * {@code <package name> + ".spi." + <simple name> + "Provider"}.
930 * Otherwise, it will load the resource bundles that are local in the
931 * given module or that are visible to the class loader of the given module
932 * (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
933 * section for details).
934 * When the resource bundle is loaded from the specified module, it is
935 * subject to the encapsulation rules specified by
936 * {@link Module#getResourceAsStream Module.getResourceAsStream}.
937 *
938 * @param baseName the base name of the resource bundle,
939 * a fully qualified class name
940 * @param module the module for which the resource bundle is searched
941 * @throws NullPointerException
942 * if {@code baseName} or {@code module} is {@code null}
943 * @throws SecurityException
944 * if a security manager exists and the caller is not the specified
945 * module and doesn't have {@code RuntimePermission("getClassLoader")}
946 * @throws MissingResourceException
947 * if no resource bundle for the specified base name can be found in the
948 * specified module
949 * @return a resource bundle for the given base name and the default locale
950 * @since 9
951 * @spec JPMS
952 * @see ResourceBundleProvider
953 */
954 @CallerSensitive
955 public static ResourceBundle getBundle(String baseName, Module module) {
956 return getBundleFromModule(Reflection.getCallerClass(), module, baseName,
957 Locale.getDefault(),
958 getDefaultControl(module, baseName));
959 }
960
961 /**
962 * Gets a resource bundle using the specified base name and locale
963 * on behalf of the specified module.
964 *
965 * <p> Resource bundles in named modules may be encapsulated. When
966 * the resource bundle is loaded from a provider, the caller module
967 * must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
968 * to declare that the module uses implementations of
969 * {@code <package name> + ".spi." + <simple name> + "Provider"}.
970 * Otherwise, it will load the resource bundles that are local in the
971 * given module or that are visible to the class loader of the given module
972 * (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
973 * section for details).
974 * When the resource bundle is loaded from the specified module, it is
975 * subject to the encapsulation rules specified by
976 * {@link Module#getResourceAsStream Module.getResourceAsStream}.
977 *
978 * <p>
979 * If the given {@code module} is an unnamed module, then this method is
980 * equivalent to calling {@link #getBundle(String, Locale, ClassLoader)
981 * getBundle(baseName, targetLocale, module.getClassLoader()} to load
982 * resource bundles that are visible to the class loader of the given
983 * unnamed module. Custom {@link java.util.spi.ResourceBundleControlProvider}
984 * implementations, if present, will only be invoked if the specified
985 * module is an unnamed module.
986 *
987 * @param baseName the base name of the resource bundle,
988 * a fully qualified class name
989 * @param targetLocale the locale for which a resource bundle is desired
990 * @param module the module for which the resource bundle is searched
991 * @throws NullPointerException
992 * if {@code baseName}, {@code targetLocale}, or {@code module} is
993 * {@code null}
994 * @throws SecurityException
995 * if a security manager exists and the caller is not the specified
996 * module and doesn't have {@code RuntimePermission("getClassLoader")}
997 * @throws MissingResourceException
998 * if no resource bundle for the specified base name and locale can
1057 }
1058
1059 /**
1060 * Gets a resource bundle using the specified base name, locale, and class
1061 * loader.
1062 *
1063 * <p>This method behaves the same as calling
1064 * {@link #getBundle(String, Locale, ClassLoader, Control)} passing a
1065 * default instance of {@link Control} unless another {@link Control} is
1066 * provided with the {@link ResourceBundleControlProvider} SPI. Refer to the
1067 * description of <a href="#modify_default_behavior">modifying the default
1068 * behavior</a>.
1069 *
1070 * <p><a id="default_behavior">The following describes the default
1071 * behavior</a>.
1072 *
1073 * <p>
1074 * Resource bundles in a named module are private to that module. If
1075 * the caller is in a named module, this method will find resource bundles
1076 * from the service providers of {@link java.util.spi.ResourceBundleProvider}
1077 * if any. Otherwise, it will load the resource bundles that are visible to
1078 * the given {@code loader} (refer to the
1079 * <a href="#bundleprovider">Resource Bundles in Named Modules</a> section
1080 * for details).
1081 * If the caller is in a named module and the given {@code loader} is
1082 * different than the caller's class loader, or if the caller is not in
1083 * a named module, this method will not find resource bundles from named
1084 * modules.
1085 *
1086 * <p><code>getBundle</code> uses the base name, the specified locale, and
1087 * the default locale (obtained from {@link java.util.Locale#getDefault()
1088 * Locale.getDefault}) to generate a sequence of <a
1089 * id="candidates"><em>candidate bundle names</em></a>. If the specified
1090 * locale's language, script, country, and variant are all empty strings,
1091 * then the base name is the only candidate bundle name. Otherwise, a list
1092 * of candidate locales is generated from the attribute values of the
1093 * specified locale (language, script, country and variant) and appended to
1094 * the base name. Typically, this will look like the following:
1095 *
1096 * <pre>
1097 * baseName + "_" + language + "_" + script + "_" + country + "_" + variant
1098 * baseName + "_" + language + "_" + script + "_" + country
1099 * baseName + "_" + language + "_" + script
1100 * baseName + "_" + language + "_" + country + "_" + variant
|