Adicionado javadoc para a classe

br.gov.frameworkdemoiselle.exception.ExceptionHandlerInterceptor

Adicionado javadoc para a classe
br.gov.frameworkdemoiselle.exception.ExceptionHandlerInterceptor
Emerson Oliveira
1 parent 2d183cfc
Showing 1 changed file with 54 additions and 1 deletions Show diff stats
impl/core/src/main/java/br/gov/frameworkdemoiselle/exception/ExceptionHandlerInterceptor.java
@@ -51,12 +51,65 @@ import javax.interceptor.InvocationContext;
 import org.slf4j.Logger;
+import exception.custom.CustomException;
+
 import br.gov.frameworkdemoiselle.DemoiselleException;
 import br.gov.frameworkdemoiselle.stereotype.Controller;
 import br.gov.frameworkdemoiselle.util.Beans;
 import br.gov.frameworkdemoiselle.util.NameQualifier;
 import br.gov.frameworkdemoiselle.util.ResourceBundle;
+/**
+ * <p>
+ * Intercepts some thrown exceptions, and calls the appropriate method. These interceptor works only in
+ * classes annotated with <b>@Contoller</b>. Above we discribe which kind of exception is intercepted and 
+ * what is an appropriate method. 
+ * <p>
+ * To be interceptable, the thrown exception must be from a type which is annotated with 
+ * <b>@ApplicationException</b>.
+ * <p>
+ * An appropriate method must be annotated with <b>@ExceptionHandler</b>, and receive as parameter some 
+ * exception that could be thrown for it's class (which have to be annotated with <b>@ApplicationException</b>).
+ * So, when this method is called, it's receive the thrown exception as parameter. In the same class shouldn't 
+ * be more than one method annotated with <b>@ExceptionHandler</b> and receiving the same type of exception.
+ * <p>
+ * <p>
+ * The examples below shows how these interceptor works:
+ * <p>
+ * 
+ * <blockquote>
+ * 
+ * <pre>
+ * &#064;ApplicationException
+ * public class CustomException extends RuntimeException {
+ * }
+ * 
+ * &#064;Controller
+ * public class CustomExceptionHandler {
+ * 
+ * 	public void throwException() {
+ *		throw new CustomException();
+ *	}
+ *	
+ *	&#064;ExceptionHandler
+ *	public void handler(CustomException exception) {
+ *		...
+ *	}
+ *
+ * }
+ * </pre>
+ * </blockquote>
+ * 
+ * <p>
+ * When the method <b>throwException</b> throw a <b>CustomException</b>, once CustomException is annotated 
+ * with @ApplicationException and CustomExceptionHandle is annotated with @Controller, the interceptor will 
+ * looking for some method (in CustomExceptionHandle) annotated with @ExceptionHandle and that receive a 
+ * CustomException as parameter to call. In the case shown, the method <b>handler</b> is called when a 
+ * <b>CustomException</b> is thrown.
+ * <p>
+ * 
+ * @author SERPRO
+ */
 @Interceptor
 @Controller
 public class ExceptionHandlerInterceptor implements Serializable {
@@ -68,7 +121,7 @@ public class ExceptionHandlerInterceptor implements Serializable {
 	private static transient Logger logger;
 	private final Map<Class<?>, Map<Class<?>, Method>> cache = new HashMap<Class<?>, Map<Class<?>, Method>>();
-
+	
 	private boolean handleException(final Exception cause, final Object target) throws Exception {
 		getLogger().info(getBundle().getString("handling-exception", cause.getClass().getCanonicalName()));
	@@ -51,12 +51,65 @@ import javax.interceptor.InvocationContext;		@@ -51,12 +51,65 @@ import javax.interceptor.InvocationContext;
51		51
52	import org.slf4j.Logger;	52	import org.slf4j.Logger;
53		53
		54	+import exception.custom.CustomException;
		55	+
54	import br.gov.frameworkdemoiselle.DemoiselleException;	56	import br.gov.frameworkdemoiselle.DemoiselleException;
55	import br.gov.frameworkdemoiselle.stereotype.Controller;	57	import br.gov.frameworkdemoiselle.stereotype.Controller;
56	import br.gov.frameworkdemoiselle.util.Beans;	58	import br.gov.frameworkdemoiselle.util.Beans;
57	import br.gov.frameworkdemoiselle.util.NameQualifier;	59	import br.gov.frameworkdemoiselle.util.NameQualifier;
58	import br.gov.frameworkdemoiselle.util.ResourceBundle;	60	import br.gov.frameworkdemoiselle.util.ResourceBundle;
59		61
		62	+/**
		63	+ * <p>
		64	+ * Intercepts some thrown exceptions, and calls the appropriate method. These interceptor works only in
		65	+ * classes annotated with <b>@Contoller</b>. Above we discribe which kind of exception is intercepted and
		66	+ * what is an appropriate method.
		67	+ * <p>
		68	+ * To be interceptable, the thrown exception must be from a type which is annotated with
		69	+ * <b>@ApplicationException</b>.
		70	+ * <p>
		71	+ * An appropriate method must be annotated with <b>@ExceptionHandler</b>, and receive as parameter some
		72	+ * exception that could be thrown for it's class (which have to be annotated with <b>@ApplicationException</b>).
		73	+ * So, when this method is called, it's receive the thrown exception as parameter. In the same class shouldn't
		74	+ * be more than one method annotated with <b>@ExceptionHandler</b> and receiving the same type of exception.
		75	+ * <p>
		76	+ * <p>
		77	+ * The examples below shows how these interceptor works:
		78	+ * <p>
		79	+ *
		80	+ * <blockquote>
		81	+ *
		82	+ * <pre>
		83	+ * @ApplicationException
		84	+ * public class CustomException extends RuntimeException {
		85	+ * }
		86	+ *
		87	+ * @Controller
		88	+ * public class CustomExceptionHandler {
		89	+ *
		90	+ * public void throwException() {
		91	+ * throw new CustomException();
		92	+ * }
		93	+ *
		94	+ * @ExceptionHandler
		95	+ * public void handler(CustomException exception) {
		96	+ * ...
		97	+ * }
		98	+ *
		99	+ * }
		100	+ * </pre>
		101	+ * </blockquote>
		102	+ *
		103	+ * <p>
		104	+ * When the method <b>throwException</b> throw a <b>CustomException</b>, once CustomException is annotated
		105	+ * with @ApplicationException and CustomExceptionHandle is annotated with @Controller, the interceptor will
		106	+ * looking for some method (in CustomExceptionHandle) annotated with @ExceptionHandle and that receive a
		107	+ * CustomException as parameter to call. In the case shown, the method <b>handler</b> is called when a
		108	+ * <b>CustomException</b> is thrown.
		109	+ * <p>
		110	+ *
		111	+ * @author SERPRO
		112	+ */
60	@Interceptor	113	@Interceptor
61	@Controller	114	@Controller
62	public class ExceptionHandlerInterceptor implements Serializable {	115	public class ExceptionHandlerInterceptor implements Serializable {
	@@ -68,7 +121,7 @@ public class ExceptionHandlerInterceptor implements Serializable {		@@ -68,7 +121,7 @@ public class ExceptionHandlerInterceptor implements Serializable {
68	private static transient Logger logger;	121	private static transient Logger logger;
69		122
70	private final Map<Class<?>, Map<Class<?>, Method>> cache = new HashMap<Class<?>, Map<Class<?>, Method>>();	123	private final Map<Class<?>, Map<Class<?>, Method>> cache = new HashMap<Class<?>, Map<Class<?>, Method>>();
71	-	124	+
72	private boolean handleException(final Exception cause, final Object target) throws Exception {	125	private boolean handleException(final Exception cause, final Object target) throws Exception {
73	getLogger().info(getBundle().getString("handling-exception", cause.getClass().getCanonicalName()));	126	getLogger().info(getBundle().getString("handling-exception", cause.getClass().getCanonicalName()));
74		127