10 JMX APIの基本要素

コード例2-1 MBeanインタフェース、HelloMBean

 
package com.example.mbeans; 
 
public interface HelloMBean { 
 
    public void sayHello(); 
    public int add(int x, int y); 
 
    public String getName(); 
 
    public int getCacheSize(); 
    public void setCacheSize(int size); 
} 
 

MBeanインタフェースは、このインタフェースを実装するJavaクラスの名前の後にMBeanを加えて名前を構成します。このインタフェースがHelloMBeanです。このインタフェースを実装するHelloクラスについては、MBeanの実装で説明します。

JMX仕様によると、MBeanインタフェースは、名前と型の指定された読込み可能で、場合によっては書込み可能な属性と、MBeanが管理するアプリケーションにより呼び出すことが可能な、名前と型の指定された操作から構成されます。コード例2-1 MBeanインタフェース、HelloMBeanに示したHelloMBeanインタフェースでは、2つの操作(Javaメソッドadd()とsayHello())を宣言しています。

HelloMbeanで宣言される2つの属性のうち、Nameは読込み専用の文字列で、CacheSizeは読み込みと書込みの両方が可能な整数です。取得メソッドと設定メソッドは、管理対象アプリケーションに属性の値へのアクセスと、場合によっては値の変更を許可するために宣言されます。JMX仕様に定義されるように、取得メソッドはgetから名前が始まり、voidを返さないすべてのpublicメソッドです。取得メソッドを使用すると、マネージャは返されたオブジェクトの型と一致する属性の値を読み込むことができます。設定メソッドは名前がsetから始まり、単一のパラメータをとるすべてのpublicメソッドです。設定メソッドを使用すると、マネージャはパラメータと同じ型の値を属性に新たに書き込むことができます。

次のセクションでは、これらの操作および属性の実装を説明します。

コード例2-2 MBeanの実装クラス、Hello

 
package com.example.mbeans; 
 
public class Hello implements HelloMBean { 
    public void sayHello() { 
        System.out.println("hello, world"); 
    } 
 
    public int add(int x, int y) { 
        return x + y; 
    } 
 
    public String getName() { 
        return this.name; 
    } 
 
 
    public int getCacheSize() { 
        return this.cacheSize; 
    } 
 
    public synchronized void setCacheSize(int size) { 
        this.cacheSize = size; 
 
        System.out.println("Cache size now " + this.cacheSize); 
    } 
 
    private final String name = "Reginald"; 
    private int cacheSize = DEFAULT_CACHE_SIZE; 
    private static final int DEFAULT_CACHE_SIZE = 200; 
} 
 

例2-2では、JavaクラスHelloは、HelloMBeanで宣言された操作と属性を定義します。この例からわかるように、例sayHello()とadd()の操作はきわめて簡単ですが、実際の操作は必要に応じて簡単にも、複雑なものにもできます。

Name属性を取得するメソッドと、cacheSize属性を取得し設定するメソッドも定義されます。この例では、Name属性の値は変わりませんが、実際の場面では、管理対象リソースの実行により変わる場合があります。たとえば、属性は稼動時間やメモリーの使用量などの統計を表す場合があります。ここでは、属性は「Reginald」という名前だけです。

setCacheSizeメソッドを呼び出すと、cacheSize属性の値を、宣言されたデフォルトの値200から変更できます。実際には、cacheSize属性を変更する場合は、エントリの破棄や新しいエントリの割り当てなど、ほかの操作を実行しなければなりません。この例では、キャッシュ・サイズが変更されたことを確認するメッセージのみが出力されますが、println()を呼び出す操作のかわりに、より複雑な操作を定義できます。

Hello MBeanとそのインタフェースを定義すると、次のセクションに示すように、Hello MBeanとインタフェースで表されるリソースを、Hello MBeanとインタフェースを使用して管理できます。

コード例2-3 JMXエージェントの作成

 
package com.example.mbeans; 
 
import java.lang.management.*; 
import javax.management.*; 
 
public class Main { 
 
   public static void main(String[] args) throws Exception { 
 
      MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 
 
      ObjectName name = new ObjectName("com.example.mbeans:type=Hello"); 
 
      Hello mbean = new Hello(); 
 
      mbs.registerMBean(mbean, name); 
 
      System.out.println("Waiting forever..."); 
      Thread.sleep(Long.MAX_VALUE); 
   } 
} 
 

例2-3では、JMXエージェントMainは、まずjava.lang.management.ManagementFactoryクラスのgetPlatformMBeanServer()メソッドを呼び出して、プラットフォーム上で稼動する任意のMBeanサーバーを取得します。プラットフォーム上で稼動中のMBeanが存在しない場合、getPlatformMBeanServer()によりJMXメソッドMBeanServerFactory.createMBeanServer()が呼び出され、自動的に稼動中のMBeanが作成されます。Mainで取得されるMBeanServerインスタンスは、mbsの名前が付けられます。

次に、Mainは作成するMBeanインスタンスのために、オブジェクト名を定義します。すべてのJMX MBeanにオブジェクト名が定義される必要があります。オブジェクト名はJMXクラスObjectNameのインスタンスであり、ドメインとキー・プロパティのリストを必ず含めるなど、JMX仕様で定義される構文に従う必要があります。この構文の詳細は、ObjectNameクラスのAPIドキュメントを参照してください。Mainで定義されるオブジェクト名、nameでは、ドメインはcom.example.mbeans (MBeanの例が格納されたパッケージ)です。また、キー・プロパティはこのオブジェクトがHello型であることを宣言します。

Helloオブジェクトのインスタンス、mbeanが作成されます。このHelloオブジェクトは、MBeanの実装で定義されたMBean Helloのインスタンスです。

Helloオブジェクトmbeanは、オブジェクト名nameを使用してMBean server mbsにMBeanとして登録されます。このために、オブジェクトとオブジェクト名を渡してJMXメソッドMBeanServer.registerMBean()を呼び出します。

Hello MBeanをMBeanサーバーに登録したあと、Mainは管理操作がHelloで実行されるのを待機します。この例の範囲では、これらの管理操作はsayHello()とadd()を呼び出し、属性値を取得および設定しています。

コード例2-4 MBeanの通知の実装

 
package com.example.mbeans; 
 
import javax.management.*; 
 
public class Hello 
        extends NotificationBroadcasterSupport implements HelloMBean { 
 
    public void sayHello() { 
        System.out.println("hello, world"); 
    } 
 
    public int add(int x, int y) { 
        return x + y; 
    } 
 
    public String getName() { 
        return this.name; 
    } 
 
    public int getCacheSize() { 
        return this.cacheSize; 
    } 
 
    public synchronized void setCacheSize(int size) { 
        int oldSize = this.cacheSize; 
        this.cacheSize = size; 
 
        System.out.println("Cache size now " + this.cacheSize); 
 
        Notification n = 
            new AttributeChangeNotification(this, 
                                            sequenceNumber++, 
                                            System.currentTimeMillis(), 
                                            "CacheSize changed", 
                                            "CacheSize", 
                                            "int", 
                                            oldSize, 
                                            this.cacheSize); 
 
        sendNotification(n); 
    } 
 
    @Override 
    public MBeanNotificationInfo[] getNotificationInfo() { 
        String[] types = new String[] { 
            AttributeChangeNotification.ATTRIBUTE_CHANGE 
        }; 
        String name = AttributeChangeNotification.class.getName(); 
        String description = "An attribute of this MBean has changed"; 
        MBeanNotificationInfo info = 
            new MBeanNotificationInfo(types, name, description); 
        return new MBeanNotificationInfo[] {info}; 
    } 
 
    private final String name = "Reginald"; 
    private int cacheSize = DEFAULT_CACHE_SIZE; 
    private static final int DEFAULT_CACHE_SIZE = 200; 
 
    private long sequenceNumber = 1; 
} 
 

コード例2-4 MBeanの通知の実装に示したように、このHello MBeanの実装によりNotificationBroadcasterSupportクラスが拡張され、このクラス自体にNotificationEmitterインタフェースが実装されます。

操作と属性の設定方法は以前と同様ですが、唯一変わったのはcacheSize属性の設定メソッドがoldSizeという新しい値を定義する点です。この値は設定操作の前にcacheSize属性の値を記録します。

通知は、javax.management.Notificationを拡張するJMXクラスAttributeChangeNotificationのインスタンスnから構築されます。この通知はAttributeChangeNotificationにパラメータとして渡される次の情報に基づいて、setCacheSize()メソッドの定義内で構築されます。

• Hello MBeanなどの通知の発行元のオブジェクト名。簡単にthisと表される
• シーケンス番号。この例では、ロング名sequenceNumberが使われ、1に設定されたあと、1つずつインクリメントする
• タイムスタンプ
• 通知メッセージの内容
• 変更された属性の名前。この場合はcacheSize
• 変更された属性の型
• 古い属性値。この場合はoldSize
• 新しい属性値。この場合はthis.cacheSize

この後、通知nがNotificationBroadcasterSupport.sendNotification()メソッドに渡されます。

最後に、MBeanNotificationが定義され、特定のJavaクラスの通知、この場合はAttributeChangeNotificationに対してMBeanが発行した別の通知インスタンスの特性が説明されます。

MBeanインタフェースHelloMBeanとJMXエージェントMainは、前出の例で使用されたものと同じです。

コード例2-5 QueueSamplerMXBeanインタフェース

 
package com.example.mxbeans; 
 
public interface QueueSamplerMXBean { 
    public QueueSample getQueueSample(); 
    public void clearQueue(); 
} 
 

この例からわかるように、MXBeanインタフェースの宣言は標準MBeanの宣言とまったく同じです。QueueSamplerMXBeanインタフェースでは、getQueueSampleとclearQueueという2つの操作を宣言しています。

コード例2-6 QueueSamplerクラス

package com.example.mxbeans; 
 
import java.util.Date; 
import java.util.Queue; 
 
public class QueueSampler implements QueueSamplerMXBean { 
     
    private Queue<String> queue; 
     
    public QueueSampler(Queue<String> queue) { 
       this.queue = queue; 
    } 
     
    public QueueSample getQueueSample() { 
        synchronized (queue) { 
            return new QueueSample(new Date(), queue.size(), queue.peek()); 
        } 
    } 
     
    public void clearQueue() { 
        synchronized (queue) { 
            queue.clear(); 
        } 
    } 
} 
 

MXBeanインタフェースで宣言されたMXBean操作のgetQueueSample()およびclearQueue()は、QueueSamplerで定義されます。getQueueSample()操作は単純に、QueueSample Java型(java.util.Queueメソッドのpeek()およびsize()によって返された値を使用して作成)のインスタンスとjava.util.Dateのインスタンスを返します。

コード例2-7 QueueSampleクラス

package com.example.mxbeans; 
 
import java.beans.ConstructorProperties; 
import java.util.Date; 
 
public class QueueSample { 
     
    private final Date date; 
    private final int size; 
    private final String head; 
     
    @ConstructorProperties({"date", "size", "head"}) 
    public QueueSample(Date date, int size, String head) { 
        this.date = date; 
        this.size = size; 
        this.head = head; 
    } 
     
    public Date getDate() { 
        return date; 
    } 
     
    public int getSize() { 
        return size; 
    } 
     
    public String getHead() { 
        return head; 
    } 
} 
 

QueueSampleクラスでは、MXBeanフレームワークがQueueSampleの取得メソッドをすべて呼び出して、指定されたインスタンスをCompositeDataに変換し、@ConstructorProperties注釈を使用して、CompositeDataからQueueSampleインスタンスを再構築します。

コード例2-8 MXBeanのMainクラスの例

package com.example.mxbeans; 
 
import java.lang.management.ManagementFactory; 
import java.util.Queue; 
import java.util.concurrent.ArrayBlockingQueue; 
import javax.management.MBeanServer; 
import javax.management.ObjectName; 
 
public class Main { 
 
    public static void main(String[] args) throws Exception { 
        MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 
         
        ObjectName name = 
                new ObjectName("com.example.mxbeans:type=QueueSampler"); 
         
        Queue<String> queue = new ArrayBlockingQueue<String>(10); 
        queue.add("Request-1"); 
        queue.add("Request-2"); 
        queue.add("Request-3"); 
        QueueSampler mxbean = new QueueSampler(queue); 
         
        mbs.registerMBean(mxbean, name); 
         
        System.out.println("Waiting..."); 
        Thread.sleep(Long.MAX_VALUE); 
    } 
} 
 

Mainクラスは、プラットフォームMBeanサーバーを取得して、MXBean QueueSamplerのオブジェクト名を作成し、QueueSampler MXBeanのQueueインスタンスを作成して処理します。次に、このQueueインスタンスを、新規作成されたQueueSampler MXBeanに送ります。これで標準MBeanとまったく同じように、MXBeanがMBeanサーバーに登録されます。

コード例2-9 Author注釈

 
package com.example.mxbeans; 
 
import java.lang.annotation.Documented; 
import java.lang.annotation.ElementType; 
import java.lang.annotation.Retention; 
import java.lang.annotation.RetentionPolicy; 
import java.lang.annotation.Target; 
import javax.management.DescriptorKey; 
 
@Documented 
@Target(ElementType.TYPE) 
@Retention(RetentionPolicy.RUNTIME) 
public @interface Author { 
    @DescriptorKey("author") 
    String value(); 
} 

この注釈は、MBeanインタフェースの作成者の名前を提供します。新しいフィールドauthorは、@Author注釈によって定義された値を持つMBeanInfo記述子に追加されます。ファイルVersionおよびDisplayNameは、これらの名前の注釈を、前述のAuthorの場合とまったく同様に定義します。VersionおよびDisplayNameの@DescriptorKey値は、それぞれ“version”および“displayname”です。

Versionの場合、新しいフィールドversionは@Version注釈によって定義された値を持つMBeanInfo記述子に追加されます。

DisplayNameの場合、新しいフィールドdisplayNameは、注釈を付けられたメソッドが取得メソッド/設定メソッドと操作のどちらであるかに応じて、それぞれ@DisplayName注釈によって定義された値を持つMBeanAttributeInfo記述子またはMBeanOperationInfo記述子に追加されます。

コード例2-10 記述子を使用したQueueSamplerMXBean

 
package com.example.mxbeans; 
 
@Author("Mr Bean") 
@Version("1.0") 
public interface QueueSamplerMXBean { 
    @DisplayName("GETTER: QueueSample") 
    public QueueSample getQueueSample(); 
    @DisplayName("OPERATION: clearQueue") 
    public void clearQueue(); 
} 
 

これで@Author注釈はMr. Bean、@Version注釈は1.0、@DisplayNameは属性QueueSampleと操作clearQueueのどちらかの名前に設定されます。