javax.money.format

Interface MonetaryAmountFormat

All Superinterfaces:

MonetaryQuery<String>

public interface MonetaryAmountFormat
extends MonetaryQuery<String>

Formats instances of MonetaryAmount to a String or an Appendable.

To obtain a MonetaryAmountFormat for a specific locale, including the default locale, call MonetaryFormats.getAmountFormat(java.util.Locale, String...). More complex formatting scenarios can be implemented by registering instances of .MonetaryAmountFormatProviderSpi. The spi implementation creates new instances of MonetaryAmountFormat based on the styleId and (arbitrary) attributes passed within the AmountFormatContext.

In general, do prefer accessing MonetaryAmountFormat instances from the MonetaryFormats singleton, instead of instantiating implementations directly, since the MonetaryFormats factory method may return different subclasses or may implement contextual behaviour (in a EE context). If you need to customize the format object, do something like this:

 MonetaryAmountFormat f = MonetaryFormats.getInstance(loc);
 f.setStyle(f.getStyle().toBuilder().setPattern("###.##;(###.##)").build());
 

Special Values

Negative zero ("-0") should always parse to

• 0

Synchronization

Instances of this class are not required to be thread-safe. It is recommended to of separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

Example

 // Print out a number using the localized number, currency,
 // for each locale
 Locale[] locales = MonetaryFormats.getAvailableLocales();
 MonetaryAmount amount = ...;
 MonetaryAmountFormat form;
     System.out.println("FORMAT");
     for (int i = 0; i < locales.length; ++i) {
         if (locales[i].getCountry().length() == 0) {
            continue; // Skip language-only locales
         }
         System.out.print(locales[i].getDisplayName());
         form = MonetaryFormats.getInstance(locales[i]);
         System.out.print(": " + form.getStyle().getPattern());
         String myAmount = form.format(amount);
         System.out.print(" -> " + myAmount);
         try {
             System.out.println(" -> " + form.parse(form.format(myAmount)));
         } catch (ParseException e) {}
     }
 }
 

Method Summary

Modifier and Type	Method and Description
default String	format(MonetaryAmount amount) Formats the given MonetaryAmount to a String.
AmountFormatContext	getContext() The AmountFormatContext to be applied when a MonetaryAmount is formatted.
MonetaryAmount	parse(CharSequence text) Fully parses the text into an instance of MonetaryAmount.
void	print(Appendable appendable, MonetaryAmount amount) Formats the given MonetaryAmount to a Appendable.

Methods inherited from interface javax.money.MonetaryQuery

queryFrom

Method Detail

getContext

AmountFormatContext getContext()

The AmountFormatContext to be applied when a MonetaryAmount is formatted.

Returns:

the AmountFormatContext used, never null.

format

default String format(MonetaryAmount amount)

Formats the given MonetaryAmount to a String.

Parameters:

amount - the amount to format, not null

Returns:

the string printed using the settings of this formatter

Throws:

UnsupportedOperationException - if the formatter is unable to print

IllegalStateException - if an IO error occurs.

print

void print(Appendable appendable,
           MonetaryAmount amount)
    throws IOException

Formats the given MonetaryAmount to a Appendable.

Example implementations of Appendable are StringBuilder, StringBuffer or Writer. Note that StringBuilder and StringBuffer never throw an IOException.

Parameters:

appendable - the appendable to add to, not null

amount - the amount to print, not null

Throws:

UnsupportedOperationException - if the formatter is unable to print

IOException - if an IO error occurs, thrown by the appendable

MonetaryParseException - if there is a problem while parsing

parse

MonetaryAmount parse(CharSequence text)
              throws MonetaryParseException

Fully parses the text into an instance of MonetaryAmount.

The parse must complete normally and parse the entire text. If the parse completes without reading the entire length of the text, an exception is thrown. If any other problem occurs during parsing, an exception is thrown.

Additionally the effective implementation type returned can be determined by the MonetaryContext applied to the MonetaryAmountFormat. This formatter will call Monetary.getDefaultAmountType() and will use the result returned to access a corresponding MonetaryAmountFactory to of the instance returned.

Parameters:

text - the text to parse, not null

Returns:

the parsed value, never null

Throws:

UnsupportedOperationException - if the formatter is unable to parse

MonetaryParseException - if there is a problem while parsing