package javax.persistence;
 
/**
* 永続化コンテキストを操作するためのインタフェース。
*
* EntityManagerインスタンスは永続化コンテキストと関連づけられています。
* 永続化コンテキストは，エンティティインスタンスのセットであり，
* 永続化されたエンティティごとに，エンティティのインスタンスは
* ユニークになっています。
* 永続化コンテキスト内では，エンティティのインスタンスと
* そのライフサイクルが管理されています。
* EntityManagerインタフェースは，永続化コンテキストを操作するための
* メソッドを定義しており，永続化されたエンティティインスタンスの作成・削除や，
* プライマリキーによるエンティティの検索，エンティティのクエリの実行などに
* 使用されます。
*
* EntityManagerによって管理できるエンティティのセットは，永続化ユニットで
* 定義します。
* 永続化ユニットは，アプリケーションによって使用されるエンティティクラスの
* グループを定義し，エンティティクラスとデータベースとのマッピングも
* 定義します。
*/
public interface EntityManager {
 
  /**
  * インスタンスをマネージド状態にして，永続化します。
  * @param entity 永続化するエンティティのインスタンス
  * @throws EntityExistsException エンティティがすでに存在した場合
  * （persistメソッドが呼ばれた時にEntityExistsExceptionがスローされるか，
  * flushまたはコミット時にEntityExistsExceptionまたは
  * そのほかのPersistenceExceptionがスローされます）
  * @throws IllegalArgumentException エンティティではない場合
  * @throws TransactionRequiredException PersistenceContextType.TRANSACTIONが指定された
  * コンテナ管理のエンティティマネージャが，トランザクションが存在しない時に
  * 呼ばれた場合
  */
  public void persist(Object entity);
  
  /**
  * エンティティの状態を現在の永続化コンテキストにマージします。
  * @param entity エンティティ
  * @return 状態が永続化コンテキストにマージされたインスタンス
  * @throws IllegalArgumentExceptionインスタンスがエンティティ
  * ではないか，removed状態のエンティティである場合
  * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
  * を指定したコンテナ管理のエンティティマネージャが，トランザクションが
  * 存在しない時に呼ばれた場合
  */
  public <T> T merge(T entity);
  
  /**
  * エンティティのインスタンスを削除します。
  * @param entity エンティティ
  * @throws IllegalArgumentExceptionインスタンスがエンティティ
  * ではないか，detached状態のエンティティである場合
  * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
  * を指定したコンテナ管理のエンティティマネージャが，トランザクションが
  * 存在しない時に呼ばれた場合
  */
  public void remove(Object entity);
  
  /**
  * プライマリキーを検索します。
  * @param entityClass エンティティクラス
  * @param primaryKey プライマリキー
  * @return 検索したエンティティのインスタンス
  * エンティティが存在しない場合はnull
  * @throws IllegalArgumentException entityClass引数がエンティティの型
  * でない場合，またはprimaryKey引数がそのエンティティのプライマリキー
  * として有効な型でない場合
  */
  public <T> T find(Class<T> entityClass, Object primaryKey);
  
  /**
  * 状態が遅延フェッチされるインスタンスを取得します。
  * リクエストしたエンティティがデータベースに存在しない場合，
  * インスタンスの状態に最初にアクセスしたときに，
  * EntityNotFoundExceptionがスローされます。
  * （getReferenceが呼ばれた時に，JPAプロバイダが
  * EntityNotFoundExceptionをスローすることも許されています）
  * アプリケーションは，エンティティマネージャがオープンしている間に
  * インスタンスにアクセスしない場合，デタッチ時にインスタンスの状態に
  * アクセスできることを期待しないでください。
  * @param entityClass エンティティクラス
  * @param primaryKey プライマリキー
  * @return 検索したエンティティのインスタンス。
  * @throws IllegalArgumentException entityClass引数がエンティティの型
  * でない場合，またはprimaryKey引数がそのエンティティのプライマリキー
  * として有効な型でない場合
  * @throws EntityNotFoundException エンティティの状態に
  * アクセスできない場合
  */
  public <T> T getReference(Class<T> entityClass, Object primaryKey);
  
  /**
  * 永続化コンテキストの状態をデータベースにフラッシュさせます。
  * @throws TransactionRequiredException トランザクションが存在しない場合
  * @throws PersistenceException フラッシュに失敗した場合
  */
  public void flush();
  
  /**
  * 永続化コンテキストに含まれるすべてのオブジェクトに適用される
  * フラッシュモードを設定します。
  * @param flushMode フラッシュモード
  */
  public void setFlushMode(FlushModeType flushMode);
  
  /**
  * 永続化コンテキストに含まれるすべてのオブジェクトに適用される
  * フラッシュモードを取得します。
  * @return flushMode フラッシュモード
  */
  public FlushModeType getFlushMode();
  
  /**
  * 永続化コンテキストに含まれるエンティティオブジェクトのロックモードを
  * セットします。
  * @param entity エンティティ
  * @param lockMode ロックモード
  * @throws PersistenceException サポートされていないロック呼び出しが
  * 行われた場合
  * @throws IllegalArgumentException インスタンスがエンティティ
  * でない場合，またはデタッチされたエンティティである場合
  * @throws TransactionRequiredException トランザクションが存在しない場合
  */
  public void lock(Object entity, LockModeType lockMode);
  
  /**
  * インスタンスの状態をデータベースの状態にリフレッシュします。
  * インスタンスの状態が変更されている場合，データベースの状態で
  * 上書きされます。
  * @param entity エンティティ
  * @throws IllegalArgumentException エンティティでないか，
  * managed状態でない場合
  * @throws TransactionRequiredException PersistenceContextType.TRANSACTION
  * が指定された
  * コンテナ管理のエンティティマネージャが，トランザクションが存在しない時に
  * 呼ばれた場合
  * @throws EntityNotFoundException エンティティがすでにデータベースに
  * 存在しない場合
  */
  public void refresh(Object entity);
  
  /**
  * 永続化コンテキストをクリアし，すべてのmanaged状態のエンティティを
  * デタッチします。
  * エンティティにデータベースにフラッシュされていない変更がある場合，
  * 永続化されません。
  */
  public void clear();
  
  /**
  * インスタンスが現在の永続化コンテキストに含まれているかをチェックします。
  * @param entity エンティティ
  * @return 含まれている場合true
  * @throws IllegalArgumentException エンティティではない場合
  */
  public boolean contains(Object entity);
  
  /**
  * JPQL(Java Persistence Query language)の文を実行するための
  * Queryインスタンスを作成します。
  * @param qlString Java Persistence Queryの文
  * @return 新しいQueryのインスタンス
  * @throws IllegalArgumentException クエリ文が有効でない場合
  */
  public Query createQuery(String qlString);
  
  /**
  * 名前付きクエリ（JPQLまたはネイティブSQL）を実行するための
  * Queryインスタンスを作成します。
  * @param name メタデータで定義されたクエリの名前
  * @return 新しいQueryのインスタンス
  * @throws IllegalArgumentException 指定された名前のクエリが
  * 定義されていない場合
  */
  public Query createNamedQuery(String name);
  
  /**
  * ネイティブSQL文（update文，delete文）を実行するための
  * Queryインスタンスを作成します。
  * @param sqlString ネイティブSQL文
  * @return 新しいQueryのインスタンス
  */
  public Query createNativeQuery(String sqlString);
  
  /**
  * ネイティブSQLのクエリを実行するためのQueryインスタンスを作成します。
  * @param sqlString ネイティブSQL文
  * @param resultClass 返り値となるインスタンスのクラス
  * @return 新しいQueryのインスタンス
  */
  public Query createNativeQuery(String sqlString, Class result-
  Class);
  
  /**
  * ネイティブSQLのクエリを実行するためのQueryインスタンスを作成します。
  * @param sqlString ネイティブSQL文
  * @param resultSetMapping 結果セットマッピングの名前
  * @return 新しいQueryのインスタンス
  */
  public Query createNativeQuery(String sqlString, String result-
  SetMapping);
  
  /**
  * EntityManagerにJTAトランザクションがアクティブになったことを通知します。
  * このメソッドは，トランザクションのスコープの外で作成された
  * アプリケーション管理のJTAエンティティマネージャを
  * 現在のJTAトランザクションに関連づけるために，
  * アプリケーションによって呼び出されます。
  * @throws TransactionRequiredException トランザクションが存在しない場合
  */
  public void joinTransaction();
  
  /**
  * 下位にあるプロバイダのオブジェクトが存在する場合は返します。
  * このメソッドの返り値は実装依存ですが，
  * Component Containerでコンテナ管理のエンティティマネージャを
  * 使用する場合は，JPAプロバイダのEntityManagerオブジェクトを返します。
  * @return JPAプロバイダのEntityManagerオブジェクト
  * /
  public Object getDelegate();
  
  /**
  * アプリケーション管理のEntityManagerをクローズします。
  * closeメソッドが呼び出されたあとは，EntityManagerインスタンスと
  * EntityManagerから取得したQueryオブジェクトの，
  * getTransactionとisOpen（falseを返します）以外のすべてのメソッドは，
  * IllegalStateExceptionをスローします。
  * EntityManagerがアクティブなトランザクションに関連づいている時に
  * このメソッドが呼ばれた場合，トランザクションが決着するまで
  * 永続化コンテキストは存続します。
  * @throws IllegalStateException コンテナ管理のEntityManagerである場合
  */
  public void close();
  
  /**
  * EntityManagerがオープンされているかどうかを返す。
  * @return EntityManagerがクローズされるまではtrueを返す。
  */
  public boolean isOpen();
  
  /**
  * リソースレベルのトランザクションオブジェクトを返します。
  * EntityTransactionインスタンスは，複数のトランザクションを，
  * シリアルに開始，コミットするために使用されます。
  * @return EntityTransactionのインスタンス
  * @throws IllegalStateException JTAエンティティマネージャで
  * このメソッドが呼び出された場合
  */
  public EntityTransaction getTransaction();
 
}

• トランザクションスコープの永続化コンテキストを使用している場合，persist，merge，remove，refreshメソッドは，トランザクションコンテキスト内で呼び出す必要があります。トランザクションコンテキストが存在しない場合，javax.persistence.TransactionRequiredExceptionがスローされます。
• find，getReferenceメソッドは，トランザクションコンテキスト外で呼び出すこともできます。トランザクションスコープの永続化コンテキストを使用している場合，結果のエンティティはデタッチド状態になります。拡張永続化コンテキストを使用している場合，結果のエンティティはmanaged状態になります。
• EntityManagerから取得したQueryとEntityTransactionオブジェクトは，EntityManagerがオープンされている間，使用できます。
• createQueryメソッドの引数が有効なJPQL（Java Persistence Query Language）でない場合，IllegalArgumentExceptionがスローされるか，クエリの実行が失敗します。ネイティブクエリが正しくない場合や，結果セットの定義がクエリの結果と互換性がない場合には，クエリが実行される時にPersistenceExceptionがスローされ，クエリの実行が失敗します。PersistenceExceptionは，可能な場合はデータベースの例外をラップしたものになっています。
• EntityManagerインタフェースのメソッドでランタイム例外がスローされる場合，トランザクションはロールバックします。
• close，isOpen，joinTransaction，getTransactionはアプリケーション管理のEntityManagerを管理するためのメソッドです。
• EJB仕様では，Stateless Session Beanで，EntityManagerのメソッドを呼び出せるのは次のメソッドです。
  
  • ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド
  • ビジネスメソッド
  • インターセプタメソッド
  • タイムアウトコールバックメソッド
  コンストラクタや，DIのセッターメソッド（setSessionContextメソッドを含む），ライフサイクルコールバックメソッド（PostConstructやPreDestroy）では，EntityManagerのメソッドを呼び出せません。許可されていない場所でEntityManagerのメソッドを呼び出した場合，KDJE56538-Eメッセージが出力され，java.lang.IllegalStateExceptionがスローされます。
  
• EJB仕様では，Stateful Session BeanでEntityManagerのメソッドを呼び出せるのは，次のメソッドです。
  
  • ライフサイクルコールバックメソッド（PostConstructやPreDestroy）
  • ビジネスインタフェースまたはコンポーネントインタフェースのビジネスメソッド
  • ビジネスメソッド
  • インターセプタメソッド
  • SessionSynchronizationのafterBeginおよびbeforeCompletionメソッド
  コンストラクタや，DIのセッターメソッド，SessionSynchronizationのafterCompletionメソッドでは，EntityManagerのメソッドを呼び出せません。許可されていない場所でEntityManagerのメソッドを呼び出した場合，KDJE56538-Eメッセージが出力され，java.lang.IllegalStateExceptionがスローされます。
  

なお，アプリケーションサーバでJPAを使用する場合は次の点にも注意してください。

• アプリケーションがインジェクト，JNDIでのルックアップ，およびEntityManagerFactoryを使用して取得したEntityManagerは，JPAプロバイダが提供するEntityManagerオブジェクトではなく，アプリケーションサーバが提供するEntityManagerのプロキシクラスになっています。このプロキシクラスのgetDelegate()を使用すると，JPAプロバイダが提供するEntityManagerオブジェクトを取得できます。ただし，コンテナ管理のEntityManagerを使用する場合，EntityManagerのライフサイクルはコンテナが管理しているので，getDelegate()を使用して取得したEntityManagerオブジェクトのclose()をアプリケーションから呼ばないでください。
• トランザクションスコープの永続化コンテキストを使用する場合で，トランザクションが存在しないときにEntityManagerのgetDelegate()を呼び出すと，コンテナは返されたEntityManagerをクローズできません。この場合には，アプリケーションでEntityManager.close()を呼び出す必要があります。