Package com.tuladb.currency

Class CurrencyCatalog

java.lang.Object
com.tuladb.currency.CurrencyCatalog
public final class CurrencyCatalog extends Object
Reads the canonical ISO 4217 catalog shipped with tuladb-core (config/currencies.json) and optionally merges a deployment override file. Provides alpha-3 / numeric / scale lookups for the HTTP boundary; the engine itself stays integer-only.

This loader is intentionally stdlib-only — no Jackson or external JSON dependency — so the tuladb-sdk/java artifact can stay zero-dep. The parser handles the well-known flat-array-of-flat-objects format we control; it is not a general-purpose JSON parser.

Override semantics mirror the Python loader: an override file may add new currencies (e.g. crypto / internal tokens) or replace the scale/name of an existing canonical entry, but may not reassign a numeric code to a different alpha-3.

  • Field Details

  • Constructor Details

  • Method Details

    • loadDefault

      public static CurrencyCatalog loadDefault()
      Load the catalog from the conventional location, applying any TULADB_CURRENCY_OVERRIDE file on top.

    • load

      public static CurrencyCatalog load(Path catalog, Path override)

    • applyOverride

      public void applyOverride(Currency entry)

    • get

      public Currency get(String code)

    • get

      public Currency get(int numeric)

    • numeric

      public int numeric(String code)

    • code

      public String code(int numeric)

    • scale

      public int scale(String code)

    • scale

      public int scale(int numeric)

    • useRegistry

      public CurrencyCatalog useRegistry(CurrencyScales scales)
      Take amount scales from the engine's currency registry instead of this catalog's file. Once set, amountDecimalToInt(java.lang.Object, java.lang.Object) and amountIntToDecimal(long, java.lang.Object) use the REGISTERED scale (cached by scales); a currency the engine does not know is a CurrencyNotRegisteredException, never the file's guess, and a numeric missing from the file is accepted if the engine has it. Without a registry the file scale is used, which can disagree with the engine for any unit not in ISO 4217 (or registered with another scale).
      Returns:
      this catalog

    • registry

      public CurrencyScales registry()
      The registry set by useRegistry(com.tuladb.currency.CurrencyScales), or null.

    • amountDecimalToInt

      public long amountDecimalToInt(Object value, Object currency)
      DASH-6: convert a human decimal amount to integer minor units using the currency's scale. Core stays integer-only; this is the boundary helper. Strings and BigDecimal follow the shared contract (contracts/amount-vectors.json, see Amounts.toMinor(String, int)): ASCII digits[.digits] only, never rounded, more fractional digits than the scale refused (trailing zeros included), int64 range. A refusal is an AmountFormatException carrying the contract's reason.

      Accepted: Long/Integer (taken as-is in minor units), BigDecimal, String like "12.50". Double/Float are REJECTED outright (binary-rounding hazard); pass a string or BigDecimal.

      Parameters:
      value - user-supplied amount
      currency - alpha-3 code or numeric (passed through normalize(Object)) for scale lookup
      Returns:
      integer minor units for the wire

    • amountIntToDecimal

      public BigDecimal amountIntToDecimal(long minorUnits, Object currency)
      DASH-6: inverse for display. Returns a BigDecimal at the currency's scale (e.g. BigDecimal("12.50") for USD when minorUnits=1250). For the contract's string form use Amounts.formatMinor(long, int).

    • containsNumeric

      public boolean containsNumeric(int numeric)

    • containsCode

      public boolean containsCode(String code)

    • size

      public int size()

    • all

      public List<Currency> all()

    • normalize

      public int normalize(Object value)
      Coerce a request-supplied currency value to its integer numeric. Alpha-3 strings are resolved via the catalog. Numerics (and numeric strings) are validated against the catalog as well — values not in the canonical list (or override) are rejected. Unknown values throw IllegalArgumentException.