L'interface EntityManager est une API qui gère le cycle de vie d'une instance d'entité.
Les entités ne peuvent pas assurer elles-mêmes leur persistance dans la base de données relationnelle ; les annotations ne sont utilisées que pour déclarer un POJO comme entité ou pour définir son mappage et ses relations avec des tables de la base de données relationnelle.
Dans JPA, le rôle de l'interface EntityManager est de permettre aux applications de gérer et de rechercher des entités dans la base de données relationnelle.
EntityManager est une API qui gère le cycle de vie d'instances d'entité. Un objet EntityManager gère un ensemble d'entités défini par une unité de persistance. Chaque instance EntityManager est associée à un contexte de persistance. Un contexte de persistance définit la portée dans laquelle des instances d'entité particulières sont créées, conservées et supprimées au moyen des fonctions mises à disposition par l'interface EntityManager. Par certains côtés, un contexte de persistance s'apparente à un contexte de transaction.
Le gestionnaire d'entités effectue un suivi des changements et des mises à jour apportés à tous les objets entity dans un contexte de persistance et les transmet à la base de données. A la fermeture du contexte de persistance, toutes les instances d'entités qui étaient gérées dans ce contexte sont détachées de celui-ci et de leur gestionnaire d'entités ; elles ne sont donc plus gérées. Lorsqu'un objet est détaché de tout contexte de persistance, il n'est plus sous contrôle d'un gestionnaire d'entités et les changements d'état qu'il subit ne sont donc pas synchronisés avec la base de données.
Une instance d'entité est soit gérée par un gestionnaire d'entités (on dit alors qu'elle est attachée à ce gestionnaire), soit non gérée (elle est détachée).
Lorsqu'une entité est attachée à un gestionnaire d'entités, ce dernier surveille les changements subis par l'entité et il les synchronise avec la base de données lorsqu'il décide de "vider" son état.
Lorsqu'une entité est détachée et qu'elle n'est donc plus associée à aucun contexte de persistance, elle est non gérée et ses changements d'état ne sont plus suivis par le gestionnaire d'entités.
Les instances d'entité deviennent non gérées et détachées lorsque la portée (transaction ou contexte de persistance étendue) prend fin. Par conséquent, les entités ainsi détachées peuvent être sérialisées et envoyées à un client distant via le réseau. Le client peut modifier de son côté ces instances d'objet sérialisées et les renvoyer au serveur pour qu'elles soient fusionnées et synchronisées avec la base de données.
Opération | Description |
---|---|
persist |
|
find | Obtient une instance d'entité gérée ayant une identité persistante (clé primaire) spécifique ; renvoie 'null' si l'instance n'est pas trouvée. |
remove | Supprime de la base de données l'entité gérée dont l'identité persistante est fournie en paramètre. |
merge | Fusionne l'état d'une entité détachée dans une copie gérée de cette même entité. L'entité gérée qui est renvoyée par cette fonction a une identité Java différente de l'entité détachée. |
refresh | Recharge l'état de l'entité à partir de la base de données. |
lock | Définit le mode de verrouillage pour un objet Entity contenu dans le contexte de persistance. |
flush | Force la synchronisation avec la base de données. |
contains | Détermine si une entité est contenue par le contexte de persistance courant. |
createQuery | Crée une instance de requête en langage dynamique JPQL (Java Persistent Query Language). |
createNamedQuery | Crée une instance d'une requête prédéfinie. |
createNativeQuery | Crée une instance de requête SQL. |
Dans un environnement Java EE, l'un des modes d'utilisation du gestionnaire d'entités est de le faire gérer par le conteneur. Dans ce mode, le conteneur est responsable de l'ouverture et de la fermeture du gestionnaire d'entités et par conséquent, du cycle de vie du contexte de persistance (d'une manière transparente pour l'application). Un gestionnaire d'entités géré par le conteneur est également responsable des limites de la transaction.
Un gestionnaire d'entités géré par le conteneur est obtenu, dans une application, par l'injection d'une dépendance ou par une recherche JNDI ; le conteneur gère l'interaction avec la fabrique de gestionnaires d'entités en toute transparence pour l'application.
Un gestionnaire d'entités géré par le conteneur nécessite l'utilisation d'une transaction JTA, car son contexte de persistance est automatiquement propagé avec la transaction JTA courante, et les références au gestionnaire d'entités qui sont mappées à la même unité de persistance fournissent l'accès au même contexte de persistance dans la transaction JTA. Cette propagation du contexte de persistance par le conteneur Java EE signifie que l'application n'a pas à passer de références aux instances de gestionnaire d'entités d'un composant à un autre.
L'utilisation d'un gestionnaire d'entités géré par l'application vous permet d'incorporer le contrôle dudit gestionnaire dans le code de l'application.