| Oracle® Fusion Middleware Oracle WebLogic Serverリソース・アダプタのプログラミング 11g リリース1(10.3.5) B60996-03 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle WebLogic Serverリソース・アダプタのプログラミング 11g リリース1(10.3.5) B60996-03 |
|
前 |
次 |
次の項では、WebLogic Serverリソース・アダプタのプログラミング・タスクについて説明します。
J2CA 1.5仕様に従い、リソース・アダプタには以下のJavaクラスが必要です。
ManagedConnectionFactory
ConnectionFactoryインタフェース
ConnectionFactory実装
Connectionインタフェース
Connection実装
これらのクラスをra.xmlファイルに指定します。例:
<managedconnectionfactory-class> com.sun.connector.blackbox.LocalTxManagedConnectionFactory </managedconnectionfactory-class> <connectionfactory-interface> javax.sql.DataSource </connectionfactory-interface> <connectionfactory-impl-class> com.sun.connector.blackbox.JdbcDataSource </connectionfactory-impl-class> <connection-interface> java.sql.Connection </connection-interface> <connection-impl-class> com.sun.connector.blackbox.JdbcConnection </connection-impl-class>
また、リソース・アダプタで着信メッセージングをサポートする場合は、サポートする着信メッセージのタイプごとにActivationSpecクラスが必要になります。第7章「メッセージ・インフローとトランザクション・インフロー」を参照してください。
これらのリソース・アダプタ・クラスの詳細は、開発するリソース・アダプタの性質によって異なります。
WebLogic Server起動クラスを使用する代わりに、javax.resource.ResourceAdapterを実装した最小限のリソース・アダプタ・クラスを持つリソース・アダプタをプログラミングし、そのクラスでstart()およびstop()メソッドを定義することができます。
|
注意: ResourceAdapterインタフェースの定義のために、endpointActivation()、Deactivation()、およびgetXAResource()メソッドも定義する必要があります。 |
リソース・アダプタがデプロイされるときに、start()メソッドが呼び出されます。アンデプロイされるときに、stop()メソッドが呼び出されます。WebLogic Server起動クラスと同様に、リソース・アダプタが開始する作業はstart()メソッドの中で実行できます。
リソース・アダプタでは、start()メソッド内でBootstrapContextを介してワーク・マネージャにアクセスするため、直接的なスレッド管理は使用しないで、Workインスタンスを送信する必要があります。それによって、WebLogic Serverは自動チューニングのワーク・マネージャを通じて、スレッドを効率的に管理できます。
実行用にWorkインスタンスが送信されたら、リソース・アダプタの完全なデプロイメントに干渉しないように、start()メソッドはすぐに復帰する必要があります。そのため、ワーク・マネージャでは、doWork()メソッドではなく、scheduleWork()またはstartWork()メソッドを呼び出す必要があります。
以下に示すのは、最小限のリソース・アダプタ・クラスを持つリソース・アダプタの例です。これは、(println文を除けば)開発できる最小限のリソース・アダプタです。この例では、start()メソッドで実行される作業はstdout (標準出力)へのメッセージの出力のみです。
例4-1 最小限のリソース・アダプタ
import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.ActivationSpec;
import javax.resource.ResourceException;
import javax.transaction.xa.XAResource;
import javax.resource.NotSupportedException;
import javax.resource.spi.BootstrapContext;
/**
* This resource adapter is the absolute minimal resource adapter that anyone can build (other than removing the println's.)
*/
public class ResourceAdapterImpl implements ResourceAdapter
{
public void start( BootstrapContext bsCtx )
{
System.out.println( "ResourceAdapterImpl started" );
}
public void stop()
{
System.out.println( "ResourceAdapterImpl stopped" );
}
public void endpointActivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
throws ResourceException
{
throw new NotSupportedException();
}
public void endpointDeactivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
{
}
public XAResource[] getXAResources(ActivationSpec aactivationspec[])
throws ResourceException
{
throw new NotSupportedException();
}
}
以下に示すのは、Workインスタンスをワーク・マネージャに送信するリソース・アダプタの例です。リソース・アダプタはstart()メソッド内で作業を開始します。したがって、J2EEに準拠した起動クラスとして機能します。
例4-2 ワーク・マネージャを使用し、Workインスタンスを送信するリソース・アダプタ
import javax.resource.NotSupportedException;
import javax.resource.ResourceException;
import javax.resource.spi.ActivationSpec;
import javax.resource.spi.BootstrapContext;
import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.work.Work;
import javax.resource.spi.work.WorkException;
import javax.resource.spi.work.WorkManager;
import javax.transaction.xa.XAResource;
/**
* This Resource Adapter starts some work in the start() method,
* thus serving as a J2EE compliant "startup class"
*/
public class ResourceAdapterWorker implements ResourceAdapter
{
private WorkManager wm;
private MyWork someWork;
public void start( BootstrapContext bsCtx )
{
System.out.println( "ResourceAdapterWorker started" );
wm = bsCtx.getWorkManager();
try
{
someWork = new MyWork();
wm.startWork( someWork );
}
catch (WorkException ex)
{
System.err.println( "Unable to start work: " + ex );
}
}
public void stop()
{
// stop work that was started in the start() method
someWork.release();
System.out.println( "ResourceAdapterImpl stopped" );
}
public void endpointActivation(MessageEndpointFactory messageendpointfactory,
ActivationSpec activationspec)
throws ResourceException
{
throw new NotSupportedException();
}
public void endpointDeactivation(MessageEndpointFactory
messageendpointfactory, ActivationSpec activationspec)
{
}
public XAResource[] getXAResources(ActivationSpec activationspec[])
throws ResourceException
{
throw new NotSupportedException();
}
// Work class
private class MyWork implements Work
{
private boolean isRunning;
public void run()
{
isRunning = true;
while (isRunning)
{
// do a unit of work (e.g. listen on a socket, wait for an inbound msg,
// check the status of something)
System.out.println( "Doing some work" );
// perhaps wait some amount of time or for some event
try
{
Thread.sleep( 60000 ); // wait a minute
}
catch (InterruptedException ex)
{}
}
}
public void release()
{
// signal the run() loop to stop
isRunning = false;
}
}
}
suspend()メソッドを使用するようにリソース・アダプタをプログラミングすると、アクティビティを中断するためのカスタムの動作を行えます。たとえば、suspend()メソッドを使用すると、進行中のトランザクションが完了するまでの間、すべての着信メッセージをキューに入れたり、メッセージの受信が一時的にブロックされていることをエンタープライズ情報システム(EIS)に通知したりできます。
その後でresume()メソッドを呼び出して、着信キューを排出してメッセージを配信するように指示したり、EISにメッセージの受信が再び可能になったことを通知したりします。基本的に、resume()メソッドによってリソース・アダプタは通常の処理を続行できるようになります。
suspend()およびresume()メソッドを開始するには、WebLogic Scripting Toolを使用して、またはWebLogic Server管理コンソールから、リソース・アダプタのランタイムMBeanをプログラム的に呼び出します。詳細は、Oracle Fusion Middleware Oracle WebLogic Server管理コンソール・ヘルプの「リソース・アダプタの起動と停止」を参照してください。
Suspendable.supportsSuspend()メソッドでは、リソース・アダプタが特定の種類の中断をサポートしているかどうかを判断します。Suspendable.isSuspended()メソッドでは、リソース・アダプタが現在中断されているかどうかを判断します。
suspend()、resume()、または本番再デプロイメントをサポートするリソース・アダプタでは、Suspendableインタフェースを実装して、これらの操作がサポートされることをWebLogic Serverに知らせる必要があります。これらの操作は、以下のことが行われた場合にWebLogic Serverによって呼び出されます。
コネクタ・コンポーネントMBeanのsuspend()メソッドによって中断が呼び出された場合。
(リソース・アダプタを含むアプリケーションの新しいバージョンがデプロイされるときに)本番再デプロイメント・シーケンスが呼び出された場合。「Suspendableインタフェースと本番再デプロイメント」を参照してください。
例 4-3では、リソース・アダプタのSuspendableインタフェースを示しています。
例4-3 Suspendableインタフェース
package weblogic.connector.extensions;
import java.util.Properties;
import javax.resource.ResourceException;
import javax.resource.spi.ResourceAdapter;
/**
* Suspendable may be implemented by a ResourceAdapter JavaBean if it
* supports suspend, resume or side-by-side versioning
* @author Copyright (c) 2002 by BEA Systems, Inc. All Rights Reserved.
* @since November 14, 2003
*/
public interface Suspendable
{
/**
* Used to indicate that inbound communication is to be suspended/resumed
*/
int INBOUND = 1;
/**
* Used to indicate that outbound communication is to be suspended/resumed
*/
int OUTBOUND = 2;
/**
* Used to indicate that submission of Work is to be suspended/resumed
*/
int WORK = 4;
/**
* Used to indicate that INBOUND, OUTBOUND & WORK are to be suspended/resumed
*/
int ALL = 7;
/**
* May be used to indicate a suspend() operation
*/
int SUSPEND = 1;
/**
* May be used to indicate a resume() operation
*/
int RESUME = 2;
/**
* Request to suspend the activity specified. The properties may be null or
* specified according to RA-specific needs
* @param type An int from 1 to 7 specifying the type of suspension being
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of one
* or more of these, or the value Suspendable.ALL )
* @param props Optional Properties (or null) to be used for ResourceAdapter
* specific purposes
* @exception ResourceException If the resource adapter can't complete the
* request
*/
void suspend( int type, Properties props ) throws ResourceException;
/**
* Request to resume the activity specified. The Properties may be null or
* specified according to RA-specific needs
*
* @param type An int from 1 to 7 specifying the type of resume being
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @param props Optional Properties (or null) to be used for ResourceAdapter
* specific purposes
* @exception ResourceException If the resource adapter can't complete the
* request
*/
void resume( int type, Properties props ) throws ResourceException;
/**
*
* @param type An int from 1 to 7 specifying the type of suspend this inquiry
* is about (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @return true iff the specified type of suspend is supported
*/
boolean supportsSuspend( int type );
/**
*
* Used to determine whether the specified type of activity is
* currently suspended.
*
* @param type An int from 1 to 7 specifying the type of activity
* requested (i.e. Suspendable.INBOUND, .OUTBOUND, .WORK or the sum of
* one or more of these, or the value Suspendable.ALL )
* @return true iff the specified type of activity is suspened by this
* resource adapter
*/
boolean isSuspended( int type );
/**
* Used to determine if this resource adapter supports the init() method used for
* resource adapter versioning (side-by-side deployment)
*
* @return true iff this resource adapter supports the init() method
*/
boolean supportsInit();
/**
* Used to determine if this resource adapter supports the startVersioning()
* method used for
* resource adapter versioning (side-by-side deployment)
*
* @return true iff this resource adapter supports the startVersioning() method
*/
boolean supportsVersioning();
/**
* Used by WLS to indicate to the current version of this resource adapter that
* a new version of the resource adapter is being deployed. This method can
* be used by the old RA to communicate with the new RA and migrate services
* from the old to the new.
* After being called, the ResourceAdapter is responsible for notifying the
* Connector container via the ExtendedBootstrapContext.complete() method, that
* it is safe to be undeployed.
*
* @param ra The new ResourceAdapter JavaBean
* @param props Properties associated with the versioning
* when it can be undeployed
* @exception ResourceException If something goes wrong
*/
void startVersioning( ResourceAdapter ra,
Properties props ) throws ResourceException;
/**
* Used by WLS to inform a ResourceAdapter that it is a new version of an already
* deployed resource adapter. This method is called prior to start() so that
* the new resource adapter may coordinate its startup with the resource adapter
* it is replacing.
* @param ra The old version of the resource adapter that is currently running
* @param props Properties associated with the versioning operation
* @exception ResourceException If the init() fails.
*/
void init( ResourceAdapter ra, Properties props ) throws ResourceException;
}
リソース・アダプタをデプロイするときに、そのアダプタのra.xml記述子の<resource-adapter-class>要素でリソース・アダプタJavaBeanが指定されている場合、Weblogic Serverコネクタ・コンテナでは、J2CA 1.5仕様(http://java.sun.com/j2ee/connector/)に従って、そのリソース・アダプタbeanのstart()メソッドを呼び出します。リソース・アダプタのコードでは、start()メソッドによって渡されるBootstrapContextオブジェクトを、次のような目的に使用できます。
Workインスタンスを送信するためにWorkManagerオブジェクトを取得する
Timerを作成する
トランザクション・インフローで使用するためのXATerminatorを取得する
これらの機能はすべてJ2CA 1.5仕様で規定されています。
必須のjavax.resource.spi.BootstrapContextの実装に加えて、リソース・アダプタのstart()メソッドに渡されるBootstrapContextオブジェクトでは、weblogic.connector.extensions.ExtendedBootstrapContextも実装します。それによって、リソース・アダプタは、診断機能を提供するWebLogic Server固有の拡張機能にアクセスできます。以下の節ではこれらの拡張機能について説明します。
WebLogic Server診断フレームワークでは、スレッドには関連付けられた診断コンテキストが含まれる場合があります。スレッド上のリクエストは、実行パスに従って進行するように、その診断コンテキストを存続期間中に伝達し続けます。ExtendedBootstrapContextによって、リソース・アダプタ開発者は、EISからメッセージのエンドポイントに至るリクエストの実行のトレースなどに使用できるStringから構成される診断コンテキストのペイロードを設定できるようになります。
この容量によって、様々な診断プロセスが提供されます。たとえば、EISからのインバウンド・メッセージ上でクライアントIDまたはセッションIDにStringを設定できます。メッセージのディスパッチ中、各種診断が収集されてシステムからリクエスト・フローが表示されます。リソース・アダプタ・クラスの開発時に、setDiagnosticContextID()およびgetDiagnosticContextID()メソッドをこの目的で利用できます。
次の診断コンテキスト・ペイロードのコンテンツに関してご注意ください。
ペイロードは、同一の実行コンテキストの他のコードによって表示でき、またWorkインスタンスに従ってプロセスからフローできます。このため、たとえばgetDiagnosticContextID()メソッドによって返される可能性があるペイロードには、アプリケーションが一切の機密データを含めていないことを確認する必要があります。
ペイロードは同一の実行コンテキストで他のコードによって上書きできます。このため、アプリケーションには、ペイロードで使用可能な固有のコンテキストIDへの依存性は含めません。また、アプリケーションはペイロードのコンテキストIDが使用前に期待される値に一致することを検証する必要もあります。
診断コンテキストの詳細は、『Oracle Fusion Middleware Oracle WebLogic Server診断フレームワークの構成と使い方』を参照してください。
WebLogic Server診断フレームワークは、リクエストを仕分けする機能も備えています。ExtendedBootstrapContextを使用すると、リソース・アダプタ開発者がどの目的で診断を行う場合でも、現在のスレッド上で4つの仕分けビットを設定し、取得できます。たとえば、仕分けビットを使用してリクエストの優先順位を設定できます。リクエストの仕分けの詳細は、『Oracle Fusion Middleware Oracle WebLogic Server診断フレームワークの構成と使い方』を参照してください。
