/*
 * 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.MonetaryException;
import javax.money.format.AmountFormatQuery;
import javax.money.format.AmountFormatQueryBuilder;
import javax.money.format.MonetaryAmountFormat;
import java.util.*;

This interface models the singleton functionality of MonetaryFormats. 

Implementations of this interface must be thread-safe.
Author:
Anatole Tresch, Werner Keil/**
 * This interface models the singleton functionality of {@link javax.money.format.MonetaryFormats}.
 * <p>
 * Implementations of this interface must be thread-safe.
 *
 * @author Anatole Tresch
 * @author Werner Keil
 */
public interface MonetaryFormatsSingletonSpi {

    
Get all available locales. This equals to MonetaryAmountFormatProviderSpi.getAvailableLocales(). 
Params:
providers – The (optional) providers to be used, ordered correspondingly.
Returns:
all available locales, never null./**
     * Get all available locales. This equals to {@link MonetaryAmountFormatProviderSpi#getAvailableLocales()}.
     *
     * @param providers The (optional) providers to be used, ordered correspondingly.
     * @return all available locales, never {@code null}.
     */
    Set<Locale> getAvailableLocales(String... providers);

    
Access all MonetaryAmountFormat instances matching the given AmountFormatQuery. 
Params:
formatQuery – The format query defining the requirements of the formatter.
Returns:
the corresponding MonetaryAmountFormat instances, never null/**
     * Access all {@link javax.money.format.MonetaryAmountFormat} instances matching the given {@link javax.money.format
     * .AmountFormatQuery}.
     *
     * @param formatQuery The format query defining the requirements of the formatter.
     * @return the corresponding {@link javax.money.format.MonetaryAmountFormat} instances, never null
     */
    Collection<MonetaryAmountFormat> getAmountFormats(AmountFormatQuery formatQuery);

    
Get the names of the currently registered format providers.
Returns:
the provider names, never null./**
     * Get the names of the currently registered format providers.
     *
     * @return the provider names, never null.
     */
    Set<String> getProviderNames();

    
Get the default provider chain, identified by the unique provider names in order as evaluated and used.
Returns:
the default provider chain, never null./**
     * Get the default provider chain, identified by the unique provider names in order as evaluated and used.
     *
     * @return the default provider chain, never null.
     */
    List<String> getDefaultProviderChain();

    
Access an MonetaryAmountFormat given a AmountFormatQuery. 
Params:
formatQuery – The format query defining the requirements of the formatter.
Throws:
MonetaryException – if no registered MonetaryAmountFormatProviderSpi can provide a corresponding MonetaryAmountFormat instance.
Returns:
the corresponding MonetaryAmountFormat/**
     * Access an {@link javax.money.format.MonetaryAmountFormat} given a {@link javax.money.format
     * .AmountFormatQuery}.
     *
     * @param formatQuery The format query defining the requirements of the formatter.
     * @return the corresponding {@link javax.money.format.MonetaryAmountFormat}
     * @throws javax.money.MonetaryException if no registered {@link javax.money.spi
     *                                       .MonetaryAmountFormatProviderSpi} can provide a
     *                                       corresponding {@link javax.money.format.MonetaryAmountFormat} instance.
     */
    default MonetaryAmountFormat getAmountFormat(AmountFormatQuery formatQuery) {
        Collection<MonetaryAmountFormat> formats = getAmountFormats(formatQuery);
        if (formats.isEmpty()) {
            throw new MonetaryException("No MonetaryAmountFormat for AmountFormatQuery " + formatQuery);
        }
        return formats.iterator().next();
    }

    
Checks if a MonetaryAmountFormat is available given a AmountFormatQuery. 
Params:
formatQuery – The format query defining the requirements of the formatter.
Returns:
true, if a t least one MonetaryAmountFormat is matching the query./**
     * Checks if a {@link javax.money.format.MonetaryAmountFormat} is available given a {@link javax.money.format
     * .AmountFormatQuery}.
     *
     * @param formatQuery The format query defining the requirements of the formatter.
     * @return true, if a t least one {@link javax.money.format.MonetaryAmountFormat} is matching the query.
     */
    default boolean isAvailable(AmountFormatQuery formatQuery) {
        return !getAmountFormats(formatQuery).isEmpty();
    }

    
Checks if a MonetaryAmountFormat is available given a AmountFormatQuery. 
Params:
locale –  the target Locale, not null.
providers – The (optional) providers to be used, ordered correspondingly.
Returns:
true, if a t least one MonetaryAmountFormat is matching the query./**
     * Checks if a {@link javax.money.format.MonetaryAmountFormat} is available given a {@link javax.money.format
     * .AmountFormatQuery}.
     *
     * @param locale    the target {@link Locale}, not {@code null}.
     * @param providers The (optional) providers to be used, ordered correspondingly.
     * @return true, if a t least one {@link javax.money.format.MonetaryAmountFormat} is matching the query.
     */
    default boolean isAvailable(Locale locale, String... providers) {
        return isAvailable(AmountFormatQuery.of(locale, providers));
    }

    
Access the default MonetaryAmountFormat given a Locale. 
Params:
locale –  the target Locale, not null.
providers – The (optional) providers to be used, ordered correspondingly.
Throws:
MonetaryException – if no registered MonetaryAmountFormatProviderSpi can provide a corresponding MonetaryAmountFormat instance.
Returns:
the matching MonetaryAmountFormat/**
     * Access the default {@link MonetaryAmountFormat} given a {@link Locale}.
     *
     * @param locale    the target {@link Locale}, not {@code null}.
     * @param providers The (optional) providers to be used, ordered correspondingly.
     * @return the matching {@link MonetaryAmountFormat}
     * @throws MonetaryException if no registered {@link MonetaryAmountFormatProviderSpi} can provide a
     *                           corresponding {@link MonetaryAmountFormat} instance.
     */
    default MonetaryAmountFormat getAmountFormat(Locale locale, String... providers) {
        return getAmountFormat(AmountFormatQueryBuilder.of(locale).setProviderNames(providers).build());
    }

    
Access the default MonetaryAmountFormat given a Locale. 
Params:
formatName – the target format name, not null.
providers –  The (optional) providers to be used, ordered correspondingly.
Throws:
MonetaryException – if no registered MonetaryAmountFormatProviderSpi can provide a corresponding MonetaryAmountFormat instance.
Returns:
the matching MonetaryAmountFormat/**
     * Access the default {@link MonetaryAmountFormat} given a {@link Locale}.
     *
     * @param formatName the target format name, not {@code null}.
     * @param providers  The (optional) providers to be used, ordered correspondingly.
     * @return the matching {@link MonetaryAmountFormat}
     * @throws MonetaryException if no registered {@link MonetaryAmountFormatProviderSpi} can provide a
     *                           corresponding {@link MonetaryAmountFormat} instance.
     */
    default MonetaryAmountFormat getAmountFormat(String formatName, String... providers) {
        return getAmountFormat(AmountFormatQueryBuilder.of(formatName).setProviderNames(providers).build());
    }

}