001/*
002 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
003 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
004 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
005 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
006 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
007 * BUTTON AT THE BOTTOM OF THIS PAGE.
008 * 
009 * Specification: JSR-354 Money and Currency API ("Specification")
010 * 
011 * Copyright (c) 2012-2013, Credit Suisse All rights reserved.
012 */
013package org.javamoney.moneta.spi;
014
015import java.util.ServiceLoader;
016import java.util.Set;
017
018import javax.money.CurrencyUnit;
019import javax.money.MonetaryAdjuster;
020import javax.money.MonetaryAmount;
021
022/**
023 * This SPI allows to extends/override the roundings available for
024 * {@link CurrencyUnit}. The JSRs implementation already provides default
025 * roundings. By registering instances of this interface using the JDK
026 * {@link ServiceLoader}, the default behaviour can be overridden and extended,
027 * e.g. for supporting also special roundings.
028 * <p>
029 * Implementations of this interface must be
030 * <ul>
031 * <li>thread-safe
032 * <li>not require loading of other resources.
033 * </ul>
034 * If required, it is possible to implement this interface in a contextual way,
035 * e.g. providing different roundings depending on the current EE application
036 * context. Though in most cases rounding should be a general concept that does
037 * not require contextual handling.
038 * 
039 * @author Anatole Tresch
040 */
041public interface RoundingProviderSpi {
042
043        /**
044         * Access the current valid rounding for the given {@link CurrencyUnit}.
045         * <p>
046         * Instances of {@link MonetaryAdjuster} returned, must be thread safe and
047         * immutable.
048         * 
049         * @param currency
050         *            the currency for which a rounding operator should be obtained,
051         *            not {@code null}.
052         * @return the corresponding rounding instance, or {@code null}.
053         */
054        MonetaryAdjuster getRounding(CurrencyUnit currency);
055
056        /**
057         * Access the rounding for the given {@link CurrencyUnit}, that was valid at
058         * the given timestamp.
059         * <p>
060         * Instances of {@link MonetaryAdjuster} returned, must be thread safe and
061         * immutable.
062         * 
063         * @param currency
064         *            the currency for which a rounding operator should be obtained,
065         *            not {@code null}.
066         * @param timestamp
067         *            the target UTC timestamp, when the rounding should be valid.
068         * @return the corresponding rounding instance, or {@code null}.
069         */
070        MonetaryAdjuster getRounding(CurrencyUnit currency, long timestamp);
071
072        /**
073         * Access the current valid rounding for the given {@link CurrencyUnit}.
074         * <p>
075         * Instances of {@link MonetaryAdjuster} returned, must be thread safe and
076         * immutable.
077         * 
078         * @param currency
079         *            the currency for which a rounding operator should be obtained,
080         *            not {@code null}.
081         * @return the corresponding rounding instance, or {@code null}.
082         */
083        MonetaryAdjuster getCashRounding(CurrencyUnit currency);
084
085        /**
086         * Access the cash rounding for the given {@link CurrencyUnit}, that was
087         * valid at the given timestamp.
088         * <p>
089         * Instances of {@link MonetaryAdjuster} returned, must be thread safe and
090         * immutable.
091         * 
092         * @param currency
093         *            the currency for which a rounding operator should be obtained,
094         *            not {@code null}.
095         * @param timestamp
096         *            the target UTC timestamp, when the rounding should be valid.
097         * @return the corresponding rounding instance, or {@code null}.
098         */
099        MonetaryAdjuster getCashRounding(CurrencyUnit currency, long timestamp);
100
101        /**
102         * Access an {@link MonetaryAdjuster} for custom rounding
103         * {@link MonetaryAmount} instances.
104         * 
105         * @param customRounding
106         *            The customRounding identifier.
107         * @return the corresponding {@link MonetaryAdjuster} implementing the
108         *         rounding, or {@code null}.
109         */
110        MonetaryAdjuster getCustomRounding(String customRoundingId);
111
112        /**
113         * Access the ids of the custom roundigs defined by this provider.
114         * 
115         * @return the ids of the defined custom roundings, never {@code null}.
116         */
117        Set<String> getCustomRoundingIds();
118
119}