Java Doc for Locale.java in  » 6.0-JDK-Modules » j2me » java » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Create a Locale object using the constructors in this class:

 Locale(String language)
 Locale(String language, String country)
 Locale(String language, String country, String variant)
 

The country argument is a valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

The variant argument is a vendor or browser-specific code. For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might construct a locale with parameters for language, country and variant as: "es", "ES", "Traditional_WIN".

Because a Locale object is just an identifier for a region, no validity check is performed when you construct a Locale. If you want to see whether particular resources are available for the Locale you construct, you must query those resources. For example, ask the NumberFormat for the locales it supports using its getAvailableLocales method.
Note: When you ask for a resource for a particular locale, you get back the best available match, not necessarily precisely what you asked for. For more information, look at ResourceBundle .

The Locale class provides a number of convenient constants that you can use to create Locale objects for commonly used locales. For example, the following creates a Locale object for the United States:

 Locale.US
 

Once you've created a Locale you can query it for information about itself. Use getCountry to get the ISO Country Code and getLanguage to get the ISO Language Code. You can use getDisplayCountry to get the name of the country suitable for displaying to the user. Similarly, you can use getDisplayLanguage to get the name of the language suitable for displaying to the user. Interestingly, the getDisplayXXX methods are themselves locale-sensitive and have two versions: one that uses the default locale and one that uses the locale specified as an argument.

The Java 2 platform provides a number of classes that perform locale-sensitive operations. For example, the NumberFormat class formats numbers, currency, or percentages in a locale-sensitive manner. Classes such as NumberFormat have a number of convenience methods for creating a default object of that type. For example, the NumberFormat class provides these three convenience methods for creating a default NumberFormat object:

 NumberFormat.getInstance()
 NumberFormat.getCurrencyInstance()
 NumberFormat.getPercentInstance()
 

 NumberFormat.getInstance(myLocale)
 NumberFormat.getCurrencyInstance(myLocale)
 NumberFormat.getPercentInstance(myLocale)
 

Each class that performs locale-sensitive operations allows you to get all the available objects of that type. You can sift through these objects by language, country, or variant, and use the display names to present a menu to the user. For example, you can create a menu of all the collation objects suitable for a given language. Such classes must implement these three class methods:

 public static Locale[] getAvailableLocales()
 public static String getDisplayName(Locale objectLocale,
 Locale displayLocale)
 public static final String getDisplayName(Locale objectLocale)
 // getDisplayName will throw MissingResourceException if the locale
 // is not one of the available locales.
 

The Java Virtual Machine sets the default locale during startup based on the host environment.

NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. Locale's constructor recognizes both the new and the old codes for the languages whose codes have changed, but this function always returns the old code.

If there is a security manager, its checkPermission method is called with a PropertyPermission("user.language", "write") permission before the default locale is changed.

The Java Virtual Machine sets the default locale during startup based on the host environment.

The Java Virtual Machine sets the default locale during startup based on the host environment. It is used by many locale-sensitive methods if no locale is explicitly specified. It can be changed using the Locale.setDefault(java.util.Locale) setDefault method. the default locale for this instance of the Java Virtual Machine

language (country, variant)

language (country)

language (variant)

country (variant)

language

country

variant

language (country, variant)

language (country)

language (variant)

country (variant)

language

country

variant

NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. Locale's constructor recognizes both the new and the old codes for the languages whose codes have changed, but this function always returns the old code. If you want to check for a specific language whose code has changed, don't do

 if (locale.getLanguage().equals("he")
 ...
 

 if (locale.getLanguage().equals(new Locale("he", "", "").getLanguage())
 ...

If there is a security manager, its checkPermission method is called with a PropertyPermission("user.language", "write") permission before the default locale is changed.

The Java Virtual Machine sets the default locale during startup based on the host environment. It is used by many locale-sensitive methods if no locale is explicitly specified.

Since changing the default locale may affect many different areas of functionality, this method should only be used if the caller is prepared to reinitialize locale-sensitive code running within the same Java Virtual Machine, such as the user interface.
throws:
  SecurityException - if a security manager exists and itscheckPermission method doesn't allow the operation.
throws:
  NullPointerException - if newLocale is null
Parameters:
  newLocale - the new default locale
See Also:   SecurityManager.checkPermission
See Also:   java.util.PropertyPermission