• トランザクションスコープの永続化コンテキストに関する規約
  トランザクションスコープの永続化コンテキストが使用されている場合に，JTAトランザクションにエンティティマネージャが関連づいていないときには，コンテナは次の処理を実行します。
  
  • コンテナは次の場合に，EntityManagerFactory.createEntityManagerを呼び出して新しいエンティティマネージャを作成します。
    JTAトランザクションのスコープ内のビジネスメソッドで，トランザクションスコープの永続化コンテキストを使用するエンティティマネージャのメソッドが初めて呼び出された場合
    
  • JTAトランザクションが決着（コミットまたはロールバック）したあとに，コンテナはEntityManager.closeを呼び出して，エンティティマネージャをクローズします。
  また，コンテナは次の条件をすべて満たすと，TransactionRequiredExceptionをスローします。
  
  • トランザクションスコープの永続化コンテキストが使用されている場合
  • トランザクションがアクティブでない場合
  • アプリケーションからEntityManagerのpersist，remove，merge，refreshメソッドが呼び出された場合
• 拡張永続化コンテキストに関する規約
  拡張永続化コンテキストが使用されている場合は，コンテナは次の処理を行います。
  
  • コンテナは次の場合に，EntityManagerFactory.createEntityManagerを呼び出して新しいエンティティマネージャを作成します。
    Stateful Session Beanのインスタンスが作成された際に，拡張永続化コンテキストを使用するエンティティマネージャへの参照が定義されている場合
    
  • コンテナは次のタイミングで，EntityManager.closeを呼び出してエンティティマネージャをクローズします。
    エンティティマネージャを作成したStateful Session Bean，および同じ永続化コンテキストを引き継いだStateful Session Beanが削除されたとき
    
  • コンテナ管理のトランザクションを使用するStateful Session Beanのビジネスメソッドの呼び出し時に，エンティティマネージャがJTAトランザクションと関連づけられていない場合には，コンテナはエンティティマネージャをJTAトランザクションに関連づけ，EntityManager.joinTransactionを呼び出します。JTAトランザクションにすでに別のエンティティマネージャが関連づけられている場合には，コンテナはEJBExceptionをスローします。
  • ビーン管理のトランザクションを使用するStateful Session Beanのビジネスメソッド内でUserTransaction.beginが呼び出された場合には，コンテナはエンティティマネージャをJTAトランザクションと関連づけ，EntityManager.joinTransactionを呼び出します。なお，ビーン管理のトランザクションについては，マニュアル「アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」の「2.7.2　BMT」を参照してください。
• コンテナ管理のエンティティマネージャに関する規約
  コンテナ管理のエンティティマネージャを使用している場合に，アプリケーションがEntityManager.closeを呼び出すと，コンテナはIllegalStateExceptionをスローします。
  @PersistenceCotnextまたはDDの<persistence-context-ref>タグで，プロパティが指定された場合には，コンテナはEntityManagerFactory.createEntityManager(Map map)メソッドを使用してエンティティマネージャを作成し，指定されたプロパティをmap引数に含めてJPAプロバイダに渡します。
  
• コネクションの自動クローズ機能について
  アプリケーションサーバの場合，Session BeanやWebコンポーネントの延長でJPAプロバイダが取得したコネクションは，コンテナの自動クローズ機能によって自動的にクローズされることがあります。コネクションの自動クローズ機能とは，コネクションのリークを防止するための機能です。
  コネクションは，次の条件を満たすと自動クローズの対象となります。
  
  • Stateless Session Beanで取得したコネクションは，ビジネスメソッドからリターンするときに，自動クローズの対象となります。
  • Stateful Session Beanで取得したコネクションは，Stateful Session Beanが破棄されるときに，自動クローズの対象となります。
  • Webコンポーネントで取得したコネクションは，サービスメソッドからリターンするときに，自動クローズの対象となります。
  ただし，これらの条件に当てはまる場合でも，コネクションがJTAトランザクションに参加しているときには，JTAトランザクションがコミットするまで自動クローズが保留されます。
  

アプリケーションで使用するエンティティマネージャが，トランザクションスコープの永続化コンテキストを使用するように定義されているか，拡張永続化コンテキストを使用するように定義されているかは，JPAプロバイダには伝わりません。JPAプロバイダでの責任は，コンテナが要求したときにエンティティマネージャを作成し，トランザクションからトランザクションの決着の通知を受け取るためのSynchronizationをトランザクションに登録することです。

• コンテナがEntityManagerFactory.createEntityManagerを呼び出したときには，JPAプロバイダは新しいエンティティマネージャを作成し，それをコンテナに返す必要があります。JTAトランザクションがアクティブである場合は，JPAプロバイダはSynchronizationをJTAトランザクションに登録する必要があります。
• コンテナがEntityManager.joinTransactionを呼び出したときには，JPAプロバイダはSynchronizationをJTAトランザクションに登録する必要があります。ただし，以前にjoinTransactionが呼び出されていて，JTAトランザクションにSynchronizationを登録済みの場合には，何もする必要はありません。
• JTAトランザクションがコミットされるときには，JPAプロバイダはすべての変更されたエンティティの状態を，データベースにフラッシュする必要があります。
• JTAトランザクションがロールバックされるときには，JPAプロバイダは，すべてのmanaged状態のエンティティをデタッチする必要があります。
• JPAプロバイダがトランザクションのロールバックの原因になる例外をスローする場合には，JPAプロバイダがトランザクションをロールバックにマークする必要があります。
• コンテナがEntityManager.closeを呼び出した場合，そのエンティティマネージャが関係したすべての未解決トランザクションが決着されたあとに，JPAプロバイダはすべての確保したリソースを解放する必要があります。エンティティマネージャがすでにクローズされている場合には，JPAプロバイダはIllegalStateExceptionをスローする必要があります。
• コンテナがEntityManager.clearを呼び出した場合，JPAプロバイダはすべてのmanaged状態のエンティティをデタッチする必要があります。

JPAプロバイダは，トランザクションにSynchronizationを登録したり，トランザクションをロールバックにマークしたりするために，TransactionSynchronizationRegistryインタフェースを使用できます。TransactionSynchronizationRegistryのインスタンスは，JNDIを使用して「java:comp/TransactionSynchronizationRegistry」という名前でルックアップできます。

インタフェース定義を次に示します。

package javax.transaction;
 
/**
 * このインタフェースは，JPAプロバイダやリソースアダプタなど，
 * アプリケーションサーバのシステムレベルのコンポーネントから使用する
 * ためのものです。
 * このインタフェースを使って，
 * 特別な順序で呼ばれるシンクロナイゼーションの登録，
 * 現在のトランザクションへのリソースオブジェクトの登録，
 * 現在のトランザクションのコンテキストの取得，
 * 現在のトランザクションのステータスの取得，
 * 現在のトランザクションをロールバックにマークできます。
 *
 * このインタフェースはステートレスなサービスオブジェクトとして，
 * アプリケーションサーバによって実装されます。
 * 同じオブジェクトを複数のコンポーネントからマルチスレッドセーフに
 * 使用できます。
 *
 * 標準的なアプリケーションサーバでは，このインタフェースを実装した
 * インスタンスは，JNDIを使用して標準的な名前でルックアップできます。
 * 標準的な名前は
 * 「java:comp/TransactionSynchronizationRegistry」です。
 */
public interface TransactionSynchronizationRegistry {
 
    /**
     * このメソッドを呼び出した時に現在のスレッドに関連づいている
     * トランザクションを表現する一意のオブジェクトを返します。
     * このオブジェクトのhashCodeとequalsメソッドは
     * オーバーライドされており，
     * ハッシュマップのキーとして使用できます。
     * トランザクションが存在しない場合には，nullを返します。
     * 
     * 同じアプリケーションサーバの同じトランザクションコンテキスト内で
     * このメソッドが呼ばれて返されたオブジェクトは，すべて同じhashCodeを
     * 持ち，equalメソッドでの比較結果はtrueとなります。
     * 
     * toStringメソッドは，トランザクションコンテキストの情報を人が
     * 読みやすい形の文字列として返します。
     * ただし，toStringで返される文字列のフォーマットは規定されていません。
     * また，toStringの結果に関して，バージョン間での互換性は
     * 保障されていません。
     * 
     * 取得したオブジェクトがシリアライズできる保障はなく，
     * JavaVMの外に出したときの動作は規定されていません。
     *
     * @return このメソッドが呼ばれたときにスレッドに関連づいている
     * トランザクションを一意に表現するオブジェクト
     */
    Object getTransactionKey();
    
    /**
     * このメソッドを呼び出した時のスレッドに関連づいているトランザクション
     * のリソースマップに，オブジェクトを追加またはリプレースします。
     * マップのキーは，コンフリクトが発生しないように，
     * このメソッドを呼び出す側で定義されたクラスである必要があります。
     * キーとして使用するクラスは，マップのキーとして適切なhashCodeとequals
     * メソッドを持っている必要があります。
     * マップのキーや値が，このクラスによって評価されたり，使用されたりする
     * ことはありません。
     * このメソッドの一般的な規約は，Mapのputメソッドと同じで，
     * キーはnull以外にする必要がありますが，値はnullにすることもできます。
     * すでにキーに関連づいた値が存在する場合，その値は置き換えられます。
     *
     * @param key マップのエントリのキー
     * @param value マップのエントリの値
     * @exception IllegalStateException アクティブなトランザクションが
     * 存在しない場合
     * @exception NullPointerException 引数のキーがnullである場合
     */
    void putResource(Object key, Object value);
    
    /**
     * このメソッドを呼び出した時のスレッドに関連づいているトランザクション
     * のリソースマップから，オブジェクトを取り出します。
     * キーは，同じトランザクション内で，事前にputResourceメソッドに
     * 指定したオブジェクトと同じである必要があります。
     * 指定されたキーが現在のリソースマップに存在しない場合は，
     * nullを返します。
     * このメソッドの一般的な規約は，Mapのputメソッドと同じで，
     * キーはnull以外にする必要がありますが，値はnullにすることもできます。
     * マップにキーが格納されていない場合や，キーに対してnullが格納
     * されている場合には，返り値はnullになります。
     * @param key マップのエントリのキー
     * @return キーに関連づけられた値
     * @exception IllegalStateException アクティブなトランザクションが
     * 存在しない場合
     * @exception NullPointerException 引数のキーがnullである場合
     */
    Object getResource(Object key);
 
    /**
     * 特別な順序で呼ばれるシンクロナイゼーションのインスタンスを登録します。
     * このメソッドで登録したSynchronizationのbeforeCompletionは，
     * すべてのSessionSynchronization.beforeCompletionや，
     * トランザクションに直接登録された
     * Synchronization.beforeCompletionが呼ばれたあとで，
     * 2フェーズコミット処理が開始される前に呼び出されます。
     * 同じように，このメソッドで登録した
     * SynchronizationのafterCompletionは，
     * 2フェーズコミット処理が完了したあとで，
     * すべてのSessionSynchronization.afterCompletionや，
     * トランザクションに直接登録されたSynchronization.afterCompletionが
     * 呼ばれる前に呼び出されます。
     * 
     * beforeCompletionは，このメソッドを呼び出した時にスレッドに
     * 関連づいていたトランザクションのコンテキストで呼び出されます。
     * beforeCompletionでは，コネクタなどのリソースへのアクセスは
     * 許可されていますが，タイマーサービスやビーンのメソッドなどの
     * ユーザコンポーネントへのアクセスは許可されていません。
     * これは，呼び出し側によって管理されているデータや，
     * registerInterposedSynchronizationで登録された
     * ほかのSynchronizationによって
     * すでにフラッシュされたデータを変更してしまうおそれがあるためです。
     * 一般的なコンテキストは，registerInterposedSynchronizationを
     * 呼び出したコンポーネントのコンテキストになります。
     * 
     * afterCompletionが呼び出される時のコンテキストは定義されていません。
     * なお，ユーザコンポーネントへのアクセスは許可されていません。
     * また，リソースをクローズすることはできますが，
     * リソースに対するトランザクショナルな操作はできません。
     * 
     *トランザクションがアクティブでない場合にこのメソッドが呼び出されたとき，
     * IllegalStateExceptionがスローされます。
     *
     * このメソッドが2フェーズコミット処理の開始後に呼び出された場合は，
     * IllegalStateExceptionがスローされます。
     * 
     * @param sync 登録するSynchronizationのインスタンス
     * @exception IllegalStateException アクティブなトランザクションが
     * 存在しない場合
     */
    void registerInterposedSynchronization(Synchronization sync);
 
    /**
     * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
     * のステータスを返します。
     * このメソッドの返り値は，
     * TransactionManager.getStatus()の結果と同じです。
     *
     * @return このメソッドを呼んだときにスレッドに関連づいている
     * トランザクションのステータス
     */
    int getTransactionStatus();
 
    /**
     * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
     * がロールバックされるようにマークします。
     *
     * @exception IllegalStateException アクティブなトランザクションが
     * 存在しない場合
     */
    void setRollbackOnly();
 
    /**
     * このメソッドを呼んだ時にスレッドに関連づいているトランザクション
     * がロールバックするようにマークされているかどうかを返します。
     *
     * @return ロールバックするようにマークされている場合はtrue
     * @exception IllegalStateException アクティブなトランザクションが
     * 存在しない場合
     */
    boolean getRollbackOnly();
}