Package org.apache.juneau.marshall

Enum Class CurrencyFormat

java.lang.Object
java.lang.Enum<CurrencyFormat>
org.apache.juneau.marshall.CurrencyFormat
All Implemented Interfaces:
Serializable, Comparable<CurrencyFormat>, Constable
public enum CurrencyFormat extends Enum<CurrencyFormat>
Supported wire formats for Currency values.

Used by MarshallingContext.Builder.currencyFormat(CurrencyFormat), Marshalled.currencyFormat(), MarshalledProp.currencyFormat(), and MarshalledConfig.currencyFormat() to control how Currency values are written to text-based wire formats.

The default is ISO_CODE which preserves the historical wire output (Currency.toString() / Currency.getCurrencyCode()).

Locale composability

SYMBOL and DISPLAY_NAME are locale-sensitive — they consult the supplied Locale (typically the MarshallingContext.getLocale() resolved through the MarshallingSession). ISO_CODE ignores the locale.

Round-trip caveat

Round-trip is strictly guaranteed only for ISO_CODE. SYMBOL parsing of a token like "$" could resolve to any of USD / CAD / AUD / MXN / HKD / SGD / NZD depending on the locale, and DISPLAY_NAME parsing is even less reliable ("Dollar" matches at least eight ISO codes). For machine-to-machine wires, prefer ISO_CODE.

Precedence (highest to lowest)
  1. @MarshalledProp(currencyFormat=…) on the bean property.
  2. @Marshalled(currencyFormat=…) on the bean class.
  3. @MarshalledConfig(currencyFormat=…) on @Rest-annotated classes / methods.
  4. Programmatic MarshallingContext.Builder.currencyFormat(CurrencyFormat).
  5. Environment variable MarshallingContext.currencyFormat.
  6. The default constant (ISO_CODE).
Parser leniency

Parsers SHALL try Currency.getInstance(String) first regardless of the parser-side CurrencyFormat setting — this handles the ISO_CODE shape unambiguously. For SYMBOL / DISPLAY_NAME, the parser falls back to a best-effort iterate-and-match scan against Currency.getAvailableCurrencies().

Binary serializers

Binary serializers (BSON / CBOR / MsgPack / Prototext / Parquet) emit a UTF-8 string regardless of this setting — there is no native Currency wire type in any supported binary format. The choice of ISO_CODE vs SYMBOL vs DISPLAY_NAME is purely about the textual content of that string.

  • Enum Constant Details

    • NOT_SET

      public static final CurrencyFormat NOT_SET
      Sentinel meaning "no value configured" — falls through to the next-higher precedence level.

    • ISO_CODE

      public static final CurrencyFormat ISO_CODE
      ISO 4217 currency code (the default).
      Example:

      USD EUR JPY

      Locale-independent. Round-trips through Currency.getInstance(String).

    • SYMBOL

      public static final CurrencyFormat SYMBOL
      Currency symbol per Currency.getSymbol(Locale).
      Example (locale en_US):

      $ € ¥

      Locale-sensitive. The symbol is resolved against the supplied locale. Round-trip is best-effort — "$" is shared by USD / CAD / AUD / MXN / HKD / SGD / NZD; the parser prefers the locale's default currency on ambiguity and throws when no match is found.

    • DISPLAY_NAME

      public static final CurrencyFormat DISPLAY_NAME
      Localized display name per Currency.getDisplayName(Locale).
      Example (locale en_US):

      US Dollar Euro Japanese Yen

      Locale-sensitive and even less round-trip-safe than SYMBOL. Use only for user-facing display contexts.

  • Method Details

    • values

      public static CurrencyFormat[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static CurrencyFormat valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • format

      public static String format(Currency value, CurrencyFormat format, Locale locale)
      Formats the specified Currency using this format.

      NOT_SET falls through to ISO_CODE. null locale is treated as Locale.ROOT.

      Parameters:
      value - The value to format. Can be null (returns null).
      format - The configured format. Can be null (treated as ISO_CODE).
      locale - The locale used by SYMBOL / DISPLAY_NAME. Can be null (treated as Locale.ROOT).
      Returns:
      The formatted wire representation, or null if value is null.

    • parse

      public static Currency parse(String value, CurrencyFormat format, Locale locale)
      Parses the specified wire value into a Currency.

      Lenient parsing — always tries Currency.getInstance(String) first (handles ISO_CODE unambiguously). For SYMBOL / DISPLAY_NAME the parser falls back to a best-effort iterate-and-match scan against Currency.getAvailableCurrencies(); when multiple currencies match a symbol, prefers the locale's default currency.

      Parameters:
      value - The wire value. Can be null or blank (returns null).
      format - The configured format hint. Can be null (treated as ISO_CODE).
      locale - The locale used to disambiguate SYMBOL / DISPLAY_NAME matches. Can be null (treated as Locale.ROOT).
      Returns:
      The parsed Currency, or null if value is null or blank.
      Throws:
      IllegalArgumentException - If the value cannot be resolved to a unique currency.

    • isNumeric

      public boolean isNumeric()
      Returns true if this format emits a numeric wire value.

      Always false — every constant emits a textual representation.

      Returns:
      false.