Développement d'un programme client d'administration

Vous pouvez développer un programme client d'administration qui utilise les API (Interfaces de programmation d'application) d'administration de WebSphere Application Server et les extensions JMX (Java™ Management Extensions).

Pourquoi et quand exécuter cette tâche

Les API d'administration du produit permettent de contrôler les aspects opérationnels de votre système distribué et offrent la possibilité de mettre à jour votre configuration. Pour plus d'informations sur l'interface AdminClient, voir la documentation des interfaces de programme d'application.

Voir les exemples d'opération de bean géré. Pour plus d'informations sur la programmation MBean, voir la documentation sur l'API Java MBean. Dans le centre de documentation, cliquez sur Référence > Interfaces de programmation > Interfaces Mbean.

Procédure

  1. Créez une instance AdminClient.

    Un programme client d'administration doit appeler des méthodes sur l'objet AdminService qui est en cours d'exécution dans le gestionnaire de déploiement ou sur le serveur d'applications dans l'installation de base.

    La classe AdminClient fournit un proxy vers l'objet AdminService distant à travers l'un des connecteurs JMX (Java Management Extensions) pris en charge.
    • L'exemple suivant montre comment créer une instance AdminClient pour le connecteur SOAP (Simple Object Access Protocol) :
      Properties connectProps = new Properties();
      connectProps.setProperty(
      AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
      
      connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
      connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8879");
      connectProps.setProperty(AdminClient.USERNAME, "test2");
      connectProps.setProperty(AdminClient.PASSWORD, "user24test");
      AdminClient adminClient = null;
      try
      {
             adminClient = AdminClientFactory.createAdminClient(connectProps);
      }
      catch (ConnectorException e)
      {
             System.out.println("Exception creating admin client: " + e);
      }
      1. Configurez un objet Propriétés.

        L'exemple configure un objet Propriétés avec les propriétés requises pour accéder au serveur. Dans ce cas, vous utilisez le connecteur SOAP pour accéder au serveur. Pour le type de connecteur, utilisez la valeur AdminClient.CONNECTOR_TYPE_SOAP.

      2. [AIX Solaris HP-UX Linux Windows][IBM i]Pour simplifier la procédure, exécutez le programme client sur le même système que le serveur. Utilisez localhost pour le nom du serveur.

        Pour accéder à un hôte éloigné au lieu d'un hôte local, utilisez un nom réseau qui peut être résolu pour cet hôte.

      3. Définissez le numéro de port que le connecteur SOAP du serveur écoute.

        Dans une configuration comportant un seul serveur, le numéro de port par défaut du connecteur SOAP sur le serveur d'applications est 8880. Dans une installation WebSphere Application Server, Network Deployment, le numéro de port par défaut du connecteur SOAP pour le gestionnaire de déploiement est 8879.

      4. Une fois que les propriétés de la connexion sont définies, utilisez la classe AdminClientFactory et l'objet Propriétés pour créer un objet AdminClient connecté au serveur sélectionné.

        En fonction de certains facteurs, tels que le protocole et l'environnement de sécurité choisis, vous pouvez être amené à définir d'autres propriétés. Par exemple, si vous activez la sécurité pour votre programme de client d'application, incluez les propriétés javax.net.ssl.*. Pour obtenir des informations plus détaillées sur l'interface AdminClient, sur les propriétés javax.net.ssl.* et sur des exemples de création supplémentaires, voir la documentation relative aux interfaces de programmation de l'application.

    • L'exemple suivant montre comment créer une instance AdminClient pour le connecteur RMI (Remote Method Invocation). Certaines commandes sont réparties sur plusieurs lignes pour des raisons d'affichage.
      Properties connectProps = new Properties();
      connectProps.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_RMI);
      connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
      connectProps.setProperty(AdminClient.CONNECTOR_PORT, "2809");
      connectProps.setProperty(AdminClient.USERNAME, "test2");
      connectProps.setProperty(AdminClient.PASSWORD, "user24test");
      System.setProperty("com.ibm.CORBA.ConfigURL", 
       "file:C:/AA/cf010839.26/profiles/AppSrv02/properties/sas.client.props");
      System.setProperty("com.ibm.SSL.ConfigURL", 
       "file:C:/AA/cf010839.26/profiles/AppSrv02/properties/ssl.client.props");
      AdminClient adminClient = null;
      try
      {
             adminClient = AdminClientFactory.createAdminClient(connectProps);
      }
      catch (ConnectorException e)
      {
             System.out.println("Exception creating admin client: " + e);
      }
      Configurations prises en charge Configurations prises en charge: Lorsque vous utilisez la méthode createAdminClient dans un code d'application qui s'exécute sur un serveur d'applications, comme dans des servlets et des fichiers JSP (JavaServer Pages), vous devez définir la propriété CACHE_DISABLED sur true. Par exemple :
      connectProps.setProperty(AdminClient.CACHE_DISABLED, "true");
      sptcfg
      1. Configurez un objet Propriétés.

        L'exemple configure un objet Propriétés avec les propriétés requises pour accéder au serveur. Dans ce cas, vous utilisez le connecteur RMI (Remote Method Invocation) pour accéder au serveur. Pour le type de connecteur, utilisez la valeur AdminClient.CONNECTOR_TYPE_RMI.

      2. [AIX Solaris HP-UX Linux Windows][IBM i]Pour simplifier la procédure, exécutez le programme client sur le même système que le serveur. Utilisez localhost pour le nom du serveur.

        Pour accéder à un hôte éloigné au lieu d'un hôte local, utilisez un nom réseau qui peut être résolu pour cet hôte.

      3. Définissez le numéro de port sur lequel le connecteur RMI du serveur est en mode écoute.

        Dans une configuration comportant un seul serveur, le numéro de port par défaut du connecteur RMI sur le serveur d'applications est 2809. Dans une installation WebSphere Application Server, Network Deployment, le numéro de port par défaut du connecteur RMI pour le gestionnaire de déploiement est 9809.

      4. Une fois que les propriétés de la connexion sont définies, utilisez la classe AdminClientFactory et l'objet Propriétés pour créer un objet AdminClient connecté au serveur sélectionné.

        En fonction de certains facteurs, tels que le protocole et l'environnement de sécurité choisis, vous pouvez être amené à définir d'autres propriétés. Par exemple, si vous activez la sécurité pour votre programme de client d'application, vous devez définir un propriété système pour pointer vers le fichier ssl.client.props le fichier sas.client.props. Si vous utilisez une machine locale, vous pouvez pointer sur l'emplacement courant. Si vous utilisez une machine distante, vous pouvez copier ces fichiers de propriétés à partir du serveur de la machine et les mettre où vous voulez en spécifiant le chemin de leur emplacement.

        Vous pouvez indiquer un nom d'utilisateur et un mot de passe dans le fichier sas.client.props. Quand vous le faites, indiquez com.ibm.CORBA.loginSource=properties. Si vous voulez définir le nom d'utilisateur et le mot de passe à l'intérieur de votre programme client, indiquez com.ibm.CORBA.loginSource=none dans le fichier sas.client.props.

  2. Recherchez un MBean.

    Lorsque vous obtenez une instance AdminClient, vous pouvez l'utiliser pour accéder aux ressources gérées sur les serveurs d'administration et les serveurs d'applications. Chaque ressource gérée enregistre un MBean auprès de l'AdminService par le biais duquel vous pouvez accéder à la ressource. Le MBean est représenté par une instance ObjectName qui identifie le MBean. Une instance ObjectName se compose d'un nom de domaine suivi d'un ensemble non ordonné d'une ou plusieurs propriétés de clé. La syntaxe du nom de domaine est la suivante :

    [domainName]:property=value[,property=value]*
    Pour WebSphere Application Server, le nom de domaine est WebSphere et les propriétés de clé définies pour l'administration sont les suivantes :
    Tableau 1. Descriptions des propriétés de clé. Les propriétés de clé sont les suivantes : types, name, cell, node et process.
    Propriété de clé Description
    type Type de MBean. Par exemple : Serveur, TraceService, Machine virtuelle Java (JVM).
    Nom Nom identificateur pour l'instance individuelle du MBean.
    cellule Nom de la cellule que le MBean exécute.
    noeud Nom du noeud que le MBean exécute.
    process Nom du processus que le MBean exécute.

    Certains MBeans dans WebSphere Application Server utilisent des propriétés de clé supplémentaires. Un MBean dépourvu de propriétés de clé peut être enregistré auprès du serveur de MBeans dans un processus de WebSphere Application Server. Toutefois, ce type de MBean ne peut pas être utilisé avec les nouvelles fonctionnalités distribuées du produit, telles que le routage de requêtes, la notification d'événements distribués, etc.

    Si vous connaissez l'ensemble de propriétés de clé d'une instanceObjectName, vous pouvez l'utiliser pour rechercher le MBean qu'il identifie. Toutefois, il est généralement plus pratique de rechercher des MBeans sans avoir à connaître toutes leurs propriétés de clé. Utilisez le caractère générique astérisque (*) pour toutes les propriétés de clé qui ne doivent pas forcément être concordantes. Le tableau suivant fournit des exemples de noms d'objet avec des propriétés de clé associées à un caractère générique, correspondant à un ou plusieurs MBeans.
    Tableau 2. Exemples de noms d'objet avec des propriétés de clé associées à un caractère générique. Incluez des astérisques (*) pour indiquer des propriétés de clé génériques.
    Nom d'objet Description
    *:type=Serveur,* Tous les MBeans de type Serveur
    *:node=Noeud1,type=Serveur,* Tous les MBeans de type Serveur sur Noeud1
    *:type=JVM,process=serveur1,node=Noeud1,* MBean de la JVM sur le système serveur1 du noeud Noeud1
    *:process=serveur1,* Tous les MBeans de tous les serveurs appelés serveur1
    *:process=serveur1,node=Noeud1,* Tous les MBeans du serveur appelé serveur1 sur Noeud1

    Vous pouvez rechercher un MBean en émettant une requête le concernant avec des objets correspondant aux propriétés de clé souhaitées. L'exemple suivant explique comment rechercher le MBean pour l'agent du noeud MyNode :

    String nodeName = "MyNode";
    String query = "WebSphere:type=NodeAgent,node=" + nodeName + ",*";
    ObjectName queryName = new ObjectName(query);
    ObjectName nodeAgent = null;
    Set s = adminClient.queryNames(queryName, null);
    if (!s.isEmpty())
        nodeAgent = (ObjectName)s.iterator().next();
    else
        System.out.println("Node agent MBean was not found");
    1. Créez une instance ObjectName avec une chaîne de requête indiquant les propriétés de clé type et node.

      Si vous utilisez le caractère générique pour le reste des propriétés de clé, ce masque permet d'obtenir les noms d'objet de tous les Mbeans dont le type et le noeud correspondent respectivement à NodeAgent et MyNode. Comme il n'existe qu'un seul agent de noeud par noeud, ces informations sont suffisantes pour identifier le MBean recherché.

    2. Transmettez cette instance ObjectName à la méthode queryNames de l'interface AdminClient.

      L'interface AdminClient effectue l'appel éloigné de l'interface AdminService pour obtenir un ensemble de noms d'objet MBean correspondant à la requête. Le second paramètre nul transmis à cette méthode est un objet expression de requête(QueryExp) que vous pouvez utiliser comme requête supplémentaire pour obtenir les MBeans correspondant au masque ObjectName du premier paramètre.

    3. Utilisez l'itérateur défini pour obtenir le premier et, dans le cas présenté ici, le seul élément.

      L'élément est l'instance ObjectName du MBean de l'agent de noeud.

  3. Utilisez le MBean.

    Les opérations qu'un MBean spécifique peut effectuer varient en fonction de l'interface de ce MBean. Un MBean peut déclarer :

    • Les attributs que vous pouvez extraire ou définir
    • Les opérations que vous pouvez invoquer
    • Les notifications pour lesquelles vous pouvez enregistrer des modules d'écoute
    Vous trouverez des informations sur les MBeans fournis par WebSphere Application Server et sur les interfaces qu'ils prennent en charge dans la documentation de l'API MBean. L'exemple suivant appelle l'une des opérations disponibles sur le MBean NodeAgent recherché plus haut. L'exemple suivant démarre le serveur d'applications MyServer :
    String opName = "launchProcess";
    String signature[] = { "java.lang.String" };
    String params[] = { "MyServer" };
    try
    {
         adminClient.invoke(nodeAgent, opName, params, signature);
    }
    catch (Exception e)
    {
         System.out.println("Exception invoking launchProcess: " + e);
    }
    La méthode AdminClient.invoke est la procédure générique à utiliser pour appeler une opération sur un Mbean. Les paramètres sont les suivants :
    • Le nom d'objet du MBean cible, nodeAgent
    • Le nom de l'opération, opName
    • Un tableau d'objets contenant les paramètres de l'opération,params
    • Un tableau de chaînes contenant la signature de la signature, signature
    L'opération launchProcess de l'exemple possède un paramètre unique correspondant à une chaîne unique qui identifie le serveur à démarrer.

    La méthode appelée renvoie une instance d'objet, que le code appelant peut utiliser pour générer le type de renvoi approprié pour l'opération invoquée. L'opération launchProcess est déclarée nulle (void) afin que vous puissiez ignorer la valeur retournée dans cet exemple.

  4. Enregistrez-vous pour obtenir des notifications d'événements.

    Outre la gestion des ressources, l'API JMX prend également en charge la surveillance des applications pour les événements d'administration spécifiques. Certains événements génèrent des notifications, par exemple, le démarrage d'un serveur. Les applications d'administration peuvent s'enregistrer comme programmes d'écoute de ces notifications. WebSphere Application Server offre une implémentation totale du modèle de notification JMX ainsi que des fonctions supplémentaires permettant de recevoir des notifications en environnement distribué. Pour connaître la liste complète des notifications émises par les MBeans du produit, reportez-vous à la classe com.ibm.websphere.management.NotificationConstants dans la documentation de l'API MBean.

    L'exemple suivant explique comment un objet peut être enregistré pour recevoir des notifications d'événements émises par un MBean à l'aide de l'agent de noeud ObjectName :

    adminClient.addNotificationListener(nodeAgent, this, null, null);

    Dans cet exemple, le premier paramètre est ObjectName pour le MBean de l'agent de noeud. Le deuxième paramètre identifie l'objet module d'écoute, qui doit implémenter l'interface NotificationListener. Dans ce cas, l'objet appelant est le module d'écoute. Le troisième paramètre est un filtre que vous pouvez utiliser pour indiquer les notifications que vous souhaitez recevoir. Si vous conservez la valeur null, vous recevez toutes les notifications émises par ce MBean. Le dernier paramètre est un objet handback que vous pouvez utiliser pour définir l'API JMX API qui effectue le renvoi lors de l'émission d'une notification.

    Si le MBean se trouve sur un autre serveur de la cellule, vous pouvez recevoir ses notifications même si le programme client d'administration est connecté au serveur du gestionnaire de déploiement. Toutes les notifications sont transmises au serveur en amont. Par exemple, une notification d'un serveur d'applications est d'abord transmise à l'agent de noeud local, puis au gestionnaire de déploiement.

    Une autre fonction optimisée fournie par le serveur d'applications permet de s'enregistrer comme module d'écoute des notifications de plusieurs MBeans avec un seul appel. Cet enregistrement est effectué via la méthode addNotificationListenerExtended de l'interface AdminClient, une extension de la méthode addNotificationListener JMX standard. Cette méthode d'extension permet de s'enregistrer pour recevoir les notifications des MBeans qui ne sont pas actuellement actifs. L'enregistrement est important dans des situations où vous souhaitez surveiller des événements liés à des ressources qui peuvent être arrêtées et redémarrées lors de la période d'utilisation du programme client d'administration.

  5. Gérez les événements.

    Les objets reçoivent des notifications d'événements JMX via la méthode handleNotification, qui est définie par l'interface NotificationListener et que chaque destinataire d'événement doit implémenter. L'exemple suivant est une implémentation de la méthode handleNotification qui signale les notifications qu'elle reçoit :

    public void handleNotification(Notification n, Object handback)
    {
         System.out.println("***************************************************");
         System.out.println("* Notification received at " + new Date().toString());
         System.out.println("* type      = " + ntfyObj.getType());
         System.out.println("* message   = " + ntfyObj.getMessage());
         System.out.println("* source    = " + ntfyObj.getSource());
         System.out.println(
         "* seqNum    = " + Long.toString(ntfyObj.getSequenceNumber()));
         System.out.println("* timeStamp = " + new Date(ntfyObj.getTimeStamp()));
         System.out.println("* userData  = " + ntfyObj.getUserData());
         System.out.println("***************************************************");
    }

Résultats

Le client d'administration peut gérer des notification d'événements qui sont émises d'un bean géré.

Eviter les incidents Eviter les incidents: Si un programme client enregistre un programme d'écoute de notification via un connecteur RMI ou JSR160RMI et l'unité d'exécution ORB n'arrête pas son exécution et empêche ainsi la machine virtuelle Java de s'arrêter, ajoutez une instruction System.exit() au programme client. La fonction ORB démarre une unité d'exécution pour gérer la propagation de notification au client. Cette unité d'exécution ne s'arrête pas automatiquement avec l'unité d'exécution principale client, excepté si l'unité d'exécution principale a une instruction System.exit(). Placez une instruction System.exit() dans un emplacement du programme client qui permet à l'unité d'exécution ORB et à l'unité d'exécution principale d'arrêter le traitement. Par exemple, placez l'instruction System.exit() dans une clause catch ou finally du bloc try principal du programme client.gotcha

Exemple : Programme client d'administration

Copiez le contenu d'un fichier nommé AdminClientExample.java. Après avoir remplacé le nom du noeud et le nom du serveur par les noms appropriés à votre configuration, compilez et exécutez ce programme à l'aide des instructions fournies dans Création d'un programme client d'administration Java personnalisé utilisant les API Java d'administration WebSphere Application Server.
import java.util.Date;
import java.util.Properties;
import java.util.Set;

import javax.management.InstanceNotFoundException;
import javax.management.MalformedObjectNameException;
import javax.management.Notification;
import javax.management.NotificationListener;
import javax.management.ObjectName;

import com.ibm.websphere.management.AdminClient;
import com.ibm.websphere.management.AdminClientFactory;
import com.ibm.websphere.management.exception.ConnectorException;

public class AdminClientExample implements NotificationListener
{

    private AdminClient adminClient;
    private ObjectName nodeAgent;
    private long ntfyCount = 0;

    public static void main(String[] args)
    {
       AdminClientExample ace = new AdminClientExample();

       // Create an AdminClient
       ace.createAdminClient();

       // Find a NodeAgent MBean
       ace.getNodeAgentMBean("ellington");

       // Invoke launchProcess
       ace.invokeLaunchProcess("server1");

       // Register for NodeAgent events
       ace.registerNotificationListener();
        
       // Run until interrupted
       ace.countNotifications();
    }

    private void createAdminClient()
    {
        // Set up a Properties object for the JMX connector attributes
        Properties connectProps = new Properties();
        connectProps.setProperty(
        AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
        connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
        connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8879");
        
        // Get an AdminClient based on the connector properties
        try
        {
            adminClient = AdminClientFactory.createAdminClient(connectProps);
        }
        catch (ConnectorException e)
        {
            System.out.println("Exception creating admin client: " + e);
            System.exit(-1);
        }
        
        System.out.println("Connected to DeploymentManager");
    }
    
    
    private void getNodeAgentMBean(String nodeName)
    {
        // Query for the ObjectName of the NodeAgent MBean on the given node
        try
        {
            String query = "WebSphere:type=NodeAgent,node=" + nodeName + ",*";
            ObjectName queryName = new ObjectName(query);
            Set s = adminClient.queryNames(queryName, null);
            if (!s.isEmpty())
                nodeAgent = (ObjectName)s.iterator().next();
            else
            {
                System.out.println("Node agent MBean was not found");
                System.exit(-1);
            }
        }
        catch (MalformedObjectNameException e)
        {
            System.out.println(e);
            System.exit(-1);
        }
        catch (ConnectorException e)
        {
            System.out.println(e);
            System.exit(-1);
        }
        
        System.out.println("Found NodeAgent MBean for node " + nodeName);
    }
    
    private void invokeLaunchProcess(String serverName)
    {
        // Use the launchProcess operation on the NodeAgent MBean to start
        // the given server
        String opName = "launchProcess";
        String signature[] = { "java.lang.String" };
        String params[] = { serverName };
        boolean launched = false;
        try
        {
            Boolean b = (Boolean)adminClient.invoke(
            
nodeAgent, opName, params, signature);
            launched = b.booleanValue();
            if (launched)
                System.out.println(serverName + " was launched");
            else
                System.out.println(serverName + " was not launched");

        }
        catch (Exception e)
        {
            System.out.println("Exception invoking launchProcess: " + e);
        }
    }
    
    private void registerNotificationListener()
    {
        // Register this object as a listener for notifications from the
        // NodeAgent MBean.  Don't use a filter and don't use a handback
        // object.
        try
        {
            adminClient.addNotificationListener(nodeAgent, this, null, null);
            System.out.println("Registered for event notifications");
        }
        catch (InstanceNotFoundException e)
        {
            System.out.println(e);
            e.printStackTrace();
        }
        catch (ConnectorException e)
        {
            System.out.println(e);
            e.printStackTrace();
        }
    }
    
    public void handleNotification(Notification ntfyObj, Object handback)
    {
        // Each notification that the NodeAgent MBean generates will result in
        // this method being called
        ntfyCount++;
        System.out.println("***************************************************");
        System.out.println("* Notification received at " + new Date().toString());
        System.out.println("* type      = " + ntfyObj.getType());
        System.out.println("* message   = " + ntfyObj.getMessage());
        System.out.println("* source    = " + ntfyObj.getSource());
        System.out.println(
        "* seqNum    = " + Long.toString(ntfyObj.getSequenceNumber()));
        System.out.println("* timeStamp = " + new Date(ntfyObj.getTimeStamp()));
        System.out.println("* userData  = " + ntfyObj.getUserData());
        System.out.println("***************************************************");

    }
    
    private void countNotifications()
    {
        // Run until killed
        try
        {
            while (true)
            {
                Thread.currentThread().sleep(60000);
                System.out.println(ntfyCount + " notification have been received");
            }
        }
        catch (InterruptedException e)
        {
        }
    }
    
}

Icône indiquant le type de rubrique Rubrique de tâche



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=tjmx_develop
Nom du fichier : tjmx_develop.html