5 JMXを使用したドメインの構成の管理
この章の内容は以下のとおりです。
WebLogic Serverドメインの変更、および変更のアクティブ化のプロセスを理解するには、Oracle WebLogic Serverドメイン構成の理解の構成の変更の管理を参照してください。
MBean属性の編集:主なステップ
MBean属性を編集するには、次の手順に従います。
親トピック: JMXを使用したドメインの構成の管理
MBean属性の変更または新しいMBean作成
既存のMBeanの属性値を変更する、新しいMBeanを作成する、またはMBeanを削除するには、次の手順に従います。
親トピック: MBean属性の編集: 主なステップ
編集操作によってスローされる例外の型
表5-1では、編集操作中にWebLogic Serverがスローする可能性があるすべての例外の型について説明します。WebLogic Serverがこのような例外をスローすると、MBeanサーバーはjavax.management.MBeanExceptionで例外をラップします。(Java SE 17 API仕様のMBeanException (https://docs.oracle.com/en/java/javase/17/docs/api/java.management/javax/management/MBeanException.html)を参照してください。)
表5-1 編集操作によってスローされる例外の型
| 例外の型 | スローされる場合 |
|---|---|
EditTimedOutException |
編集セッションを開始するリクエストがタイムアウトした場合。 |
NotEditorException |
ロックを取得せずにMBeanを編集しようとした場合、または、管理ユーザーが現在のロックを取り消して編集セッションを開始する場合。 |
ValidationException |
MBean属性の値を、誤ったデータ型、許容される範囲外の値、指定された値ではない値、他の属性との依存関係に適合しない値などに設定した場合。 |
親トピック: MBean属性の編集: 主なステップ
変更の表示と取消し
以下の節では、編集セッション中に行った変更の操作について説明します。
WebLogic Serverはjavax.management.openmbean.CompositeType型のChangeオブジェクトに変更を記述します。Java SE 17 API仕様のCompositeType (https://docs.oracle.com/en/java/javase/17/docs/api/java.management/javax/management/openmbean/CompositeType.html)を参照してください。
JMXを通じて、現在のサーバー・セッション中にのみ発生したドメインの構成の変更に関する情報にアクセスできます。WebLogic Serverは構成ファイルのアーカイブを保持しますが、JMXを通じてアーカイブされたデータを利用したり、アーカイブのバージョンを比較したりはできません。
保存されていない変更の表示
MBean属性を変更するたびに、WebLogic Serverはその変更に関する情報が含まれるChangeオブジェクトを作成します。変更を保存するまでは、これらのオブジェクトにConfigurationManagerMBean Changes属性からアクセスできます。Oracle WebLogic Server MBeanリファレンスのConfigurationManagerMBeanを参照してください。
編集セッションを終了するときに、保存されていない変更は破棄されます。
保存されていない変更を表示するには、次の手順に従います。
例5-1 保存されていない変更を表示するサンプル・メソッド
public void listUnsaved() throws Exception {
ObjectName cfgMgr = (ObjectName) connection.getAttribute(service,
"ConfigurationManager");
Object[] list = (Object[])connection.getAttribute(cfgMgr, "Changes");
int length = (int) list.length;
for (int i = 0; i < length; i++) {
System.out.println("Unsaved change: " + list[i].toString());
}
}例5-1のコードでは、保存されていない変更を表示するメソッドを作成します。呼出し側メソッドは編集MBeanサーバーとの接続をすでに確立しているものとします。
親トピック: 変更の表示と取消し
アクティブ化されていない変更の表示
変更が保存されると、WebLogic Serverは保留中の構成ファイルで変更を永続化します。編集セッションを開始したユーザーがConfigurationManagerMBean undoUnactivatedChanges()操作(アクティブ化されていない変更を保留中ファイルから元に戻す)を呼び出さない限り、複数の編集セッションにわたる場合でも、変更は保留中の構成ファイルに保持されます。
ConfigurationManagerMBean UnactivatedChanges属性には、保存されていない変更と、保存されてまだアクティブ化されていない変更の両方のChangeオブジェクトが格納されます。(保存されてまだアクティブ化されていない変更のみを格納する属性はありません。)Oracle WebLogic Server MBeanリファレンスのConfigurationManagerMBeanのアクティブ化されていない変更を参照してください。
現在の編集セッション中に保存してまだアクティブ化していない変更、または以前の編集セッションで保存されてまだアクティブ化されていない変更を表示するには、次の手順に従います。
例5-2 アクティブ化されていない変更を表示するサンプル・メソッド
public void listUnactivated() throws Exception {
ObjectName cfgMgr = (ObjectName) connection.getAttribute(service,
"ConfigurationManager");
Object[] list = (Object[])connection.getAttribute(cfgMgr,
"UnactivatedChanges");
int length = (int) list.length;
for (int i = 0; i < length; i++) {
System.out.println("Unactivated changes: " + list[i].toString());
}
}例5-2のコードでは、アクティブ化されていない変更を表示するメソッドを作成します。呼出し側メソッドは編集MBeanサーバーとの接続をすでに確立しているものとします。
親トピック: 変更の表示と取消し
現在のアクティブ化タスクにある変更の表示
変更をアクティブ化すると、WebLogic ServerはActivationTaskMBeanのインスタンスを作成します。このインスタンスには、アクティブ化される変更ごとに1つのChangeオブジェクトが格納されます。このActivationTaskMBeanには、次のいずれかからアクセスできます。
-
ConfigurationManagerMBeanactivate()メソッド - 現在のアクティブ化タスクを表すActivationTaskMBeanのオブジェクト名を返します。 -
ConfigurationManagerMBeanCompletedActivationTasks属性 - 現在の管理サーバーのインスタンス化中に作成されたすべてのActivationTaskMBeanインスタンスのリストが含まれている可能性があります。「メモリーに格納されているすべてのアクティブ化タスクの表示」を参照してください。
現在のアクティブ化タスクにある変更のみを表示するには、次の手順に従います。
例5-3 現在のアクティブ化タスクにある変更を表示するサンプル・メソッド
public void activateAndList()
throws Exception {
ObjectName cfgMgr = (ObjectName) connection.getAttribute(service,
"ConfigurationManager");
ObjectName task = (ObjectName) connection.invoke(cfgMgr, "activate",
new Object[] { new Long(120000) }, new String[] { "java.lang.Long" });
Object[] changes = (Object[])connection.getAttribute(task, "Changes");
int i = (int) changes.length;
for (int i = 0; i< i; i++) {
System.out.println("Changes activated: " + changes[i].toString());
}
}例5-3のコードでは、現在の編集セッションでアクティブ化されたすべての変更を表示するメソッドを作成します。呼出し側メソッドは編集MBeanサーバーとの接続をすでに確立しているものとします。
親トピック: 変更の表示と取消し
変更の取消し
ConfigurationManagerMBeanには、編集セッション中に行われた変更を取り消すための2つの操作があります。
-
undo保存されていない変更を元に戻します。
-
undoUnactivatedChanges保存されているかどうかに関わらず、まだアクティブ化されていないすべての変更を元に戻します。以前の編集セッションで他のユーザーが変更を保存して、その変更をアクティブ化していない場合に、
ConfigurationManagerMBeanundoUnactivatedChanges()操作を呼び出すと、それらの変更も元に戻されます。このメソッドを呼び出した後、保留中の構成ファイルは、アクティブなサーバーが使用している動作中の構成ファイルと同じになります。
変更を取り消すには、編集セッションを開始して、ConfigurationManagerMBean undoまたはundoUnactivatedChanges操作を呼び出します。
たとえば:
connection.invoke(cfgMgr, "undo", null, null);
親トピック: 変更の表示と取消し
変更のアクティブ化の追跡
activate操作を呼び出すときにWebLogic Serverが作成する各ActivationTaskMBeanでは、変更のリストを保持する他に、変更をアクティブ化したユーザー、アクティブ化タスクのステータス、変更がアクティブ化された時刻が記述されます。
管理サーバーはActivationTaskMBeanのインスタンスをメモリー内にのみ保持します。つまり、インスタンスは永続化されず、管理サーバーを停止するときに破棄されます。ActivationTaskMBeanインスタンスにはChangeオブジェクトのリスト(各オブジェクトはMBean属性の1つの変更を表す)が含まれているため、メモリーを大量に使用します。メモリーを節約するため、デフォルトでは、管理サーバーはごく最近のActivationTaskMBeanインスタンスしかメモリー内に保持しません。デフォルトを変更するには、ConfigurationManagerMBean CompletedActivationTasksCount属性の値を増やします。
以下の節では、ActivationTaskMBeanのインスタンスの操作について説明します。
親トピック: JMXを使用したドメインの構成の管理
現在のアクティブ化タスクのステータスの表示
activate操作を呼び出すと、WebLogic Serverはアクティブ化タスクを表現するActivationTaskMBeanインスタンスを返します。
ActivationTaskMBean State属性は、アクティブ化タスクのステータスを表します。この属性にはint値が格納され、ActivationTaskMBeanは各int値の定数を定義します。Oracle WebLogic Server MBeanリファレンスのActivationTaskMBeanを参照してください。
現在のアクティブ化タスクのステータスを表示するには、次の手順に従います。
- 編集セッションを開始して、少なくとも1つのMBean属性を変更します。
ConfigurationManagerMBeanactivate(long timeout)操作を呼び出して、その出力をActivationTaskMBean型の変数に割り当てます。ActivationTaskMBeanState属性の値を取得します。
親トピック: 変更のアクティブ化の追跡
メモリーに格納されているすべてのアクティブ化タスクの表示
activate操作が返すActivationTaskMBeanは1つのアクティブ化タスクのみを表します。管理サーバーは、ユーザーがパージするまでこのActivationTaskMBeanをメモリー内に保持します(「完了したアクティブ化タスクのメモリーからのパージ」を参照)。パージしないと、アクティブ化タスクの数はConfigurationManagerMBean CompletedActivationTasksCount属性の値を超えます。
現在メモリーに格納されているすべてのActivationTaskMBeanインスタンスにアクセスするには、次の手順に従います(例5-4を参照してください):
例5-4 メモリー内のすべてのアクティブ化タスクを表示するサンプル・メソッド
public void listActivated() throws Exception {
ObjectName cfgMgr = (ObjectName) connection.getAttribute(service,
"ConfigurationManager");
ObjectName[] list = (ObjectName[])connection.getAttribute(cfgMgr,
"CompletedActivationTasks");
System.out.println("Listing completed activation tasks.");
int length = (int) list.length;
for (int i = 0; i < length; i++) {
System.out.println("Activation task " + i);
System.out.println("User who started activation: " +
connection.getAttribute(list[i], "User"));
System.out.println("Task state: " + connection.getAttribute(list[i],
"State"));
System.out.println("Start time: " + connection.getAttribute(list[i],
"StartTime"));
Object[] changes = (Object[])connection.getAttribute(list[i], "Changes");
int l = (int) changes.length;
for (int y = 0; y < l; y++) {
System.out.println("Changes activated: " + changes[y].toString());
}
}
}親トピック: 変更のアクティブ化の追跡
完了したアクティブ化タスクのメモリーからのパージ
ActivationTaskMBeanインスタンスにはChangeオブジェクトのリスト(各オブジェクトはMBean属性の1つの変更を表す)が含まれているため、メモリーを大量に使用します。
管理サーバーでメモリー不足になった場合は、完了したアクティブ化タスクをメモリーからパージできます。その後でConfigurationManagerMBean CompletedActivationTasksCount属性の値を減らします。
完了したアクティブ化タスクをメモリーからパージするには、編集MBeanサーバーに接続して、ConfigurationManagerMBean purgeCompletedActivationTasks操作を呼び出します。
たとえば:
connection.invoke(cfgMgr, "purgeCompletedActivationTasks", null, null);
親トピック: 変更のアクティブ化の追跡
ロックの管理
変更によって保留中の構成MBean階層が矛盾した状態にならないように、一度に1人のユーザーだけがMBeanを編集できます。ユーザーがConfigurationManagerMBean startEdit操作を呼び出すと、ConfigurationManagerMBeanは他のユーザーが編集セッションを開始できないように(ロック)します。
以下のアクションによってロックが解除されます。
-
ConfigurationManagerMBeanactivate操作が成功するか、タイムアウトします。ActivationTaskMBeanwaitForTaskCompletion操作を使用すると、アクティブ化プロセスが完了するまでブロックできます。 -
ConfigurationManagerMBeanstopEdit操作が成功します。 -
他のユーザーがロックを取得しているときに、管理者権限を持つユーザーが
ConfigurationManagerMBeancancelEdit操作を呼び出します。たとえば、
connection.invoke(cfgMgr, "cancelEdit", null, null); -
あるユーザーIDにより編集セッションが開始され、別のプロセスが同じユーザーIDで編集セッションを開始します。
たとえば、WebLogicリモート・コンソールを使用して編集セッションを開始し、その後でWebLogic Scripting Tool (WLST)を使用して同じユーザーIDで編集セッションを開始することができます。WLSTのセッションによってWebLogicリモート・コンソールのセッションのロックは解除されます。
別のプロセスが同じユーザーIDで編集セッションを開始しないようにするには、
startEdit操作にbooleanの値trueを渡して、排他的なロックを取得します。Oracle WebLogic Server MBeanリファレンスのstartEdit(waitTimeInMillis, timeOutInMillis, exclusive)を参照してください。
ロックが解除されると、保存されていないすべての変更は失われます。
親トピック: JMXを使用したドメインの構成の管理
ベスト・プラクティス:編集と例外処理の推奨パターン
編集するコードを複数のtry-catchブロックに整理することをお薦めします。そのようにすると、特定の型のエラーを捕捉して適切に対応できます。たとえば、編集が無効な場合に編集セッション全体を破棄するのではなく、その変更を保存して、例外をスローし、無効な変更をアクティブ化せずに終了することができます。
JMXエージェントはすべての例外をjavax.management.MBeanException型の汎用的な例外でラップします。JMXクライアントはMBeanException.getTargetException()を使用して、ラップされた例外のラップを解除することができます。
次のような構成を利用することを検討してください(例5-5の擬似コードを参照してください):
-
編集MBeanサーバーに接続し、編集セッションを開始し、変更を行って保存するtryブロック。
このtryブロックの後、
MBeanException内にラップされた以下の型の例外ごとに1つのcatchブロック。-
EditTimedOutExceptionConfigurationManagerMBeanstartEdit()操作が指定された時間内にロックを取得できない場合、この例外がスローされます。 -
NotEditorException編集セッションがタイムアウトするか、管理者がユーザーの編集セッションを取り消した場合、この例外がスローされます(「ロックの管理」を参照してください。)
-
ValidationException誤ったデータ型、許容される範囲外の値、指定された値ではない値、他の属性との依存関係に適合しない値などをMBeanに設定した場合、この例外がスローされます。
ValidationExceptionを処理するコードの内部には、検証エラーを修正する、またはConfigurationManagerMBeanstopEdit()操作を呼び出して編集セッションを停止するtryブロックを入れます。tryブロックで編集セッションを停止する場合、そのcatchブロックではNotEditorExceptionを無視する必要があります。この例外は、保留中の構成MBean階層でのロックを失ったことを表しますが、ここでは変更を破棄してロックを解放しようとしているので、この例外がスローされてもエラー状態ではありません。
-
-
保存された変更をアクティブ化するtryブロック。
ConfigurationManageractivate(long timeout)操作はActivationTaskMBeanのインスタンスを返します。このインスタンスには、アクティブ化タスクに関する情報が格納されています。activate()のタイムアウト期間を1分間に設定して、その後でActivationTaskMBeanState属性の値をチェックすることをお薦めします。Stateに定数STATE_COMMITTEDが含まれている場合、変更はドメインで正常にアクティブ化されたことになります。この時点でreturn文を使用して編集作業を終了できます。アクティブ化タスクが成功すると、startEdit()で作成したロックが解放されます。Stateに別の値が含まれている場合、アクティブ化はactivate(long timeout)で指定したタイムアウト期間中に成功しなかったことになります。ActivationTaskMBeanError属性の値を取得すると原因を見つけられます。このtryブロックの後、ラップされた以下の型の例外を捕捉する1つのcatchブロック。
NotEditorException
変更をアクティブ化するときにこの例外がスローされた場合は、編集セッションがタイムアウトしたか管理者によって取り消されたために、変更はアクティブ化されません。
-
(オプション)保存された変更を取り消すtryブロック。
クラスがアクティブ化のtryブロックで終了(return)しない場合、アクティブ化タスクは成功しなかったことになります。保存されている変更が、将来の試行でアクティブ化されないようにするには、
ConfigurationManagerMBeanundoUnactivatedChanges()操作を呼び出します。そうしない場合、保存されている変更は保留中の構成ファイルに保持されます。次回、あるユーザーが保存した変更をアクティブ化しようとすると、WebLogic Serverはそのユーザーが保存した変更と一緒に、保存されている変更をアクティブ化しようとします。
このtryブロックの後、ラップされた以下の型の例外を無視する1つのcatchブロック。
NotEditorException
-
編集セッションを停止するtryブロック。
アクティブ化タスクが失敗した場合に変更を破棄する場合は、元のタイムアウト期間が経過するのを待つ必要はありません。編集を直ちに停止できます。
このtryブロックの後、以下の型の例外を無視する1つのcatchブロック。
NotEditorException
-
ActivationTaskMBeanError属性に格納されている例外をスローします。
例5-5 編集と例外処理のコードの概要
try {
//Initialize the connection and start the edit session
...
ObjectName domainConfigRoot = (ObjectName) connection.invoke(cfgMgr,
"startEdit",
new Object[] { new Integer(30000), new Integer(300000) },
new String[] { "java.lang.Integer", "java.lang.Integer" });
// Modify the domain
...
// Save your changes
connection.invoke(cfgMgr, "save", null, null);
} catch (MBeanException e) {
Exception targetException = e.getTargetException();
if (targetException instanceof EditTimedOutException) {
// Could not get the lock. Notify user
...
throw new MyAppCouldNotStartEditException(e);
}
if (targetException instanceof NotEditorException) {
...
throw new MyAppEditSessionFailed(e);
}
if (targetException instanceof ValidationException) {
...
try {
connection.invoke(cfgMgr, "stopEdit", null, null);
// A wrapped NotEditorException here indicates that you no longer have a
// lock on the pending configuration MBean hierarchy; however,
// because you want to abandon changes and release your lock anyway,
// it is not an error condition for this exception to be thrown
// and you can safely ignore it.
} catch (MBeanException e) {
Exception targetException = e.getTargetException();
if (targetException instanceof NotEditorException) {
//ignore
}
}
throw new MyAppEditChangesInvalid(e);
}
else {
throw MBeanException (e);
}
}
// Changes have been saved, now activate them
try {
// Activate the changes
ActivationTaskMBean task = (ObjectName) connection.invoke(cfgMgr,
"activate",
new Object[] { new Long(60000) },
new String[] { "java.lang.Long" });
// Everything worked, just return.
String status = (String) connection.getAttribute(task, "State");
if (status.equals("4"))
return;
// If there is an activation error, use ActivationTaskMBean.getError
// to get information about the error
failure = connection.getAttribute(task, "Error");
// If you catch a wrapped NotEditorException, your changes were not activated
// because your edit session ended or was cancelled by an administrator.
// Throw the wrapped exception.
} catch (MBeanException e) {
Exception targetException = e.getTargetException();
if (targetException instanceof NotEditorException) {
...
throw new MyAppEditSessionFailed(e);
}
}
// If your class executes the remaining lines, it is because activating your
// saved changes failed.
// Optional: You can undo the saved changes that failed to activate. If you
// do not undo your saved changes, they will be activated the next time
// someone attempts to activate changes.
// try {
// {
// connection.invoke(cfgMgr, "undoUnactivatedChanges", null, null);
// catch(MBeanException e) {
// Exception targetException = e.getTargetException();
// if (targetException instanceof NotEditorException) {
// ...
// throw new MyAppEditSessionFailed(e);
// }
// }
// Stop the edit session
try {
connection.invoke(cfgMgr, "stopEdit", null, null);
// If your activation attempt fails and you are ready to abandon
// changes, there is no need to wait until your original timeout
// period to expire. You can stop editing immediately
// and you can safely ignore any wrapped NotEditorException.
} catch (MBeanException e) {
Exception targetException = e.getTargetException();
if (targetException instanceof NotEditorException) {
//ignore
}
}
...
// Output the information about the error that caused the activation to
// fail.
throw new MyAppEditSessionFailed(connection.getAttribute(task, "Error"));親トピック: JMXを使用したドメインの構成の管理
暗号化された値の設定と取得
権限のないアクセスからパスワードなどの重要なデータを保護するために、WebLogic Server構成MBeanのいくつかの属性は暗号化されます。そうした属性の値はドメインのconfig.xmlファイルに暗号化された文字列として保持され、メモリー内の値は暗号化されたバイト配列として表されます。暗号化されている属性は、名前がEncryptedで終わります。たとえばServerMBeanでは、IIOPプロトコルを介したアクセスの保護に使用されるパスワードがDefaultIIOPPasswordEncryptedという名前の属性として公開されます。後方互換性をサポートし、リモートのJMXクライアントがWebLogic Server MBeanのパスワードを設定できるようにするため、暗号化される各属性では、値を暗号化して設定するための、安全性がやや低い手段を提供しています。
以下の節では、暗号化された属性の扱い方について説明します。
暗号化された属性の値の設定(推奨技術)
この方法を使用するには、(例5-6を参照してください):
例5-6 例:暗号化された属性の値の設定(推奨技術)
public void editDefaultIIOPPassword(ObjectName cfgRoot) throws Exception {
// Get the ServerMBean from the DomainMBean
ObjectName server = (ObjectName) connection.invoke(cfgRoot,
"lookupServer", new Object[] { "myserver" },
new String[] { "java.lang.String" });
// Get new password from standard in. Assign it to a byte array.
System.out.println("Enter new password and press enter: ");
byte userinput[] = new byte[10];
System.in.read(userinput);
// Encrypt the byte array and set it as the encrypted
// attribute value.
Attribute newpassword = new Attribute("DefaultIIOPPasswordEncrypted",
weblogic.management.EncryptionHelper.encrypt(userinput));
connection.setAttribute(server, newpassword);
System.out.println("New password is set to: " +
connection.getAttribute(server, "DefaultIIOPPasswordEncrypted"));
// Clear the byte array.
weblogic.management.EncryptionHelper.clear(userinput);
}親トピック: 暗号化された値の設定と取得
暗号化された属性の値の設定(互換性のある技術)
9.0より前では、JMXクライアントは暗号化された値を設定するための別の方法を使用していました。JMXクライアントはこの互換性のある方法を引続き使用できます。また、リモートJMXクライアントから暗号化された値を設定する場合は、この方法のみを使用できます。互換性のある方法では、暗号化されていないパスワードを格納するStringを作成するので、安全性が低くなります。WebLogic ServerがStringを暗号化されたバイト配列に変換しても、ガベージ・コレクションが行われてメモリーが再割当てされるまで、Stringはメモリー内に残ります。
互換性のある方法を使用するには、次の手順に従います。
たとえば:
public void editDefaultIIOPPassword(ObjectName cfgRoot, String password)
throws Exception {
// Get the ServerMBean from the DomainMBean
ObjectName server = (ObjectName) connection.invoke(cfgRoot, "lookupServer",
new Object[]{"myserver"},new String[]{"java.lang.String"});
Attribute newpassword = new Attribute("DefaultIIOPPassword",
"password");
connection.setAttribute(server, newpassword);
} 親トピック: 暗号化された値の設定と取得
暗号化された値のバックアップ
パスワードのバックアップ・コピーを作成するには、MBeanの暗号化された値のゲッター・メソッドを使用して、暗号化されたバイト配列を取得します。次に、バイト配列の値をファイルに書き込みます。WebLogic Serverでは、暗号化されている値を復号化するAPIまたは他のユーティリティは提供していません。
パスワードの値を回復する必要がある場合は、保存した値をバイト配列に読み込んで、それをパラメータとしてMBeanServerConnection.setAttributeメソッドに渡すことができます(「暗号化された属性の値の設定(推奨技術)」を参照してください) 。
ノート:
WebLogic Serverドメインでは独自の暗号化アルゴリズムを使用しているため、パスワードの暗号化されていない値がすべてのドメインで同じ場合でも、ドメインごとに別々にパスワードをバックアップして回復する必要があります。
各ドメインで暗号化された同じパスワードをバックアップするかわりに、MBeanの対応する暗号化されていない値のゲッター・メソッドを使用できます。このゲッターはパスワードを復号化してStringにコピーします。ガベージ・コレクションが行われてメモリーが再割当てされるまで、Stringはメモリーから消去されません。
親トピック: 暗号化された値の設定と取得