BenQ Mobile

javax.microedition.global
Class Formatter

java.lang.Object
  extended byjavax.microedition.global.Formatter

public final class Formatter
extends java.lang.Object

Creates locale-specific renditions of data items. The following data items are handled:

  • dates
  • times
  • number
  • percentages
  • currency amounts
  • It is also possible to construct messages that have ordered parameters. Formatting methods MUST NOT return null. If a formatting method cannot perform the requested formatting, the return value SHOULD be the empty string. This allows applications to check if the formatting succeeded by examining the length of the return string.

    Selected locale

    The locale used by the Formatter determines the formatting rules. The selected locale is either the value of the microedition.locale system property or the locale passed as a string parameter to the constructor.

    If the selected locale is null or the empty string, formatting is locale-neutral (see below). If the selected locale is non-null and non-empty, but the Formatter implementation does not support it, the constructors throw an UnsupportedLocaleException.

    If the selected locale is supported, the formatting is performed according to the rules of the locale. These rules are implementation-specific and are not exposed to application programmers.

    To find out which locales are supported in the implementation, call the getSupportedLocales() method.

    Date and time formatting styles

    This class defines a number of constants that determine the extent and style of the result when the formatDateTime method is called. The following styles are currently defined:

  • short date only
  • long date only
  • short time only
  • long time only
  • short date and time
  • long date and time
  • Mixed combinations (i.e. short date with long time and vice versa) are not supported. In styles with both date and time component are present their mutual depends on the locale.

    Locale neutral formatting

    In locale neutral formatting dates and times conform to the Internet date/time profile for the ISO 8601 standard as defined in RFC 3339. Numbers and currencies are formatted using Long.toString or Double.toString, and currency amounts have no currency symbol. In percentage formatting the Unicode character U+0025 PERCENT SIGN is appended to the formatted number.

    Locale neutral formatting is provided because the MIDP specification allows the microedition.locale system property to be null. In such cases constructing a formatter will use the locale-neutral values to avoid an exceptional condition. The application can also explicitly request locale-neutral behaviour by passing null as the locale.

    Copyright: Copyright (c) Siemens AG 2004 * ALL RIGHTS RESERVED

    Version:
    0.1
    Author:
    COM SWC 21 MAO

    Field Summary
    static int DATE_LONG
              Constant for the long date style.
    static int DATE_SHORT
              Constant for the short date style.
    static int DATETIME_LONG
              Constant for the short date and time style.
    static int DATETIME_SHORT
              Constant for the short date style.
    static int TIME_LONG
              Constant for the long time style.
    static int TIME_SHORT
              Constant for the short time style.
     
    Constructor Summary
    Formatter()
              Constructs a formatter based on the current locale, which is the value of the microedition.
    Formatter(java.lang.String locale)
              Constructs a formatter for the specified locale.
     
    Method Summary
     java.lang.String formatCurrency(double number)
              Formats a currency amount using locale-specific rules.
     java.lang.String formatCurrency(double number, java.lang.String currencyCode)
              Formats a currency amount using the locale-specific rules but using the symbol of the specified currency.
     java.lang.String formatDateTime(java.util.Calendar dateTime, int style)
              Formats a date/time instance using locale-specific rules.
    static java.lang.String formatMessage(java.lang.String template, java.lang.String[] params)
              Formats a message with a variable number of ordered parameters.
     java.lang.String formatNumber(double number)
              Formats a decimal number using locale-specific rules.
     java.lang.String formatNumber(double number, int decimals)
              Formats a decimal number using locale-specific rules, with the specified number of decimals.
     java.lang.String formatNumber(long number)
              Formats an integer using locale-specific rules.
     java.lang.String formatPercentage(float value, int decimals)
              Formats a percentage with the specified number of decimals using locale-specific rules.
     java.lang.String formatPercentage(long value)
              Formats a percentage using locale-specific rules.
     java.lang.String getLocale()
              Gets the locale of this formatter.
    static java.lang.String[] getSupportedLocales()
              Gets the list of the locales supported by the formatter, as an array of valid microedition.locale values.
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    DATE_SHORT

    public static final int DATE_SHORT
    Constant for the short date style.

    See Also:
    Constant Field Values

    DATE_LONG

    public static final int DATE_LONG
    Constant for the long date style.

    See Also:
    Constant Field Values

    TIME_SHORT

    public static final int TIME_SHORT
    Constant for the short time style.

    See Also:
    Constant Field Values

    TIME_LONG

    public static final int TIME_LONG
    Constant for the long time style.

    See Also:
    Constant Field Values

    DATETIME_SHORT

    public static final int DATETIME_SHORT
    Constant for the short date style.

    See Also:
    Constant Field Values

    DATETIME_LONG

    public static final int DATETIME_LONG
    Constant for the short date and time style.

    See Also:
    Constant Field Values
    Constructor Detail

    Formatter

    public Formatter()
              throws UnsupportedLocaleException
    Constructs a formatter based on the current locale, which is the value of the microedition. locale system property.

    If the system property value is null, locale neutral formatting rules are used. If the implementation does not support the current locale, an UnsupportedLocaleException is thrown.

    Throws:
    UnsupportedLocaleException - if the current locale is not supported by the implementation
    .

    Formatter

    public Formatter(java.lang.String locale)
              throws UnsupportedLocaleException
    Constructs a formatter for the specified locale.

    If the specified locale is null or the empty string, locale neutral formatting rules are used. If the implementation does not support the specified locale, an UnsupportedLocaleException is thrown.

    Parameters:
    locale - the locale identifier
    Throws:
    UnsupportedLocaleException - if the specified locale is not supported by the implementation locale is not valid according to the MIDP 2.0 specification
    Method Detail

    getLocale

    public java.lang.String getLocale()
    Gets the locale of this formatter. The return value is null if this Formatter is using locale-neutral formatting.

    Returns:
    the locale, or null if using locale-neutral formatting

    formatDateTime

    public java.lang.String formatDateTime(java.util.Calendar dateTime,
                                           int style)
                                    throws java.lang.IllegalArgumentException
    Formats a date/time instance using locale-specific rules. The style parameter determines the extent and style of the result.

    Parameters:
    dateTime - the date and time to format the formatting
    style - to use
    Returns:
    the date and/or time formatted as a string
    Throws:
    java.lang.IllegalArgumentException - if the style constant is not one of those defined in this class

    formatMessage

    public static java.lang.String formatMessage(java.lang.String template,
                                                 java.lang.String[] params)
                                          throws java.lang.IllegalArgumentException
    Formats a message with a variable number of ordered parameters. The template argument is a string that may contain placeholders for the parameters. The placeholders are of the form {n} or {nn} where n is a digit 0...9. This allows parameters numbered from 0 to 99. Leading zeros in parameter numbers below 10 are accepted. If there is only one parameter, it is specified as {0} (or {00}). The placeholders MAY occur in arbitrary order, and they determine the final order of the actual parameters in the result string. Not all parameters have to be used in the template, but any parameter MAY occur an arbitrary number of times

    The parameters are passed as an array of strings. This method does not actually format dates, times, and other data; the items must be already formatted and the strings placed in the parameter array. This method then performs a simple string substitution.

    If you need to include the { character in the template, it MUST be escaped using {{, so that it is not mistaken for the initial delimiter of a placeholder.

    The length of the params array determines the upper bound of the {nn} parameters in the template. If the template contains references to parameter numbers higher than params.length - 1, this method throws an IllegalArgumentException

    Parameters:
    template - - the string template
    params - - the parameters to insert
    Returns:
    the formatted message
    Throws:
    java.lang.IllegalArgumentException - - if the template refers to parameter numbers larger than params.length - 1 if the template or the parameter array is null

    formatCurrency

    public java.lang.String formatCurrency(double number)
    Formats a currency amount using locale-specific rules. This method assumes that the amount is in the locale's currency. The result uses the locale-specific decimal separator and may include grouping separators. This method does not perform any currency conversions based on exchange rates.

    Parameters:
    number - - the currency amount to format
    Returns:
    the formatted currency amount

    formatCurrency

    public java.lang.String formatCurrency(double number,
                                           java.lang.String currencyCode)
                                    throws java.lang.IllegalArgumentException
    Formats a currency amount using the locale-specific rules but using the symbol of the specified currency. The currency is specified using its ISO 4217 three-letter code, such as "USD", "EUR" or "GBP". If there is a currency symbol attached to the ISO 4217 code in the implementation, that symbol MUST be used instead of the locale's currency symbol. If the implementation does not provide a currency symbol for a given ISO 4217 code, the code MUST be used as such.

    The result MAY include a locale-specific decimal separator and grouping separators. The number of decimals is also locale-specific. This method MUST NOT perform any currency conversions based on exchange rates.

    Parameters:
    number - - the currency amount to format
    currencyCode - - the ISO 4217 currency code to use
    Returns:
    the formatted currency amount
    Throws:
    java.lang.IllegalArgumentException - - if the currencyCode is not a valid ISO 4217 code if currencyCode is null

    formatNumber

    public java.lang.String formatNumber(long number)
    Formats an integer using locale-specific rules. The result may include grouping separators.

    Parameters:
    number - - the number to format
    Returns:
    the formatted number

    formatNumber

    public java.lang.String formatNumber(double number)
    Formats a decimal number using locale-specific rules. The result includes a locale-specific decimal separator and may include grouping separators.

    Parameters:
    number - - the number to format.
    Returns:
    the formatted decimal number.

    formatNumber

    public java.lang.String formatNumber(double number,
                                         int decimals)
                                  throws java.lang.IllegalArgumentException
    Formats a decimal number using locale-specific rules, with the specified number of decimals. The result MAY include a locale-specific decimal separator and grouping separators.

    The number of decimals MUST be between 1 and 15. The formatted result MUST have exactly the specified number of decimals, even if some of the trailing digits are zeroes

    Parameters:
    number - - the number to format.
    decimals - - the number of decimals to use.
    Returns:
    the formatted decimal number
    Throws:
    java.lang.IllegalArgumentException - - if the number of decimals is not between 1 and 15, inclusive.

    formatPercentage

    public java.lang.String formatPercentage(long value)
    Formats a percentage using locale-specific rules. This method places the locale-specific percent sign at the correct position in relation to the number, with the appropriate amount of space (possibly none) between the sign and the number. Does not handle negative percentages.

    Parameters:
    value - long the value to be formatted
    Returns:
    the formatted percetage

    formatPercentage

    public java.lang.String formatPercentage(float value,
                                             int decimals)
                                      throws java.lang.IllegalArgumentException
    Formats a percentage with the specified number of decimals using locale-specific rules. This method places the locale-specific percent sign at the correct position in relation to the number, with the appropriate amount of space (possibly none) between the sign and the number. A percentage is expressed as a decimal number, with the value 0.0 interpreted as 0% and the value 1.0 as 100%. Percentages larger than 100% are expressed as values greater than 1.0. Negative percentages are allowed, and expressed as values smaller than 0.0. The percentage is rounded to the specified number of decimals. The number of decimals MUST be between 1 and 15. The formatted result MUST have exactly the specified number of decimals, even if some of the trailing digits are zeroes.

    Parameters:
    value - the percentage to format, expressed as a positive or negative number
    decimals - the number of decimals to use (1 <= decimals <= 15)
    Returns:
    the formatted percentage string
    Throws:
    java.lang.IllegalArgumentException

    getSupportedLocales

    public static java.lang.String[] getSupportedLocales()
    Gets the list of the locales supported by the formatter, as an array of valid microedition.locale values.

    If no locales are supported, the list is empty, but never null. As the value null is not technically a valid locale, but a special value to trigger locale-neutral formatting, it must not appear in the array.

    Returns:
    an array of strings containing the locale values.

    BenQ Mobile

    Copyright © 2006 BenQ Mobile GmbH & Co. OHG or respective copyright owner.
    All Rights Reserved.
    BenQ Corp. is a trademark licensee of Siemens AG.


    For further information about Mobility Toolkit (MTK) visit our Developer Portal.