Gestion des erreurs de commande

HCL Commerce utilise une structure de gestion des erreurs de commande bien définie qui est simple à utiliser dans le code personnalisé. De base, la structure gère les erreurs d'une manière qui prend en charge les magasins multiculturels. Les sections suivantes décrivent les types d'exceptions qu'une commande peut lancer, la façon dont les exceptions sont traitées, la façon dont le texte du message est stocké et utilisé, la façon dont les exceptions sont enregistrées et comment utiliser l'infrastructure fournie dans vos propres commandes.

Types d'exceptions

Une commande peut lancer l'une des exceptions suivantes :

ECApplicationException: Cette exception est lancée si l'erreur est liée à l'entrée de l'utilisateur et échoue toujours. Par exemple, lorsqu'un utilisateur entre un paramètre non valide, une ECApplicationException est émise. Lorsque cette exception est émise, le contrôleur de solution ne relance pas la commande, même s'il est spécifié qu'il s'agit d'une commande pouvant faire l'objet d'une nouvelle tentative.
ECSystemException: Cette exception est lancée si une exception d'exécution ou une erreur de configuration de HCL Commerce est détectée. Des exemples de ce type d'exception incluent les exceptions de création, les exceptions à distance et autres exceptions EJB. Lorsque ce type d'exception est émis, le contrôleur de solution relance la commande si la commande peut faire l'objet d'une nouvelle tentative et que l'exception a été causée par une impasse de base de données ou une restauration de base de données.

Les deux exceptions précédentes sont des classes qui prolongent la classe ECException, qui se trouve dans le package com.ibm.commerce.exception.

Pour lancer l'une de ces exceptions, les informations suivantes doivent être spécifiées :

Nom de la vue d'erreur: Vue qui sera utilisée pour afficher l'erreur. Pour les requêtes Web, le contrôleur Web recherche ce nom dans les fichiers de configuration Struts.
Objet ECMessage: ECMessage définit les informations statiques relatives à la raison de l'exception. Cette valeur correspond au texte du message contenu dans un fichier de propriétés.
ECParameter: ECParameter renvoie les erreurs associées à l'application. L'exception peut indiquer plusieurs erreurs puisque chaque partie d'une exception d'application représente une erreur.
Paramètres d'erreur: Ces paires nom-valeur sont utilisées pour remplacer les informations dans le message d'erreur. Par exemple, un message peut contenir un paramètre pour conserver le nom de la méthode qui a lancé l'exception. Ce paramètre est défini lorsque l'exception est lancée, puis lorsque le message d'erreur est enregistré, le fichier journal contient le nom de la méthode réelle.
Données d'erreur: Il s'agit d'attributs facultatifs qui peuvent être mis à la disposition de la page JSP par le biais du bean de données d'erreur.

La manipulation des exceptions est étroitement intégrée au système de journalisation. Lorsqu'une exception système est lancée, elle est automatiquement enregistrée.

Fichirs de propriétés de message d'erreur

Afin de simplifier la maintenance des messages d'erreur et de prendre en charge les magasins multilingues, le texte des messages d'erreur est stocké dans les fichiers de propriétés nommés xxxxSystemMessages_ locale.properties ou yyyy UserMessages_ locale.properties, qui sont organisés en packages nommés com.ibm.commerce.zzzz. ras.properties. Ici, xxxx, yyyy et zzzz sont des chaînes arbitraires.

Deux types de messages sont définis dans les fichiers de propriétés de message d'erreur : messages utilisateur et messages système. Les messages utilisateur sont affichés aux clients dans leurs navigateurs. Les messages système sont capturés automatiquement dans le journal des messages, les messages utilisateur ne le sont pas.

Le contexte de commande renvoie un identificateur pour indiquer la langue utilisée par le client. Lorsqu'un message est requis, le contrôleur de solution détermine le fichier de propriétés à utiliser en fonction de l'identificateur de langue.

Lorsqu'une erreur est lancée, l'un des paramètres requis est un objet message. Pour les ECSystemExceptions, l'objet message doit contenir deux clés, une pour le message système et l'autre pour le message utilisateur. Le message système est enregistré, tandis que le message utilisateur est affiché au client. Pour les ECApplicationExceptions, l'objet de message contient la clé du message utilisateur (les messages système ne sont pas utilisés).

Les messages système peuvent être personnalisés et vous pouvez en créer de nouveaux. Lorsque le code personnalisé lance une ECSystemException, il doit spécifier une clé de message pour l'un des messages système prédéfinis ou un message système personnalisé. Des messages utilisateur personnalisés peuvent également être créés. Les nouveaux messages système et les nouveaux messages utilisateur doivent être stockés dans un fichier de propriétés distinct.

Flux de gestion des exceptions

Le contrôleur de solution appelle une commande de contrôleur.
La commande lance une exception qui est capturée par le contrôleur de solution. Il peut s'agir soit d'une ECApplicationException, soit d'une ECSystemException. L'objet exception contient les informations suivantes :
- Nom de la vue d'erreur
- Object ECMessage
- Paramètres d'erreur
- Facultatif : Données d'erreur
Pour une application Web, la structure struts détermine le rapport global d'erreur trouvé dans le fichier de configuration struts et appelle l'affichage d'erreur spécifié. Lors de l'appel de la commande, le contrôleur de solution compose un ensemble de propriétés à partir de l'objet ECException et définit l'affichage d'erreur à l'aide de la méthode setInputProperties.
ErrorDataBean transmet les paramètres d'erreur à l'objet assistance de message.
Le StoreErrorDataBean mappe les codes d'erreur aux messages.

Gestion des exceptions dans le code personnalisé

Lors de la création de nouvelles commandes, il est important d'inclure une gestion des exceptions appropriée. Vous pouvez profiter de la structure de gestion des erreurs et de messagerie fournie dans HCL Commerce en spécifiant les informations requises lors de la capture d'une exception.

L'écriture de votre propre logique de gestion des exceptions implique les étapes suivantes :

Capturer les exceptions de votre commande qui nécessitent un traitement spécial.
Etablir une ECApplicationException ou une ECSystemException basée sur le type d'exception capturée.
Si l'exception ECApplicationException utilise un nouveau message, définir le message dans un nouveau fichier de propriétés.

Capturer et créer des exceptions

Pour illustrer les deux premières étapes, le snippet de code suivant montre un exemple de capture d'une exception système au sein d'une commande :


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

L'objet ECMessage _ERR_FINDER_EXCEPTION précédent est défini comme suit :


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

Le texte du message _ERR_FINDER_EXCEPTION est défini dans le fichier ecServerMessages_xx_XX.properties (où _xx_XX est un indicateur de paramètre régional tel que _en_US), comme suit :


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

Lorsque vous capturez une exception système, il existe un ensemble prédéfini de messages qui peuvent être utilisés. Ceux-ci sont décrits dans la table suivante :


Objet message	Description
_ERR_FINDER_EXCEPTION	Lancé lorsqu'une erreur est renvoyée à partir d'un appel de méthode de recherche EJB.
_ERR_REMOTE_EXCEPTION	Lancé lorsqu'une erreur est renvoyée à partir d'un appel de méthode distant EJB.
_ERR_CREATE_EXCEPTION	Lancé lorsqu'une erreur se produit en créant une instance EJB.
_ERR_NAMING_EXCEPTION	Lancé lorsqu'une erreur est renvoyée depuis le serveur de noms.
_ERR_GENERIC	Lancé lorsqu'une erreur système inattendue se produit. Par exemple, une exception liée à un pointeur nul :

Lorsque vous capturez une exception d'application, vous pouvez soit utiliser un message existant spécifié dans le fichier de propriétés du message d'erreur approprié, soit créer un nouveau message stocké dans un nouveau fichier de propriétés. Comme spécifié précédemment, vous must not modifier l'un des fichiers de propriétés de message d'erreur prédéfinis.

Le snippet de code suivant montre un exemple de capture d'une exception d'application dans une commande :


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); 
}

L'objet ECMessage _ERR_CUSTOMER_INVALID précédent est défini comme suit :


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

Lors de la création de nouveaux messages utilisateur, vous devez les affecter avec un type d'UTILISATEUR, comme suit :


ECMessageType.USER

Le texte du message _ERR_CUSTOMER_INVALID est contenu dans le fichier ecCustomerMessages.properties. Ce fichier doit résider dans un répertoire qui se trouve dans le chemin d'accès de la classe. Le texte est défini comme suit :


_ERR_CUSTOMER_INVALID = Invalid ID "{0}"