/*
 * Copyright 2012-2016 Credit Suisse
 * Copyright 2018-2020 Werner Keil, Otavio Santana, Trivadis AG
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.money.spi;

import javax.money.*;
import java.util.Collection;
import java.util.List;
import java.util.Optional;
import java.util.Set;

This class models the accessor for rounding instances, modeled as MonetaryOperator. 

This class is thread-safe.
Author:
Anatole Tresch, Werner Keil/**
 * This class models the accessor for rounding instances, modeled as
 * {@link javax.money.MonetaryOperator}.
 * <p>
 * This class is thread-safe.
 *
 * @author Anatole Tresch
 * @author Werner Keil
 */
public interface MonetaryRoundingsSingletonSpi {

    
Allows to access the names of the current defined roundings.
Params:
providers – the providers and ordering to be used. By default providers and ordering as defined in
                 #getDefaultProviders is used.
Returns:
the set of custom rounding ids, never null./**
     * Allows to access the names of the current defined roundings.
     *
     * @param providers the providers and ordering to be used. By default providers and ordering as defined in
     *                  #getDefaultProviders is used.
     * @return the set of custom rounding ids, never {@code null}.
     */
    Set<String> getRoundingNames(String... providers);

    
Allows to access the names of the current registered rounding providers.
Returns:
the set of provider names, never null./**
     * Allows to access the names of the current registered rounding providers.
     *
     * @return the set of provider names, never {@code null}.
     */
    Set<String> getProviderNames();

    
Access a list of the currently registered default providers. The default providers are used, when
no provider names are passed by the caller.
See Also:
RoundingQueryBuilder
Returns:
the provider names in order, defining the provider chain. The default provider chain configured in javamoney.properties is used./**
     * Access a list of the currently registered default providers. The default providers are used, when
     * no provider names are passed by the caller.
     *
     * @return the provider names in order, defining the provider chain.
     * The default provider chain configured in {@code javamoney.properties} is used.
     * @see javax.money.RoundingQueryBuilder
     */
    List<String> getDefaultProviderChain();

    
Execute a query for MonetaryRounding. This allows to model more complex used cases, such as historic or special roundings. 
Params:
query – the query to be expected, not null.
Returns:
the roundings found, never null./**
     * Execute a query for {@link javax.money.MonetaryRounding}. This allows to model more complex used cases,
     * such as historic or special roundings.
     *
     * @param query the query to be expected, not null.
     * @return the roundings found, never null.
     */
    Collection<MonetaryRounding> getRoundings(RoundingQuery query);


    
Creates a MonetaryRounding that can be added as MonetaryOperator to chained calculations. The instance must lookup the concrete MonetaryRounding instance from the MonetaryRoundingsSingletonSpi based on the input MonetaryAmount's CurrencyUnit. 
Returns:
the (shared) default rounding instance./**
     * Creates a {@link MonetaryRounding} that can be added as {@link javax.money.MonetaryOperator} to
     * chained calculations. The instance must lookup the concrete
     * {@link javax.money.MonetaryRounding} instance from the {@link javax.money.spi.MonetaryRoundingsSingletonSpi}
     * based on the input {@link javax.money.MonetaryAmount}'s {@link javax.money.CurrencyUnit}.
     *
     * @return the (shared) default rounding instance.
     */
    MonetaryRounding getDefaultRounding();

    
Access a MonetaryRounding for rounding MonetaryAmount instances given a currency. 
Params:
currencyUnit – The currency, which determines the required precision. As RoundingMode, by default, RoundingMode.HALF_UP is sued.
providers –    the optional provider list and ordering to be used
Throws:
MonetaryException – if no such rounding could be provided.
Returns:
a new instance MonetaryOperator implementing the rounding, never null./**
     * Access a {@link javax.money.MonetaryRounding} for rounding {@link javax.money.MonetaryAmount}
     * instances given a currency.
     *
     * @param currencyUnit The currency, which determines the required precision. As
     *                     {@link java.math.RoundingMode}, by default, {@link java.math.RoundingMode#HALF_UP}
     *                     is sued.
     * @param providers    the optional provider list and ordering to be used
     * @return a new instance {@link javax.money.MonetaryOperator} implementing the
     * rounding, never {@code null}.
     * @throws MonetaryException if no such rounding could be provided.
     */
    default MonetaryRounding getRounding(CurrencyUnit currencyUnit, String... providers) {
        MonetaryRounding op =
                getRounding(RoundingQueryBuilder.of().setProviderNames(providers).setCurrency(currencyUnit).build());
        return Optional.ofNullable(op).orElseThrow(() -> new MonetaryException(
                "No rounding provided for CurrencyUnit: " + currencyUnit.getCurrencyCode()));
    }


    
Access a MonetaryRounding using the rounding name. 
Params:
roundingName – The rounding name, not null.
providers –    the optional provider list and ordering to be used
Throws:
IllegalArgumentException – if no such rounding is registered using a RoundingProviderSpi instance.
Returns:
the corresponding MonetaryOperator implementing the rounding, never null./**
     * Access a {@link javax.money.MonetaryRounding} using the rounding name.
     *
     * @param roundingName The rounding name, not null.
     * @param providers    the optional provider list and ordering to be used
     * @return the corresponding {@link javax.money.MonetaryOperator} implementing the
     * rounding, never {@code null}.
     * @throws IllegalArgumentException if no such rounding is registered using a
     *                                  {@link javax.money.spi.RoundingProviderSpi} instance.
     */
    default MonetaryRounding getRounding(String roundingName, String... providers) {
        MonetaryRounding op =
                getRounding(RoundingQueryBuilder.of().setProviderNames(providers).setRoundingName(roundingName).build());
        return Optional.ofNullable(op)
                .orElseThrow(() -> new MonetaryException("No rounding provided with rounding name: " + roundingName));
    }


    
Query a specific rounding with the given query. If multiple roundings match the query the first one is selected, since the query allows to determine the providers and their ordering by setting AbstractQuery.getProviderNames(). 
Params:
query – the rounding query, not null.
Returns:
the rounding found, or null, if no rounding matches the query./**
     * Query a specific rounding with the given query. If multiple roundings match the query the first one is
     * selected, since the query allows to determine the providers and their ordering by setting {@link
     * RoundingQuery#getProviderNames()}.
     *
     * @param query the rounding query, not null.
     * @return the rounding found, or null, if no rounding matches the query.
     */
    default MonetaryRounding getRounding(RoundingQuery query) {
        Collection<MonetaryRounding> roundings = getRoundings(query);
        if (roundings.isEmpty()) {
            return null;
        }
        return roundings.iterator().next();
    }

    
Checks if any MonetaryRounding is matching the given query. 
Params:
query – the rounding query, not null.
Returns:
true, if at least one rounding matches the query./**
     * Checks if any {@link javax.money.MonetaryRounding} is matching the given query.
     *
     * @param query the rounding query, not null.
     * @return true, if at least one rounding matches the query.
     */
    default boolean isRoundingAvailable(RoundingQuery query) {
        return !getRoundings(query).isEmpty();
    }

    
Checks if a MonetaryRounding is available given a roundingId. 
Params:
roundingId – The rounding identifier.
providers –  the providers and ordering to be used. By default providers and ordering as defined in
                  #getDefaultProviders is used.
Throws:
IllegalArgumentException – if no such rounding is registered using a RoundingProviderSpi instance.
Returns:
true, if a corresponding MonetaryRounding is available./**
     * Checks if a {@link MonetaryRounding} is available given a roundingId.
     *
     * @param roundingId The rounding identifier.
     * @param providers  the providers and ordering to be used. By default providers and ordering as defined in
     *                   #getDefaultProviders is used.
     * @return true, if a corresponding {@link javax.money.MonetaryRounding} is available.
     * @throws IllegalArgumentException if no such rounding is registered using a
     *                                  {@link RoundingProviderSpi} instance.
     */
    default boolean isRoundingAvailable(String roundingId, String... providers) {
        return isRoundingAvailable(
                RoundingQueryBuilder.of().setProviderNames(providers).setRoundingName(roundingId).build());
    }

    
Checks if a MonetaryRounding is available given a CurrencyUnit. 
Params:
currencyUnit – The currency, which determines the required precision. As RoundingMode, by default, RoundingMode.HALF_UP is used.
providers –    the providers and ordering to be used. By default providers and ordering as defined in
                    #getDefaultProviders is used.
Throws:
IllegalArgumentException – if no such rounding is registered using a RoundingProviderSpi instance.
Returns:
true, if a corresponding MonetaryRounding is available./**
     * Checks if a {@link MonetaryRounding} is available given a {@link javax.money.CurrencyUnit}.
     *
     * @param currencyUnit The currency, which determines the required precision. As {@link java.math.RoundingMode},
     *                     by default, {@link java.math.RoundingMode#HALF_UP} is used.
     * @param providers    the providers and ordering to be used. By default providers and ordering as defined in
     *                     #getDefaultProviders is used.
     * @return true, if a corresponding {@link javax.money.MonetaryRounding} is available.
     * @throws IllegalArgumentException if no such rounding is registered using a
     *                                  {@link RoundingProviderSpi} instance.
     */
    default boolean isRoundingAvailable(CurrencyUnit currencyUnit, String... providers) {
        return isRoundingAvailable(RoundingQueryBuilder.of().setProviderNames(providers).setCurrency(currencyUnit).build());
    }
}