public class

FormatUtils

extends Object
java.lang.Object
   ↳ com.microstrategy.utils.FormatUtils

Class Overview

This class provides support for parsing and formatting different data types used in our application. Parsing and formatting for different locales is configurable via the configuration XML file. This is an utility class containing only static methods.

There are pairs of parse/format methods for each supported data type. The parse methods take the string and locale parameters and return proper data type. The format methods take a number or date object and locale and return formatted string. In all cases if configuration XML does not contain formatting information for requested locale and data type proper default format will be used.

The parseInteger and parseNumber methods shall be used for parsing numbers. The former accepts only integers while the later accepts both integers and fractional numbers.

There are several methods for parsing date and time data. The parseAnyDate method accepts strings representing date, time or date-time. It first uses date-time patterns, then date patterns and then time patterns. The parseDate, parseTime and parseDateTime methods accept only one kind of input.

The normalizeNumber and normalizeAnyDate methods can be used to produce "normalized" representation of input string. This representation is based on corresponding output pattern. Those methods recognize the kind of input string and produce corresponding output. For example if input string contains date without time the output string will also contain date without time.

The converNumber and convertAnyDate methods can be used to convert numbers or dates from one locale to another. There are two versions of each of this method. One that takes original string from-locale and to-locale and another that takes only original string and to-locale. The last one always converts into the standard (US) locale. All those methods recognize the kind of input string and produce corresponding output. For example if input string contains date without time the output string will also contain date without time.

The convertNumberPattern and convertDatePattern methods convert corresponding patterns from a specific locale into another one. There are two versions of each of this method. One that takes original pattern from-locale and to-locale and another that takes only original pattern and to-locale. The last one always converts into the standard (US) locale.

From 8.0, we introduce a child node "display" into each locale setting. The child text node of this node will define the desired format for diplaying different types of value in web page. When the "display" node is missing (either whole locale is missing, or just "display" node is missing), the output format define for the same locale will be used, except for date/time object. The default format for date and time is SHORT style for date and MEDIUM style for time. A set of display method will be used to formatting object according to the format defination in these "display" nodes.

Summary

Public Constructors
FormatUtils()
Public Methods
static String convertAnyDate(String str, Locale fromLoc, Locale toLoc)
Converts input string from fromLoc locale into toLoc locale.
static String convertAnyDate(String str, Locale fromLoc)
Converts input string from specified locale into default US locale.
static String convertBigDecimal(String str, Locale fromLoc, Locale toLoc)
Converts a big decimal string from fromLoc into toLoc.
static String convertNumber(String str, Locale fromLoc, Locale toLoc)
Converts input string from fromLoc locale into toLoc locale.
static String convertNumber(String str, Locale fromLoc)
Converts input string from specified locale into default US locale.
static String convertNumberPattern(String pattern, Locale fromLoc, Locale toLoc)
Converts number pattern from fromLoc into toLoc.
static String convertNumberPattern(String pattern, Locale fromLoc)
Converts number pattern from specified locale into default US locale.
static String displayDate(Date date, Locale loc)
Display a Date object using date DISPLAY format for specified locale
static String displayDateTime(Date date, Locale loc)
Displays a Date object using date-time DISPLAY format for specified locale
static String displayInteger(long number, Locale loc)
Formats a number using interger DISPLAY format for specified locale
static String displayNumber(double number, Locale loc)
Displays a number using number DISPLAY format for specified locale
static String displayTime(Date date, Locale loc)
Displays a Date object using time DISPLAY format for specified locale
static String formatDate(Date date, Locale loc)
Formats a Date object using date output format for specified locale
static String formatDateTime(Date date, Locale loc)
Formats a Date object using date-time output format for specified locale
static String formatInteger(long number, Locale loc)
Formats a number using integer output format for specified locale
static String formatNumber(Number number, Locale loc)
Formats a number using number output format for specified locale
static String formatNumber(double number, Locale loc)
Formats a number using number output format for specified locale
static String formatTime(Date date, Locale loc)
Formats a Date object using time output format for specified locale
static String getDateDisplayFormatPattern(Locale loc)
static List<String> getDateInputFormatPatterns(Locale loc)
static DateFormat getDateOutputFormat(Locale loc)
Returns DateFormat for specified locale.
static String getDateOutputFormatPattern(Locale loc)
static DateFormat getDateTimeDisplayFormat(Locale loc)
static String getFormatXML(Locale loc)
static List<String> getIntegerInputFormatPatterns(Locale loc)
static String getIntegerOutputFormatPattern(Locale loc)
static List<String> getNumberInputFormatPatterns(Locale loc)
static DecimalFormat getNumberOutputFormat(Locale loc)
static String getNumberOutputFormatPattern(Locale loc)
static String getSeparatorFormat(Locale loc)
static Set getSupportedLocales()
Returns a set containing supported locales.
static String getTimeDisplayFormatPattern(Locale loc)
static List<String> getTimeInputFormatPatterns(Locale loc)
static DateFormat getTimeOutputFormat(Locale loc)
static String getTimeOutputFormatPattern(Locale loc)
synchronized static void init(String filePath)
Re-initializes the class using configuration XML file.
static String normalizeAnyDate(String str, Locale loc)
Converts input string into standard format.
static String normalizeNumber(String str, Locale loc)
Converts input string into standard format.
static Date parseAnyDate(String str, Locale loc)
Parses input string using all available date patterns for specified locale.
static Date parseDate(String str, Locale loc)
Parses input string using date patterns for specified locale.
static Date parseDateTime(String str, Locale loc)
Parses input string using date-time patterns for specified locale.
static String parseInputForIServer(String input, int dataType, Locale loc)
Return a string representation of user input that can be appropriately handled by IServer
static Number parseInteger(String str, Locale loc)
Parses input string using integer patterns for specified locale.
static Number parseNumber(String str, Locale loc)
Parses input string using number patterns for specified locale.
static Date parseTime(String str, Locale loc)
Parses input string using time patterns for specified locale.
static boolean validateBigDecimal(String value, Locale locale)
Returns whether parseNumber(String, Locale) succeeded or not.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public FormatUtils ()

Public Methods

public static String convertAnyDate (String str, Locale fromLoc, Locale toLoc)

Converts input string from fromLoc locale into toLoc locale. First this method parses input string using fromLoc patterns then formats it using proper toLoc output format. This method recognizes the kind of input string. For example if input string contains date without time then the date output format will be used.

Parameters
str input string
fromLoc from locale
toLoc to locale
Returns
  • converted string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException if the input locale is null

public static String convertAnyDate (String str, Locale fromLoc)

Converts input string from specified locale into default US locale. First this method parses input string using fromLoc patterns then formats it using proper US locale output format. This method recognizes the kind of input string. For example if input string contains date without time then the date output format will be used.

Parameters
str input string
fromLoc from locale
Returns
  • converted string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException if the input locale is null

public static String convertBigDecimal (String str, Locale fromLoc, Locale toLoc)

Converts a big decimal string from fromLoc into toLoc. Conversion is done by replacing pattern symbols specific to fromLoc locale with corresponding symbols for toLoc locale.

Parameters
str big decimal pattern
fromLoc source locale
toLoc target locale
Returns
  • The converted big decimal string from fromLoc into toLoc.
Throws
IllegalArgumentException if the input locale is null

public static String convertNumber (String str, Locale fromLoc, Locale toLoc)

Converts input string from fromLoc locale into toLoc locale. First this method parses input string using fromLoc patterns then formats it using proper toLoc output format. This method recognizes the kind of input string, if it represents integer then integer output format will be used, otherwise the number output format will be used.

Parameters
str input string
fromLoc from locale
toLoc to locale
Returns
  • converted string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter fromLoc or toLoc is null.

public static String convertNumber (String str, Locale fromLoc)

Converts input string from specified locale into default US locale. First this method parses input string using fromLoc patterns then formats it using proper US locale output format. This method recognizes the kind of input string, if it represents integer then integer output format will be used, otherwise the number output format will be used.

Parameters
str input string
fromLoc from locale
Returns
  • converted string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static String convertNumberPattern (String pattern, Locale fromLoc, Locale toLoc)

Converts number pattern from fromLoc into toLoc. Conversion is done by replacing pattern symbols specific to fromLoc locale with corresponding symbols for toLoc locale.

Parameters
pattern input string
fromLoc from locale
toLoc to locale
Returns
  • converted string
Throws
IllegalArgumentException if the input locale is null

public static String convertNumberPattern (String pattern, Locale fromLoc)

Converts number pattern from specified locale into default US locale. Conversion is done by replacing pattern symbols specific to fromLoc locale with corresponding symbols for US locale.

Parameters
pattern input string
fromLoc from locale
Returns
  • converted string
Throws
IllegalArgumentException if the input locale is null

public static String displayDate (Date date, Locale loc)

Display a Date object using date DISPLAY format for specified locale

Parameters
date a date to be displayed
loc locale
Returns
  • formatted date string
Throws
IllegalArgumentException
IllegalArgumentException

public static String displayDateTime (Date date, Locale loc)

Displays a Date object using date-time DISPLAY format for specified locale

Parameters
date a date to be displayed in web page
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException
IllegalArgumentException

public static String displayInteger (long number, Locale loc)

Formats a number using interger DISPLAY format for specified locale

Parameters
number long a number to be displayed in web page
loc Locale
Returns
  • String formatted number string
Throws
IllegalArgumentException
IllegalArgumentException

public static String displayNumber (double number, Locale loc)

Displays a number using number DISPLAY format for specified locale

Parameters
number a number to be displayed in web page
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException
IllegalArgumentException

public static String displayTime (Date date, Locale loc)

Displays a Date object using time DISPLAY format for specified locale

Parameters
date a date to be displayed in web page
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException
IllegalArgumentException

public static String formatDate (Date date, Locale loc)

Formats a Date object using date output format for specified locale

Parameters
date a date to be formatted
loc locale
Returns
  • formatted date string
Throws
IllegalArgumentException

public static String formatDateTime (Date date, Locale loc)

Formats a Date object using date-time output format for specified locale

Parameters
date a date to be formatted
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException

public static String formatInteger (long number, Locale loc)

Formats a number using integer output format for specified locale

Parameters
number a number to be formatted
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException Thrown when input parameter loc is null.

public static String formatNumber (Number number, Locale loc)

Formats a number using number output format for specified locale

Parameters
number a Number object to be formatted
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException

public static String formatNumber (double number, Locale loc)

Formats a number using number output format for specified locale

Parameters
number a number to be formatted
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException

public static String formatTime (Date date, Locale loc)

Formats a Date object using time output format for specified locale

Parameters
date a date to be formatted
loc locale
Returns
  • formatted number string
Throws
IllegalArgumentException

public static String getDateDisplayFormatPattern (Locale loc)

public static List<String> getDateInputFormatPatterns (Locale loc)

public static DateFormat getDateOutputFormat (Locale loc)

Returns DateFormat for specified locale.

Parameters
loc locale
Returns
  • DateFormat for the specified locale.

public static String getDateOutputFormatPattern (Locale loc)

public static DateFormat getDateTimeDisplayFormat (Locale loc)

public static String getFormatXML (Locale loc)

public static List<String> getIntegerInputFormatPatterns (Locale loc)

public static String getIntegerOutputFormatPattern (Locale loc)

public static List<String> getNumberInputFormatPatterns (Locale loc)

public static DecimalFormat getNumberOutputFormat (Locale loc)

public static String getNumberOutputFormatPattern (Locale loc)

public static String getSeparatorFormat (Locale loc)

public static Set getSupportedLocales ()

Returns a set containing supported locales.

Returns
  • set containing supported locales

public static String getTimeDisplayFormatPattern (Locale loc)

public static List<String> getTimeInputFormatPatterns (Locale loc)

public static DateFormat getTimeOutputFormat (Locale loc)

public static String getTimeOutputFormatPattern (Locale loc)

public static synchronized void init (String filePath)

Re-initializes the class using configuration XML file. (Original initialization is done in the static constructor).

Parameters
filePath input stream of configuration XML
Throws
WebUtilsException

public static String normalizeAnyDate (String str, Locale loc)

Converts input string into standard format. First this method parses input string then formats it using proper output format. This method recognizes the kind of input string. For example if input string contains date without time then the date output format will be used.

Parameters
str input string
loc locale
Returns
  • normalized string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static String normalizeNumber (String str, Locale loc)

Converts input string into standard format. First this method parses input string then formats it using proper output format. This method recognizes the kind of input string, if it represents integer then integer output format will be used, otherwise the number output format will be used.

Parameters
str input string
loc locale
Returns
  • normalized string
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static Date parseAnyDate (String str, Locale loc)

Parses input string using all available date patterns for specified locale. This method accepts any date string. First it tries parsing input string using date-time patterns, then using date patterns and then using time patterns. This process stops at first successfull try.

Parameters
str input string
loc locale
Returns
  • parsed number
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static Date parseDate (String str, Locale loc)

Parses input string using date patterns for specified locale. This method accepts dates without time.

Parameters
str input string
loc locale
Returns
  • parsed date
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static Date parseDateTime (String str, Locale loc)

Parses input string using date-time patterns for specified locale. This method accepts only date-time strings.

Parameters
str input string
loc locale
Returns
  • parsed date
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static String parseInputForIServer (String input, int dataType, Locale loc)

Return a string representation of user input that can be appropriately handled by IServer

Parameters
input String input
dataType int from EnumDSSXMLDataType
loc current session's number Locale
Returns
  • String containing value of input
Throws
ParseException

public static Number parseInteger (String str, Locale loc)

Parses input string using integer patterns for specified locale. This method accepts only integer numbers.

Parameters
str input string
loc locale
Returns
  • parsed number
Throws
ParseException if no one pattern accepted input string

public static Number parseNumber (String str, Locale loc)

Parses input string using number patterns for specified locale. This method accepts both decimal and fractional numbers.

Parameters
str input string
loc locale
Returns
  • parsed number
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static Date parseTime (String str, Locale loc)

Parses input string using time patterns for specified locale. This method accepts strings containing time only.

Parameters
str input string
loc locale
Returns
  • parsed number
Throws
ParseException if no one pattern accepted input string
IllegalArgumentException Thrown when input parameter loc is null.

public static boolean validateBigDecimal (String value, Locale locale)

Returns whether parseNumber(String, Locale) succeeded or not.

Parameters
value input string
locale locale
Returns