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 .
- 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);
}
- 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.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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.
- 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.
- 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: 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
- 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.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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.
- 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.
- 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.
- 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");
- 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.
- 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.
- 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.
- 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.
- 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.
- 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: 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 Serverimport 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)
{
}
}
}