javax.persistence

インタフェース EntityManager

public interface EntityManager

永続化コンテキストと対話するために使用されるインタフェース。

EntityManagerのインスタンスは永続化コンテキストに関連付けられています。 永続化コンテキストとは永続的なエンティティの単位に対して一意のエンティティインスタンスが存在するエンティティインスタンスの集合です。 永続化コンテキスト内では、エンティティインスタンスとそのライフサイクルが管理されます。 EntityManagerのAPIは、永続化されたエンティティインスタンスを作成および削除し、主キーでエンティティを見つけ、エンティティを照会するために使用されます。

与えられたEntityManagerのインスタンスによって管理できるエンティティの集合は永続化ユニットによって定義されます。 永続化ユニットはアプリケーションによって関連付けまたはグループ化され、単一のデータベースへのマッピングで配置されなければならないすべてのクラスの集合を定義します。

導入されたバージョン:

Java Persistence 1.0

関連項目:

Query, TypedQuery, CriteriaQuery, PersistenceContext, StoredProcedureQuery

メソッドのサマリー

修飾子とタイプ	メソッドと説明
void	clear() 永続化コンテキストをクリアし、すべての管理下のエンティティをデタッチ状態にします。
void	close() アプリケーション管理のエンティティマネージャーをクローズします。
boolean	contains(java.lang.Object entity) インスタンスが現在の永続化コンテキストに所属する管理下のエンティティインスタンスであるかを確認します。
<T> EntityGraph<T>	createEntityGraph(java.lang.Class<T> rootType) 動的にEntityGraphを作成するのに使用できる可変なEntityGraphを返します。
EntityGraph<?>	createEntityGraph(java.lang.String graphName) 名前付きEntityGraphの可変なコピーを返します。
Query	createNamedQuery(java.lang.String name) 名前付き(JPQLまたはネイティブSQLの)クエリーを実行するためのQueryインスタンスを作成します。
<T> TypedQuery<T>	createNamedQuery(java.lang.String name, java.lang.Class<T> resultClass) JPQLの名前付きクエリーを実行するためのTypedQueryのインスタンスを作成します。
StoredProcedureQuery	createNamedStoredProcedureQuery(java.lang.String name) ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。
Query	createNativeQuery(java.lang.String sqlString) ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。
Query	createNativeQuery(java.lang.String sqlString, java.lang.Class resultClass) ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。
Query	createNativeQuery(java.lang.String sqlString, java.lang.String resultSetMapping) ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。
Query	createQuery(CriteriaDelete deleteQuery) クライテリア削除クエリーのためのQueryのインスタンスを作成します。
<T> TypedQuery<T>	createQuery(CriteriaQuery<T> criteriaQuery) クライテリアクエリーのためのTypedQueryのインスタンスを作成します。
Query	createQuery(CriteriaUpdate updateQuery) クライテリア更新クエリーのためのQueryのインスタンスを作成します。
Query	createQuery(java.lang.String qlString) JPQLのステートメントを実行するためのQueryのインスタンスを作成します。
<T> TypedQuery<T>	createQuery(java.lang.String qlString, java.lang.Class<T> resultClass) JPQLのステートメントを実行するためのTypedQueryのインスタンスを作成します。
StoredProcedureQuery	createStoredProcedureQuery(java.lang.String procedureName) ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。
StoredProcedureQuery	createStoredProcedureQuery(java.lang.String procedureName, java.lang.Class... resultClasses) ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。
StoredProcedureQuery	createStoredProcedureQuery(java.lang.String procedureName, java.lang.String... resultSetMappings) ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。
void	detach(java.lang.Object entity) 与えられたエンティティを永続化コンテキストから削除し、マネージドエンティティをデタッチ状態にします。
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey) 主キーで見つけます。
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode) 主キーで見つけ、ロックします。
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties) 指定されたプロパティを使用して主キーで見つけ、ロックします。
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, java.util.Map<java.lang.String,java.lang.Object> properties) 指定されたプロパティを使用して主キーで見つけます。
void	flush() 永続化コンテキストを基となるデータベースと同期化させます。
CriteriaBuilder	getCriteriaBuilder() CriteriaQueryオブジェクトを作るためのCriteriaBuilderのインスタンスを返します。
java.lang.Object	getDelegate() 利用可能な場合にEntityManagerの基となるプロバイダーオブジェクトを返します。
EntityGraph<?>	getEntityGraph(java.lang.String graphName) 名前付きEntityGraphを返します。
<T> java.util.List<EntityGraph<? super T>>	getEntityGraphs(java.lang.Class<T> entityClass) 与えられたクラスの型のために定義されたすべての名前付きEntityGraphを返します。
EntityManagerFactory	getEntityManagerFactory() このエンティティマネージャーのエンティティマネージャーファクトリーを返します。
FlushModeType	getFlushMode() 永続化コンテキストに含まれるすべてのオブジェクトに適用されるフラッシュモードを取得します。
LockModeType	getLockMode(java.lang.Object entity) エンティティインスタンスのための現在のロックモードを取得します。
Metamodel	getMetamodel() 永続化ユニットのメタモデルにアクセスするためのMetamodelインターフェースのインスタンスを返します。
java.util.Map<java.lang.String,java.lang.Object>	getProperties() エンティティマネージャーに有効なプロパティーとヒントと関連する値を取得します。
<T> T	getReference(java.lang.Class<T> entityClass, java.lang.Object primaryKey) 状態がLAZYフェッチされる可能性のあるインスタンスを取得します。
EntityTransaction	getTransaction() リソースレベルのEntityTransactionオブジェクトを返します。
boolean	isJoinedToTransaction() 現在のトランザクションにエンティティマネージャーが参加しているかどうかを返します。
boolean	isOpen() エンティティマネージャーがオープンしているかどうかを返します。
void	joinTransaction() エンティティマネージャーにJTAトランザクションがアクティブであることを示し、永続化コンテキストをそれに参加させます。
void	lock(java.lang.Object entity, LockModeType lockMode) 永続化コンテキストに含まれるエンティティインスタンスを指定されたロックモード型でロックします。
void	lock(java.lang.Object entity, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties) 永続化コンテキストに含まれるエンティティインスタンスを指定されたロックモード型と指定されたプロパティでロックします。
<T> T	merge(T entity) 与えられたエンティティの状態を現在の永続化コンテキストにマージします。
void	persist(java.lang.Object entity) インスタンスを管理し、永続化します。
void	refresh(java.lang.Object entity) データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きします。
void	refresh(java.lang.Object entity, LockModeType lockMode) データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きし、 指定されたロックモード型でロックします。
void	refresh(java.lang.Object entity, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties) データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きし、 指定されたロックモード型および指定されたプロパティでロックします。
void	refresh(java.lang.Object entity, java.util.Map<java.lang.String,java.lang.Object> properties) 指定されたプロパティを使用してデータベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きします。
void	remove(java.lang.Object entity) エンティティのインスタンスを削除します。
void	setFlushMode(FlushModeType flushMode) 永続化コンテキストに含まれるすべてのオブジェクトに適用されるフラッシュモードを設定します。
void	setProperty(java.lang.String propertyName, java.lang.Object value) エンティティマネージャーにプロパティもしくはヒントを設定します。
<T> T	unwrap(java.lang.Class<T> cls) プロバイダ固有のAPIへのアクセスを許可するために指定された型のオブジェクトを返します。

メソッドの詳細

persist

void persist(java.lang.Object entity)

インスタンスを管理し、永続化します。

パラメータ:

entity - エンティティのインスタンス

例外:

EntityExistsException - エンティティがすでに存在する場合(エンティティがすでに存在する場合、 永続化操作が実行された場合にEntityExistsExceptionが投げられるか、 EntityExistsExceptionもしくはほかのPersistenceExceptionがフラッシュもしくはコミット時に投げられる場合があります。)

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合

merge

<T> T merge(T entity)

与えられたエンティティの状態を現在の永続化コンテキストにマージします。

パラメータ:

entity - エンティティのインスタンス

戻り値:

状態がマージされた管理下にあるインスタンス

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでないか、削除されたエンティティの場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合

remove

void remove(java.lang.Object entity)

エンティティのインスタンスを削除します。

パラメータ:

entity - エンティティのインスタンス

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでないか、デタッチ状態のエンティティの場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合

find

<T> T find(java.lang.Class<T> entityClass,
           java.lang.Object primaryKey)

主キーで見つけます。 指定されたクラスと主キーのエンティティを検索します。 エンティティインスタンスが永続化コンテキストに含まれている場合はそこから戻されます。

パラメータ:

entityClass - エンティティクラス

primaryKey - 主キー

戻り値:

見つかったエンティティのインスタンス、存在しない場合はnull

例外:

java.lang.IllegalArgumentException - 最初の引数がエンティティ型を示さない場合、または2番目の引数がそのエンティティの主キーの有効な型でないかnullの場合

find

<T> T find(java.lang.Class<T> entityClass,
           java.lang.Object primaryKey,
           java.util.Map<java.lang.String,java.lang.Object> properties)

指定されたプロパティを使用して主キーで見つけます。 指定されたクラスと主キーのエンティティを検索します。 エンティティインスタンスが永続化コンテキストに含まれている場合はそこから戻されます。 ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

パラメータ:

entityClass - エンティティクラス

primaryKey - 主キー

properties - 標準およびベンダー固有のプロパティとヒント

戻り値:

見つかったエンティティのインスタンス、存在しない場合はnull

例外:

java.lang.IllegalArgumentException - 最初の引数がエンティティ型を示さない場合、または2番目の引数がそのエンティティの主キーの有効な型でないかnullの場合

導入されたバージョン:

Java Persistence 2.0

find

<T> T find(java.lang.Class<T> entityClass,
           java.lang.Object primaryKey,
           LockModeType lockMode)

主キーで見つけ、ロックします。 指定されたクラスと主キーのエンティティを検索し、指定されたロックタイプを配慮してロックします。 エンティティインスタンスが永続化コンテキストに含まれ、そこから返される場合、このメソッドはエンティティに対してロックメソッドが呼び出された場合と同じ効果を及ぼします。

エンティティが永続化コンテキスト内で見つかり、悲観ロックモードタイプが指定され、エンティティにバージョン属性が含まれている場合、 永続化プロバイダはデータベースロックを取得する際に楽観バージョンチェックも実行する必要があります。 これらのチェックに失敗するとOptimisticLockExceptionが投げられます。

ロックモードタイプが悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

パラメータ:

entityClass - エンティティクラス

primaryKey - 主キー

lockMode - ロックモード

戻り値:

見つかったエンティティのインスタンス、存在しない場合はnull

例外:

java.lang.IllegalArgumentException - 最初の引数がエンティティ型を示さない場合、または2番目の引数がそのエンティティの主キーの有効な型でないかnullの場合

TransactionRequiredException - トランザクションが存在せず、エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合、 または現在のトランザクションに結合されていないエンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合

OptimisticLockException - 楽観バージョンチェックに失敗した場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

導入されたバージョン:

Java Persistence 2.0

find

<T> T find(java.lang.Class<T> entityClass,
           java.lang.Object primaryKey,
           LockModeType lockMode,
           java.util.Map<java.lang.String,java.lang.Object> properties)

指定されたプロパティを使用して主キーで見つけ、ロックします。 指定されたクラスと主キーのエンティティを検索し、指定されたロックタイプを配慮してロックします。 エンティティインスタンスが永続化コンテキストに含まれる場合、そこから返されます。

エンティティが永続化コンテキストで見つかり、悲観ロックモードタイプが指定され、エンティティにバージョン属性が含まれている場合、 永続化プロバイダはデータベースロックを取得する際に楽観バージョンチェックも実行する必要があります。 これらのチェックに失敗するとOptimisticLockExceptionが投げられます。

ロックモードタイプが悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

ポータブルアプリケーションでは標準のタイムアウトヒントに頼るべきではありません。 使用されているデータベースとプロバイダが使用しているロックメカニズムによっては、ヒントが観測される場合とされない場合があります。

パラメータ:

entityClass - エンティティクラス

primaryKey - 主キー

lockMode - ロックモード

properties - 標準およびベンダー固有のプロパティとヒント

戻り値:

見つかったエンティティのインスタンス、存在しない場合はnull

例外:

java.lang.IllegalArgumentException - 最初の引数がエンティティ型を示さない場合、または2番目の引数がそのエンティティの主キーの有効な型でないかnullの場合

TransactionRequiredException - トランザクションが存在せず、エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合、 または現在のトランザクションに結合されていないエンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合

OptimisticLockException - 楽観バージョンチェックに失敗した場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

導入されたバージョン:

Java Persistence 2.0

getReference

<T> T getReference(java.lang.Class<T> entityClass,
                   java.lang.Object primaryKey)

状態がLAZYフェッチされる可能性のあるインスタンスを取得します。 要求されたインスタンスがデータベースに存在しない場合は、インスタンスの状態に最初にアクセスしたときにEntityNotFoundExceptionがスローされます。 (永続化プロバイダーのランタイムはgetReferenceが呼び出されたときにEntityNotFoundExceptionをスローすることが許可されています。) アプリケーションはエンティティマネージャーがオープン状態である間にアプリケーションによってアクセスされた場合を除き デタッチ状態の時にインスタンスの状態が利用可能であることをアプリケーションは期待してはなりません。

パラメータ:

entityClass - エンティティクラス

primaryKey - 主キー

戻り値:

見つかったエンティティのインスタンス

例外:

java.lang.IllegalArgumentException - 最初の引数がエンティティ型を示さない場合、または2番目の引数がそのエンティティの主キーの有効な型でないかnullの場合

EntityNotFoundException - エンティティの状態にアクセスできない場合

flush

void flush()

永続化コンテキストを基となるデータベースと同期化させます。

例外:

TransactionRequiredException - トランザクションが存在しない場合、もしくはエンティティマネージャーが現在のトランザクションに参加していない場合

PersistenceException - フラッシュに失敗した場合

setFlushMode

void setFlushMode(FlushModeType flushMode)

永続化コンテキストに含まれるすべてのオブジェクトに適用されるフラッシュモードを設定します。

パラメータ:

flushMode - フラッシュモード

getFlushMode

FlushModeType getFlushMode()

永続化コンテキストに含まれるすべてのオブジェクトに適用されるフラッシュモードを取得します。

戻り値:

フラッシュモード

lock

void lock(java.lang.Object entity,
          LockModeType lockMode)

永続化コンテキストに含まれるエンティティインスタンスを指定されたロックモード型でロックします。

悲観ロックモードタイプが指定され、エンティティにバージョン属性が含まれている場合、 永続化プロバイダはデータベースロックを取得する際に楽観バージョンチェックも実行する必要があります。 これらのチェックに失敗するとOptimisticLockExceptionが投げられます。

ロックモードタイプが悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

パラメータ:

entity - エンティティインスタンス

lockMode - ロックモード

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはデタッチ状態のエンティティの場合

TransactionRequiredException - トランザクションが存在しない場合、もしくはエンティティマネージャーが現在のトランザクションに参加していない場合

EntityNotFoundException - 悲観ロックが行われた時にエンティティがデータベースに存在しない場合

OptimisticLockException - 楽観バージョンチェックに失敗した場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

lock

void lock(java.lang.Object entity,
          LockModeType lockMode,
          java.util.Map<java.lang.String,java.lang.Object> properties)

永続化コンテキストに含まれるエンティティインスタンスを指定されたロックモード型と指定されたプロパティでロックします。

悲観ロックモードタイプが指定され、エンティティにバージョン属性が含まれている場合、 永続化プロバイダはデータベースロックを取得する際に楽観バージョンチェックも実行する必要があります。 これらのチェックに失敗するとOptimisticLockExceptionが投げられます。

ロックモードタイプが悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

ポータブルアプリケーションでは標準のタイムアウトヒントに頼るべきではありません。 使用されているデータベースとプロバイダが使用しているロックメカニズムによっては、ヒントが観測される場合とされない場合があります。

パラメータ:

entity - エンティティインスタンス

lockMode - ロックモード

properties - 標準およびベンダー固有のプロパティとヒント

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはデタッチ状態のエンティティの場合

TransactionRequiredException - トランザクションが存在しない場合、もしくはエンティティマネージャーが現在のトランザクションに参加していない場合

EntityNotFoundException - 悲観ロックが行われた時にエンティティがデータベースに存在しない場合

OptimisticLockException - 楽観バージョンチェックに失敗した場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

導入されたバージョン:

Java Persistence 2.0

refresh

void refresh(java.lang.Object entity)

データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きします。

パラメータ:

entity - エンティティインスタンス

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはエンティティが管理下にない場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合

EntityNotFoundException - エンティティがデータベースに存在しない場合

refresh

void refresh(java.lang.Object entity,
             java.util.Map<java.lang.String,java.lang.Object> properties)

指定されたプロパティを使用してデータベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きします。

ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

パラメータ:

entity - エンティティインスタンス

properties - 標準およびベンダー固有のプロパティとヒント

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはエンティティが管理下にない場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合

EntityNotFoundException - エンティティがデータベースに存在しない場合

導入されたバージョン:

Java Persistence 2.0

refresh

void refresh(java.lang.Object entity,
             LockModeType lockMode)

データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きし、 指定されたロックモード型でロックします。

ロックモードタイプが悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

パラメータ:

entity - エンティティインスタンス

lockMode - ロックモード

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはエンティティが管理下にない場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合、 トランザクションが存在せず拡張エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合、 または現在のトランザクションに結合されていない拡張エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合

EntityNotFoundException - エンティティがデータベースに存在しない場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

導入されたバージョン:

Java Persistence 2.0

refresh

void refresh(java.lang.Object entity,
             LockModeType lockMode,
             java.util.Map<java.lang.String,java.lang.Object> properties)

データベースからのインスタンスの状態をリフレッシュし、存在する場合はエンティティに加えられた変更を上書きし、 指定されたロックモード型および指定されたプロパティでロックします。

ロックモード型が悲観ロックで、エンティティインスタンスが見つかってもロックできない場合は、次のようになります。

• データベースのロックが失敗した場合にトランザクションレベルのロールバックが発生すると、PessimisticLockExceptionが投げられます。
• データベースのロックに失敗した場合にステートメントレベルのロールバックのみが発生すると、LockTimeoutExceptionが投げられます。

ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

ポータブルアプリケーションでは標準のタイムアウトヒントに頼るべきではありません。 使用されているデータベースとプロバイダが使用しているロックメカニズムによっては、ヒントが観測される場合とされない場合があります。

パラメータ:

entity - エンティティインスタンス

lockMode - ロックモード

properties - 標準およびベンダー固有のプロパティとヒント

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合、もしくはエンティティが管理下にない場合

TransactionRequiredException - トランザクションが存在しないときにPersistenceContextType.TRANSACTION型のコンテナ管理エンティティマネージャーで呼び出された場合、 トランザクションが存在せず拡張エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合、 または現在のトランザクションに結合されていない拡張エンティティマネージャーで呼び出された時にNONE以外のロックモードが指定されている場合

EntityNotFoundException - エンティティがデータベースに存在しない場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされた場合

LockTimeoutException - 悲観ロックに失敗し、ステートメントのみがロールバックされた場合

PersistenceException - サポートされていないロック呼び出しが行われた場合

導入されたバージョン:

Java Persistence 2.0

clear

void clear()

永続化コンテキストをクリアし、すべての管理下のエンティティをデタッチ状態にします。 データベースにフラッシュされていないエンティティへの変更はデータベースに永続化されません。

detach

void detach(java.lang.Object entity)

与えられたエンティティを永続化コンテキストから削除し、マネージドエンティティをデタッチ状態にします。 フラッシュされてないエンティティへの変更(エンティティの削除を含む)があった場合、それらはデータベースへ同期化されません。 以前にデタッチ状態になったエンティティを参照するエンティティは、それを引き続き参照します。

パラメータ:

entity - エンティティのインスタンス

例外:

java.lang.IllegalArgumentException - インスタンスがエンティティでない場合

導入されたバージョン:

Java Persistence 2.0

contains

boolean contains(java.lang.Object entity)

インスタンスが現在の永続化コンテキストに所属する管理下のエンティティインスタンスであるかを確認します。

パラメータ:

entity - エンティティのインスタンス

戻り値:

永続化コンテキスト内のエンティティであるかを示すboolean

例外:

java.lang.IllegalArgumentException - エンティティでない場合

getLockMode

LockModeType getLockMode(java.lang.Object entity)

エンティティインスタンスのための現在のロックモードを取得します。

パラメータ:

entity - エンティティインスタンス

戻り値:

ロックモード

例外:

TransactionRequiredException - トランザクションが存在しない場合、 もしくはエンティティマネージャーが現在のトランザクションに参加していない場合

java.lang.IllegalArgumentException - インスタンスが管理下のエンティティでなく、トランザクションがアクティブな場合

導入されたバージョン:

Java Persistence 2.0

setProperty

void setProperty(java.lang.String propertyName,
                 java.lang.Object value)

エンティティマネージャーにプロパティもしくはヒントを設定します。 ベンダー固有のプロパティまたはヒントが認識されない場合、それは暗黙のうちに無視されます。

パラメータ:

propertyName - プロパティもしくはヒントの名前

value - プロパティーもしくはヒントの値

例外:

java.lang.IllegalArgumentException - 2つ目の引数が実装に対して不正な場合

導入されたバージョン:

Java Persistence 2.0

getProperties

java.util.Map<java.lang.String,java.lang.Object> getProperties()

エンティティマネージャーに有効なプロパティーとヒントと関連する値を取得します。 Mapの内容への変更は有効な設定に影響を与えません。

戻り値:

エンティティマネージャーに有効なプロパティのマップとヒント

導入されたバージョン:

Java Persistence 2.0

createQuery

Query createQuery(java.lang.String qlString)

JPQLのステートメントを実行するためのQueryのインスタンスを作成します。

パラメータ:

qlString - JQPLの文字列

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - クエリー文字列が不正である場合

createQuery

<T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)

クライテリアクエリーのためのTypedQueryのインスタンスを作成します。

パラメータ:

criteriaQuery - クライテリアクエリーオブジェクト

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - クライテリアクエリー文字列が不正である場合

導入されたバージョン:

Java Persistence 2.0

createQuery

Query createQuery(CriteriaUpdate updateQuery)

クライテリア更新クエリーのためのQueryのインスタンスを作成します。

パラメータ:

updateQuery - クライテリア更新クエリーオブジェクト

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 更新クエリー文字列が不正である場合

導入されたバージョン:

Java Persistence 2.1

createQuery

Query createQuery(CriteriaDelete deleteQuery)

クライテリア削除クエリーのためのQueryのインスタンスを作成します。

パラメータ:

deleteQuery - クライテリア削除クエリーオブジェクト

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 削除クエリー文字列が不正である場合

導入されたバージョン:

Java Persistence 2.1

createQuery

<T> TypedQuery<T> createQuery(java.lang.String qlString,
                              java.lang.Class<T> resultClass)

JPQLのステートメントを実行するためのTypedQueryのインスタンスを作成します。 クエリーのSELECTリストは一つの項目のみ含まれなければならず、resultClass引数で指定された型に割り当て可能である必要があります。

パラメータ:

qlString - JQPLの文字列

resultClass - クエリーの結果の型

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - クエリー文字列が不正である場合、 またはクエリー結果が指定された型に割り当てる事が出来ない場合

導入されたバージョン:

Java Persistence 2.0

createNamedQuery

Query createNamedQuery(java.lang.String name)

名前付き(JPQLまたはネイティブSQLの)クエリーを実行するためのQueryインスタンスを作成します。

パラメータ:

name - メタデータ内で定義されたクエリーの名前

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 指定された名前でクエリーが定義されていない場合、またはクエリー文字列が不正である場合

createNamedQuery

<T> TypedQuery<T> createNamedQuery(java.lang.String name,
                                   java.lang.Class<T> resultClass)

JPQLの名前付きクエリーを実行するためのTypedQueryのインスタンスを作成します。 クエリーのSELECTリストは一つの項目のみ含まれなければならず、resultClass引数で指定された型に割り当て可能である必要があります。

パラメータ:

name - メタデータ内で定義されたクエリーの名前

resultClass - クエリーの結果の型

戻り値:

新しいクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 指定された名前でクエリーが定義されていない場合、またはクエリー文字列が不正である場合、 またはクエリー結果が指定された型に割り当てる事が出来ない場合

導入されたバージョン:

Java Persistence 2.0

createNativeQuery

Query createNativeQuery(java.lang.String sqlString)

ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。例えば、更新または削除です。 クエリーが更新もしくは削除用のクエリーでない場合、クエリーの実行により、SQLの結果の各行はObject[]型の結果(またはSELECTリストにカラムが1つのみの場合はObject型の結果) として戻されます。 カラムの値はSELECTリストに表示される順に戻され、デフォルトのJDBC型のマッピングが適用されます。

パラメータ:

sqlString - ネイティブSQLクエリー文字列

戻り値:

新しいクエリーのインスタンス

createNativeQuery

Query createNativeQuery(java.lang.String sqlString,
                        java.lang.Class resultClass)

ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。

パラメータ:

sqlString - ネイティブSQLクエリー文字列

resultClass - 結果のインスタンスのクラス

戻り値:

新しいクエリーのインスタンス

createNativeQuery

Query createNativeQuery(java.lang.String sqlString,
                        java.lang.String resultSetMapping)

ネイティブSQLクエリーを実行するためのQueryのインスタンスを作成します。

パラメータ:

sqlString - ネイティブSQLクエリー文字列

resultSetMapping - 結果セットのマッピングの名前

戻り値:

新しいクエリーのインスタンス

createNamedStoredProcedureQuery

StoredProcedureQuery createNamedStoredProcedureQuery(java.lang.String name)

ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。

パラメーターはストアドプロシージャーが実行される前に登録される必要があります。

ストアドプロシージャーが一つ以上の結果を返す場合、結果セットはObject[]型のリストとして戻されます。

パラメータ:

name - メタデータ内のストアドプロシージャークエリーに割り当てられている名前

戻り値:

新しいストアドプロシージャークエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 与えられた名前のストアドプロシージャーが定義されていない場合

導入されたバージョン:

Java Persistence 2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(java.lang.String procedureName)

ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。

パラメーターはストアドプロシージャーが実行される前に登録される必要があります。

ストアドプロシージャーが一つ以上の結果を返す場合、結果セットはObject[]型のリストとして戻されます。

パラメータ:

procedureName - データベース内のストアドプロシージャーの名前

戻り値:

新しいストアドプロシージャークエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 与えられた名前のストアドプロシージャーが存在しない場合(もしくはクエリーの実行が失敗する場合)

導入されたバージョン:

Java Persistence 2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(java.lang.String procedureName,
                                                java.lang.Class... resultClasses)

ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。

パラメーターはストアドプロシージャーが実行される前に登録される必要があります。

resultClass引数はストアドプロシージャーの実行で戻される結果セットの順番で指定しなければなりません。

パラメータ:

procedureName - データベース内のストアドプロシージャーの名前

resultClasses - ストアドプロシージャーによって生成された結果セットがマッピングされるクラス

戻り値:

新しいストアドプロシージャークエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 与えられた名前のストアドプロシージャーが存在しない場合(もしくはクエリーの実行が失敗する場合)

導入されたバージョン:

Java Persistence 2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(java.lang.String procedureName,
                                                java.lang.String... resultSetMappings)

ストアドプロシージャーをデータベースで実行するためのStoredProcedureQueryのインスタンスを作成します。

パラメーターはストアドプロシージャーが実行される前に登録される必要があります。

resultSetMapping引数はストアドプロシージャーの実行で戻される結果セットの順番で指定しなければなりません。

パラメータ:

procedureName - データベース内のストアドプロシージャーの名前

resultSetMappings - ストアドプロシージャーが返す結果セットのマッピングに使用される結果セットマッピングの名前

戻り値:

新しいストアドプロシージャークエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 与えられた名前のストアドプロシージャーが存在しない場合(もしくはクエリーの実行が失敗する場合)

joinTransaction

void joinTransaction()

エンティティマネージャーにJTAトランザクションがアクティブであることを示し、永続化コンテキストをそれに参加させます。

これはJTAのアプリケーション管理のエンティティマネージャーがアクティブなトランザクションのスコープ外で作られたか、 SynchronizationType.UNSYNCHRONIZED型のエンティティマネージャーであるときに、 現在のJTAトランザクションに参加するときに呼び出される必要があります。

例外:

TransactionRequiredException - トランザクションが存在しない場合

isJoinedToTransaction

boolean isJoinedToTransaction()

現在のトランザクションにエンティティマネージャーが参加しているかどうかを返します。 エンティティマネージャーが現在のトランザクションに参加していない場合やアクティブなトランザクションが存在しない場合はfalseを返します。

戻り値:

boolean

導入されたバージョン:

Java Persistence 2.1

unwrap

<T> T unwrap(java.lang.Class<T> cls)

プロバイダ固有のAPIへのアクセスを許可するために指定された型のオブジェクトを返します。 プロバイダのEntityManagerの実装が指定されたクラスをサポートしていない場合はPersistenceExceptionが投げられます。

パラメータ:

cls - 返されるオブジェクトのクラス、これは通常はEntityManagerの基となる実装クラスか、その実装のインターフェース

戻り値:

指定されたクラスのインスタンス

例外:

PersistenceException - プロバイダがこの呼び出しをサポートしていない場合

導入されたバージョン:

Java Persistence 2.0

getDelegate

java.lang.Object getDelegate()

利用可能な場合にEntityManagerの基となるプロバイダーオブジェクトを返します。 このメソッドの結果は実装に依存します。 新しいアプリケーションではunwrapメソッドを使用するのが望ましいです。

戻り値:

EntityManagerの基となるプロバイダーオブジェクト

close

void close()

アプリケーション管理のエンティティマネージャーをクローズします。 このメソッドが呼び出された後、このEntityManagerと、 このEntityManagerから得られたすべてのQueryとTypedQuery、 StoredProcedureQueryオブジェクトのすべてのメソッドはgetPropertiesと、getTransaction、 isOpen(このメソッドはfalseを返します)を除いてIllegalStateExceptionを投げるようになります。 エンティティマネージャーがアクティブなトランザクションに参加しているときにこのメソッドが呼び出された場合、 トランザクションが完了するまで永続化コンテキストは管理されたままとなります。

例外:

java.lang.IllegalStateException - エンティティマネージャーがコンテナ管理の場合

isOpen

boolean isOpen()

エンティティマネージャーがオープンしているかどうかを返します。

戻り値:

エンティティマネージャーがクローズされるまではtrue

getTransaction

EntityTransaction getTransaction()

リソースレベルのEntityTransactionオブジェクトを返します。 EntityTransactionインスタンスは複数のトランザクションを開始およびコミットするために連続して使用できます。

戻り値:

EntityTransaction instance

例外:

java.lang.IllegalStateException - JTAのエンティティマネージャーで実行された場合

getEntityManagerFactory

EntityManagerFactory getEntityManagerFactory()

このエンティティマネージャーのエンティティマネージャーファクトリーを返します。

戻り値:

EntityManagerFactoryのインスタンス

例外:

java.lang.IllegalStateException - エンティティマネージャーがすでにクローズされている場合

導入されたバージョン:

Java Persistence 2.0

getCriteriaBuilder

CriteriaBuilder getCriteriaBuilder()

CriteriaQueryオブジェクトを作るためのCriteriaBuilderのインスタンスを返します。

戻り値:

CriteriaBuilderのインスタンス

例外:

java.lang.IllegalStateException - エンティティマネージャーがすでにクローズされている場合

導入されたバージョン:

Java Persistence 2.0

getMetamodel

Metamodel getMetamodel()

永続化ユニットのメタモデルにアクセスするためのMetamodelインターフェースのインスタンスを返します。

戻り値:

Metamodelのインスタンス

例外:

java.lang.IllegalStateException - エンティティマネージャーがすでにクローズされている場合

導入されたバージョン:

Java Persistence 2.0

createEntityGraph

<T> EntityGraph<T> createEntityGraph(java.lang.Class<T> rootType)

動的にEntityGraphを作成するのに使用できる可変なEntityGraphを返します。

パラメータ:

rootType - エンティティグラフのクラス

戻り値:

エンティティグラフ

導入されたバージョン:

Java Persistence 2.1

createEntityGraph

EntityGraph<?> createEntityGraph(java.lang.String graphName)

名前付きEntityGraphの可変なコピーを返します。 指定された名前でエンティティグラフが存在しない場合はnullを返します。

パラメータ:

graphName - エンティティグラフの名前

戻り値:

エンティティグラフ

導入されたバージョン:

Java Persistence 2.1

getEntityGraph

EntityGraph<?> getEntityGraph(java.lang.String graphName)

名前付きEntityGraphを返します。 返されたEntityGraphは不変であるとみなされる必要があります。

パラメータ:

graphName - 存在するエンティティグラフの名前

戻り値:

名前付きエンティティグラフ

例外:

java.lang.IllegalArgumentException - 与えられた名前のEntityGraphが存在しない場合

導入されたバージョン:

Java Persistence 2.1

getEntityGraphs

<T> java.util.List<EntityGraph<? super T>> getEntityGraphs(java.lang.Class<T> entityClass)

与えられたクラスの型のために定義されたすべての名前付きEntityGraphを返します。

パラメータ:

entityClass - エンティティクラス

戻り値:

指定されたエンティティのために定義されたすべてのエンティティグラフのリスト

例外:

java.lang.IllegalArgumentException - クラスがエンティティではない場合

導入されたバージョン:

Java Persistence 2.1