/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
package org.hibernate.boot.registry.selector.spi;

import java.util.Collection;
import java.util.concurrent.Callable;

import org.hibernate.service.Service;

Service which acts as a registry for named strategy implementations.

Strategies are more open ended than services, though a strategy managed here might very well also be a service.  The
strategy is any interface that has multiple, (possibly short) named implementations.
 StrategySelector manages resolution of particular implementation by (possibly short) name via the selectStrategyImplementor method, which is the main contract here. As indicated in the docs of that method the given name might be either a short registered name or the implementation FQN. As an example, consider resolving the TransactionCoordinatorBuilder implementation to use. To use the JDBC-based TransactionCoordinatorBuilder the passed name might be either "jdbc" or "org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorBuilderImpl" (which is the FQN). 
 Strategy implementations can be managed by registerStrategyImplementor and unRegisterStrategyImplementor. Originally designed to help the OSGi use case, though no longer used there. 
 The service also exposes a general typing API via resolveStrategy and resolveDefaultableStrategy which accept implementation references rather than implementation names, allowing for a multitude of interpretations of said "implementation reference". See the docs for resolveDefaultableStrategy for details. 
Author:
Steve Ebersole/**
 * Service which acts as a registry for named strategy implementations.
 * <p/>
 * Strategies are more open ended than services, though a strategy managed here might very well also be a service.  The
 * strategy is any interface that has multiple, (possibly short) named implementations.
 * <p/>
 * StrategySelector manages resolution of particular implementation by (possibly short) name via the
 * {@link #selectStrategyImplementor} method, which is the main contract here.  As indicated in the docs of that
 * method the given name might be either a short registered name or the implementation FQN.  As an example, consider
 * resolving the {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder} implementation to use.  To use the
 * JDBC-based TransactionCoordinatorBuilder the passed name might be either {@code "jdbc"} or
 * {@code "org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorBuilderImpl"} (which is the FQN).
 * <p/>
 * Strategy implementations can be managed by {@link #registerStrategyImplementor} and
 * {@link #unRegisterStrategyImplementor}.  Originally designed to help the OSGi use case, though no longer used there.
 * <p/>
 * The service also exposes a general typing API via {@link #resolveStrategy} and {@link #resolveDefaultableStrategy}
 * which accept implementation references rather than implementation names, allowing for a multitude of interpretations
 * of said "implementation reference".  See the docs for {@link #resolveDefaultableStrategy} for details.
 *
 * @author Steve Ebersole
 */
public interface StrategySelector extends Service {
	
Registers a named implementor of a particular strategy contract.
Params:
strategy – The strategy contract.
name – The registration name
implementation – The implementation Class
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible./**
	 * Registers a named implementor of a particular strategy contract.
	 *
	 * @param strategy The strategy contract.
	 * @param name The registration name
	 * @param implementation The implementation Class
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 */
	<T> void registerStrategyImplementor(Class<T> strategy, String name, Class<? extends T> implementation);

	
Un-registers a named implementor of a particular strategy contract.  Un-registers all named registrations
for the given strategy contract naming the given class.
Params:
strategy – The strategy contract.
implementation – The implementation Class
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible./**
	 * Un-registers a named implementor of a particular strategy contract.  Un-registers all named registrations
	 * for the given strategy contract naming the given class.
	 *
	 * @param strategy The strategy contract.
	 * @param implementation The implementation Class
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 */
	<T> void unRegisterStrategyImplementor(Class<T> strategy, Class<? extends T> implementation);

	
Locate the named strategy implementation.
Params:
strategy – The type of strategy to be resolved.
name – The name of the strategy to locate; might be either a registered name or the implementation FQN.
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible.
Returns:
The named strategy implementation class./**
	 * Locate the named strategy implementation.
	 *
	 * @param strategy The type of strategy to be resolved.
	 * @param name The name of the strategy to locate; might be either a registered name or the implementation FQN.
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 *
	 * @return The named strategy implementation class.
	 */
	<T> Class<? extends T> selectStrategyImplementor(Class<T> strategy, String name);

	
Resolve strategy instances. See discussion on resolveDefaultableStrategy. Only difference is that here, the implied default value is null. 
Params:
strategy – The type (interface) of the strategy to be resolved.
strategyReference – The reference to the strategy for which we need to resolve an instance.
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible.
Returns:
The strategy instance/**
	 * Resolve strategy instances. See discussion on {@link #resolveDefaultableStrategy}.
	 * Only difference is that here, the implied default value is {@code null}.
	 *
	 * @param strategy The type (interface) of the strategy to be resolved.
	 * @param strategyReference The reference to the strategy for which we need to resolve an instance.
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 *
	 * @return The strategy instance
	 */
	<T> T resolveStrategy(Class<T> strategy, Object strategyReference);

	
Resolve strategy instances. The incoming reference might be:

    
 null - in which case defaultValue is returned. 
    

        An actual instance of the strategy type - it is returned, as is
    
    
 A reference to the implementation Class - an instance is created by calling Class.newInstance() (aka, the class's no-arg ctor). 
    
 The name of the implementation class - First the implementation's Class reference is resolved, and then an instance is created by calling Class.newInstance() 

Params:
strategy – The type (interface) of the strategy to be resolved.
strategyReference – The reference to the strategy for which we need to resolve an instance.
defaultValue – THe default value to use if strategyReference is null
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible.
Returns:
The strategy instance/**
	 * Resolve strategy instances. The incoming reference might be:<ul>
	 *     <li>
	 *         {@code null} - in which case defaultValue is returned.
	 *     </li>
	 *     <li>
	 *         An actual instance of the strategy type - it is returned, as is
	 *     </li>
	 *     <li>
	 *         A reference to the implementation {@link Class} - an instance is created by calling
	 *         {@link Class#newInstance()} (aka, the class's no-arg ctor).
	 *     </li>
	 *     <li>
	 *         The name of the implementation class - First the implementation's {@link Class} reference
	 *         is resolved, and then an instance is created by calling {@link Class#newInstance()}
	 *     </li>
	 * </ul>
	 *
	 * @param strategy The type (interface) of the strategy to be resolved.
	 * @param strategyReference The reference to the strategy for which we need to resolve an instance.
	 * @param defaultValue THe default value to use if strategyReference is null
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 *
	 * @return The strategy instance
	 */
	<T> T resolveDefaultableStrategy(Class<T> strategy, Object strategyReference, T defaultValue);

	
Resolve strategy instances. The incoming reference might be:

    
 null - in which case defaultValue is returned. 
    

        An actual instance of the strategy type - it is returned, as is
    
    
 A reference to the implementation Class - an instance is created by calling Class.newInstance() (aka, the class's no-arg ctor). 
    
 The name of the implementation class - First the implementation's Class reference is resolved, and then an instance is created by calling Class.newInstance() 

Params:
strategy – The type (interface) of the strategy to be resolved.
strategyReference – The reference to the strategy for which we need to resolve an instance.
defaultResolver – A strategy for resolving the default value strategyReference resolves to null.
Type parameters:
<T> – The type of the strategy.  Used to make sure that the strategy and implementation are type
compatible.
Returns:
The strategy instance/**
	 * Resolve strategy instances. The incoming reference might be:<ul>
	 *     <li>
	 *         {@code null} - in which case defaultValue is returned.
	 *     </li>
	 *     <li>
	 *         An actual instance of the strategy type - it is returned, as is
	 *     </li>
	 *     <li>
	 *         A reference to the implementation {@link Class} - an instance is created by calling
	 *         {@link Class#newInstance()} (aka, the class's no-arg ctor).
	 *     </li>
	 *     <li>
	 *         The name of the implementation class - First the implementation's {@link Class} reference
	 *         is resolved, and then an instance is created by calling {@link Class#newInstance()}
	 *     </li>
	 * </ul>
	 *
	 * @param strategy The type (interface) of the strategy to be resolved.
	 * @param strategyReference The reference to the strategy for which we need to resolve an instance.
	 * @param defaultResolver A strategy for resolving the default value strategyReference resolves to null.
	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
	 * compatible.
	 *
	 * @return The strategy instance
	 */
	<T> T resolveDefaultableStrategy(Class<T> strategy, Object strategyReference, Callable<T> defaultResolver);

	<T> T resolveStrategy(Class<T> strategy, Object strategyReference, Callable<T> defaultResolver, StrategyCreator<T> creator);

	<T> T resolveStrategy(Class<T> strategy, Object strategyReference, T defaultValue, StrategyCreator<T> creator);

	
Retrieve all of the registered implementors of the given strategy.  Useful
to allow defaulting the choice to the single registered implementor when
only one is registered
Returns:
The implementors. Should never return null/**
	 * Retrieve all of the registered implementors of the given strategy.  Useful
	 * to allow defaulting the choice to the single registered implementor when
	 * only one is registered
	 *
	 * @return The implementors.  Should never return {@code null}
	 */
	<T> Collection<Class<? extends T>> getRegisteredStrategyImplementors(Class<T> strategy);
}