javax.money.spi.MonetaryAmountsSingletonQuerySpi Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of money-api-bp Show documentation

JSR 354 provides an API for representing, transporting, and performing comprehensive calculations with Money and Currency. This module provides a forward compatible backport of the API.

There is a newer version: 1.0.4

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.spi;

import javax.money.MonetaryAmount;
import javax.money.MonetaryAmountFactory;
import javax.money.MonetaryAmountFactoryQuery;
import java.util.Collection;

/**
 * SPI (core) for the backing implementation of the {@link javax.money.Monetary} singleton, implementing
 * the query functionality for amounts.
 *
 * @author Anatole Tresch
 */
public interface MonetaryAmountsSingletonQuerySpi {

    /**
     * Get the {@link javax.money.MonetaryAmountFactory} implementation class, that best matches to cover the given
     * {@link javax.money.MonetaryContext}.
     * 
     * The evaluation order should consider the following aspects:
     * 

     * If {@link javax.money.MonetaryContext#getAmountType()} is explicitly defined, it should be considered.
     * Nevertheless if precision/scale cannot be met, a {@link javax.money.MonetaryException} should
     * be thrown.
     * 
The remaining implementation class candidates must cover the required precision.
     * 
The remaining implementation class candidates must cover the required max scale.
     * 
If max scale is met, but {@code precision==0} (unlimited precision), the
     * {@link javax.money.MonetaryAmount} implementation candidate should be chosen with highest possible
     * precision.
     * 
If still multiple implementation candidates qualify, the ones with
     * {@code Flavor.PERFORMANCE} are preferred.
     * 
After this point the selection may be arbitrary.
     * 
     *
     * @return the {@link javax.money.MonetaryAmount} implementation class, that best matches to cover the given
     * {@link javax.money.MonetaryContext}, never {@code null}.
     * @throws javax.money.MonetaryException if no {@link javax.money.MonetaryAmount} implementation class can cover
     *                                       the required
     *                                       {@link javax.money.MonetaryContext}.
     */
    Collection> getAmountFactories(MonetaryAmountFactoryQuery query);

    /**
     * Checks if an {@link javax.money.MonetaryAmountFactory} is matching the given query.
     *
     * @param query the factory query, not null.
     * @return true, if at least one {@link javax.money.MonetaryAmountFactory} matches the query.
     */
    boolean isAvailable(MonetaryAmountFactoryQuery query);

    /**
     * Executes the query and returns the {@link javax.money.MonetaryAmount} implementation type found,
     * if there is only one type.
     * If multiple types match the query, the first one is selected.
     *
     * @param query the factory query, not null.
     * @return the type found, or null.
     */
    Class getAmountType(MonetaryAmountFactoryQuery query);

    /**
     * Executes the query and returns the {@link javax.money.MonetaryAmount} implementation types found.
     *
     * @param query the factory query, not null.
     * @return the type found, or null.
     */
    Collection> getAmountTypes(MonetaryAmountFactoryQuery query);

    /**
     * Executes the query and returns the {@link javax.money.MonetaryAmountFactory} implementation type found,
     * if there is only one type. If multiple types match the query, the first one is selected.
     *
     * @param query the factory query, not null.
     * @return the type found, or null.
     */
    MonetaryAmountFactory getAmountFactory(MonetaryAmountFactoryQuery query);

}