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

import java.util.*;

public interface ClassToInstanceMapper
{
    public interface NoInstanceFactory<T>
    {
        /**
         * @return !null
         */
        Class<T> getFor();

        /**
         * @return should probably not be null
         */
        T createInstance();
    }

    /**
     * Get a List (!null) of all the currently "set" Factories
     */
    List<NoInstanceFactory<?>> getNoInstanceFactories();

    /**
     * Set 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.
     *
     * @param pFactory !null
     *
     * @throws IllegalArgumentException if pFactory is null
     * @throws IllegalStateException    if this is a duplicate Factory
     */
    void setNoInstanceFactory( NoInstanceFactory<?> pFactory );

    /**
     * @param pClass !null
     *
     * @return null if not found or current instance set / replaced
     *
     * @throws IllegalArgumentException if pClass is null
     */
    <T> T checkGet( Class<T> pClass )
            throws IllegalArgumentException;

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

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

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

    /**
     * Remove the instance (pInstance) of pClass, that IS currently 'registered' (previously set &/ 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( Class<T> pClass, V pInstance )
            throws IllegalArgumentException, IllegalStateException;

    void clearAllInstances();
}