javax.management.remote

インタフェース JMXConnector

すべてのスーパーインタフェース:

AutoCloseable, Closeable

既知のすべての実装クラス:

RMIConnector

public interface JMXConnector
extends Closeable

JMX API コネクタのクライアント側です。このタイプのオブジェクトは、コネクタサーバーに接続するために使用できます。

このタイプの新しく作成されたオブジェクトは接続されていません。このオブジェクトを使用するためには、connect メソッドを呼び出す必要があります。ただし、JMXConnectorFactory.connect で作成されたオブジェクトはすでに接続されています。

導入されたバージョン:

1.5

フィールドのサマリー

フィールド

修飾子と型	フィールドと説明
static String	CREDENTIALS 接続中にコネクタサーバーに送信する証明書を指定する属性の名前です。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
void	addConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) 接続状態の変化を通知されるリスナーを追加します。
void	close() クライアントとサーバーの接続を終了します。
void	connect() コネクタサーバーとの接続を確立します。
void	connect(Map<String,?> env) コネクタサーバーとの接続を確立します。
String	getConnectionId() コネクタサーバーから、この接続の ID を取得します。
MBeanServerConnection	getMBeanServerConnection() リモート MBean サーバーを表す MBeanServerConnection オブジェクトを返します。
MBeanServerConnection	getMBeanServerConnection(Subject delegationSubject) 指定された委譲対象の代わりにオペレーションを実行する、リモート MBean サーバーを表す MBeanServerConnection オブジェクトを返します。
void	removeConnectionNotificationListener(NotificationListener listener) 状態の変更を通知されるリスナーをリストから削除します。
void	removeConnectionNotificationListener(NotificationListener l, NotificationFilter f, Object handback) 状態の変更を通知されるリスナーをリストから削除します。

フィールドの詳細

CREDENTIALS

static final String CREDENTIALS

接続中にコネクタサーバーに送信する証明書を指定する属性の名前です。この属性に関連付けられた値は、サーバーの JMXAuthenticator の適切な型の直列化可能なオブジェクトです。

関連項目:

定数フィールド値

メソッドの詳細

connect

void connect()
             throws IOException

コネクタサーバーとの接続を確立します。このメソッドは、connect(null) と同等です。

例外:

IOException - 通信障害により接続を確立できなかった場合。

SecurityException - セキュリティー上の理由により接続を確立できなかった場合。

connect

void connect(Map<String,?> env)
             throws IOException

コネクタサーバーとの接続を確立します。

このオブジェクト上で、すでに connect が呼び出されている場合、もう 1 回呼び出しても何も起こりません。一方、connect のあとで close() が呼び出されている場合、再度 connect を呼び出すと IOException がスローされます。

このオブジェクト上で connect が 1 回も呼び出されていない場合、または、呼び出しに対して例外が生成された場合、connect を呼び出すとコネクタサーバーとの接続が試行されます。

パラメータ:

env - 接続のプロパティー。このマップ内のプロパティーは、JMXConnector の作成時に指定されたマップ内のプロパティーをオーバーライドする (存在する場合)。このパラメータが null の場合、空のマップを指定した場合と同じことになる。

例外:

IOException - 通信障害により接続を確立できなかった場合。

SecurityException - セキュリティー上の理由により接続を確立できなかった場合。

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection()
                                               throws IOException

リモート MBean サーバーを表す MBeanServerConnection オブジェクトを返します。通常、JMXConnector に対してこのメソッドを 2 回呼び出した場合、各呼び出しで同じ MBeanServerConnection オブジェクトが返されます。ただし、これは必須条件ではありません。

返された MBeanServerConnection 内の各メソッドに対してこのメソッドを呼び出すと、リモート MBean サーバー内の対応するメソッドが呼び出されます。MBean サーバーメソッドによって返される値が、クライアントに返される値となります。MBean サーバーメソッドが Exception をスローした場合、クライアントには同じ Exception が返されます。MBean サーバーメソッド自体、またはその呼び出しの試行で Error が発生した場合、クライアントには、発生した Error をラップする JMXServerErrorException が返されます。

このメソッドの呼び出しは、getMBeanServerConnection(null) の呼び出しと同等です。委譲対象が指定されておらず、MBeanServerConnection 上で呼び出されたすべてのオペレーションは認証対象 (存在する場合) を使用する必要があります。

戻り値:

メソッドをリモート MBean サーバーに転送することにより MBeanServerConnection インタフェースを実装するオブジェクト。

例外:

IOException - 有効な MBeanServerConnection を作成できない場合。たとえば、connect メソッドによるリモート MBean サーバーとの接続がまだ確立されていない場合、MBean サーバーとの接続がすでに終了している場合、接続が中断された場合など。

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection(Subject delegationSubject)
                                               throws IOException

指定された委譲対象の代わりにオペレーションを実行する、リモート MBean サーバーを表す MBeanServerConnection オブジェクトを返します。通常、JMXConnector および Subject に対してこのメソッドを 2 回呼び出した場合、各呼び出しで同じ MBeanServerConnection オブジェクトが返されます。ただし、これは必須条件ではありません。

返された MBeanServerConnection 内の各メソッドに対してこのメソッドを呼び出すと、認証対象ではなく委譲対象に代わって、リモート MBean サーバー内の対応するメソッドが呼び出されます。MBean サーバーメソッドによって返される値が、クライアントに返される値となります。MBean サーバーメソッドが Exception をスローした場合、クライアントには同じ Exception が返されます。MBean サーバーメソッド自体、またはその呼び出しの試行で Error が発生した場合、クライアントには、発生した Error をラップする JMXServerErrorException が返されます。

パラメータ:

delegationSubject - Subject。これの代わりに要求が実行される。null も可、その場合は認証済み Subject の代わりに要求が実行される (存在する場合)。

戻り値:

メソッドをリモート MBean サーバーに転送することにより、委譲対象の代わりに MBeanServerConnection インタフェースを実装するオブジェクト。

例外:

IOException - 有効な MBeanServerConnection を作成できない場合。たとえば、connect メソッドによるリモート MBean サーバーとの接続がまだ確立されていない場合、MBean サーバーとの接続がすでに終了している場合、接続が中断された場合など。

close

void close()
           throws IOException

クライアントとサーバーの接続を終了します。現行の要求または新しい要求が、getMBeanServerConnection() から返される MBeanServerConnection を使用する場合、IOException がスローされます。

このオブジェクト上で、すでに close が呼び出されている場合、もう 1 回呼び出しても何も起こりません。close が 1 回も呼び出されていない場合、または、呼び出しに対して例外が生成された場合は、接続の終了が試行されます。この試行に成功した場合、close は通常どおり終了します。失敗した場合は例外が生成されることがあります。

接続の終了は、時間のかかるオペレーションです。たとえばサーバーがクラッシュした場合、終了オペレーションはネットワークプロトコルのタイムアウトまで中断される可能性があります。終了オペレーションの途中で待たされたくない場合は、別スレッドで実行してください。

定義:

close、インタフェース: AutoCloseable

定義:

close、インタフェース: Closeable

例外:

IOException - 接続を正常に終了できない場合。この例外がスローされた場合、接続のサーバー側が正常に終了したかどうかは不明。

addConnectionNotificationListener

void addConnectionNotificationListener(NotificationListener listener,
                                     NotificationFilter filter,
                                     Object handback)

接続状態の変化を通知されるリスナーを追加します。このリスナーは、JMXConnectionNotification 型の通知を受信します。実装により、これ以外の型の通知が送信される場合もあります。

このメソッドに追加できるリスナーの数に制限はありません。フィルタとハンドバックに同一の値または異なった値を指定して、同一のリスナーを繰り返し追加することも可能です。複製エントリも特別扱いされません。たとえば、リスナーをフィルタなしで 2 回登録した場合、各通知で、このリスナーの handleNotification メソッドが 2 回呼び出されます。

パラメータ:

listener - 接続状態通知を受け取るリスナー。

filter - リスナーに配信される通知を選択するフィルタ。すべての通知を配信する場合は null。

handback - 各通知とともにリスナーに渡されるオブジェクト。null も可。

例外:

NullPointerException - listener が null である場合。

関連項目:

removeConnectionNotificationListener(javax.management.NotificationListener), NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener listener)
                                          throws ListenerNotFoundException

状態の変更を通知されるリスナーをリストから削除します。削除対象として指定できるのは、以前に追加されたリスナーのみです。条件に該当するリスナーが複数存在する場合、すべて削除されます。

パラメータ:

listener - 接続状態通知を受け取るリスナー。

例外:

NullPointerException - listener が null である場合。

ListenerNotFoundException - リスナーがこの JMXConnector に登録されていない場合。

関連項目:

removeConnectionNotificationListener(NotificationListener, NotificationFilter, Object), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener l,
                                        NotificationFilter f,
                                        Object handback)
                                          throws ListenerNotFoundException

状態の変更を通知されるリスナーをリストから削除します。削除対象として指定できるのは、以前に同じ 3 つのパラメータで追加されたリスナーのみです。条件に該当するリスナーが複数存在する場合も、削除されるのは 1 つだけです。

パラメータ:

l - 接続状態通知を受け取るリスナー。

f - リスナーに配信される通知を選択するフィルタ。null も可。

handback - 各通知とともにリスナーに渡されるオブジェクト。null も可。

例外:

ListenerNotFoundException - リスナーがこの JMXConnector に登録されていない場合、または指定されたフィルタおよびハンドバックで登録されていない場合。

関連項目:

removeConnectionNotificationListener(NotificationListener), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

getConnectionId

String getConnectionId()
                       throws IOException

コネクタサーバーから、この接続の ID を取得します。コネクタサーバー内のすべての接続は一意の ID を持ち、この ID は接続の寿命が尽きるまで変わりません。

戻り値:

この接続の一意の ID。コネクタサーバーが JMXConnectionNotification に格納する ID と同じ。package description は接続 ID の規約の説明。

例外:

IOException - 接続の終了、中断などが原因で接続 ID を取得できない場合。