Extension du système d'administration WebSphere Application Server avec des MBeans personnalisés

Vous pouvez étendre le système d'administration WebSphere Application Server en fournissant et en enregistrant de nouveaux Mbeans JMX (Java™ Management Extensions) (pour plus de détails, voir la spécification JMX 1.x) dans l'un des processus WebSphere.

Pourquoi et quand exécuter cette tâche

Les MBeans JMX représentent l'interface de gestion pour une partie spécifique de la logique. Toutes les ressources gérées figurant dans l'infrastructure du produit standard, sont représentées sous la forme de MBeans JMX. Il existe différentes façons de créer vos propres MBeans et de les enregistrer auprès du MBeanServer JMX s'exécutant dans n'importe quel processus WebSphere. Pour plus d'informations, voir la documentation sur l'API (Application Programming Interface) Java MBean. Dans le centre de documentation, cliquez sur Référence > Interfaces Mbean.

Procédure

  1. Créez des MBeans JMX personnalisés.

    Vous avez le choix entre plusieurs approches pour créer des MBeans en vue d'étendre le système d'administration du produit. Vous pouvez utiliser n'importe quel MBean JMX existant d'une autre application. Vous pouvez enregistrer tout MBean testé dans un serveur JMX hors de l'environnement WebSphere Application Server au sein d'un processus du produit, incluant des MBeans standard, dynamiques, ouverts et modèle.

    En plus de tout MBean JMX existant et de ceux écrits et testés à l'extérieur de l'environnement du produit, vous pouvez utiliser des extensions réparties spéciales fournies par WebSphere et créer un fournisseur d'ExtensionMBean WebSphere. Cette alternative permet une meilleure intégration avec l'ensemble des fonctions réparties du système d'administration du produit. Un fournisseur d'ExtensionMBean implique que vous fournissiez un fichier XML qui contient un descripteur de MBean basé sur le DTD fourni avec le produit. Ce descripteur indique au système WebSphere l'ensemble des attributs, des opérations et des notifications que votre MBean prend en charge. Grâce à ces informations, le système WebSphere peut acheminer des demandes éloignées vers le MBean et enregistrer les modules d'écoute éloignés pour qu'ils reçoivent les notifications d'événements du MBean.

    Tous les MBeans internes de WebSphere suivent la structure du MBean modèle. Les classes Java pures fournissent la véritable logique des fonctions de gestion et la classe MBeanFactory de WebSphere lit la description de ces fonctions à partir du descripteur de MBean XML et crée une instance d'un ModelMBean qui correspond au descripteur. Cette instance de ModelMBean est liée à vos classes Java et elle est enregistrée auprès du MBeanServer qui s'exécute dans le même processus que vos classes. Votre code Java est désormais appelable à partir de n'importe quel client d'administration WebSphere Application Server par le biais du ModelMBean créé et enregistré pour le représenter.

    [z/OS]Les Mbeans utilisateur exécutés à la fois sur les plateformes réparties WebSphere Application Server et la plateforme WebSphere Application Server for z/OS peuvent nécessiter un codage spécial pour fonctionner correctement dans le modèle de processus multiples z/OS. Il n'existe qu'un seul serveur de Mbean sur les plateformes où chaque serveur d'applications est exécuté sur une seule machine virtuelle Java (JVM). Le serveur MBean contrôle tous les MBeans enregistrés auprès de ce serveur d'applications. Sur la plateforme z/OS, il existe un processus de contrôle et une fédération de processus serviteur, chacun d'eux possédant son propre serveur de MBean. Le processus de contrôle dispose de son propre serveur proxy de MBean pour répartir les requêtes entre les processus serviteur. Voir la représentation détaillée du flux de requêtes du modèle de processus multiples MBeans JMX.

  2. Définissez éventuellement une règle de sécurité du MBean explicite.

    Si vous ne définissez pas de règle de sécurité du MBean, le produit utilise la règle de sécurité par défaut.

  3. Enregistrez les nouveaux MBeans. L'enregistrement du MBean peut se faire de diverses manières.

    Vous pouvez l'enregistrer avec le service d'administration de WebSphere Application Server.

    Vous pouvez également l'enregistrer avec le serveur MBean dans un processus WebSphere Application Server. La liste qui suit décrit les options disponibles dans l'ordre de préférence :
    • Utilisez la classe MBeanFactory. Si vous souhaitez une intégration maximale avec le système WebSphere Application Server, utilisez la classe MBeanFactory pour gérer le cycle de vie de votre MBean par le biais des méthodes activateMBean et deactivateMBean de la classe MBeanFactory. Utilisez ces méthodes en fournissant une sous-classe de la superclasse abstraite RuntimeCollaborator et un fichier de descripteur du MBean XML. En utilisant cette approche, vous fournissez une classe Java pure qui implémente l'interface de gestion définie dans le descripteur du MBean. La classe MBeanFactory crée le ModelMBean réel et l'enregistre auprès du système d'administration du produit pour votre compte.

      Cette option est conseillée pour l'enregistrement de MBeans modèle.

    • Utilisez l'interface JMXManageable et CustomService. Vous pouvez simplifier davantage le processus d'intégration avec l'administration WebSphere en implémentant une interface CustomService qui elle-même implémente l'interface JMXManageable. Cette approche vous évite de fournir le RuntimeCollaborator. Une fois que votre interface CustomService est initialisée, la classe MBeanFactory de WebSphere lit votre fichier de descripteur du MBean XML, puis crée, lie et enregistre automatiquement un MBean auprès de votre interface CustomService. Une fois que la méthode shutdown de votre CustomService est appelée, le système du produit désactive automatiquement votre MBean.
    • Utilisez l'interface AdminService. Vous pouvez appeler la méthode registerMBean() sur l'interface AdminService et l'appel est délégué au MBeanServer sous-jacent du processus, suite aux vérifications de sécurité appropriées. Vous pouvez obtenir une référence à l'AdminService à l'aide de la méthode getAdminService() de la classe AdminServiceFactory.

      Cette option est conseillée pour l'enregistrement de MBeans standard, dynamiques et ouverts. Implémentez la classe UserCollaborator pour utiliser les MBeans et leur offrir un niveau cohérent de support à travers les plateformes réparties et z/OS.

      [z/OS]Pour la plateforme z/OS, un MBean enregistré via la méthode registerMBean() dans l'interface AdminService n'est pas visible de l'extérieur du serveur et peut uniquement être appelé depuis le processus serviteur dans lequel il a été enregistré.

    • Obtenez des instances de MBeanServer directement. Vous pouvez obtenir une référence directe à l'instance de MBeanServer JMX qui s'exécute dans n'importe quel processus du produit en appelant la méthode getMBeanServer() de la classe MBeanFactory. Vous obtenez une référence à la classe MBeanFactory en appelant la méthode getMBeanFactory() de l'interface AdminService.

      Lorsqu'un MBean personnalisé est directement enregistré avec le serveur de MBean, le nom d'objet de MBean est étendu avec les clés de cellule, de noeud et de nom de processus par défaut. L'enregistrement permet au MBean de participer aux fonctions réparties du système d'administration. Vous pouvez désactiver le comportement par défaut en définissant la propriété personnalisée com.ibm.websphere.mbeans.disableRouting.

      Voir Propriétés personnalisées des services d'administration pour plus d'informations sur la définition et l'utilisation de la propriété personnalisée com.ibm.websphere.mbeans.disableRouting.

Résultats

Quelle que soit l'approche utilisée pour créer et enregistrer votre MBean, vous devez configurer les droits d'accès de sécurité Java 2 pour le code de votre nouveau MBean. AdminService et MBeanServer de WebSphere sont étroitement protégés à l'aide des droits d'accès de sécurité Java 2 et, si vous n'octroyez pas explicitement les droits d'accès à votre code, des exceptions de sécurité sont générées lorsque vous essayez d'appeler les méthodes de ces classes. Si vous fournissez votre MBean dans le cadre de votre application, vous pouvez définir les droits d'accès dans le fichier was.policy que vous fournissez avec les métadonnées de votre application. Si vous utilisez une interface CustomService ou un autre code qui n'est pas fourni en tant qu'application, vous pouvez éditer le fichier library.policy dans la configuration du noeud, ou encore le fichier server.policy situé dans le répertoire properties pour une installation spécifique.

[z/OS]

Exemple : Le MBean SampleStateMBean

MBeanDescriptor

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MBean SYSTEM "MbeanDescriptor.dtd">
<MBean type="SampleStateMBean"
  aggregationHandlerClass="com.ibm.ws390.sample.SampleStateAggregationHandler"
  eventHandlerClass="com.ibm.ws390.sample.SampleStateEventHandler"
  invocationHandlerClass="com.ibm.ws390.sample.SampleStateInvocationHandler"
  stateObjectClass="com.ibm.ws390.sample.SampleState"
  version="6.0"
  platform="dynamicproxy"
  description="Sample State MBean for the documentation example.">

  <attribute description="The name of the MBean."
    getMethod="getMBeanName" name="mbeanName" type="java.lang.String"
    proxyInvokeType="unicall"/>
  <attribute description="The state of the MBean." name="state"
    getMethod="getState" setMethod="setState" type="java.lang.String"
    proxyInvokeType="multicall" proxySetterInvokeType="multicall"/>
  <operation
    description="Initialize the State MBean."
    impact="ACTION" name="initializeState" role="operation"
    targetObjectType="objectReference" type="void" proxyInvokeType="multicall">
    <signature>
      <parameter description="The name of the MBean."
        name="mbeanName" type="java.lang.String"/>
      <parameter description="The initial state of the MBean."
        name="mbeanName" type="java.lang.String"/>
    </signature>
  </operation>
  
  <notification name="j2ee.state.starting" severity="6" log="false"
                description="This sample state MBean is in starting state.">
      <notificationType>j2ee.state.starting</notificationType>
  </notification>
  <notification name="j2ee.state.running" severity="6" log="false"
                description="This sample state MBean is in running state.">
      <notificationType>j2ee.state.running</notificationType>
  </notification>
  <notification name="j2ee.state.stopping" severity="6" log="false"
                description="This sample state MBean is in stopping state.">
      <notificationType>j2ee.state.stopping</notificationType>
  </notification>
  <notification name="j2ee.state.stopped" severity="6" log="false"
                description="This sample state MBean is in stopped state.">
      <notificationType>j2ee.state.stopped</notificationType>
  </notification>    
</MBean>

SampleState implementation

package com.ibm.ws390.sample;

import com.ibm.ejs.ras.Tr;
import com.ibm.ejs.ras.TraceComponent;
import java.io.Serializable;
import com.ibm.websphere.management.dynamicproxy.StateObject;

public class SampleState extends StateObject {
    
    private static TraceComponent tc =
    Tr.register(SampleState.class,"SampleState",null);
    
    // Package protected STATE constants.
    static final String STATE_STARTING = "j2ee.state.starting";
    static final String STATE_RUNNING  = "j2ee.state.running";
    static final String STATE_STOPPING = "j2ee.state.stopping";
    static final String STATE_STOPPED  = "j2ee.state.stopped";
    
    // Dynamicproxy State is initialized with STOPPED state.
    private String state = STATE_STOPPED;
    
    public SampleState() {
        if (tc.isEntryEnabled()) Tr.entry(tc,"<init>");
        
        // State is initialized during "state" initialization,
        // but can also be initialized here in the constructor as well.
        /*
        state = "WebSphere
Application Server for z/OS ready for e-business";
        */
        
        if (tc.isEntryEnabled()) Tr.exit(tc,"<init>");
    }
    
    public synchronized String getState() {
        if (tc.isEntryEnabled()) Tr.entry(tc,"getState");
        if (tc.isEntryEnabled()) Tr.exit(tc,"getState",state);
        return state;
    }
    
    public synchronized void setState(String state) {
        if (tc.isEntryEnabled()) Tr.entry(tc,"setState",state);
        this.state = state;
        if (tc.isEntryEnabled()) Tr.exit(tc,"setState");
    }
    
    public synchronized String getStateObjectInfo() {
        return state;
    }
}

SampleStateAggregationHandler implementation

package com.ibm.ws390.sample;

import com.ibm.websphere.management.dynamicproxy.AggregationHandler;
import com.ibm.websphere.management.dynamicproxy.StateObject;

import com.ibm.ejs.ras.Tr;
import com.ibm.ejs.ras.TraceComponent;

public class SampleStateAggregationHandler implements AggregationHandler {
    
    private static TraceComponent tc =
    Tr.register(SampleStateAggregationHandler.class,"SampleState",null);
    
    /**
     * Return an aggregated result from a multicall Mbean operation which
     * compiles through all servant MBeans' results and returns a respective
     * single return value for an invoked method.
     *
     * @param  methodName           MBean method name
     * @param  params               MBean method parameters
     * @param  signatures           MBean method signatures
     * @param  servantMBeanResults  Result of each servant MBean instances
     *                              invoked by the dynamicproxy multicast 
     *                              invocation.
     *                              Note: this value can be "null" OR can be
     *                              an array of "null"s in case return value
     *                              of the method is "void." Implementation
     *                              of this method MUST handle this case to
     *                              avoid a <code>NullPointerException</code>.
     * @param stateObject
     *        MBean provider provided <code>StateObject</code> used by 
     *        dynamicproxy MBean in CR to manage its state. Note: this object
     *        MAY BE null if "stateObjectClass" was not specified OR internal
     *        error occurred during initialization of this dynamicproxy MBean.
     *        Implmentation MUST properly handle "null" input.
     *                
     * @return aggregated result as defined by MBean xml for specified
     *         MBean operation.
     */
    public Object aggregateResults(String methodName,
                                   Object[] params,
                                   String[] signatures,
                                   Object[] servantMBeanResults,
                                   StateObject stateObject) {
                                       
        if (tc.isEntryEnabled()) Tr.entry(tc,"aggregateResults",methodName);
        
        // As you can see from the MBeanDescriptor of SampleStateMBean,
        // it declares the following four methods:
        // 1. String getMBeanName()         [proxyInvokeType == unicall]
        // 2. String getState()             [proxyInvokeType == multicall]
        // 3. void setState(String)         [proxyInvokeType == multicall]
        // 4. void initializeState()        [proxyInvokeType == multicall]
        //
        // From these methods, the only one that requires aggregation
        // is #2 getState method which is a multicall MBean operation AND
        // it returns a value that can be aggregated.
        //
        // In this example, we simply take each servants' getState MBean
        // request result and concatenate them into one long String that
        // displays each servants' state. 
        if (methodName.equals("getState")) {
            StringBuffer stateBuf = new StringBuffer();
            
            for (int i=0; i<servantMBeanResults.length; i++) {
                stateBuf.append("SERVANT #" + i + " state ==|" + 
                                servantMBeanResults[i] + "|== ");
            }
            return stateBuf.toString();
        }
        // If we also had an example method which returns say an int, 
        // getNumberOfMBeans(), it can take the similar approach
        // and to add each servants' getNumberOfMBeans() result together here.
        /* example added for non-existent method: int getNumberOfMBeans()
        else if (methodName.equals("getNumberOfMBeans")) {
            int aggregatedResult = 0;
            
            for (int i=0; i<servantMBeanResults.length; i++) {
                aggregatedResult += (int) servantMBeanResults[i];
            }
            return aggregatedResult;
        }
        */
        
        return methodName + " is NOT handled by " + getClass().getName() + "!";
    }
    
}

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_extend
Nom du fichier : tjmx_extend.html