001package common.http.error;
002
003import usecase.auth.BannedUserException;
004
005import java.lang.annotation.ElementType;
006import java.lang.annotation.Retention;
007import java.lang.annotation.RetentionPolicy;
008import java.lang.annotation.Target;
009
010/**
011 * <p>L'annotazione consente di impostare in modo dichiarativo se inviare eventuali errori in formato JSON nel corpo della risposta</p>
012 * <p>Affinché funzioni, è necessario che la servlet su cui applicare l'annotazione estenda {@link common.http.interceptor.InterceptableServlet}</p>
013 * <p>È possibile applicare l'annotazione ai singoli metodi "doX" implementati (es. doGet). Applicare l'annotazione
014 * direttamente alla classe equivale ad applicarla su tutti i metodi "doX" implementati.</p>
015 * <p>Quando un metodo "doX" annotato con {@link JSONError} lancia una particolare eccezione
016 * (elencata in basso), si verificano le seguenti azioni: </p>
017 * <ul>
018 *     <li>Viene catturata l'eccezione allo scopo di recuperare i messaggi di errore rilevanti
019 *     per inserirli nell'attributo di richiesta <pre>errors</pre></li>
020 *     <li>I messaggi raccolti vengono inclusi in un array JSON con chiave <pre>errors</pre></li>
021 *     <li>Viene impostato l'apposito status code a seconda dell'eccezione catturata</li>
022 *     <li>Il JSON risultante viene scritto sulla risposta</li>
023 * </ul>
024 * <p>Le eccezioni catturate sono le seguenti:  </p>
025 * <table>
026 *     <tr>
027 *         <td>Eccezione</td><td>Messaggi di errore</td><td>Status code</td>
028 *     </tr>
029 *     <tr>
030 *         <td>{@link javax.validation.ConstraintViolationException}</td><td>I messaggi degli oggetti {@link javax.validation.ConstraintViolation}</td><td>400</td>
031 *     </tr>
032 *     <tr>
033 *         <td>{@link IllegalArgumentException}</td><td>{@link IllegalArgumentException#getMessage()}</td><td>400</td>
034 *     </tr>
035 *     <tr>
036 *         <td>{@link usecase.auth.AuthenticationRequiredException}</td><td>{@link usecase.auth.AuthenticationRequiredException#getMessage()}</td><td>401</td>
037 *     </tr>
038 *     <tr>
039 *         <td>{@link usecase.auth.BannedUserException}</td><td>La durata del ban, contenuta in {@link BannedUserException#getDuration()}</td><td>403</td>
040 *     </tr>
041 *     <tr>
042 *         <td>{@link usecase.auth.AuthorizationException}</td><td>{@link usecase.auth.AuthorizationException#getMessage()}</td><td>403</td>
043 *     </tr>
044 *     <tr>
045 *         <td>{@link RuntimeException}</td><td>{{@link RuntimeException#getMessage()}}</td><td>4500</td>
046 *     </tr>
047 *     <tr>
048 *         <td>{@link javax.servlet.ServletException}</td><td>{{@link javax.servlet.ServletException#getMessage()}}</td><td>500</td>
049 *     </tr>
050 *     <tr>
051 *         <td>{@link java.io.IOException}</td><td>{{@link java.io.IOException#getMessage()}}</td><td>500</td>
052 *     </tr>
053 * </table>
054 * @see ForwardOnErrorInterceptor
055 * @see common.http.interceptor.InterceptableServlet
056 * @see common.http.interceptor.ServletInterceptor
057 */
058@Target({ElementType.METHOD,ElementType.TYPE})
059@Retention(RetentionPolicy.RUNTIME)
060public @interface JSONError {
061}