Service de connexion test

WebSphere Application Server fournit un service de connexion test pour la validation des configurations des sources de données. L'opération testConnection instancie la configuration de la source de données puis ferme immédiatement la connexion.

Si la définition de la source de données comprend une variable WebSphere, vous pouvez déterminer de quelle manière les paramètres de portée définis à la fois pour la variable et la source de données peuvent affecter les résultats de la connexion test. L'étape suivante consiste à choisir laquelle des trois méthodes vous souhaitez utiliser pour activer le service de connexion test : par le biais de la console d'administration, de l'outil wsadmin ou d'un programme Java™ autonome.

Vérification des paramètres de portée

L'association de variables WebSphere à vos configurations de sources de données peut entraîner des résultats de connexion test qui ne sont pas cohérents avec le comportement d'exécution de votre application. Dans certains cas, une opération de connexion test échoue, alors que la source physique de données fonctionne normalement lors de l'exécution. L'origine du conflit potentiel réside dans la différence entre la façon dont votre serveur d'applications traite les paramètres de portée des variables WebSphere lors de l'exécution et la façon dont il traite ces même paramètres de portée pour une opération de connexion test. Comprendre cette différence vous permet de créer des configurations de sources de données avec succès.

Lors de l'exécution, WebSphere Application Server appelle une source de données physique en résolvant la variable appropriée au niveau de la portée lorsque l'un des critères suivants est présent :
  • La portée de la variable peut contenir la configuration de la source de données ; ce qui signifie que la variable dispose de la portée la plus importante.
  • Les portées de la variable et la source de données sont identiques.
Le serveur d'applications répond à ces conditions en tentant de résoudre la variable à chaque niveau du spectre de portée. En d'autres termes, le produit essaie de résoudre la variable dans la portée du serveur, puis dans la portée du cluster, ensuite dans la portée du noeud, et finalement dans la portée de la cellule.
Néanmoins, le serveur d'applications teste les connexions sur une portée uniquement ; il effectue l'opération de test dans la JVM de la même portée que celle de la configuration de la source de données. Le produit tente de résoudre la variable de chemin de classe du pilote pour cette portée uniquement.
Tableau 1. Corrélation de la portée de la source de données avec la connexion test JVM. Corrélation de la portée de la source de données de cellule, noeud, cluster et serveur avec la connexion test JVM correspondante où l'opération s'est produite.
Portée de la source de données JVM dans lequel l'opération de connexion test se produit
Cell Processus du gestionnaire
Node Processus de l'agent du noeud (du noeud correspondant)
Cluster Agent du noeud pour chaque noeud contenant un membre de cluster
Serveur Serveur ; si le serveur n'est pas disponible, l'opération de connexion test est de nouveau tentée dans l'agent du noeud qui contient le serveur d'applications.
[z/OS]Restriction : Dans une implémentation Network Deployment du serveur d'applications, vous ne pouvez pas tester des connexions pour les sources de données suivantes au niveau du noeud ou du cluster :
  • Source de données IBM Data Server Driver for JDBC and SQLJ avec le pilote de type 2
  • Source de données DB2 Universal JDBC Driver Provider avec le pilote de type 2
Vous pouvez créer des configurations de niveau noeud ou cluster des sources de données utilisées par l'application ; ces configurations doivent fonctionner correctement dans l'environnement d'exécution. Pour exécuter avec succès le test de connexion sur les sources de données cependant, vous devez tester les sources de données au niveau du serveur uniquement. Le serveur d'applications émettra l'exception suivante pour un test de connexion au niveau du noeud :
java.sql.SQLException: Failure in loading T2 native library db2jcct2DSRA0010E: SQL state = null, Error Code = -99,999
Dans certains cas cependant, l'erreur peut être similaire au message suivant :
T2zOS exception: [jcc][T2zos]T2zosReusableConnection.flowConnect:initRRSAFAttach
:2528: Connection dead
Ces deux sources de données sont basées sur des pilotes JDBC de type 2 qui doivent accéder aux bibliothèques natives T2. L'environnement d'exécution du serveur d'applications offre cet accès pour les sources de données dans un processus serveur, mais le service de connexion test n'offre pas l'accès à ces fichiers natifs lorsqu'il s'exécute dans le processus agent de noeud.

Ainsi, lorsque vous créez ces sources de données au niveau du noeud ou du cluster, vous pouvez souhaiter créer temporairement les mêmes configurations au niveau d'un serveur à des fins de test. Exécutez l'opération de connexion test au niveau du serveur pour déterminer si les paramètres de source de données sont valides pour la configuration globale.

Si la portée de la variable WebSphere est inférieure à celle de la source de données, l'opération de connexion test échoue. Le tableau suivant répertorie les scénarios à l'origine de cet échec, ainsi que ceux qui réussissent.
Tableau 2. Résultats de la connexion test pour les différentes combinaisons de source de données et de variable WebSphere. Les résultats du test pour les différentes combinaisons de source de données et de variable WebSphere sont affichés dans la table.
Portée de la source de données Variables de niveau cellule Variables de niveau noeud Variables de niveau serveur
Niveau de la cellule Réussite Echec Echec
Niveau noeud Réussite Réussite Echec
Niveau du serveur Réussite Réussite Réussite

Contrairement à ce que l'on pourrait attendre, ces échecs de connexion test ne se traduisent généralement pas par des échecs d'exécution. Vérifiez que l'emplacement des fichiers du pilote JDBC est accessible à tous les clients qui doivent utiliser la source de données et configurez la variable WebSphere avec le chemin complet de l'emplacement.

Une des combinaisons de portée répertoriées dans le tableau 2 peut néanmoins produire le scénario inverse : l'opération de connexion test se déroule correctement, mais la source de données échoue au moment de l'exécution. Cette anomalie survient dans le cas d'une source de données de niveau cellule qui utilise une variable WebSphere. Le test de connexion réussit car l'opération dans le processus du gestionnaire de déploiement (comme indiqué au tableau 1), dans lequel le serveur d'applications peut résoudre la variable de niveau cellule. La source de données peut échouer pendant l'exécution car la variable de niveau cellule peut être remplacée par une valeur nulle.

Lorsque vous créez un noeud, le serveur d'applications crée des variables d'environnement pour tous les pilotes JDBC pris en charge au niveau du noeud, et initialise chaque variable avec une chaîne vide. Un serveur d'applications tentant de résoudre des variables de la borne inférieure du spectre de portée à la borne supérieure, la variable de niveau noeud remplace celle de niveau cellule à l'exécution. Le serveur lit la chaîne vide et l'accepte comme chemin de classes du pilote JDBC. Ce chemin de classe nulle entraîne une exception classNotFound lorsque le serveur tente d'utiliser la source de données.

Avec l'une des options d'administration du serveur d'applications, vous pouvez empêcher la chaîne vide de devenir la valeur finale de la variable de chemin de classes du pilote.

  • Utilisation de la console d'administration WebSphere Application Server : l'assistant de source de données copie la valeur de la variable de niveau cellule (définie dans l'assistant de création du fournisseur JDBC) dans la variable de niveau noeud de même nom. L'assistant effectue cette copie uniquement si la variable de niveau noeud contient la valeur de chaîne vide ; ainsi, le programme ne modifie pas un chemin de classe valide défini précédemment.
    Pour vous assurer que la source de données fonctionne avec la variable de niveau noeud à l'exécution, procédez comme suit :
    1. Installez les fichiers du pilote JDBC sur le noeud du gestionnaire de déploiement, ainsi que sur les noeuds sur lesquels la source de données doit fonctionner.
    2. Définissez la variable WebSphere d'un fournisseur JDBC au niveau cellule à l'aide du chemin des fichiers du pilote sur le gestionnaire de déploiement.
    3. Vérifiez que la source de données est associée au fournisseur JDBC du gestionnaire de déploiement et qu'elle est associée au même niveau de cellule.
      Important : Pour garantir la réussite, installez les fichiers du pilote à des emplacements avec des noms complets identiques sur tous les noeuds, y compris le noeud du gestionnaire de déploiement. Sinon, le même scénario de réussite de connexion test, mais avec échec de l'exécution, est susceptible de se produire.
  • Utilisation de l'outil de script wsadmin : pour faire fonctionner la source de données lors de l'opération de connexion test et de l'exécution, créez des configurations de chemins de classes de pilotes identiques au niveau cellule et à tous les niveaux noeud appropriés. Procédez comme suit :
    1. Installez les fichiers du pilote JDBC sur le noeud du gestionnaire de déploiement ; utilisez ce nom de chemin pour définir la variable du chemin de classe du pilote pour un fournisseur JDBC au niveau de la cellule.
    2. Vérifiez que la source de données est associée au fournisseur JDBC du gestionnaire de déploiement et qu'elle est associée au même niveau de cellule.
    3. Sur chaque noeud sur lequel la source de données doit être opérationnelle, installez les fichiers du pilote JDBC et utilisez le chemin pour définir la variable WebSphere au niveau du noeud. Chacun de ces fournisseurs doit disposer de la même configuration.
      Important : Pour garantir la réussite, installez les fichiers du pilote à des emplacements avec des noms complets identiques sur tous les noeuds, y compris le noeud du gestionnaire de déploiement. Sinon, le même scénario de réussite de connexion test, mais avec échec de l'exécution, est susceptible de se produire.

Utilisez les ressources de niveau cellule uniquement si tous les noeuds qui doivent accéder à la source de données, y compris le noeud du gestionnaire de déploiement, s'exécutent sur la même plateforme et si les pilotes JDBC sont installés au même emplacement. Sinon, utilisez le niveau noeud comme paramètre de portée la plus importante pour les sources de données.

Contournement des recherches de variables

Vous pouvez ignorer les recherches de variables d'environnement en changeant les entrées de chemin de classe pour le fournisseur JDBC en valeurs codées en dur. Cependant, cette stratégie ne réussit que si vous définissez le chemin de classe à l'identique de celui de tous les noeuds sur lesquels la source de données doit fonctionner.

Activation du service de connexion test

Vous pouvez activer le service de connexion test via la console d'administration, l'outil wsadmin ou un programme Java autonome. Chaque processus appelle les mêmes méthodes sur le même MBean.

Console d'administration

WebSphere Application Server vous permet de tester une connexion à partir de la console d'administration en appuyant simplement sur un bouton : les pages Collection de sources de données, Paramètres de la source de données, Collection de sources de données (version 4) et Paramètres de la source de données (version 4) contiennent toutes un bouton Connexion Test. Après avoir défini et sauvegardé une source de données, vous pouvez cliquer sur ce bouton pour vous assurer que les paramètres contenus dans la définition de la source de données sont corrects. Dans la page de la collection, vous pouvez sélectionner plusieurs sources de données et les tester toutes à la fois. Certaines conditions doivent d'abord être remplies. Pour plus d'informations, voir la rubrique Test d'une connexion avec la console d'administration.

Remarque : L'erreur suivante se produit lorsque vous cliquez sur Connexion test pour connecter une source de données Sybase à partir de la console d'administration.
La connexion test a échoué pour la source de données isagent sur le serveur server1 sur le noeud 
svtaix24Node01 avec l'erreur suivante : java.lang.Exception: 
java.sql.SQLException: JZ006: Caught IOException: java.net.ConnectException: A 
Hôte distant a refusé une tentative de connexion. DSRA0010E: SQL State = JZ006, 
Error Code = 0
Cette erreur se produit lorsque le numéro de port de la source de données Sybase ne correspond pas au port configuré sur le serveur Sybase. Le numéro de port par défaut est 5000. Vérifiez le numéro de port du serveur Sybase dans le fichier des interfaces sous /<sybase install directory>.

Outil WsAdmin

L'outil wsadmin fournit une interface de script pour une gamme complète de fonctions d'administration de WebSphere Application Server. Etant donné que la fonctionnalité Test Connection est implémentée en tant que méthode sur un MBean et que wsadmin peut appeler les méthodes de MBean, wsadmin peut être employé pour tester les connexions aux sources de données. Vous disposez de deux options pour tester une connexion de source de données via wsadmin :

L'objet AdminControl de wsadmin comporte une opération testConnection, qui teste les propriétés de configuration d'un objet source de données. Pour plus d'informations, reportez-vous à la rubrique Test d'une connexion avec wsadmin.

Vous pouvez aussi tester une connexion en appelant l'opération MBean. Utilisez la rubrique "Exemple : Test d'une connexion à la source de données à l'aide de wsadmin" comme guide pour appliquer cette technique.

Programme autonome Java

Vous pouvez tester une connexion en exécutant la méthode testConnection sur le MBean DataSourceCfgHelper. Cette méthode vous permet de transmettre l'ID de configuration de la source de données configurée. Le programme Java se connecte à un serveur JMX (Java Management Extensions) pour accéder au MBean. Dans une installation WebSphere Application Server, Network Deployment d'Application Server, vous vous connectez au serveur JMX qui s'exécute dans le gestionnaire de déploiement, généralement sur le port 8879.

La valeur renvoyée par cet appel est 0, un nombre positif ou une exception. 0 indique que l'opération a abouti, sans avertissement. Un nombre positif indique que l'opération a abouti, avec un certain nombre d'avertissements. Une exception indique que le test de la connexion a échoué.

Remarque : Exemple : Test d'une connexion à l'aide de testConnection(ConfigID).

L'échantillon de code suivant crée une instance de source de données et une instance de connexion associée, et les teste pour s'assurer de la connectivité de la base de données.

Ce programme utilise JMX pour établir une connexion avec un serveur en cours d'exécution et appeler la méthode testConnection sur le MBean DataSourceCfgHelper. L'acronyme ND dans une ligne commentaire indique que le code qui suit concerne WebSphere Application Server WebSphere Application Server, Network Deployment. Le mot Base dans une ligne commentaire indique que le code qui suit s'applique à WebSphere Application Server.

/**
 * Description
 * Programme de test d'adaptateur de ressources vérifiant que les interfaces du MBean fonctionnent.
 * Les interfaces suivantes sont testées :
 * 
 *  ---  testConnection()
 * 
 * 
 * L'environnement suivant doit être préalablement défini
 * C:\src>java -Djava.ext.dirs=C:\WebSphere\AppServer\lib;C:\WebSphere\AppServer\java\jre\lib\ext testDSGUI
 * doit comporter le jre pour log.jar et mail.jar, sinon l'exception de classe introuvable est émise
 * 
 * 
 */

import java.util.Iterator;
import java.util.Locale;
import java.util.Properties;
import java.util.Set;

import javax.management.InstanceNotFoundException;
import javax.management.MBeanException;
import javax.management.MalformedObjectNameException;
import javax.management.ObjectName;
import javax.management.RuntimeMBeanException;
import javax.management.RuntimeOperationsException;

import com.ibm.websphere.management.AdminClient;
import com.ibm.websphere.management.AdminClientFactory;
import com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException;

public class testDSGUI {

//Utilisez le port 8880 pour l'installation de base ou le port 8879 pour l'installation ND
String port = "8880";
// String port = "8879";
String host = "localhost";
final static boolean verbose = true;

// exemple : ID de configuration pour source de données déclarée au niveau du noeud pour une installation de base
private static final String resURI = "cells/cat/nodes/cat|resources.xml#DataSource_1";

// exemple : source de données 4.0 déclarée au niveau du noeud pour une installation de base
//    private static final String resURI = "cells/cat/nodes/cat|resources.xml#WAS40DataSource_1";

// exemple : source de données Apache Derby déclarée au niveau du serveur pour une installation de base
//private static final String resURI = "cells/cat/nodes/cat/servers/server1/resources.xml#DataSource_6";

// exemple : source de données au niveau du noeud pour une installation ND
//private static final String resURI = "cells/catNetwork/nodes/cat|resources.xml#DataSource_1";

// exemple : source de données au niveau du serveur pour une installation ND
//private static final String resURI = "cells/catNetwork/nodes/cat/servers/server1|resources.xml#DataSource_4";

// exemple : source de données au niveau de la cellule pour une installation ND
//private static final String resURI = "cells/catNetwork|resources.xml#DataSource_1";

 public static void main(String[] args) {
  testDSGUI cds = new testDSGUI();
  cds.run(args);
 }

/**
 * Cette méthode teste l'objet ResourceMbean.
 * 
 * @param args
 * @exception Exception
 */
 public void run(String[] args) {

  try {

	System.out.println("Connexion au serveur d'applications.......");

        /*************************************************************************/
        /**    Initialisation d'AdminClient                                     */
        /*************************************************************************/	
	Properties adminProps = new Properties();
	adminProps.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
	adminProps.setProperty(AdminClient.CONNECTOR_HOST, host);
	adminProps.setProperty(AdminClient.CONNECTOR_PORT, port);
	AdminClient adminClient = null;
	try {
	    adminClient = AdminClientFactory.createAdminClient(adminProps);
	} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
  	    System.out.println("NLS : Impossible d'établir une connexion au serveur d'applications\n");
	    ce.printStackTrace();
	    System.exit(1);
	}

       /*************************************************************************/
       /**    Recherche du Mbean                                                */
       /*************************************************************************/
	ObjectName handle = null;
	try {
                // Envoyer dans une chaîne de pointeur vers une adresse http 
                // par ex., le texte suivant suffit pour une installation de base
                ObjectName queryName = new ObjectName("WebSphere:type=DataSourceCfgHelper,*");

                // Pour une installation ND, vous devez indiquer le noeud/processus à partir                 // duquel le test doit être effectué
                // par ex., sur le serveur
//ND: ObjectName queryName = new OjectName
				("WebSphere:cell=catNetwork,node=cat,process=server1,type=DataSourceCfgHelper,*");
                // par ex., sur l'agent de noeud
//ND: ObjectName queryName = new ObjectName
				("WebSphere:cell=catNetwork,node=cat,process=nodeagent,type=DataSourceCfgHelper,*");
//ND: eg run in the   Manager
//ND: ObjectName queryName = new ObjectName
			("WebSphere:cell=catNetwork,node=catManager,process=dmgr,type=DataSourceCfgHelper,*");
	Set s = adminClient.queryNames(queryName, null);
	Iterator iter = s.iterator();
	while (iter.hasNext()) {
                // utiliser le premier MBean trouvé
	 	handle = (ObjectName) iter.next();
		System.out.println("Found this ->" + handle);
		}
		if (handle == null) {
			System.out.println("NLS: Did not find this MBean>>" + queryName);
			System.exit(1);
		}
	} catch (MalformedObjectNameException mone) {
		System.out.println("Vérifiez la variable programme queryName" + mone);
	} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
		System.out.println("Impossible de se connecter au serveur d'applications" + ce);
	}

         /*************************************************************************/
         /**           Paramètres de génération à transmettre au MBean                          */
         /*************************************************************************/
	String[] signature = { "java.lang.String" };
	Object[] params = { resURI };
	Object result = null;

       	if (verbose) {
		System.out.println("\nTest de la connexion à la base de données en utilisant " +  handle);
	}

	try {
               /*************************************************************************/
               /**  Lancez le test de connexion à la base de données                    */
               /*************************************************************************/
		result = adminClient.invoke(handle, "testConnection", params, signature);
	} catch (MBeanException mbe) {
		// ****** toutes les exceptions utilisateur figurent ici
		if (verbose) {
			Exception ex = mbe.getTargetException(); // il s'agit de l'exception réelle provenant du MBean
			System.out.println("\nNLS : l'exception Mbean qui a été reçue contient " + ex);
			ex.printStackTrace();
			System.exit(1);
		}
	} catch (InstanceNotFoundException infe) {
		System.out.println("Impossible de trouver " + infe);
	} catch (RuntimeMBeanException rme) {
		Exception ex = rme.getTargetException();
		ex.printStackTrace(System.out);
		throw ex;
	} catch (Exception ex) {
		System.out.println("\nUne exception inattendue s'est produite : " + ex);
		ex.printStackTrace();
	}

         /*************************************************************************/
         /**  Traitez le résultat.  Ce sera le nombre d'avertissements             */
         /**  émis.  Un résultat égal à 0 indique l'établissement d'une connexion  */
         /**  avec aucun avertissement.                                                        */
         /*************************************************************************/

	//Un résultat égal à 0 indique l'établissement d'une connexion avec aucun avertissement.
	System.out.println("Result= " + result);

  } catch (RuntimeOperationsException roe) {
	Exception ex = roe.getTargetException();
	ex.printStackTrace(System.out);
  } catch (Exception ex) {
	System.out.println("Une exception générale s'est produite");
	ex.printStackTrace(System.out);
  }
 }
}
Conseil : Vérifiez que vous exécutez le service de connexion test au même niveau qu'une source de données existante. Par exemple, n'exécutez pas le service de connexion test au niveau du noeud si votre source de données est configurée au niveau du serveur. Si le service de connexion test et la source de données ne sont pas au même niveau, un incident de chargement se produit. Dans cette situation, recherchez la source du script db2profile sur l'ordinateur et vérifiez que l'environnement contient des pointeurs désignant les bibliothèques natives DB2. Le script db2profile se trouve dans le répertoire racine de l'ID utilisateur DB2.

Icône indiquant le type de rubrique Rubrique de concept



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cdat_testcon
Nom du fichier : cdat_testcon.html