ManagedConnection (Jakarta EE Platform API)

```
public interface ManagedConnection
```
ManagedConnection インスタンスは、基礎となる EIS への物理接続を表します。
ManagedConnection インスタンスは、javax.transaction.xa.XAResource と jakarta.resource.spi.LocalTransaction の 1 組のインターフェースへのアクセスを提供します。
XAResource インターフェースは、トランザクションマネージャーが、トランザクションを基礎となる EIS リソースマネージャーインスタンスに関連付けおよび関連付け解除し、2 フェーズコミットプロトコルを実行するために使用されます。ManagedConnection インターフェースは、トランザクションマネージャーによって直接使用されません。XAResource インターフェースの詳細は、Jakarta™ Transactions 仕様に記載されています。
LocalTransaction インターフェースは、ローカルトランザクションを管理するためにアプリケーションサーバーによって使用されます。
バージョン:
0.5
作成者:
Rahul Sharma
関連事項:
ManagedConnectionFactory, XAResourceSE, LocalTransaction

メソッドのサマリー

すべてのメソッドインスタンスメソッド抽象メソッド
修飾子と型	メソッドと説明
`void`	`addConnectionEventListener(ConnectionEventListener listener)` 接続イベントリスナーを ManagedConnection インスタンスに追加します。
`void`	`associateConnection(ObjectSE connection)` 通常、コンテナーによって使用され、アプリケーションレベルの接続ハンドルと ManagedConnection インスタンスの関連付けを変更します。
`void`	`cleanup()` アプリケーションサーバーはこのメソッドを呼び出して、ManagedConnection インスタンスのクリーンアップを強制します。
`void`	`destroy()` 基盤となるリソースマネージャーへの物理接続を破棄します。
`ObjectSE`	`getConnection(SubjectSE subject, ConnectionRequestInfo cxRequestInfo)` ManagedConnection インスタンスによって表される基礎となる物理接続の新しい接続ハンドルを作成します。
`LocalTransaction`	`getLocalTransaction()` `jakarta.resource.spi.LocalTransaction` インスタンスを返します。
`PrintWriterSE`	`getLogWriter()` この ManagedConnection インスタンスのログライターを取得します。
`ManagedConnectionMetaData`	`getMetaData()` この接続の基盤となる EIS リソースマネージャーインスタンスのメタデータ情報を取得します。
`XAResourceSE`	`getXAResource()` `javax.transaction.xa.XAresource` インスタンスを返します。
`void`	`removeConnectionEventListener(ConnectionEventListener listener)` すでに登録されている接続イベントリスナーを ManagedConnection インスタンスから削除します。
`void`	`setLogWriter(PrintWriterSE out)` この ManagedConnection インスタンスのログライターを設定します。

- メソッドの詳細
  - getConnection
```
ObjectSE getConnection(SubjectSE subject,
                     ConnectionRequestInfo cxRequestInfo)
              throws ResourceException
```
    ManagedConnection インスタンスによって表される基礎となる物理接続の新しい接続ハンドルを作成します。この接続ハンドルは、基盤となる物理接続を参照するためにアプリケーションコードによって使用されます。この接続ハンドルは、リソースアダプター実装固有の方法で ManagedConnection インスタンスに関連付けられます。
    ManagedConnection は、サブジェクトと追加の ConnectionRequest 情報（リソースアダプターに固有で、アプリケーションサーバーには不透明）を使用して、物理接続の状態を設定します。
    パラメーター:
    subject - JAAS サブジェクトとしてのセキュリティコンテキスト
    cxRequestInfo - ConnectionRequestInfo インスタンス
    戻り値:
    接続ハンドルを表す汎用オブジェクトインスタンス。CCI の場合、ManagedConnection インスタンスによって作成される接続ハンドルの型は jakarta.resource.cci.Connection です。
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    ResourceAdapterInternalException - リソースアダプターの内部エラー状態
    SecurityException - セキュリティ関連のエラー状態
    CommException - EIS インスタンスとの通信に失敗しました
    EISSystemException - EIS インスタンスの内部エラー状態 - EIS インスタンスが ManagedConnection の状態の設定に関与している場合に使用されます
  - destroy
```
void destroy()
      throws ResourceException
```
    基盤となるリソースマネージャーへの物理接続を破棄します。
    接続プールのサイズを管理するために、アプリケーションサーバーは明示的に ManagedConnection.destroy を呼び出して、物理接続を破棄できます。リソースアダプターは、メソッド destroy が呼び出されたときに、この ManagedConnection インスタンスに割り当てられたすべてのシステムリソースを破棄する必要があります。
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    IllegalStateException - 接続を破棄するための不正な状態
  - cleanup
```
void cleanup()
      throws ResourceException
```
    アプリケーションサーバーはこのメソッドを呼び出して、ManagedConnection インスタンスのクリーンアップを強制します。
    メソッド ManagedConnection.cleanup は、ManagedConnection インスタンスによって維持されているクライアント固有の状態のクリーンアップを開始します。クリーンアップにより、この ManagedConnection インスタンスを使用して作成されたすべての接続ハンドルが無効になります。基盤となる ManagedConnection のクリーンアップ後に、アプリケーションコンポーネントが接続ハンドルを使用しようとすると、例外が発生するはずです。
    ManagedConnection のクリーンアップは、常にアプリケーションサーバーによって実行されます。進行中の未完了のトランザクション（ManagedConnection インスタンスに関連付けられている）がある場合、アプリケーションサーバーは ManagedConnection.cleanup を呼び出さないでください。
    すでにクリーンアップされた接続で ManagedConnection.cleanup メソッドを呼び出しても、例外はスローされません。
    ManagedConnection インスタンスのクリーンアップは、クライアント固有の状態をリセットし、接続を接続プールに戻す準備をします。クリーンアップ方法では、リソースアダプターが物理パイプを閉じて、物理接続に関連付けられているシステムリソースを再利用することはできません。
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    ResourceAdapterInternalException - リソースアダプターの内部エラー状態
    IllegalStateException - 接続クリーンアップを呼び出すための不正な状態。例 - 接続のクリーンアップを許可しないローカルトランザクションが進行中の場合
  - associateConnection
```
void associateConnection(ObjectSE connection)
                  throws ResourceException
```
    通常、コンテナーがアプリケーションレベルの接続ハンドルと ManagedConnection インスタンスの関連付けを変更するために使用されます。コンテナーは適切な ManagedConnection インスタンスを見つけて、associateConnection メソッドを呼び出す必要があります。接続ハンドルをアクティブな接続ハンドルとして設定するために、コンテナーは associateConnection メソッドを使用して、接続ハンドルに関連付けられた同じ ManagedConnection を設定することもできます。
    リソースアダプターは、associateConnection メソッドを実装する必要があります。ManagedConnection のメソッド実装では、現在関連付けられている ManagedConnection から接続ハンドル (パラメーターとして渡される) の関連付けを解除し、新しい接続ハンドルをそれ自体に関連付ける必要があります。
    パラメーター:
    connection - アプリケーションレベルの接続ハンドル
    例外:
    ResourceException - 接続ハンドルをこの ManagedConnection インスタンスに関連付けることができませんでした
    IllegalStateException - このメソッドを呼び出すための不正な状態
    ResourceAdapterInternalException - リソースアダプターの内部エラー状態
  - addConnectionEventListener
```
void addConnectionEventListener(ConnectionEventListener listener)
```
    接続イベントリスナーを ManagedConnection インスタンスに追加します。
    登録された ConnectionEventListener インスタンスには、接続の終了イベントとエラーイベント、および管理対象接続でのローカルトランザクション関連のイベントが通知されます。
    パラメーター:
    listener - 登録する新しい ConnectionEventListener
  - removeConnectionEventListener
```
void removeConnectionEventListener(ConnectionEventListener listener)
```
    すでに登録されている接続イベントリスナーを ManagedConnection インスタンスから削除します。
    パラメーター:
    listener - 削除する登録済みの接続イベントリスナー
  - getXAResource
```
XAResourceSE getXAResource()
                  throws ResourceException
```
    javax.transaction.xa.XAresource インスタンスを返します。ManagedConnection インスタンスがトランザクションマネージャーによって調整されている Jakarta Transactions トランザクションで使用されている場合、アプリケーションサーバーはこの XAResource インスタンスをトランザクションマネージャーに参加させます。
    戻り値:
    XAResource インスタンス
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    ResourceAdapterInternalException - リソースアダプターの内部エラー状態
    NotSupportedException - これがコネクターでサポートされていない場合
  - getLocalTransaction
```
LocalTransaction getLocalTransaction()
                              throws ResourceException
```
    jakarta.resource.spi.LocalTransaction インスタンスを返します。LocalTransaction インターフェースは、RM インスタンスのローカルトランザクションを管理するためにコンテナーによって使用されます。
    戻り値:
    LocalTransaction インスタンス
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    ResourceAdapterInternalException - リソースアダプターの内部エラー状態
    NotSupportedException - これがコネクターでサポートされていない場合
  - getMetaData
```
ManagedConnectionMetaData getMetaData()
                               throws ResourceException
```
    この接続の基盤となる EIS リソースマネージャーインスタンスのメタデータ情報を取得します。ManagedConnectionMetaData インターフェースは、ManagedConenction インスタンスに関連付けられた基礎となる EIS インスタンスに関する情報を提供します。
    戻り値:
    ManagedConnectionMetaData インスタンス
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    NotSupportedException - これがコネクターでサポートされていない場合
  - setLogWriter
```
void setLogWriter(PrintWriterSE out)
           throws ResourceException
```
    この ManagedConnection インスタンスのログライターを設定します。
    ログライターは、この ManagedConnection インスタンスのすべてのロギングおよびトレースメッセージが出力される文字出力ストリームです。Application Server は、接続プールの要件に基づいて、出力ストリームと ManagedConnection インスタンスの関連付けを管理します。
    ManagedConnection オブジェクトが最初に作成されると、このインスタンスに関連付けられたデフォルトのログライターが ManagedConnectionFactory から取得されます。アプリケーションサーバーは、この ManagedConnection に固有のログライターを設定し、setLogWriter メソッドを使用してこのインスタンスをログに記録 / トレースできます。
    パラメーター:
    out - 関連付けられる文字出力ストリーム
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外
    ResourceAdapterInternalException - リソースアダプター関連のエラー状態
  - getLogWriter
```
PrintWriterSE getLogWriter()
                  throws ResourceException
```
    この ManagedConnection インスタンスのログライターを取得します。
    ログライターは、この ManagedConnection インスタンスのすべてのロギングおよびトレースメッセージが出力される文字出力ストリームです。ConnectionManager は、接続プール要件に基づいて、出力ストリームと ManagedConnection インスタンスの関連付けを管理します。
    ManagedConnection インスタンスに関連付けられたログライターは、（この接続を作成した）ManagedConnectionFactory からデフォルトとして設定されたものでも、アプリケーションサーバーによってこのインスタンス専用に設定されたものでもかまいません。
    戻り値:
    この Managed-Connection インスタンスに関連付けられた文字出力ストリーム
    例外:
    ResourceException - 操作が失敗した場合の一般的な例外

インターフェース ManagedConnection

メソッドのサマリー

メソッドの詳細

getConnection

destroy

cleanup

associateConnection

addConnectionEventListener

removeConnectionEventListener

getXAResource

getLocalTransaction

getMetaData

setLogWriter

getLogWriter