HHH-8159 - Apply fixups indicated by analysis tools

hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java

@@ -26,8 +26,11 @@ package org.hibernate.boot.registry;
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * Specialization of the {@link org.hibernate.service.ServiceRegistry} contract mainly to make the
+ * Provides the most basic services needed.  Class loading, etc.
- * {@link StandardServiceRegistryBuilder#StandardServiceRegistryBuilder(BootstrapServiceRegistry)} signature type-safe
+ *
+ * Specialized mainly for type safety.
+ *
+ * @see BootstrapServiceRegistryBuilder
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java

@@ -39,13 +39,15 @@ import org.hibernate.integrator.internal.IntegratorServiceImpl;
 import org.hibernate.integrator.spi.Integrator;
 
 /**
- * Builder for bootstrap {@link org.hibernate.service.ServiceRegistry} instances.
+ * Builder for {@link BootstrapServiceRegistry} instances.  Provides registry for services needed for
+ * most operations.  This includes {@link Integrator} handling and ClassLoader handling.
+ *
+ * Additionally responsible for building and managing the {@link org.hibernate.boot.registry.selector.spi.StrategySelector}
  *
  * @author Steve Ebersole
  * @author Brett Meyer
  *
- * @see BootstrapServiceRegistryImpl
+ * @see StandardServiceRegistryBuilder
- * @see StandardServiceRegistryBuilder#StandardServiceRegistryBuilder(org.hibernate.boot.registry.BootstrapServiceRegistry)
  */
 public class BootstrapServiceRegistryBuilder {
 	private final LinkedHashSet<Integrator> providedIntegrators = new LinkedHashSet<Integrator>();
@@ -53,12 +55,11 @@ public class BootstrapServiceRegistryBuilder {
 	private ClassLoaderService providedClassLoaderService;
 	private StrategySelectorBuilder strategySelectorBuilder = new StrategySelectorBuilder();
 	
-	
-
 	/**
 	 * Add an {@link Integrator} to be applied to the bootstrap registry.
 	 *
 	 * @param integrator The integrator to add.
+	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public BootstrapServiceRegistryBuilder with(Integrator integrator) {
@@ -67,7 +68,7 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Adds a provided {@link ClassLoader} for use in class-loading and resource-lookup
+	 * Adds a provided {@link ClassLoader} for use in class-loading and resource-lookup.
 	 *
 	 * @param classLoader The class loader to use
 	 *
@@ -82,9 +83,9 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Adds a provided {@link ClassLoaderService} for use in class-loading and resource-lookup
+	 * Adds a provided {@link ClassLoaderService} for use in class-loading and resource-lookup.
 	 *
-	 * @param classLoader The class loader to use
+	 * @param classLoaderService The class loader service to use
 	 *
 	 * @return {@code this}, for method chaining
 	 */
@@ -94,9 +95,10 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Applies the specified {@link ClassLoader} as the application class loader for the bootstrap registry
+	 * Applies the specified {@link ClassLoader} as the application class loader for the bootstrap registry.
 	 *
 	 * @param classLoader The class loader to use
+	 *
 	 * @return {@code this}, for method chaining
 	 *
 	 * @deprecated Use {@link #with(ClassLoader)} instead
@@ -108,9 +110,10 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Applies the specified {@link ClassLoader} as the resource class loader for the bootstrap registry
+	 * Applies the specified {@link ClassLoader} as the resource class loader for the bootstrap registry.
 	 *
 	 * @param classLoader The class loader to use
+	 *
 	 * @return {@code this}, for method chaining
 	 *
 	 * @deprecated Use {@link #with(ClassLoader)} instead
@@ -122,9 +125,10 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Applies the specified {@link ClassLoader} as the Hibernate class loader for the bootstrap registry
+	 * Applies the specified {@link ClassLoader} as the Hibernate class loader for the bootstrap registry.
 	 *
 	 * @param classLoader The class loader to use
+	 *
 	 * @return {@code this}, for method chaining
 	 *
 	 * @deprecated Use {@link #with(ClassLoader)} instead
@@ -136,9 +140,10 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Applies the specified {@link ClassLoader} as the environment (or system) class loader for the bootstrap registry
+	 * Applies the specified {@link ClassLoader} as the environment (or system) class loader for the bootstrap registry.
 	 *
 	 * @param classLoader The class loader to use
+	 *
 	 * @return {@code this}, for method chaining
 	 *
 	 * @deprecated Use {@link #with(ClassLoader)} instead
@@ -150,11 +155,13 @@ public class BootstrapServiceRegistryBuilder {
 	}
 
 	/**
-	 * Applies a named strategy implementation to the bootstrap registry
+	 * Applies a named strategy implementation to the bootstrap registry.
 	 *
 	 * @param strategy The strategy
 	 * @param name The registered name
 	 * @param implementation The strategy implementation Class
+	 * @param <T> Defines the strategy type and makes sure that the strategy and implementation are of
+	 * compatible types.
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -176,7 +183,7 @@ public class BootstrapServiceRegistryBuilder {
 	 * @see org.hibernate.boot.registry.selector.spi.StrategySelector#registerStrategyImplementor(Class, String, Class)
 	 */
 	@SuppressWarnings( {"UnusedDeclaration"})
-	public <T> BootstrapServiceRegistryBuilder withStrategySelectors(AvailabilityAnnouncer availabilityAnnouncer) {
+	public BootstrapServiceRegistryBuilder withStrategySelectors(AvailabilityAnnouncer availabilityAnnouncer) {
 		for ( Availability availability : availabilityAnnouncer.getAvailabilities() ) {
 			this.strategySelectorBuilder.addExplicitAvailability( availability );
 		}
@@ -200,7 +207,8 @@ public class BootstrapServiceRegistryBuilder {
             }
 			
 			classLoaderService = new ClassLoaderServiceImpl( classLoaders );
-		} else {
+		}
+		else {
 			classLoaderService = providedClassLoaderService;
 		}
 

hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceInitiator.java

@@ -30,7 +30,9 @@ import org.hibernate.service.spi.ServiceInitiator;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * Contract for an initiator of services that target the standard {@link org.hibernate.service.ServiceRegistry}
+ * Contract for an initiator of services that target the standard {@link org.hibernate.service.ServiceRegistry}.
+ *
+ * @param <R> The type of the service initiated.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java

@@ -28,7 +28,6 @@ import java.util.HashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Properties;
 
 import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;
 import org.hibernate.boot.registry.internal.StandardServiceRegistryImpl;
@@ -53,6 +52,9 @@ import org.hibernate.service.spi.ServiceContributor;
  * @see org.hibernate.boot.registry.BootstrapServiceRegistryBuilder
  */
 public class StandardServiceRegistryBuilder {
+	/**
+	 * The default resource name for a hibernate configuration xml file.
+	 */
 	public static final String DEFAULT_CFG_RESOURCE_NAME = "hibernate.cfg.xml";
 
 	private final Map settings;
@@ -63,7 +65,7 @@ public class StandardServiceRegistryBuilder {
 	private final ConfigLoader configLoader;
 
 	/**
-	 * Create a default builder
+	 * Create a default builder.
 	 */
 	public StandardServiceRegistryBuilder() {
 		this( new BootstrapServiceRegistryBuilder().build() );
@@ -96,8 +98,10 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Read settings from a {@link Properties} file.  Differs from {@link #configure()} and {@link #configure(String)}
+	 * Read settings from a {@link java.util.Properties} file by resource name.
-	 * in that here we read a {@link Properties} file while for {@link #configure} we read the XML variant.
+	 *
+	 * Differs from {@link #configure()} and {@link #configure(String)} in that here we expect to read a
+	 * {@link java.util.Properties} file while for {@link #configure} we read the XML variant.
 	 *
 	 * @param resourceName The name by which to perform a resource look up for the properties file.
 	 *
@@ -113,7 +117,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Read setting information from an XML file using the standard resource location
+	 * Read setting information from an XML file using the standard resource location.
 	 *
 	 * @return this, for method chaining
 	 *
@@ -126,7 +130,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Read setting information from an XML file using the named resource location
+	 * Read setting information from an XML file using the named resource location.
 	 *
 	 * @param resourceName The named resource
 	 *
@@ -136,7 +140,7 @@ public class StandardServiceRegistryBuilder {
 	 */
 	@SuppressWarnings( {"unchecked"})
 	public StandardServiceRegistryBuilder configure(String resourceName) {
-		JaxbHibernateConfiguration configurationElement = configLoader.loadConfigXmlResource( resourceName );
+		final JaxbHibernateConfiguration configurationElement = configLoader.loadConfigXmlResource( resourceName );
 		for ( JaxbHibernateConfiguration.JaxbSessionFactory.JaxbProperty xmlProperty : configurationElement.getSessionFactory().getProperty() ) {
 			settings.put( xmlProperty.getName(), xmlProperty.getValue() );
 		}
@@ -145,7 +149,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Apply a setting value
+	 * Apply a setting value.
 	 *
 	 * @param settingName The name of the setting
 	 * @param value The value to use.
@@ -159,7 +163,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Apply a groups of setting values
+	 * Apply a groups of setting values.
 	 *
 	 * @param settings The incoming settings to apply
 	 *
@@ -185,7 +189,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Adds a user-provided service
+	 * Adds a user-provided service.
 	 *
 	 * @param serviceRole The role of the service being added
 	 * @param service The service implementation
@@ -198,8 +202,14 @@ public class StandardServiceRegistryBuilder {
 		return this;
 	}
 
+	/**
+	 * Build the StandardServiceRegistry.
+	 *
+	 * @return The StandardServiceRegistry.
+	 */
+	@SuppressWarnings("unchecked")
 	public StandardServiceRegistry build() {
-		Map<?,?> settingsCopy = new HashMap();
+		final Map<?,?> settingsCopy = new HashMap();
 		settingsCopy.putAll( settings );
 		Environment.verifyProperties( settingsCopy );
 		ConfigurationHelper.resolvePlaceHolders( settingsCopy );
@@ -220,8 +230,10 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	private void applyServiceContributors() {
-		LinkedHashSet<ServiceContributor> serviceContributors =
+		final LinkedHashSet<ServiceContributor> serviceContributors =
-				bootstrapServiceRegistry.getService( ClassLoaderService.class ).loadJavaServices( ServiceContributor.class );
+				bootstrapServiceRegistry.getService( ClassLoaderService.class )
+						.loadJavaServices( ServiceContributor.class );
+
 		for ( ServiceContributor serviceContributor : serviceContributors ) {
 			serviceContributor.contribute( this );
 		}
@@ -230,6 +242,11 @@ public class StandardServiceRegistryBuilder {
 	/**
 	 * Temporarily exposed since Configuration is still around and much code still uses Configuration.  This allows
 	 * code to configure the builder and access that to configure Configuration object (used from HEM atm).
+	 *
+	 * @return The settings map.
+	 *
+	 * @deprecated Temporarily exposed since Configuration is still around and much code still uses Configuration.
+	 * This allows code to configure the builder and access that to configure Configuration object (used from HEM atm).
 	 */
 	@Deprecated
 	public Map getSettings() {

hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java

@@ -31,15 +31,16 @@ import java.util.List;
 import org.hibernate.service.Service;
 
 /**
- * A service for interacting with class loaders
+ * A service for interacting with class loaders.
  *
  * @author Steve Ebersole
  */
 public interface ClassLoaderService extends Service {
 	/**
-	 * Locate a class by name
+	 * Locate a class by name.
 	 *
 	 * @param className The name of the class to locate
+	 * @param <T> The returned class type.
 	 *
 	 * @return The class reference
 	 *
@@ -48,7 +49,7 @@ public interface ClassLoaderService extends Service {
 	public <T> Class<T> classForName(String className);
 
 	/**
-	 * Locate a resource by name (classpath lookup)
+	 * Locate a resource by name (classpath lookup).
 	 *
 	 * @param name The resource name.
 	 *
@@ -57,7 +58,7 @@ public interface ClassLoaderService extends Service {
 	public URL locateResource(String name);
 
 	/**
-	 * Locate a resource by name (classpath lookup) and gets its stream
+	 * Locate a resource by name (classpath lookup) and gets its stream.
 	 *
 	 * @param name The resource name.
 	 *
@@ -66,7 +67,7 @@ public interface ClassLoaderService extends Service {
 	public InputStream locateResourceStream(String name);
 
 	/**
-	 * Locate a series of resource by name (classpath lookup)
+	 * Locate a series of resource by name (classpath lookup).
 	 *
 	 * @param name The resource name.
 	 *

hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoadingException.java

@@ -25,16 +25,27 @@ package org.hibernate.boot.registry.classloading.spi;
 import org.hibernate.HibernateException;
 
 /**
- * Indicates a problem performing class loading
+ * Indicates a problem performing class loading.
  *
  * @author Steve Ebersole
  */
 public class ClassLoadingException extends HibernateException {
-	public ClassLoadingException(String string, Throwable root) {
+	/**
-		super( string, root );
+	 * Constructs a ClassLoadingException using the specified message and cause.
+	 *
+	 * @param message A message explaining the exception condition.
+	 * @param cause The underlying cause
+	 */
+	public ClassLoadingException(String message, Throwable cause) {
+		super( message, cause );
 	}
 
-	public ClassLoadingException(String s) {
+	/**
-		super( s );
+	 * Constructs a ClassLoadingException using the specified message.
+	 *
+	 * @param message A message explaining the exception condition.
+	 */
+	public ClassLoadingException(String message) {
+		super( message );
 	}
 }

hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * The class loading service SPI.
+ */
+package org.hibernate.boot.registry.classloading.spi;

hibernate-core/src/main/java/org/hibernate/boot/registry/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Defines service registry contracts application are likely to want to utilize for
+ * configuring Hibernate behavior.
+ *
+ * {@link BootstrapServiceRegistry} is the
+ */
+package org.hibernate.boot.registry;

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/Availability.java

@@ -24,10 +24,34 @@
 package org.hibernate.boot.registry.selector;
 
 /**
+ * Describes the availability of a named strategy implementation.  A strategy + selector name should resolve
+ * to a single implementation.
+ *
+ * todo : better name?
+ *
+ * @param <T> The type of the strategy described by this implementation availability.
+ *
  * @author Steve Ebersole
  */
-public interface Availability {
+public interface Availability<T> {
-	public Class getStrategyRole();
+	/**
+	 * The strategy role.  Best practice says this should be an interface.
+	 *
+	 * @return The strategy contract/role.
+	 */
+	public Class<T> getStrategyRole();
+
+	/**
+	 * Any registered names for this strategy availability.
+	 *
+	 * @return The registered selection names.
+	 */
 	public Iterable<String> getSelectorNames();
-	public Class getStrategyImplementation();
+
+	/**
+	 * The strategy implementation class.
+	 *
+	 * @return The strategy implementation.
+	 */
+	public Class<? extends T> getStrategyImplementation();
 }

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/AvailabilityAnnouncer.java

@@ -25,12 +25,17 @@ package org.hibernate.boot.registry.selector;
 
 /**
  * Responsible for announcing the availability of strategy selector(s).  Can be registered directly with the
- * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} or located via discovery
+ * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} or located via discovery.
  *
  * todo : better name?
  *
  * @author Steve Ebersole
  */
 public interface AvailabilityAnnouncer {
+	/**
+	 * Get all availabilities announced by this announcer.
+	 *
+	 * @return All announced availabilities
+	 */
 	public Iterable<Availability> getAvailabilities();
 }

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/SimpleAvailabilityImpl.java

@@ -26,31 +26,49 @@ package org.hibernate.boot.registry.selector;
 import java.util.Arrays;
 
 /**
+ * A simple implementation of Availability.
+ *
+ * @param <T> The strategy type.
+ *
  * @author Steve Ebersole
  */
-public class SimpleAvailabilityImpl implements Availability {
+public class SimpleAvailabilityImpl<T> implements Availability<T> {
-	private final Class strategyRole;
+	private final Class<T> strategyRole;
-	private final Class strategyImplementation;
+	private final Class<? extends T> strategyImplementation;
 	private final Iterable<String> selectorNames;
 
+	/**
+	 * Constructs a SimpleAvailabilityImpl.
+	 *
+	 * @param strategyRole The strategy contract
+	 * @param strategyImplementation The strategy implementation class
+	 * @param selectorNames The selection/registration names for this implementation
+	 */
 	public SimpleAvailabilityImpl(
-			Class strategyRole,
+			Class<T> strategyRole,
-			Class strategyImplementation,
+			Class<? extends T> strategyImplementation,
 			Iterable<String> selectorNames) {
 		this.strategyRole = strategyRole;
 		this.strategyImplementation = strategyImplementation;
 		this.selectorNames = selectorNames;
 	}
 
+	/**
+	 * Constructs a SimpleAvailabilityImpl.
+	 *
+	 * @param strategyRole The strategy contract
+	 * @param strategyImplementation The strategy implementation class
+	 * @param selectorNames The selection/registration names for this implementation
+	 */
 	public SimpleAvailabilityImpl(
-			Class strategyRole,
+			Class<T> strategyRole,
-			Class strategyImplementation,
+			Class<? extends T> strategyImplementation,
 			String... selectorNames) {
 		this( strategyRole, strategyImplementation, Arrays.asList( selectorNames ) );
 	}
 
 	@Override
-	public Class getStrategyRole() {
+	public Class<T> getStrategyRole() {
 		return strategyRole;
 	}
 
@@ -60,7 +78,7 @@ public class SimpleAvailabilityImpl implements Availability {
 	}
 
 	@Override
-	public Class getStrategyImplementation() {
+	public Class<? extends T> getStrategyImplementation() {
 		return strategyImplementation;
 	}
 }

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java

@@ -98,6 +98,8 @@ import org.hibernate.hql.spi.TemporaryTableBulkIdStrategy;
 import org.jboss.logging.Logger;
 
 /**
+ * Builder for StrategySelector instances.
+ *
  * @author Steve Ebersole
  */
 public class StrategySelectorBuilder {
@@ -105,15 +107,31 @@ public class StrategySelectorBuilder {
 
 	private final List<Availability> explicitAvailabilities = new ArrayList<Availability>();
 
+	/**
+	 * Adds an explicit (as opposed to discovered) strategy availability.
+	 *
+	 * @param strategy The strategy
+	 * @param implementation The strategy implementation
+	 * @param name The registered name
+	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
+	 * compatible.
+	 */
 	@SuppressWarnings("unchecked")
 	public <T> void addExplicitAvailability(Class<T> strategy, Class<? extends T> implementation, String name) {
-		addExplicitAvailability( new SimpleAvailabilityImpl( strategy, implementation, name ) );
+		addExplicitAvailability( new SimpleAvailabilityImpl<T>( strategy, implementation, name ) );
 	}
 
-	public void addExplicitAvailability(Availability availability) {
+	/**
+	 * Adds an explicit (as opposed to discovered) strategy availability.
+	 *
+	 * @param availability The strategy implementation availability.
+	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
+	 * compatible.
+	 */
+	public <T> void addExplicitAvailability(Availability<T> availability) {
 		if ( !availability.getStrategyRole().isInterface() ) {
 			// not good form...
-			log.debug( "Registering non-interface strategy implementation : " + availability.getStrategyRole().getName()  );
+			log.debug( "Registering non-interface strategy : " + availability.getStrategyRole().getName()  );
 		}
 
 		if ( ! availability.getStrategyRole().isAssignableFrom( availability.getStrategyImplementation() ) ) {
@@ -126,8 +144,16 @@ public class StrategySelectorBuilder {
 		explicitAvailabilities.add( availability );
 	}
 
+	/**
+	 * Builds the selector.
+	 *
+	 * @param classLoaderService The class loading service used to (attempt to) resolve any un-registered
+	 * strategy implementations.
+	 *
+	 * @return The selector.
+	 */
 	public StrategySelector buildSelector(ClassLoaderService classLoaderService) {
-		StrategySelectorImpl strategySelector = new StrategySelectorImpl( classLoaderService );
+		final StrategySelectorImpl strategySelector = new StrategySelectorImpl( classLoaderService );
 
 		// build the baseline...
 		addDialects( strategySelector );
@@ -151,7 +177,7 @@ public class StrategySelectorBuilder {
 	}
 
 	@SuppressWarnings("unchecked")
-	private void applyFromAvailability(StrategySelectorImpl strategySelector, Availability availability) {
+	private <T> void applyFromAvailability(StrategySelectorImpl strategySelector, Availability<T> availability) {
 		for ( String name : availability.getSelectorNames() ) {
 			strategySelector.registerStrategyImplementor(
 					availability.getStrategyRole(),

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorImpl.java

@@ -35,6 +35,8 @@ import org.hibernate.boot.registry.selector.spi.StrategySelectionException;
 import org.hibernate.boot.registry.selector.spi.StrategySelector;
 
 /**
+ * Standard implementation of the StrategySelector contract.
+ *
  * @author Steve Ebersole
  */
 public class StrategySelectorImpl implements StrategySelector {
@@ -45,6 +47,11 @@ public class StrategySelectorImpl implements StrategySelector {
 
 	private final ClassLoaderService classLoaderService;
 
+	/**
+	 * Constructs a StrategySelectorImpl using the given class loader service.
+	 *
+	 * @param classLoaderService The class loader service usable by this StrategySelectorImpl instance.
+	 */
 	public StrategySelectorImpl(ClassLoaderService classLoaderService) {
 		this.classLoaderService = classLoaderService;
 	}
@@ -57,7 +64,7 @@ public class StrategySelectorImpl implements StrategySelector {
 			namedStrategyImplementorByStrategyMap.put( strategy, namedStrategyImplementorMap );
 		}
 
-		Class old = namedStrategyImplementorMap.put( name, implementation );
+		final Class old = namedStrategyImplementorMap.put( name, implementation );
 		if ( old == null ) {
 			log.trace(
 					String.format(
@@ -83,7 +90,7 @@ public class StrategySelectorImpl implements StrategySelector {
 
 	@Override
 	public <T> void unRegisterStrategyImplementor(Class<T> strategy, Class<? extends T> implementation) {
-		Map<String,Class> namedStrategyImplementorMap = namedStrategyImplementorByStrategyMap.get( strategy );
+		final Map<String,Class> namedStrategyImplementorMap = namedStrategyImplementorByStrategyMap.get( strategy );
 		if ( namedStrategyImplementorMap == null ) {
 			log.debug( "Named strategy map did not exist on call to un-register" );
 			return;
@@ -106,7 +113,7 @@ public class StrategySelectorImpl implements StrategySelector {
 	@Override
 	@SuppressWarnings("unchecked")
 	public <T> Class<? extends T> selectStrategyImplementor(Class<T> strategy, String name) {
-		Map<String,Class> namedStrategyImplementorMap = namedStrategyImplementorByStrategyMap.get( strategy );
+		final Map<String,Class> namedStrategyImplementorMap = namedStrategyImplementorByStrategyMap.get( strategy );
 		if ( namedStrategyImplementorMap != null ) {
 			final Class registered = namedStrategyImplementorMap.get( name );
 			if ( registered != null ) {

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/package-info.java

@@ -1 +1,5 @@
-package org.hibernate.boot.registry.selector;
+/**
+ * Defines a feature-set around named registration of implementations of various contracts and the ability
+ * to select those implementations.
+ */
+package org.hibernate.boot.registry.selector;

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/spi/StrategySelectionException.java

@@ -26,14 +26,27 @@ package org.hibernate.boot.registry.selector.spi;
 import org.hibernate.HibernateException;
 
 /**
+ * Indicates a problem performing the selection/resolution.
+ *
  * @author Steve Ebersole
  */
 public class StrategySelectionException extends HibernateException {
+	/**
+	 * Constructs a StrategySelectionException using the specified message.
+	 *
+	 * @param message A message explaining the exception condition.
+	 */
 	public StrategySelectionException(String message) {
 		super( message );
 	}
 
-	public StrategySelectionException(String message, Throwable root) {
+	/**
-		super( message, root );
+	 * Constructs a StrategySelectionException using the specified message and cause.
+	 *
+	 * @param message A message explaining the exception condition.
+	 * @param cause The underlying cause.
+	 */
+	public StrategySelectionException(String message, Throwable cause) {
+		super( message, cause );
 	}
 }

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/spi/StrategySelector.java

@@ -37,6 +37,8 @@ public interface StrategySelector extends Service {
 	 * @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.
 	 */
 	public <T> void registerStrategyImplementor(Class<T> strategy, String name, Class<? extends T> implementation);
 
@@ -46,6 +48,8 @@ public interface StrategySelector extends Service {
 	 *
 	 * @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.
 	 */
 	public <T> void unRegisterStrategyImplementor(Class<T> strategy, Class<? extends T> implementation);
 
@@ -54,6 +58,8 @@ public interface StrategySelector extends Service {
 	 *
 	 * @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.
 	 */
@@ -65,6 +71,8 @@ public interface StrategySelector extends Service {
 	 *
 	 * @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
 	 */
@@ -91,6 +99,8 @@ public interface StrategySelector extends Service {
 	 * @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
 	 */

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/spi/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Defines actual contract used for strategy selection : {@link StrategySelector}.
+ */
+package org.hibernate.boot.registry.selector.spi;