Manejo de errores de mandatos

HCL Commerce utiliza una infraestructura de manejo de errores de mandatos bien definida que es fácil de utilizar en el código personalizado. Por diseño, la infraestructura maneja los errores de manera que se da soporte a tiendas multiculturales. En las siguientes secciones se describen los tipos de excepciones que puede generar un mandato, cómo se manejan las excepciones, cómo se guarda y utiliza el texto de los mensajes, cómo se anotan las excepciones y cómo utilizar la infraestructura suministrada en sus propios mandatos.

Tipos de excepciones

Un mandato puede generar una de las siguientes excepciones:

ECApplicationException: Esta excepción se genera si el error está relacionado con la entrada de usuario y siempre fallará. Por ejemplo, cuando un usuario entra un parámetro que no es válido, se genera una excepción ECApplicationException. Cuando se genera esta excepción, el controlador de soluciones no vuelve a intentar ejecutar el mandato aunque se haya especificado como mandato que puede reintentarse.
ECSystemException: Esta excepción se genera si se detecta una excepción de tiempo de ejecución o un error de configuración de HCL Commerce. Ejemplos de este tipo de excepción son las excepciones de creación, las excepciones remotas y otras excepciones EJB. Cuando se genera este tipo de excepción, el controlador de soluciones vuelve a intentar ejecutar el mandato, si el mandato se puede reintentar y la excepción se generó debido a un punto muerto en la base de datos o una retrotracción en la base de datos.

Las dos excepciones anteriores son clases que se amplían de la clase ECException, que se encuentra en el paquete com.ibm.commerce.exception.

Para generar una de estas excepciones, debe especificarse la siguiente información:

Nombre de vista de error: La vista que se utilizará para mostrar el error. Para las peticiones web, el controlador web busca este nombre en los archivos de configuración de Struts.
Objeto ECMessage: ECMessage define la información estática relacionada con la razón de la excepción. Este valor corresponde al texto del mensaje contenido en un archivo de propiedades.
ECParameter: ECParameter devuelve los errores asociados a la aplicación. La excepción puede indicar varios errores ya que cada parte de una excepción de aplicación representa un error.
Parámetros de error: Estos pares nombre-valor se utilizan para sustituir información en el mensaje de error. Por ejemplo, un mensaje puede incluir un parámetro que contenga el nombre del método que generó la excepción. Este parámetro se establece cuando se genera la excepción, y cuando se anota el mensaje de error, el archivo de anotaciones cronológicas contiene el nombre del método real.
Datos de error: Son atributos opcionales que puede utilizar la página JSP a través del bean de datos de error.

El manejo de excepciones está integrado en el sistema de anotación cronológica. Cuando se genera una excepción del sistema, ésta se anota cronológicamente de forma automática.

Archivos de propiedades de mensajes de error

Para simplificar el mantenimiento de los mensajes de error y para dar soporte a tiendas multilingües, el texto de los mensajes de error se guarda en los archivos llamados xxxxSystemMessages_locale.properties o yyyyUserMessages_locale.properties, que están organizados en los paquetes denominados com.ibm.commerce.zzzz.ras.properties. Donde xxxx, yyyy y zzzz son series arbitrarias.

En los archivos de propiedades de mensajes de error hay dos tipos de mensajes definidos: mensajes de usuario y mensajes del sistema. Los mensajes de usuario se muestran a los clientes en sus navegadores. Los mensajes del sistema se capturan automáticamente en el registro de mensajes, los mensajes de usuario no.

El contexto del mandato devuelve un identificador para indicar el idioma que utiliza el cliente. Cuando se necesita un mensaje, el controlador de soluciones determina qué archivo de propiedades se debe utilizar según el identificador del idioma.

Cuando se genera un error, uno de los parámetros necesarios es un objeto mensaje. Para ECSystemExceptions, el objeto mensaje debe contener dos claves, una para el mensaje del sistema y otra para el mensaje de usuario. El mensaje del sistema se registra, mientras que el mensaje del usuario se muestra al cliente. Para ECApplicationExceptions, el objeto mensaje contiene la clave para el mensaje de usuario (los mensajes del sistema no se utilizan).

Los mensajes del sistema pueden personalizarse y puede crear nuevos. Cuando el código personalizado genera una excepción ECSystemException, debe especificar una clave de mensaje para uno de los mensajes predefinidos o un mensaje del sistema personalizado. También se pueden crear mensajes de usuario personalizados. Los nuevos mensajes del sistema y de usuario pueden guardarse en un archivo de propiedades distinto.

Flujo del manejo de excepciones

El controlador de soluciones invoca un mandato de controlador.
El mandato genera una excepción que detecta el controlador de soluciones. Dicha excepción puede ser ECApplicationException o ECSystemException. El objeto de excepción contiene la siguiente información:
- Nombre de vista de error
- Objeto ECMessage
- Parámetros de error
- Opcional: Datos de error
En una aplicación web, la infraestructura de Struts determina el reenvío global de error encontrado en el archivo de configuración de Struts e invoca la vista de error especificada. Al invocar el mandato, el controlador de soluciones crea un conjunto de propiedades a partir del objeto ECException y establece la vista de error utilizando el método setInputProperties.
El bean de datos de error pasa los parámetros de error al objeto de ayuda de mensaje.
StoreErrorDataBean correlaciona los códigos de error con mensajes.

Manejo de excepciones en el código personalizado

Al crear nuevos mandatos es importante incluir el manejo de excepciones adecuado. Puede aprovechar la infraestructura de manejo de errores y de mensajería que se proporciona en HCL Commerce, especificando la información necesaria cuando se detecta una excepción.

Al crear su propia lógica de manejo de excepciones debe tener en cuenta lo siguiente:

Deben detectarse las excepciones del mandato que necesitan un proceso especial.
Debe crearse una excepción ECApplicationException o una ECSystemException, según el tipo de excepción detectada.
Si la excepción ECApplicationException utiliza un nuevo mensaje, debe definirse el mensaje en el nuevo archivo de propiedades.

Detección y creación de excepciones

Para ilustrar los dos primeros pasos, el siguiente fragmento de código muestra un ejemplo de cómo se detecta una excepción del sistema en un mandato:


try {
// your business logic
}
catch(FinderException e) {
     throw new ECSystemException (ECMessage._ERR_FINDER_EXCEPTION, 
          className, methodName, new Object [] {e.toString()}, e); 
}

El objeto ECMessage _ERR_FINDER_EXCEPTION se define de la forma siguiente:


public static final ECMessage _ERR_FINDER_EXCEPTION = 
new ECMessage (ECMessageSeverity.ERROR, ECMessageType.SYSTEM, 
     ECMessageKey._ERR_FINDER_EXCEPTION);

El texto del mensaje _ERR_FINDER_EXCEPTION se define dentro del archivo ecServerMessages_xx_XX.properties (donde _xx_XX es un indicador local como por ejemplo, _en_US) de la forma indicada a continuación:


_ERR_FINDER_EXCEPTION  = 
     The following Finder Exception occurred during processing: "{0}".

Al detectarse una excepción del sistema, puede utilizarse un conjunto predefinido de mensajes. Dichos mensajes se describen en la siguiente tabla:


Objeto de mensaje	Descripción:
_ERR_FINDER_EXCEPTION	Se genera cuando se devuelve un error desde una llamada de método buscador EJB.
_ERR_REMOTE_EXCEPTION	Se genera cuando se devuelve un error desde una llamada de método remoto EJB.
_ERR_CREATE_EXCEPTION	Se genera cuando se produce un error al crear una instancia EJB.
_ERR_NAMING_EXCEPTION	Se genera cuando se devuelve un error desde el servidor de nombres.
_ERR_GENERIC	Se genera cuando se produce un error inesperado del sistema. Por ejemplo, una excepción de puntero nulo.

Al detectar una excepción de aplicación, puede utilizar un mensaje existente que esté especificado en el correspondiente archivo de propiedades de mensajes de error o crear un nuevo mensaje que se guarda en un nuevo archivo de propiedades. Como se ha especificado anteriormente, must not modifique cualquiera de los archivos de propiedades de mensajes de error predefinidos.

En el siguiente fragmento de código se muestra un ejemplo de cómo se detecta una excepción de aplicación en un mandato:


try {
// your business logic

}
// catch some new type of application exception
catch(//your new exception)
 {
     throw new ECApplicationException (MyMessages._ERR_CUSTOMER_INVALID, 
          className, methodName, errorTaskName, someNVPs); 
}

El objeto ECMessage _ERR_CUSTOMER_INVALID anterior se define de la forma siguiente:


public static final ECMessage _ERR_CUSTOMER_INVALID = 
     new ECMessage (ECMessageSeverity.ERROR, ECMessageType.USER, 
     MyMessagesKey._ERR_CUSTOMER_INVALID, "ecCustomerMessages");

Al crear nuevos mensajes de usuario, debe asignarles el tipo USER de la forma indicada a continuación:


ECMessageType.USER

El texto del mensaje _ERR_CUSTOMER_INVALID está incluido en el archivo ecCustomerMessages.properties Este archivo debe estar en un directorio que esté indicado en la variable de entorno CLASSPATH. El texto se define de la forma indicada a continuación:


_ERR_CUSTOMER_INVALID = Invalid ID "{0}"