[vc_row][vc_column][vc_column_text]Hemos revisado el manejo de excepciones tanto las buenas prácticas y los errores comunes. Si ha revisado estos artículos probablemente puede reconocer algunos patrones. Se debe proporcionar información detallada de la situación que esta causando la excepción, y no debe eliminar nada que sea útil para el que llama al método.
Siempre se puede realizar esto mediante el uso de excepciones estandars con buenos mensajes. La clase Java Exception describe el tipo de evento y el mensaje proporciona información detallada al respecto. Puede llevar este concepto un paso más allá al usar una excepción personalizada.
Las excepciones personalizadas proporcionan la flexibilidad de agregar atributos y métodos que no son parte de una Exception estandard. Estos pueden almacenar información adicional, cono un código de error específico de la aplicación o proporcionar métodos útiles que pueden ser utilizados para manejar o presentar la excepción al usuario.[/vc_column_text][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]
Recomendaciones para las Excepciones personalizadas
A continuación presentamos 4 buenas prácticas que puede seguir cuando decida implementar una excepción personalizada. Estas recomendaciones hacen que su código y el API sean fáciles de entender. Estos también reducen el uso de documentación excesiva.
1. Siempre proporciona un beneficio
La descripción previa donde indicamos de atributos o métodos adicionales muestra la intención de una excepción personalizada. Este proporciona información o funcionalidad que no es parte de las excepciones Java estandard.
Esta es la esencia de la primera y más importante recomendación. De otra manera, tu excepción no proporciona beneficio comparado con el gran número de excepciones proporcionado por el JDK.
Si no proporciona beneficio adicional, es mejor utilizar una excepción estándar, como UnsupportedOperationException o IllegalArgumentException. Todos los desarrolladores Java conocen estas excepciones. Esto hace de su código y librería fácil de entender.
2. Seguir las convenciones de Nombre
Cuando observa una clase del tipo Exception proporcionado por el JDK, rápidamente reconoce que todas terminan con «Exception». Esta convención general de nombres es utilizada a través del ecosistema de Java. La excepción personalizada debe seguir esta convención.
3. Proporciona comentarios Javadoc para la Excepción personalizada
No se debería hablar de esta buena práctica, pero hay muchas excepciones personalizadas que no tienen documentación Javadoc.
Es una buena práctica documentar todas las clases, atributos, constructores y métodos de su API. Si ha tenido que utilizar un API no documentado, sabe de que estamos hablando. Un API no documentado es muy difícil de utilizar.
Las clases de Excepción no deberían ser la parte más obvia del API, pero son parte del mismo. Tan pronto como uno de sus métodos orientados al cliente arroja una excepción, la clase de excepción se convierte en parte de la API. Esto implica que requiere documentación y un buen Javadoc.
El Javadoc debe describir el significado general de la excepción y la situación en la cual esta sucede. El objetivo es ayudar a otros desarrolladores a entender su API y evitar escenarios de errores comunes.
1 2 3 4 5 6 7 | /** * The MyBusinessException wraps all checked standard Java exception and enriches them with a custom error code. * You can use this code to retrieve localized error messages and to link to our online documentation. * * @author TJanssen */ public class MyBusinessException extends Exception { ... } |
4. Proporciona un Constructor que establezca la causa
Muy a menudo, su código detecta una excepción estándar antes de lanzar una excepción personalizada. No deberías ocultar este hecho. La excepción detectada generalmente contiene información esencial que necesitará para analizar un incidente en producción.
En el siguiente ejemplo, NumberFormatException proporciona información detallada sobre el error. Perderá esta información si no la establece como la causa de MyBusinessException.
1 2 3 4 5 6 7 | public void wrapException(String input) throws MyBusinessException { try { // do something } catch (NumberFormatException e) { throw new MyBusinessException("A message that describes the error.", e, ErrorCode.INVALID_PORT_CONFIGURATION); } } |
Exception y RuntimeException proporciona constructores que aceptan Throwable que describe la causa de la excepción. Tu excepción debe hacer lo mismo, debes implementar al menos un constructor que reciba Throwable como un parámetro y los entregue a la super clase.
1 2 3 4 5 6 7 8 9 | public class MyBusinessException extends Exception { public MyBusinessException(String message, Throwable cause, ErrorCode code) { super(message, cause); this.code = code; } ... } |
Estas son las recomendaciones más importantes para implementar excepciones personalizadas.[/vc_column_text][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]
Implementación de una Excepción personalizada
Cuando implementas una excepción del tipo checked, necesitas heredas de la clase Exception. Esto es lo único que tienes que hacer para implementar una excepción personalizada. Pero tal como explicamos, se debe proporcionar un constructor en donde agreguemos la causa de la excepción y proporcione beneficios comparado con las excepciones estándar.
El siguiente ejemplo realiza esto. Como puede ver, se ha agregado información Javadoc para describir la excepción. También se ha implementado un constructor con la excepción origen. Y como un beneficio adicional MyBusinessException utiliza un enumeration personalizado que almacena los errores para identificar el problema. Los clientes pueden usar el código de error para mostrar mensajes de error localizados o indicar al usuario que incluya este código en un ticket de soporte.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | /** * The MyBusinessException wraps all checked standard Java exception and enriches them with a custom error code. * You can use this code to retrieve localized error messages and to link to our online documentation. * * @author TJanssen */ public class MyBusinessException extends Exception { private static final long serialVersionUID = 7718828512143293558 L; private final ErrorCode code; public MyBusinessException(ErrorCode code) { super(); this.code = code; } public MyBusinessException(String message, Throwable cause, ErrorCode code) { super(message, cause); this.code = code; } public MyBusinessException(String message, ErrorCode code) { super(message); this.code = code; } public MyBusinessException(Throwable cause, ErrorCode code) { super(cause); this.code = code; } public ErrorCode getCode() { return this.code; } } |
Eso es todo lo que necesita hacer para implementar una excepción personalizada. Ahora puede lanzar MyBusinessException como parte de su código, especificarla como parte de un método o manejarla en una clausula catch.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | public void handleExceptionInOneBlock() { try { wrapException(new String("99999999")); } catch (MyBusinessException e) { // handle exception log.error(e); } } private void wrapException(String input) throws MyBusinessException { try { // do something } catch (NumberFormatException e) { throw new MyBusinessException("A message that describes the error.", e, ErrorCode.INVALID_PORT_CONFIGURATION); } } |
[/vc_column_text][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]
Implementación de Excepciones Unchecked
La implementación de una excepción unchecked es similar a una excepción checked. Debes seguir las mismas recomendaciones escritas en este artículo. La única diferencia es que la excepción del tipo unchecked debe retornar RuntimeException en lugar de Exception.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | /** * The MyUncheckedBusinessException wraps all unchecked standard Java exception and enriches them with a custom error code. * You can use this code to retrieve localized error messages and to link to our online documentation. * * @author TJanssen */ public class MyUncheckedBusinessException extends RuntimeException { private static final long serialVersionUID = -8460356990632230194 L; private final ErrorCode code; public MyUncheckedBusinessException(ErrorCode code) { super(); this.code = code; } public MyUncheckedBusinessException(String message, Throwable cause, ErrorCode code) { super(message, cause); this.code = code; } public MyUncheckedBusinessException(String message, ErrorCode code) { super(message); this.code = code; } public MyUncheckedBusinessException(Throwable cause, ErrorCode code) { super(cause); this.code = code; } public ErrorCode getCode() { return this.code; } } |
Puede utilizar MyUncheckedBusinessException de la misma forma a otras excepciones unchecked. Puede lanzarla en su código y capturarla en una sentencia catch. Y puede, pero no necesita indicar si el método lo lanza.
1 2 3 4 5 6 7 | private void wrapException(String input) { try { // do something } catch (NumberFormatException e) { throw new MyUncheckedBusinessException("A message that describes the error.", e, ErrorCode.INVALID_PORT_CONFIGURATION); } } |
[/vc_column_text][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]
Resumen
Como se describe en esta publicación, la implementación de una excepción personalizada es fácil. Solo necesita extender Exception para una excepción checked personalizada o RuntimeException si es una excepción unchecked personalizada.
Además de eso, debes seguir algunas buenas prácticas, que hacen que su código sea más fácil de leer y su API más fácil de utilizar. Estas son las 4 mejores prácticas para excepciones personalizadas en Java:
- Solo debe implementar una excepción personalizada si proporciona un beneficio en comparación con las excepciones estándar de Java.
- El nombre de la clase de su excepción personalizada debe terminar en Exception.
- Si un método API especifica una excepción, la clase de excepción se convierte en parte del API y se debe documentar.
- Debe proporcionar un constructor que establezca la causa de la excepción.
Este artículo esta basado en Implementing Custom Exceptions In Java[/vc_column_text][/vc_column][/vc_row]
