http://java.net/projects/javamoney: JSR 354 provides an API for representing, transporting, and performing comprehensive calculations with Money and Currency. (JSR 354 - Expert Group)
  • Anatole Tresch (Credit Suisse)
  • Werner Keil
  • Thomas Hüsler (Espalier Technologies)
  • Otávio Santana
  • Simon Martinelli
  • Christopher Pheby
  • Jefferson Prestes
  • Jeremy Davies
  • Manuela Grindei
  • Benjamin Cotton
  • Stephen Colebourne
  • Greg Bakos
  • Tony Jewell
  • Rajmahendra Hegde (JUG Chennai)
  • Scott James
  • Matthias Buecker
  • Sanjay Nagpal
  • Mohamed Taman
  • Bob Lee
  • Arumugam Swaminathan 
/*
 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE CONDITION THAT YOU
 * ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT. PLEASE READ THE TERMS AND CONDITIONS OF THIS
 * AGREEMENT CAREFULLY. BY DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF
 * THE AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE" BUTTON AT THE
 * BOTTOM OF THIS PAGE. Specification: JSR-354 Money and Currency API ("Specification") Copyright
 * (c) 2012-2013, Credit Suisse All rights reserved.
 */
package javax.money;


Factory for MonetaryAmount instances for a given type. It can be accessed, by 

 Implementations of this interface allow to get MonetaryAmount instances providing different data as required: 
    

  • the CurrencyUnit, or the corresponding currency code (must be solvable by Monetary).
    • 

  • the number part
    • 

  • the MonetaryContext
    • 

  • by passing any MonetaryAmount instance, it is possible to convert an arbitrary amount implementation to the implementation provided by this factory. If the current factory cannot support the precision/scale as required by the current NumberValue a MonetaryException must be thrown.
    • 

 If not defined a default MonetaryContext is used, which can also be configured by adding configuration to a file /javamoney.properties to the classpath. 
 Hereby the entries. e.g. for a class MyMoney should start with a.b.MyMoney.ctx. The entries valid must be documented on the according implementation class, where the following entries are defined for all implementation types (example below given for a class a.b.MyMoney: 
    

  • a.b.MyMoney.ctx.precision to define the maximal supported precision.
    • 

  • a.b.MyMoney.ctx.maxScale to define the maximal supported scale.
    • 

  • a.b.MyMoney.ctx.fixedScale to define the scale to be fixed (constant).
    • 





Implementation specification
 Instances of this interface are not required to be
thread-safe!

Author:Anatole Tresch, Werner Keil
Version:0.6.1
/**
 * Factory for {@link MonetaryAmount} instances for a given type. It can be accessed, by
 * <ul>
 * <li>calling {@link MonetaryAmount#getFactory()}, returning a {@link MonetaryAmountFactory}
 * creating amounts of the same implementation type, which also provided the factory instance.</li>
 * <li>calling {@link Monetary#getAmountFactory(Class)} accessing a
 * {@link MonetaryAmountFactory} for a concrete type <code>Class<T></code>.</li>
 * <li>calling {@link Monetary#getDefaultAmountFactory()} accessing a default
 * {@link MonetaryAmountFactory}.
 * </ul>
 * <p>
 * Implementations of this interface allow to get {@link MonetaryAmount} instances providing
 * different data as required:
 * <ul>
 * <li>the {@link CurrencyUnit}, or the corresponding currency code (must be solvable by
 * {@link Monetary}).</li>
 * <li>the number part</li>
 * <li>the {@link MonetaryContext}</li>
 * <li>by passing any {@link MonetaryAmount} instance, it is possible to convert an arbitrary amount
 * implementation to the implementation provided by this factory. If the current factory cannot
 * support the precision/scale as required by the current {@link NumberValue} a
 * {@link MonetaryException} must be thrown.</li>
 * </ul>
 * If not defined a default {@link MonetaryContext} is used, which can also be configured by adding
 * configuration to a file {@code /javamoney.properties} to the classpath.
 * <p>
 * Hereby the entries. e.g. for a class {@code MyMoney} should start with {@code a.b.MyMoney.ctx}. The entries valid
 * must be documented
 * on the according implementation class, where the following entries are defined for all implementation types
 * (example below given for a class {@code a.b.MyMoney}:
 * <ul>
 * <li>{@code a.b.MyMoney.ctx.precision} to define the maximal supported precision.</li>
 * <li>{@code a.b.MyMoney.ctx.maxScale} to define the maximal supported scale.</li>
 * <li>{@code a.b.MyMoney.ctx.fixedScale} to define the scale to be fixed (constant).</li>
 * </ul>
 * <p>
 * <h2>Implementation specification</h2> Instances of this interface are <b>not</b> required to be
 * thread-safe!
 *
 * @author Anatole Tresch
 * @author Werner Keil
 * @version 0.6.1
 */
public interface MonetaryAmountFactory<T extends MonetaryAmount> {

    
Access the MonetaryAmount implementation type. 
Returns:the MonetaryAmount implementation type, never null.
/**
     * Access the {@link MonetaryAmount} implementation type.
     *
     * @return the {@link MonetaryAmount} implementation type, never {@code null}.
     */
    Class<? extends MonetaryAmount> getAmountType();

    
Sets the CurrencyUnit to be used. 
Params:
Throws:
Returns:This factory instance, for chaining.
/**
     * Sets the {@link CurrencyUnit} to be used.
     *
     * @param currencyCode the currencyCode of the currency to be used, not {@code null}. The currency code
     *                     will be resolved using {@link Monetary#getCurrency(String, String...)}.
     * @return This factory instance, for chaining.
     * @throws UnknownCurrencyException if the {@code currencyCode} is not resolvable.
     */
    default MonetaryAmountFactory<T> setCurrency(String currencyCode) {
        return setCurrency(Monetary.getCurrency(currencyCode));
    }

    
Sets the CurrencyUnit to be used. 
Params:
Returns:This factory instance, for chaining.
/**
     * Sets the {@link CurrencyUnit} to be used.
     *
     * @param currency the {@link CurrencyUnit} to be used, not {@code null}
     * @return This factory instance, for chaining.
     */
    MonetaryAmountFactory<T> setCurrency(CurrencyUnit currency);

    
Sets the number to be used.

Params:
  • number – the number to be used
Returns:This factory instance, for chaining.
/**
     * Sets the number to be used.
     *
     * @param number the number to be used
     * @return This factory instance, for chaining.
     */
    MonetaryAmountFactory<T> setNumber(double number);

    
Sets the number to be used.

Params:
  • number – the number to be used
Returns:This factory instance, for chaining.
/**
     * Sets the number to be used.
     *
     * @param number the number to be used
     * @return This factory instance, for chaining.
     */
    MonetaryAmountFactory<T> setNumber(long number);

    
Sets the number to be used.

Params:
  • number – the number to be used, not null.
Returns:This factory instance, for chaining.
/**
     * Sets the number to be used.
     *
     * @param number the number to be used, not {@code null}.
     * @return This factory instance, for chaining.
     */
    MonetaryAmountFactory<T> setNumber(Number number);

    
Get the maximum possible number that this type can represent. If the numeric model has no limitations on the numeric range, null should be returned. If MonetaryContext.getPrecision() returns a value > 0 this method is required to provide a maximal amount. 
Returns:the maximum possible number, or null.
/**
     * Get the maximum possible number that this type can represent. If the numeric model has no limitations on the
     * numeric range, null should be returned. If {@link MonetaryContext#getPrecision()} returns a value > 0 this
     * method is required to provide a maximal amount.
     *
     * @return the maximum possible number, or null.
     */
    NumberValue getMaxNumber();

    
Get the minimum possible number that this type can represent. If the numeric model has no limitations on the numeric range, null should be returned. If MonetaryContext.getPrecision() returns a value > 0 this method is required to provide a maximal amount. 
Returns:the minimum possible number, or null.
/**
     * Get the minimum possible number that this type can represent. If the numeric model has no limitations on the
     * numeric range, null should be returned.  If {@link MonetaryContext#getPrecision()} returns a value > 0 this
     * method is required to provide a maximal amount.
     *
     * @return the minimum possible number, or null.
     */
    NumberValue getMinNumber();

    
Sets the MonetaryContext to be used. 
Params:
Throws:
See Also:
Returns:This factory instance, for chaining.
/**
     * Sets the {@link MonetaryContext} to be used.
     *
     * @param monetaryContext the {@link MonetaryContext} to be used, not {@code null}.
     * @return This factory instance, for chaining.
     * @throws MonetaryException when the {@link MonetaryContext} given exceeds the capabilities supported by this
     *                           factory type.
     * @see #getMaximalMonetaryContext()
     */
    MonetaryAmountFactory<T> setContext(MonetaryContext monetaryContext);

    
Uses an arbitrary MonetaryAmount to initialize this factory. Properties reused are: 
    

  • CurrencyUnit,
    • 

  • Number value,
    • 

  • MonetaryContext.
    • 



Params:
  • amount – the amount to be used, not null.
Throws:
Returns:this factory instance, for chaining.
/**
     * Uses an arbitrary {@link MonetaryAmount} to initialize this factory. Properties reused are:
     * <ul>
     * <li>CurrencyUnit,</li>
     * <li>Number value,</li>
     * <li>MonetaryContext.</li>
     * </ul>
     *
     * @param amount the amount to be used, not {@code null}.
     * @return this factory instance, for chaining.
     * @throws MonetaryException when the {@link MonetaryContext} implied by {@code amount.getContext()}
     *                           exceeds the capabilities supported by this factory type.
     */
    default MonetaryAmountFactory<T> setAmount(MonetaryAmount amount) {
        setCurrency(amount.getCurrency());
        setNumber(amount.getNumber());
        setContext(amount.getContext());
        return this;
    }

    
Creates a new instance of MonetaryAmount, using the current data set on this factory. 
See Also:
Returns:the corresponding MonetaryAmount.
/**
     * Creates a new instance of {@link MonetaryAmount}, using the current data set on this factory.
     *
     * @return the corresponding {@link MonetaryAmount}.
     * @see #getAmountType()
     */
    T create();

    
Returns the default MonetaryContext used, when no MonetaryContext is provided. 
 The default context is not allowed to exceed the capabilities of the maximal MonetaryContext supported. 
See Also:
Returns:the default MonetaryContext, never null.
/**
     * Returns the default {@link MonetaryContext} used, when no {@link MonetaryContext} is
     * provided.
     * <p>
     * The default context is not allowed to exceed the capabilities of the maximal
     * {@link MonetaryContext} supported.
     *
     * @return the default {@link MonetaryContext}, never {@code null}.
     * @see #getMaximalMonetaryContext()
     */
    MonetaryContext getDefaultMonetaryContext();

    
Returns the maximal MonetaryContext supported, for requests that exceed these maximal capabilities, an ArithmeticException must be thrown. 
Returns:the maximal MonetaryContext supported, never null
/**
     * Returns the maximal {@link MonetaryContext} supported, for requests that exceed these maximal
     * capabilities, an {@link ArithmeticException} must be thrown.
     *
     * @return the maximal {@link MonetaryContext} supported, never {@code null}
     */
    default MonetaryContext getMaximalMonetaryContext() {
        return getDefaultMonetaryContext();
    }

}