// This Source Code is in the Public Domain per: http://unlicense.org
package org.litesoft.core;

import org.litesoft.commonfoundation.annotations.*;

import java.util.*;

public interface ClassToInstanceMapper {
    public interface NoInstanceFactory<T> {
        @NotNull Class<T> getFor();

        @NotNull T createInstance();
    }

    /**
     * Get all the currently "registered" Factories
     */
    @NotNull List<NoInstanceFactory<?>> getNoInstanceFactories();

    /**
     * @return current instance registered, or null
     */
    @Nullable <T> T checkGet( @NotNull Class<T> pClass );

    /**
     * Get the previously 'registered' (register &/ replaced) instance of pClass.
     * NOTE: if there is no instance currently registered, then one is attempted to be added using a previously registered NoInstanceFactory.
     *
     * @return instance of pClass
     *
     * @throws IllegalStateException    if no instance previously 'registered' for pClass
     */
    @NotNull <T> T get( @NotNull Class<T> pClass )
            throws IllegalStateException;

    /**
     * Register a Factory into this Mapper.
     *
     * This Factory is used to create an Instance (and register it) when "get" is called and no Instance is currently registered.
     * These factories can be copied into new ClassToInstanceMapper(s) so that a "singleton" instance exists "per" ClassToInstanceMapper.
     *
     * @throws IllegalStateException    if this is a duplicate Factory
     */
    void register( @NotNull NoInstanceFactory<?> pFactory )
            throws IllegalStateException;

    /**
     * Register an instance (pInstance) of pClass, that is NOT currently 'registered' (previously registered, but not subsequently removed)
     *
     * @throws IllegalStateException    if an instance for pClass IS currently 'registered'
     */
    <T, V extends T> void register( @NotNull Class<T> pClass, @NotNull V pInstance )
            throws IllegalStateException;

    /**
     * Register an instance (pInstance) of pClass, regardless of its current registered state.
     */
    <T, V extends T> void forceRegister( @NotNull Class<T> pClass, @NotNull V pInstance );

    /**
     * Remove the instance (pInstance) of pClass, that IS currently 'registered' (previously register &/ replaced, but not subsequently removed)
     *
     * @param pClass    !null
     * @param pInstance !null
     *
     * @throws IllegalArgumentException if either pClass or pInstance is null
     * @throws IllegalStateException    if pInstance of pClass is NOT currently 'registered' for pClass
     */
    <T, V extends T> void remove( @NotNull Class<T> pClass, V pInstance )
            throws IllegalArgumentException, IllegalStateException;

    void clearAllInstances();
}