Desarrollo de un programa cliente administrativo

Puede desarrollar un programa cliente administrativo que utiliza las interfaces de programación de aplicaciones (API) administrativas de WebSphere Application Server y Java™ Management Extensions (JMX).

Acerca de esta tarea

Las API administrativas del producto permiten controlar los aspectos operativos del sistema distribuido además de la posibilidad de actualizar la configuración. Para obtener información acerca de la interfaz AdminClient, consulte la documentación de las interfaces de programación de aplicaciones.

Vea ejemplos de operaciones de MBean. Si desea información sobre la programación de MBean, consulte la documentación de la API Java de MBean. En este Information Center, pulse Referencia > Intefaces de programación > Interfaces de Mbean.

Procedimiento

  1. Cree una instancia de AdminClient.

    Un programa cliente administrativo debe invocar métodos en el objeto AdminService que se esté ejecutando en el gestor de despliegue o en el servidor de aplicaciones de la instalación base.

    La clase AdminClient proporciona un proxy al AdminService remoto a través de uno de los conectores JMX (Java Management Extensions) soportados.
    • El siguiente ejemplo muestra cómo crear una instancia de AdminClient para el conector 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("Excepción al crear el cliente de administración: " + e);
      }
      1. Configure un objeto Properties.

        El ejemplo configura un objeto Properties con las propiedades necesarias para acceder al servidor. En este caso se utiliza el conector SOAP para acceder al servidor; para el tipo de conector, utilice el valor: AdminClient.CONNECTOR_TYPE_SOAP.

      2. [AIX Solaris HP-UX Linux Windows][IBM i]Para simplificar las cosas, ejecute el programa cliente en la misma máquina que el servidor; utilice localhost como nombre de host.

        Para acceder a un host remoto en lugar de acceder a un host local, utilice un nombre de red que pueda resolverse para dicho host.

      3. Defina el número de puerto en el que recibe el conector SOAP del servidor.

        En una instalación de un único servidor, el número de puerto predeterminado para el conector SOAP del servidor de aplicaciones es 8880. En una instalación de WebSphere Application Server, Network Deployment, el número de puerto predeterminado para el conector SOAP del gestor de despliegue es 8879.

      4. Una vez que haya definido las propiedades de conexión, utilice la clase AdminClientFactory y el objeto Properties para crear un objeto AdminClient que esté conectado al servidor seleccionado.

        En función de factores tales como el protocolo y el entorno de seguridad que se utilicen, es posible que deba definir otras propiedades. Por ejemplo, si habilita la seguridad para el programa de cliente de aplicaciones, incluya las propiedades javax.net.ssl.*. Si desea información más detallada sobre la interfaz de AdminClient, las propiedades javax.net.ssl.* y ejemplos de creación adicionales, consulte la interfaz de AdminClient en la documentación de las interfaces de programación de aplicaciones.

    • El siguiente ejemplo muestra cómo crear una instancia de AdminClient para el conector RMI (Remote Method Invocation). Para facilitar la impresión, algunos mandatos se han partido en varias líneas.
      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("Excepción al crear el cliente de administración: " + e);
      }
      Supported configurations Supported configurations: Cuando se utiliza el método de createAdminClient dentro del código de aplicación que se ejecuta en un servidor de aplicaciones, como en los servlets y archivos JSP (JavaServer Pages), debe establecer la propiedad CACHE_DISABLED en true. Por ejemplo:
      connectProps.setProperty(AdminClient.CACHE_DISABLED, "true");
      sptcfg
      1. Configure un objeto Properties.

        El ejemplo configura un objeto Properties con las propiedades necesarias para acceder al servidor. En este caso se utiliza el conector Remote Method Invocation para acceder al servidor; para el tipo de conector, utilice el valor: AdminClient.CONNECTOR_TYPE_RMI.

      2. [AIX Solaris HP-UX Linux Windows][IBM i]Para simplificar las cosas, ejecute el programa cliente en la misma máquina que el servidor; utilice localhost como nombre de host.

        Para acceder a un host remoto en lugar de acceder a un host local, utilice un nombre de red que pueda resolverse para dicho host.

      3. Establezca el número de puerto en el que escucha el conector RMI del servidor.

        En una instalación de un único servidor, el número de puerto predeterminado para el conector RMI del servidor de aplicaciones es 2809. En una instalación de WebSphere Application Server, Network Deployment, el número de puerto predeterminado para el conector RMI del gestor de despliegue es 9809.

      4. Una vez que haya definido las propiedades de conexión, utilice la clase AdminClientFactory y el objeto Properties para crear un objeto AdminClient que esté conectado al servidor seleccionado.

        En función de factores tales como el protocolo y el entorno de seguridad que se utilicen, es posible que deba definir otras propiedades. Por ejemplo, si habilita la seguridad para el programa de cliente de aplicaciones, debe establecer una propiedad del sistema de modo que señale al archivo ssl.client.props y al archivo sas.client.props. Si la ejecución se realiza en una máquina local, puede señalar a dicha ubicación. Si se realiza en una máquina remota, puede copiar estos archivos de propiedades desde la máquina servidor y guardarlos donde prefiera, especificando la vía de acceso al lugar donde ha guardado los archivos.

        Puede especificar un nombre de usuario y una contraseña dentro del archivo sas.client.props. Si lo hace, especifique com.ibm.CORBA.loginSource=properties. Si desea establecer el nombre de usuario y la contraseña dentro del programa cliente, especifique com.ibm.CORBA.loginSource=none en el archivo sas.client.props.

  2. Localice un MBean.

    Una vez que haya obtenido una instancia de AdminClient, puede utilizarla para acceder a los recursos gestionados en los servidores de administración y los servidores de aplicaciones. Cada recurso gestionado registra un MBean con AdminService mediante el cual puede acceder al recurso. El MBean está representado por una instancia de ObjectName que identifica el MBean. Una instancia de ObjectName consta de un nombre de dominio seguido de un conjunto no clasificado de una o varias propiedades clave. La sintaxis para el nombre de dominio es la siguiente:

    [domainName]:property=value[,property=value]*
    Para WebSphere Application Server, el nombre de dominio es WebSphere y las propiedades clave definidas para la administración son las siguientes:
    Tabla 1. Descripciones de las propiedades clave. Entre las propiedades clave se incluyen type, name, cell, node y process.
    Propiedad clave Descripción
    tipo Tipo de MBean. Por ejemplo: Server, TraceService, Java virtual Machine (JVM).
    name Identificador de nombre de la instancia individual del MBean.
    cell Nombre de la célula que el MBean está ejecutando.
    node Nombre del nodo que el MBean está ejecutando.
    process Nombre del proceso que el MBean está ejecutando.

    Algunos MBeans de WebSphere Application Server utilizan propiedades clave adicionales. Un MBean sin propiedades clave puede registrarse con el servidor MBean en un proceso de WebSphere Application Server. No obstante, un MBean de este tipo no puede participar en las mejoras distribuidas que añade el producto, por ejemplo, el direccionamiento de solicitudes, la notificación de sucesos distribuidos, etc.

    Si conoce el conjunto completo de propiedades clave para una instancia de ObjectName, puede utilizarlo para localizar el MBean al que identifica. No obstante, localizar MBeans sin conocer todas sus propiedades clave es generalmente más práctico y conveniente. Utilice el asterisco (*) como carácter comodín para las propiedades clave que no es necesario que coincidan. En la tabla siguiente se proporcionan algunos ejemplos de nombres de objeto con propiedades clave comodín que coinciden con uno o varios MBeans.
    Tabla 2. Ejemplos de nombres de objeto con propiedades clave comodín. Utilice asteriscos (*) para especificar propiedades clave comodín.
    Nombre de objeto Descripción
    *:type=Server,* Todos los MBeans de tipo Server
    *:node=Nodo1,type=Server,* Todos los MBeans de tipo Servidor que se encuentran en el Nodo1
    *:type=JVM,process=servidor1,node=Nodo1,* El MBean JVM del servidor denominado servidor1 del nodo Nodo1
    *:process=servidor1,* Todos los MBeans de todos los servidores de nominados servidor1
    *:process=servidor1,node=Nodo1,* Todos los MBeans del servidor denominado servidor1 del nodo Nodo1

    Puede localizar un MBean realizando una consulta sobre el mismo con los nombres de objeto que coinciden con las propiedades clave. En el ejemplo siguiente se muestra cómo localizar el MBean para el agente de nodo del nodo, MiNodo:

    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("No se ha encontrado el MBean del agente de nodo");
    1. Cree una instancia de ObjectName con una cadena de consulta que especifique las propiedades clave del tipo y el nodo.

      Utilizando caracteres comodín para las propiedades clave restantes, este patrón coincide con los nombres de objeto para todos los MBeans de tipo NodeAgent del nodo MiNodo. Puesto que sólo hay un agente de nodo por nodo, esta información es suficiente para identificar el MBean que desea.

    2. Proporcione esta instancia de ObjectName al método queryNames de la interfaz AdminClient.

      La interfaz AdminClient realiza la llamada remota a la interfaz AdminService para obtener el conjunto de nombres de objetos MBean que coinciden con la consulta. El segundo parámetro nulo para este método es un objeto de expresión de consulta (QueryExp) que puede utilizarse como consulta adicional para los MBeans que coinciden con el patrón de ObjectName en el primer parámetro.

    3. Utilice el repetidor de conjunto para obtener el primer y, en este caso, único elemento.

      El elemento es la instancia de ObjectName de MBean del agente de nodo.

  3. Utilice el MBean.

    Lo que pueda llegar a hacer un MBean en concreto depende de la interfaz de gestión de dicho MBean. Un MBean puede declarar lo siguiente:

    • Atributos que pueden obtenerse o definirse
    • Operaciones que pueden invocarse
    • Notificaciones para las que el usuario puede registrar escuchas
    Para los MBeans que proporciona WebSphere Application Server, puede encontrar información sobre las interfaces que admiten en la documentación de API de MBean. El siguiente ejemplo invoca una de las operaciones disponibles en el MBean de NodeAgent localizado anteriormente. El ejemplo siguiente inicia el servidor de aplicaciones MiServidor:
    String opName = "launchProcess";
    String signature[] = { "java.lang.String" };
    String params[] = { "MiServidor" };
    try
    {
         adminClient.invoke(nodeAgent, opName, params, signature);
    }
    		catch (Exception e)
    {
         System.out.println("Excepción al invocar launchProcess: " + e);
    }
    El método AdminClient.invoke es un medio genérico para invocar cualquier operación en cualquier MBean. Los parámetros son:
    • El nombre de objeto del MBean de destino, nodeAgent
    • El nombre de la operación, opName
    • Una matriz de objetos que contiene los parámetros de operación, params
    • Una matriz de cadenas que contiene la signatura de la operación, signature
    La operación launchProcess del ejemplo tiene un único parámetro que es una cadena que identifica el servidor que debe iniciarse.

    El método de invocación devuelve una instancia de objeto, que el código de llamada puede utilizar para emitir el tipo de retorno correcto para la operación invocada. La operación launchProcess se declara como nula por lo que puede ignorarse el valor de retorno de este ejemplo.

  4. Registre los sucesos.

    Además de gestionar los recursos, la API JMX también da soporte a la supervisión de sucesos de administración específicos. Algunos sucesos producen notificaciones, por ejemplo, cuando se inicia un servidor. Las aplicaciones administrativas pueden registrarse como escuchas de estas notificaciones. WebSphere Application Server proporciona una implementación completa del modelo de notificación JMX y proporciona funciones adicionales de forma que pueda recibir notificaciones en un entorno distribuido. Si desea una lista completa de las notificaciones emitidas de los MBeans del producto, consulte la clase com.ibm.websphere.management.NotificationConstants en la documentación de la API de MBean.

    En el ejemplo siguiente se muestra cómo puede un objeto registrar las notificaciones de sucesos que se han emitido desde un MBean utilizando el agente de nodo ObjectName:

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

    En este ejemplo, el primer parámetro es el nombre de objeto (ObjectName) para el MBean del agente de nodo. El segundo parámetro identifica el objeto de escucha, que debe implementar la interfaz. En este caso, el objeto que efectúa la llamada es la escucha. El tercer parámetro es un filtro que puede utilizarse para indicar qué notificaciones deben recibirse. Si deja este valor como null, recibirá todas las notificaciones de este MBean. El parámetro final es un objeto handback que puede utilizarse para establecer que la API JMX regrese cuando emita una notificación.

    Si el MBean se encuentra en otro servidor de la célula, puede recibir sus notificaciones aunque el programa cliente administrativo esté conectado al servidor del gestor de despliegue. Todas las notificaciones fluyen en el servidor en sentido ascendente. Por ejemplo, una notificación de un servidor de aplicaciones primero fluye al agente de nodo local y luego al gestor de despliegue.

    Otra característica mejorada que proporciona Application Server es la capacidad de registrarse como escucha de notificaciones de varios MBeans con una llamada. Este registro se realiza a través del método addNotificationListenerExtended de la interfaz AdminClient, una extensión del método addNotificationListener JMX estándar. Este método de extensión permite registrarse para MBeans que actualmente no están activos. El registro es importante en situaciones en las que se desean supervisar sucesos de recursos que pueden detenerse y reiniciarse durante el tiempo de vida del programa cliente administrativo.

  5. Gestione los sucesos.

    Los objetos reciben las notificaciones de sucesos JMX a través del método handleNotification, que se define mediante la interfaz NotificationListener y que cualquier receptor de sucesos debe implementar. El ejemplo siguiente es una implementación del método handleNotification que informa de las notificaciones que recibe:

    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("***************************************************");
    }

Resultados

El cliente administrativo puede manejar notificaciones de suceso emitidos desde un MBean.

Avoid trouble Avoid trouble: Si un programa cliente registra un escucha de notificación a través de un conector RMI o JSR160RMI y el la hebra del ORB no deja de ejecutarse y, así, se impide salir a la máquina virtual Java, añada una sentencia System.exit() al programa cliente. El ORB inicia una hebra para manejar la propagación de la notificación al cliente. Esta hebra no sale automáticamente con la hebra principal del cliente, a menos que la hebra principal tenga una sentencia System.exit(). Coloque una sentencia System.exit() en una ubicación en el programa cliente que permite a la hebra de ORB y a la hebra principal detener el proceso. Por ejemplo, coloque la sentencia System.exit() en una cláusula catch o finally del bloque principal del programa cliente try. gotcha

Ejemplo: programa de cliente administrativo

Copie el contenido a un archivo llamado AdminClientExample.java. Tras modificar el nombre del nodo y el nombre del servidor por los valores apropiados para la configuración, puede compilarlo y ejecutarlo utilizando las instrucciones de Creación de un programa cliente administrativo Java personalizado mediante las API Java administrativas de 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();

       // Crear un AdminClient
       ace.createAdminClient();

       // Encontrar un NodeAgent MBean
       ace.getNodeAgentMBean("ellington");

       // Invocar a launchProcess
       ace.invokeLaunchProcess("server1");

       // Registrar los sucesos de NodeAgent
       ace.registerNotificationListener();
        
       // Ejecutar hasta que se interrumpa
       ace.countNotifications();
    }

    private void createAdminClient()
    {
        // Establecer un objeto Properties para los atributos del conector JMX
        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");
        
        // Obtener un AdminClient basándose en las propiedades del conector
        try
        {
            adminClient = AdminClientFactory.createAdminClient(connectProps);
        }
        catch (ConnectorException e)
        {
            System.out.println("Excepción al crear el cliente de administración: " + e);
            System.exit(-1);
        }
        
        System.out.println("Conectado a DeploymentManager");
    }
    
    
    private void getNodeAgentMBean(String nodeName)
    {
        // Consultar el ObjectName del NodeAgent MBean en el nodo especificado
        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("No se ha encontrado el MBan del agente de
nodo");
                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)
    {
        // Utilizar la operación launchProcess en el NodeAgent MBean para iniciar
        // el servidor especificado
        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("Excepción al invocar launchProcess: " + e);
        }
    }
    
    private void registerNotificationListener()
    {
        // Registrar este objeto como un receptor para notificaciones del
        // NodeAgent MBean.  No utilizar un filtro ni un objeto
        // handback.
        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)
    {
        // Cada notificación que genera el NodeAgent MBean provocará que
        // se llame a este método
        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()
    {
        // Ejecutar hasta que se interrumpa
        try
        {
            while (true)
            {
                Thread.currentThread().sleep(60000);
                System.out.println(ntfyCount + " notification have been received");
            }
        }
        catch (InterruptedException e)
        {
        }
    }
    
}

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=tjmx_develop
File name: tjmx_develop.html