javax.money.MonetaryAmountFactory Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of money-api Show documentation
JSR 354 provides an API for representing, transporting, and performing comprehensive calculations with Money and Currency.
There is a newer version: 1.1
Show newest version
/*
 * 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 {@link MonetaryAmount} instances for a given type. It can be accessed, by
 * 
 * calling {@link MonetaryAmount#getFactory()}, returning a {@link MonetaryAmountFactory}
 * creating amounts of the same implementation type, which also provided the factory instance.
 * calling {@link MonetaryAmounts#getAmountFactory(Class)} accessing a
 * {@link MonetaryAmountFactory} for a concrete type Class.
 * calling {@link MonetaryAmounts#getAmountFactory()} accessing a default
 * {@link MonetaryAmountFactory}.
 * 
 * 
 * Implementations of this interface allow to get {@link MonetaryAmount} instances providing
 * different data as required:
 * 

 * the {@link CurrencyUnit}, or the corresponding currency code (must be solvable by
 * {@link javax.money.MonetaryCurrencies}).
 * the number part
 * the {@link MonetaryContext}
 * 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.
 * 
 * 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.
 * 
 * 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}:
 * 
 * {@code a.b.MyMoney.ctx.precision} to define the maximal supported precision.
 * {@code a.b.MyMoney.ctx.maxScale} to define the maximal supported scale.
 * {@code 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!
 * 
 * @version 0.6.1
 * @author Anatole Tresch
 * @author Werner Keil
 */
public interface MonetaryAmountFactory {

	/**
	 * Access the {@link MonetaryAmount} implementation type.
	 * 
	 * @return the {@link MonetaryAmount} implementation type, never {@code null}.
	 */
	Class getAmountType();

	/**
	 * 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 MonetaryCurrencies#getCurrency(String)}.
	 * @throws UnknownCurrencyException
	 *             if the {@code currencyCode} is not resolvable.
	 * @return This factory instance, for chaining.
	 */
	MonetaryAmountFactory setCurrency(String currencyCode);

	/**
	 * 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 setCurrency(CurrencyUnit currency);

	/**
	 * Sets the number to be used.
	 * 
	 * @param number
	 *            the number to be used
	 * @return This factory instance, for chaining.
	 */
	MonetaryAmountFactory setNumber(double number);

	/**
	 * Sets the number to be used.
	 * 
	 * @param number
	 *            the number to be used
	 * @return This factory instance, for chaining.
	 */
	MonetaryAmountFactory setNumber(long number);

	/**
	 * Sets the number to be used.
	 * 
	 * @param number
	 *            the number to be used, not {@code null}.
	 * @return This factory instance, for chaining.
	 */
	MonetaryAmountFactory setNumber(Number number);

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

	/**
	 * Uses an arbitrary {@link MonetaryAmount} to initialize this factory. Properties reused are:
	 * 
	 * CurrencyUnit,
	 * Number value,
	 * MonetaryContext.
	 * 
	 * 
	 * @param amount
	 *            the amount to be used, not {@code null}.
	 * @throws MonetaryException
	 *             when the {@link MonetaryContext} implied by {@code amount.getMonetaryContext()}
	 *             exceeds the capabilities supported by this factory type.
	 * @return this factory instance, for chaining.
	 */
	MonetaryAmountFactory setAmount(MonetaryAmount amount);

	/**
	 * 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 {@link MonetaryContext} used, when no {@link MonetaryContext} is
	 * provided.
	 * 
	 * The default context is not allowed to exceed the capabilities of the maximal
	 * {@link MonetaryContext} supported.
	 * 
	 * @see #getMaximalMonetaryContext()
	 * @return the default {@link MonetaryContext}, never {@code null}.
	 */
	MonetaryContext getDefaultMonetaryContext();

	/**
	 * 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}
	 */
	MonetaryContext getMaximalMonetaryContext();

}