インデックス

JMXを使ってJava Service Wrapperをコントロールする

Java Service Wrapperは、Java Management Extensions (JMX) MBean インターフェイス (J2SE 5.0 JMX, JavaSE6 JMX) を提供しており、それを使うと、JMXインターフェイスを利用しているWrapperのコントロールが可能です。 このセクションではJMX対応の自分のアプリケーションの設定方法について説明しており、 Java Service Wrapperで提供しているMBeansが有効になります。

JConsole

オラクルのJDK5.0から、 Javaモニタリング(監視)管理コンソールツール『JConsole (J2SE 5.0)』 『JConsole (JavaSE6)』 が導入されました。 詳細はそのリンク先をご覧いただきますが、 JConsoleは、適切に、設定されたJVMへの接続を簡単にし、様々な機能を監視および管理します。

セキュリティ上の理由のため、JVMを遠隔モニタリング(監視)する機能は、デフォルトで有効になっていません。 この機能を有効にするために、JVM起動時に [com.sun.management.jmxremote (J2SE 5.0), (JavaSE6)] システムプロパティを定義する必要があります。 下記のとおり、 [wrapper.java.additional.<n>] プロパティを使って、JVMパラメータを指定して、 Wrapperを利用することで可能になります。

設定例:(JVMパラメータの指定)
wrapper.java.additional.1=-Dcom.sun.management.jmxremote

現在、Java Service Wrapperは2つのMBeanインターフェイスを提供しています。

一つ目のMBean、 [org.tanukisoftware.wrapper.jmx.WrapperManagerMBean]、 インターフェイスは、WrapperやJVMの基本情報を提供しており、JVMを停止したり再起動したり、 完全なフルスレッドダンプをトリガーする機能なども提供しています。 このMBeanの登録は、 [org.tanukisoftware.wrapper.WrapperManager.mbean] システムプロパティを設定することでコントロールされています。 デフォルトで有効です。

二つ目のMBean、 [org.tanukisoftware.wrapper.jmx.WrapperManagerTestingMBean]、 インターフェイスは、テスト用に様々な障害状況をトリガーすることを可能にしますが、 テスト環境の外部では利用するべきではありません。 このMBeanの登録は、 [org.tanukisoftware.wrapper.WrapperManager.mbean.testing] システムプロパティを設定することでコントロールされています。 デフォルトで無効です。

設定例:(JVMパラメータの指定)
wrapper.java.additional.1=-Dcom.sun.management.jmxremote
wrapper.java.additional.2=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean=TRUE
wrapper.java.additional.3=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean.testing=false

登録されたWrapper MBeansは、 [org.tanukisoftware.wrapper] パッケージ下で、JConsoleインターフェイスのMBeanタブ上に表示されます。

JBoss

JBossで、Java Service WrapperのMBeanインターフェイスを登録する方法は驚くほどシンプルです。 これは、既にJBossがJava Service Wrapperでインテグレーションされているという前提の話です。 インテグレーション方法1のセクションで、 特にJBossを利用している例がありますので参照してください。 この説明では、JBossインテグレーション例で説明しているディレクトリーに、 全てのWrapperファイルをインストールしているという前提で進めます。 特に、「wrapper.jar」ファイルが、 「${jboss.home}/lib」ディレクトリーに配置されていると仮定します。

JBossでは、「MBean」によって追加される、 クラスと同じ名前を持つインターフェイスを実装しているいかなるオブジェクト、1つのMBeanとして、登録できます。 Java Service Wrapperは、そのような2つのクラス [WrapperManager]と [WrapperManagerTesting]を [org.tanukisoftware.wrapper.jmx] パッケージで提供しています。

一つ目のクラス [WrapperManager] では、Java Service Wrapperに関する他の情報を提供すると同様に、「JVM再起動」や「JVM停止」のいくつかの機能を提供しています。 二つ目のクラス [WrapperManagerTesting] では、動作テストで便利な2,3つの方法に触れています。 それらのクラスは、最終商品リリースに含めたくない場合には、They are broken out. さらに詳しくは、JavaDocs をご覧ください。

上記の両方のMBeansを登録するには、 「${jboss.home}/server/default/deploy」ディレクトリーに、 ファイル名「java-service-wrapper-service.xml」で XMLファイルを作成してください。 そのファイルは以下のものが含まれているはずです:

設定例:(java-service-wrapper-service.xml)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE server>
<server>
    <classpath archives="wrapper.jar" codebase="../../lib"/>
    
    <mbean code="org.tanukisoftware.wrapper.jmx.WrapperManager"
               name="JavaServiceWrapper:service=WrapperManager"/>
    
    <mbean code="org.tanukisoftware.wrapper.jmx.WrapperManagerTesting"
               name="JavaServiceWrapper:service=WrapperManagerTesting"/>
</server>

wrapper.jar」ファイルの配置場所は、 XMLファイルの配置場所への相対参照であることに注意してください。

そのファイルを保存すると、ほとんど即座に、JBossはそれを検知して、 作成した新しいMBeansを登録するはずです。 JBossを再起動する必要はありません。イケてるね。

では、実際に新しいMBeansを利用するには、シンプルに、ご利用のブラウザで JBossのJMX「http://localhost:8080/jmx-console/」へ アクセスしてください: 2つのMBeans[WrapperManager]と [WrapperManagerTesting]がある、 JavaServiceWrapperエージェントに気がつくことでしょう。 どちらかのMBeansを選択すると、 そのMBeansによって提供されるアクションやアトリビュート(属性)のセットが表示されます。

JBoss 6.*

Please make sure you have done all steps as described above.

JBoss with version 6 is utilizing internally a MBeanServer Factory based on org.jboss.system.server.jmx.MBeanServerBuilderImpl, however this one is incompatible to the default JVM MBeanServerBuilder (javax.management.MBeanServerBuilder). Usually this wouldn't be a problem as JBoss when running stand-alone it sets the Platform MBeanService and all subsequent MBeans will be created from its MBeanServerBuilder. However when the Wrapper starts, it will register its MBeans and hence the JVM doesn't have a MBeanServer at this time yet, it will create a MBeanServer using the JVM's default MBeanServer. When JBoss starts, it tries to register its MBeans to the MBeanServer, however because of the incompatibility with the default JVM's MBeanServer, JBoss will fail to register any MBean.

In order to use the MBeans of the Wrapper and make it possible for JBoss to register its MBeans, the JVM needs to get instructed to not use the default Factory but the one used by JBoss, which is in fact just an extension of the default. In order to do so you need to set the following properties:

wrapper.java.classpath.N=%JBOSS_HOME%/lib/jboss-logmanager.jar

wrapper.java.additional.N=-Djboss.platform.mbeanserver
wrapper.java.additional.N=-Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl
wrapper.java.additional.N=-Djava.util.logging.manager=org.jboss.logmanager.LogManager
wrapper.java.additional.N=-Dorg.jboss.logging.Logger.pluginClass=org.jboss.logging.logmanager.LoggerPluginImpl

Please make sure N is a number, which hasn't been assigned.

In detail the above properties mean, that JBoss should use the platform MBeanServer to register MBeans (-Djboss.platform.mbeanserver). The JVM should use org.jboss.system.server.jmx.MBeanServerBuilderImpl as MBeanServer Factory (-Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl). Hence to that, the Log Manager of the JVM and JBoss have to be redefined. As this Log Manager is not on the classpath, it also needs to get added there.

After this steps have been done, the Wrapper should be able to run JBoss 6.* without any problems and able to register it's MBeans side-by-side with JBoss.

MX4J

ToDoリスト(作業中)。 (このセクションは未完成で、単なる忘備録として掲載しています。 このセクションの提案をお気軽に送信してください)

MX4J

Sun JMX リファレンス実装

ToDoリスト(作業中)。 (このセクションは未完成で、単なる忘備録として掲載しています。 このセクションの提案をお気軽に送信してください)

オラクスのリファレンス実装は、ただのリファレンス実装です。 WrapperのMBeansを登録する際に決まった手順はなく、 各アプリケーションでそのBeans登録のカスタム方法を作成する傾向にあります。

多くのアプリケーションでは、それぞれのシンタックス(構造文法ルール)で定義しますが、 オラクスでは、MBeansを定義する1つの手法として、Management Appletのショート、「MLET」タグを定義します。 そのシンタックス(構造文法ルール)は、JavaDocsで、 [javax.management.loading.MLet(J2SE 1.4) (J2SE 5.0) (JavaSE6) (JavaSE7)] クラスについて説明しています。 次のMLETタグは、Wrapperで提供されたMBeansの登録に利用できます。 それらは本当のXMLではないことに注意してください。

MLETタグ
<MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManager
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManager>
<MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManagerTesting
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManagerTesting>

さらに詳しくは、オラクルのサイト 『Java Managagement Extensions (JMX)』 をご覧ください。

(Java Management Extensions(JMX) ドキュメンテーション: J2SE 5.0 / JavaSE 6