5. JMXアプリケーションの開発

5.1. チュートリアル

WebOTXの運用管理エージェントにアクセスするためのJMXアプリケーションの作成方法について説明します。
JMXアプリケーションを作成するには次のAPIを利用します。

JMX API
JMX Remote API

それぞれのAPIリファレンスについては[ リファレンス集開発編（共通） ] を参照してください。

本章では、上記APIを利用してMBeanの属性を取得、設定したり、オペレーションを呼び出したり、Notification通知を受け取る手順について説明します。

5.1.1. JMXアプリケーション動作環境について

WebOTXの運用管理エージェントにアクセスするためのJMXアプリケーションを動作させるための環境設定について説明します。

5.1.1.1. ビルド環境

Java SE Development Kit
Java SE Development Kit 7 以上を使用してください。
CLASSPATH
「5.1.3.1. JMXRemoteClientクラスを利用する方法」で作成したソースをビルドする場合は、以下のライブラリをクラスパスに追加してください。
- ${INSTALL_ROOT}/modules/jmx-remote-client.jar

5.1.1.2. 実行環境

Java SE Development Kit

Java SE Development Kit 7 以上を使用してください。
CLASSPATH

「5.1.3.1. JMXRemoteClientクラスを利用する方法」で作成したクラスを実行する場合は、以下のライブラリをクラスパスに追加してください。
- ${INSTALL_ROOT}/lib/wo-client.jar
証明書ファイル

サーバ/クライアント間のSSL通信で利用する証明書ファイルが必要です。サーバ側の認証ファイルに格納されている情報の認証情報が格納されている必要があります。サンプルアプリケーションにもサンプル用の証明書ファイル(cacerts.jks)がありますのでこれを利用することも可能です。
システムプロパティ

JMXアプリケーションとして次のシステムプロパティを利用します。クライアントの証明書ファイルを指定します。
- javax.net.ssl.trustStore

5.1.2. JMX Remote APIの設定について

JMX Remote APIを利用したクライアントを作成する場合、次のimport文を含める必要があります。

コーディング例

import java.util.*;
import java.security.*;
import java.io.*;
import javax.net.ssl.*;
                  
//
// JMX API
//
import javax.management.MBeanAttributeInfo;
import javax.management.MBeanOperationInfo;
import javax.management.MBeanNotificationInfo;
import javax.management.MBeanInfo;
                  
import javax.management.Attribute;
import javax.management.MBeanServerConnection;
import javax.management.MBeanServerInvocationHandler;
import javax.management.ObjectName;
import javax.management.AttributeList;
                  
//
// JMX Remote API
//
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;

5.1.3. JMXConnectorの生成

運用管理エージェントに接続するためにJMXConnectorオブジェクトを作成します。
JMXConnectorオブジェクトを作成するには、WebOTXが提供するJMXRemoteClientクラスを利用する方法と、標準のJMX Remote API利用してプロファイル情報を個別に設定する方法があります。

5.1.3.1. JMXRemoteClientクラスを利用する方法

コーディング例

//
// WebOTX API
//
import com.nec.webotx.enterprise.admin.jmx.remote.client.*;
import com.nec.webotx.enterprise.admin.jmx.remote.plainclient.*;


// URLの生成
// プロトコル RMI
// ホスト名 localhost
// 管理ポート番号 6212
JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://host:6212/management/rmi-jmx-connector");

// JMXRemoteClientの生成
final JMXRemoteClient jmxcl = new JMXRemoteClient();
jmxcl.config(System.getProperty("javax.net.ssl.trustStore"), "changeit", false);

// JMXConnectorの生成
final JMXConnector jmxc = jmxcl.connect(url.toString(), username, password);

URLの生成

利用するプロトコル名、アクセスする運用管理エージェントのホスト名、ポート番号からJMXServiceURLオブジェクトを生成します。WebOTXのデフォルトで作成されるdomain1に接続するためには上記コードのように"rmi"プロトコルは6212ポートを利用します。

JMXRemoteClientの生成

JMXRemoteClientクラスを作成し、証明書ファイル（システムプロパティ「javax.net.ssl.trustStore」から取得）と証明書ファイルのパスワード(“changeit”)を指定します。

JMXConnectorの生成

urlとユーザ名、パスワードを指定して運用管理エージェントに接続し、JMXConnectorオブジェクトを取得します。 urlはJMXServiceURLクラスから作成できますが、直接生成することもできます。直接生成する場合は次のフォーマットでurlを作成してください。

service:jmx:[protocol]://[host]:[port][url-path]

表5.1.3.1-1
パラメータ	説明
protocol	運用管理エージェントと通信するためのプロトコル名を指定します。 jmxmp :JMXMPプロトコル rmi :RMIプロトコル RMIプロトコル使用時、WebOTXでは、JNDIを経由し、接続を行います。この場合、下記のようにurlを作成してください。 service:jmx:rmi:///jndi/rmi://[host]:[port][url-path]
host	運用管理エージェントのホスト名
port	protocolで指定したプロトコルのポート番号 JMXMPプロトコルの場合：6712 RMIプロトコルの場合：6212 省略時は6212(管理ドメインのデフォルトポート番号)が指定されます。
url-path	RFC 2609の仕様に従ったurlパス名。

5.1.3.2. 標準のJMX Remote APIを利用する方法

コーディング例

// プロファイル情報格納領域の生成
HashMap env = new HashMap();

// SSLSocketFactoryの生成
tring truststore = System.getPropery("javax.net.ssl.trustStore");
char truststorepass[] = "changeit".toCharArray();
KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream(truststore), truststorepass);
TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
tmf.init(ks);
SSLContext ctx = SSLContext.getInstance("TLSv1");
ctx.init(null, tmf.getTrustManagers(), null);
SSLSocketFactory ssf = ctx.getSocketFactory();

// プロバイダ関数の登録
Security.addProvider( new com.nec.webotx.enterprise.admin.jmx.remote.plainclient.ClientProvider());

// プロファイル情報の設定
env.put("jmx.remote.profiles","TLS SASL/PLAIN");
env.put("jmx.remote.tls.socket.factory", ssf);
env.put("jmx.remote.tls.enabled.protocols", "TLSv1");
env.put("jmx.remote.tls.enabled.cipher.suites","SSL_RSA_WITH_NULL_MD5");

// コールバック関数の登録
env.put("jmx.remote.sasl.callback.handler"
        , new com.nec.webotx.enterprise.admin.jmx.remote.client.UserPasswordCallbackHandler(user, password));

// URLの生成
// プロトコル RMI
// ホスト名 localhost
// 管理ポート番号 6212
JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://host:6212/management/rmi-jmx-connector");

// JMXConnectorの生成
final JMXConnector jmxc = JMXConnectorFactory.connect(url, env);

SSLSocketFactoryの生成

証明書ファイル(システムプロパティ「javax.net.ssl.trustStore」から取得)と証明書ファイルのパスワード(“changeit”)から認証情報を取得して、サーバ/クライアント間のSSL通信で利用するSSLSocketFactoryオブジェクトを作成します。証明書ファイルには、サーバ側の${INSTANCE_ROOT}/config/keystore.jksファイルに格納されている情報の認証情報が格納されている必要があります。作成したオブジェクトは、後でプロファイル情報として設定します。

プロバイダ関数の設定

WebOTX で使用するJMXMPプロトコルでは、SASL/PLAINを利用しています。SASL/PLAINのクライアント側の処理を提供するプロバイダ関数を設定します。この例で使用するプロバイダ関数は、${INSTALL_ROOT}/modules/jmx-remote-client.jarで提供されます。このクラスを使用する場合は、コンパイル時に jmx-remote-client.jar を、実行時に${INSTALL_ROOT}/lib/wo-client.jarをクラスパスに追加してください。

プロファイル情報の設定

WebOTX で使用するJMXMPプロトコルを利用するための各プロファイル情報を設定します。これらの情報はサーバ／クライアントで一致させる必要があります。

コールバック関数の登録

SASL/PLAINで利用するcallback関数を設定します。この例で使用するコールバック関数は${INSTALL_ROOT}/modules/jmx-remote-client.jarで提供されます。このクラスを使用する場合は、コンパイル時に jmx-remote-client.jar を、実行時に${INSTALL_ROOT}/lib/wo-client.jarをクラスパスに追加してください。このコールバック関数の引数には、接続するドメインでotxadminグループに所属するユーザ名とパスワード情報を設定します。

URLの生成

利用するプロトコル名、アクセスする運用管理エージェントのホスト名、ポート番号を指定してJMXServiceURLオブジェクトを生成します。WebOTXのデフォルトで作成されるdomain1に接続するためには上記コードのようにプロトコルは"rmi"ポートは6212を指定します。

JMXConnectorの生成

URLとプロファイル情報(env)を指定してJMXConnectorオブジェクトを生成します。

5.1.4. MBeanServerConnectionの取得

運用管理エージェントのMBeanを取得するためにMBeanServerConnectionを取得します。

コーディング例

	MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();

MBeanServerConnectionインタフェース

JMXではローカルでMBeanにアクセスするためにMBeanServerインタフェースを利用しますが、リモートではMBeanServerConnectionインタフェースを利用します。

5.1.5. MBeanのObjectNameの取得

運用管理エージェントのMBeanServerConnectionを利用してMBeanのObjectNameを取得します。

コーディング例

// オブジェクト名の検索
ObjectName objname = new ObjectName("*:*");
et objnames = mbsc.queryNames(objname,null);

for (final Iterator i=objnames.iterator();i.hasNext(); ) {
    bjectName name = (ObjectName)i.next();
    System.out.println("MBean: " + name);
}

オブジェクト名の検索について

JMXにおいてMBeanにはMBeanを一意に識別するオブジェクト名が割り当てられています。MBeanServerConnectionインタフェースでMBeanにアクセスするためのメソッドの引数には必ずオブジェクト名を指定します。そこでMBeanServerConnectionのインタフェースではMBeanの検索するためのメソッド(queryNames,queryMBeans)を提供しています。

queryNames,queryMBeansメソッドも引数は同じです。返却値が引数で指定した条件にマッチするObjectNameクラスのsetかMBeanクラスのsetかの違いがあるだけです。

queryNames,queryMBeansメソッドの第一引数はObjectNameです。このObjectNameでは以下のワイルドカードを使用することが可能です。指定したObjectNameにマッチするMBeanを検索することになります。

* :空の1つを含むどんな文字シーケンスとも一致します。
? :1つのどんな単一文字とも一致します。

以下に例を示します。次のObjectNameでMBeansがMBeanServerに登録されると仮定します。デフォルトドメイン名は”DefaultDomain”とします。

MyDomain:description=Printer,type=laser
MyDomain:description=Disk,capacity=2
DefaultDomain:description=Disk,capacity=1
DefaultDomain:description=Printer,type=ink

DefaultDomain:description=Printer,type=laser,date=1993

Socrates:description=Printer,type=laser,date=1993

“*:*” はMBeanサーバの全てのオブジェクトと一致します。パターンとして使用される無効のストリング・オブジェクトあるいは空のストリング("")名は、"*:*"と等価です。
“:*” はデフォルトのドメイン(DefaultDomain)の全てのオブジェクトと一致します。
“MyDomain:*”はMyDomainの中の全てのオブジェクトが一致します。
“??Domain:*”はMyDomainの中でオブジェクトとすべて一致します。
“*Dom*:*”はMyDomainとDefaultDomainの中の全てのオブジェクトと一致します。
“*:description=Printer,type=laser,*” は、次のオブジェクトと一致します。

MyDomain:description=Printer,type=laser
DefaultDomain:description=Printer,type=laser,date=1993
Socrates:description=Printer,type=laser,date=1993
“*Domain:description=Printer,*”は、次のオブジェクトと一致します。

MyDomain:description=Printer,type=laser
DefaultDomain:description=Printer,type=ink
DefaultDomain:description=Printer,type=laser,date=1993

queryNames,queryMBeansメソッドの第二引数はQueryExpです。QueryExpはユーザ定義の属性値を基にMBeanのフィルタリング条件を指定します。なおQueryExpをnullに指定するとフィルタリングは行いません。

QueryExpは属性値のconstraints(数値については“equals”や”less-than”、文字列については”matches”のようなもの)から構成されています。このconstraintsは”and”や”or”のようなオペレーションも含みます。例えば次のようなExpressionが定義できます。

"Retrieve the MBeans for which the attribute age is at least 20 and the attribute name starts with G and ends with ling"
(属性”age”の値が少なくとも20であり、属性”name”の値がGから始まりlingで終わるMBeanを検索する)

上記のコーディング例ではオブジェクト名に”*:*”を指定しているのでドメインに登録されている全てのMBeanのオブジェクト名を取得できます。

5.1.6. MBeanInfoの取得

MBeanの情報を取得するにはMBeanInfoを取得する必要があります。MBeanInfoを取得することによりそのMBeanがサポートする属性やオペレーションやNotificationの情報を取得することができます。

コーディング例

MBeanInfo info = mbsc.getMBeanInfo((ObjectName)name);
MBeanAttributeInfo[] attrs = info.getAttributes();
if (attrs != null){
  for (int j=0; j<attrs.length; j++) {
    System.out.println("attribute : " + attrs[j].getName());
  }
}

MBeanOperationInfo[] ops = info.getOperations();
if (ops != null){
  for (int j=0; j< ops.length; j++) {
    System.out.println("operation : " + ops[j].getName());
  }
}

MBeanNotificationInfo[] nts = info.getNotifications();
if (nts != null){
  for (int j=0; j< nts.length; j++) {
    System.out.println("nts : " + nts[j].getName());
  }
}

MBeanInfo

MBeanInfoにはそのMBeanに関する以下の情報を取得することが出来ます。

属性の情報(MBeanAttributeInfo)
属性名、属性の型などを取得することが出来ます。
オペレーションの情報(MBeanOperationInfo)
オペレーション名、返却値の型、引数の情報などを取得することが出来ます。
Notificationの情報(MBeanNotificationInfo)
サポートするNotificationのタイプを取得することが出来ます。

5.1.7. 属性の取得

MBeanの属性値を取得します。

コーディング例

// 属性の取得
Object attrValue = mbsc.getAttribute(name,attrs[j].getName());
System.out.println(attrs[j].getName() + " = " + attrValue);

属性の取得

属性を取得するにはMBeanServerConnectionの次のメソッドを呼び出します。

getAttribute :指定した属性の値を取得します。
getAttributes :指定した複数の属性の値を取得します。

5.1.8. 属性の設定

MBeanの属性値を設定します。

コーディング例

// 属性の設定
Attribute attr = new Attribute("description","sample test")；
mbsc.setAttribute(,name,attr);

属性の設定

属性を設定するにはMBeanServerConnectionの次のメソッドを呼び出します。

setAttribute :指定した属性の値を設定します。
setAttributes:指定した複数の属性の値を設定します。

5.1.9. オペレーションの呼び出し

MBeanのオペレーションを呼び出します。

コーディング例

// オペレーションの呼び出し
Object retValue = mbsc.invoke(name, "start",null,null);

オペレーションの呼び出し

オペレーションを呼び出すにはMBeanServerConnectionのinvokeメソッドを呼び出します。

5.1.10. Notificationの受信

MBeanのNotificationを受信します。

コーディング例

SampleListener listener = new SampleListener();
mbsc.addNotificationListener(name, listener, null, null);

Notificationリスナクラスの作成

Notification受信をするためのNotificationリスナを作成します。javax.management.NotificationListenerインタフェースをimplementsしたリスナクラスを作成します。 Notificationイベントが発生した場合、handleNotificationオペレーションがコールバックされるのでhandleNotificationオペレーションを実装します。

Notificationリスナの登録

Notificationを受信するにはNotificationリスナを登録する必要があります。MBeanServerConnectionのaddNotificationListenerメソッドを呼び出し、Notificationリスナを登録します。登録が完了すると指定したMBeanで発生したNotificationイベントを受信することができます。