[hibernate-commits] Hibernate SVN: r16990 - search/trunk/src/main/java/org/hibernate/search/util.

[hibernate-commits at lists.jboss.org]

Author: sannegrinovero
Date: 2009-07-01 18:55:25 -0400 (Wed, 01 Jul 2009)
New Revision: 16990

Modified:
   search/trunk/src/main/java/org/hibernate/search/util/PluginLoader.java
Log:
javadoc for HSEARCH-384 improve error messages for loading plugins and add consistency to the performed checks

Modified: search/trunk/src/main/java/org/hibernate/search/util/PluginLoader.java
===================================================================
--- search/trunk/src/main/java/org/hibernate/search/util/PluginLoader.java	2009-07-01 22:38:30 UTC (rev 16989)
+++ search/trunk/src/main/java/org/hibernate/search/util/PluginLoader.java	2009-07-01 22:55:25 UTC (rev 16990)
@@ -4,13 +4,29 @@
 import org.hibernate.util.ReflectHelper;
 
 /**
+ * Utility class to load instances of other classes by using a fully qualified name,
+ * or from a class type.
+ * Uses reflection and throws SearchException(s) with proper descriptions of the error,
+ * like the target class is missing a proper constructor, is an interface, is not found...
  * 
  * @author Sanne Grinovero
- *
- * @param <T>
  */
 public class PluginLoader {
 	
+	/**
+	 * Creates an instance of a target class designed by fully qualified name
+	 * 
+	 * @param <T> matches the type of targetSuperType: defines the return type
+	 * @param targetSuperType the return type of the function, the classNameToLoad will be checked
+	 * to be assignable to this type.
+	 * @param classNameToLoad a fully qualified class name, whose type is assignable to targetSuperType
+	 * @param caller the class of the caller, needed for classloading purposes
+	 * @param componentDescription a meaningful description of the role the instance will have,
+	 * used to enrich error messages to describe the context of the error
+	 * @return a new instance of classNameToLoad
+	 * @throws SearchException wrapping other error types with a proper error message for all kind of problems, like
+	 * classNotFound, missing proper constructor, wrong type, security errors.
+	 */
 	public static <T> T instanceFromName(Class<T> targetSuperType, String classNameToLoad,
 			Class<?> caller, String componentDescription) {
 		final Class<?> clazzDef;
@@ -23,6 +39,16 @@
 		return instanceFromClass( targetSuperType, clazzDef, componentDescription );
 	}
 	
+	/**
+	 * Creates an instance of target class
+	 * @param <T> the type of targetSuperType: defines the return type
+	 * @param targetSuperType the created instance will be checked to be assignable to this type
+	 * @param classToLoad the class to be instantiated
+	 * @param componentDescription a role name/description to contextualize error messages
+	 * @return a new instance of classToLoad
+	 * @throws SearchException wrapping other error types with a proper error message for all kind of problems, like
+	 * missing proper constructor, wrong type, security errors.
+	 */
 	@SuppressWarnings("unchecked")
 	public static <T> T instanceFromClass(Class<T> targetSuperType, Class<?> classToLoad, String componentDescription) {
 		checkClassType( classToLoad, componentDescription );
@@ -66,6 +92,13 @@
 		}
 	}
 
+	/**
+	 * Verifies if target class has a no-args constructor, and that it is
+	 * accessible in current security manager.
+	 * @param classToLoad the class type to check
+	 * @param componentDescription adds a meaningful description to the type to describe in the
+	 * 	exception message
+	 */
 	public static void checkHasValidconstructor(Class<?> classToLoad, String componentDescription) {
 		try {
 			classToLoad.getConstructor();