Oracle Tuxedo JMX Interface

This chapter contains the following sections:

•

Overview

•	Configurations

•	Creating a JMX Connection

Overview

The JMXAgent embedded in tlisten supplies a list of JMX MBeans. Using the functions exported by those MBeans, users can monitor and manage Oracle Tuxedo application by JMX invocation. Following is an example of shutting down a Tuxedo Server by JMX Java client.

Listing 1‑1 Shutting Down a Tuxedo Server by JMX Java Client

// Client.java

import java.io.IOException;

import java.util.HashMap;

import java.util.Map;

import java.util.Set;

 

import javax.management.MBeanServerConnection;

import javax.management.ObjectInstance;

import javax.management.ObjectName;

import javax.management.remote.JMXConnector;

import javax.management.remote.JMXConnectorFactory;

import javax.management.remote.JMXServiceURL;

 

import oracle.tuxedo.jmx.tux.exception.JMXPropertiesException;

import oracle.tuxedo.jmx.tux.utility.Encryption;

 

public class Client {

 

public static void main(String[] args) throws IOException,

JMXPropertiesException, Exception {

String host = "XXXXXX.oracle.com";

String port = "26999";

 

String username = "oracle";

// Tuxedo password and application password must be encrypted.

String password = Encryption.getInstance().encrypt("password");

// Tuxedo application password.

String appPassword = Encryption.getInstance().encrypt("apppassword");

 

String[] credentials = new String[] { username, password, appPassword };

Map<String, Object> env = new HashMap<String, Object>();

env.put("jmx.remote.credentials", credentials);

 

// Create an RMI connector client and

// connect it to the RMI connector server;

JMXServiceURL url = new JMXServiceURL(String.format(

"service:jmx:rmi://%s:%s/jndi/rmi://%s:%s/server", host, port,

host, port));

 

JMXConnector jmxc = JMXConnectorFactory.connect(url, env);

MBeanServerConnection mbsc = jmxc.getMBeanServerConnection(null);

// Get AdminBean by the MBean name

Set<?> mbeans = mbsc.queryMBeans(new ObjectName(

"DefaultJMXDomain:type=adminBean"), null);

ObjectInstance objectInstance = (ObjectInstance) mbeans.iterator()

.next();

ObjectName objectName = objectInstance.getObjectName();

// The parameter value list for shutdownServer methond.

Object[] params = { "/testarea/oracle/test/tuxconfig", "APPGRP", 102, 0, null };

// The parameter type list for shutdown Server method.

String[] signature = { String.class.getName(), String.class.getName(),

Integer.class.getName(), Integer.class.getName(),

String.class.getName() };

Object result = mbsc.invoke(objectName, "shutdownServer", params,

signature);

System.out.print(result);

}

}

 

Run the following command to compile the java file:

javac -classpath $TUXDIR/jmx/tmjmx_exceptions.jar:$TUXDIR/jmx/ tmjmx_tux.jar Client.java

A Client.class is generated. Use the following command to run this client:

java -classpath $TUXDIR/jmx/tmjmx_exceptions.jar:$TUXDIR/jmx/tmjmx_tux.jar:. Client

The output result is as follows:

Shutting down server processes ...

 

Server Id = 102 Group Id = APPGRP Machine = SITE1: shutdown succeeded

1 process stopped.

For more information, see MBeans and JMX Operations.

Configurations

Following configurations must be done before invoking the JMX client:

•	Start the tlisten and Tuxedo domain. For more information, refer to “Starting the tlisten Process”, “Configuring the UBBCONFIG File", and "Loading UBBCONFIG and Booting up Oracle Tuxedo" sections in Enterprise Manager for Oracle Tuxedo Getting Started Guide.

•	For the Tuxedo domain which security is not “NONE”, add the Tuxedo user as tpsysadm. For example: tpusradd -g group1 -c tpsysadm user1

•	Add $TUXDIR/udataobj/jmx/tmjmx_exceptions.jar to the client’s classpath when running the client to invoke the JMX Agent in tlisten.

Creating a JMX Connection

Use the following JMX Service URL to create a JMX connection:

service:jmx:rmi:///jndi/rmi://rmihost:rmiport/server

The rmihost and rmiport are the host and port configured in tlisten by the –j option. After configuring this option, a JMX Agent runs in a JVM started in the tlisten process by JNI technology.

The "jmx.remote.credentials" must be a String array which is parsed in the following order.

 

Order	Tuxedo Authentication and Authorization Data	Comments
0	User Name	Optional. Required when the Tuxedo security or JMX security is enabled; otherwise leave it blank. If the Tuxedo security is enabled, it is the Tuxedo username; If JMX security is enabled, it is the JMX user name added by jmxaaacfg.
1	Password	Optional. Required if the Tuxedo security or JMX security is enabled; otherwise leave it blank. If the password is not null, it must be encrypted using the oracle.tuxedo.jmx.tux.utility.Encryption.encrypt() method in $TUXDIR/jmx/tmjmx_tux.jar
2	Application Password	Optional. Required if the Tuxedo security is enabled; otherwise leave it blank. If the application password is not null, it must be encrypted using the oracle.tuxedo.jmx.tux.utility.Encryption.encrypt() method in $TUXDIR/jmx/tmjmx_tux.jar
3	DOMAINID	Optional. Required in the case of multiple domains within one tlisten.
4	IPCKEY	Optional. Required in the case of multiple domains within one tlisten.
5	TUXCONFIG	Optional. Required after the tlisten restarts.
6	NONTUXAUTH	Optional. Add "NONTUXAUTH" in the list of "jmx.remote.credentials" , the Tuxedo authentication is not taken place when connecting JMX server. In this case, the invocation of the JMX operations which requires Tuxedo authentication will fail.

Following is an example of creating JMX connector.

Listing 1‑2 Creating JMX Connector

String[] credentials = new String[] { username, password, appPassword };

Map<String, Object> env = new HashMap<String, Object>();

env.put("jmx.remote.credentials", credentials);

 

// Create an RMI connector client and

// connect it to the RMI connector server;

JMXServiceURL url = new JMXServiceURL(String.format(

"service:jmx:rmi://%s:%s/jndi/rmi://%s:%s/server", host, port,

host, port));

 

JMXConnector jmxc = JMXConnectorFactory.connect(url, env);