123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225 |
- ---
- title: Entity Providers
- order: 5
- layout: page
- ---
-
- [[jpacontainer.entityprovider]]
- = Entity Providers
-
- Entity providers provide access to entities persisted in a data store. They are
- essentially wrappers over a JPA entity manager, adding optimizations and other
- features important when binding persistent data to a user interface.
-
- The choice and use of entity providers is largely invisible if you create your
- [classname]#JPAContainer# instances with the [classname]#JPAContainerFactory#,
- which hides such details.
-
- JPAContainer entity providers can be customized, which is necessary for some
- purposes. Entity providers can be Enterprise JavaBeans (EJBs), which is useful
- when you use them in a Java EE application server.
-
- [[jpacontainer.entityprovider.built-in]]
- == Built-In Entity Providers
-
- JPAContainer includes various kinds of built-in entity providers: caching and
- non-caching, read-write and read-only, and batchable.
-
- __Caching__ is useful for performance, but takes some memory for the cache and
- makes the provider stateful. __Batching__, that is, running updates in larger
- batches, can also enhance performance and be used together with caching. It is
- stateless, but doing updates is a bit more complex than otherwise.
-
- Using a __read-only__ container is preferable if read-write capability is not
- needed.
-
- All built-in providers are __local__ in the sense that they provide access to
- entities using a local JPA entity manager.
-
- The [classname]#CachingMutableLocalEntityProvider# is usually recommended as the
- first choise for read-write access and [classname]#CachingLocalEntityProvider#
- for read-only access.
-
- === [classname]#LocalEntityProvider#
-
- A read-only, lazy loading entity provider that does not perform caching and
- reads its data directly from an entity manager.
-
- You can create the provider with [methodname]#makeNonCachedReadOnly()# method in
- [classname]#JPAContainerFactory#.
-
-
- === [classname]#MutableLocalEntityProvider#
-
- Extends [classname]#LocalEntityProvider# with write support. All changes are
- directly sent to the entity manager.
-
- Transactions can be handled either internally by the provider, which is the
- default, or by the container. In the latter case, you can extend the class and
- annotate it, for example, as described in
- <<jpacontainer.entityprovider.built-in>>.
-
- The provider can notify about updates to entities through the
- [interfacename]#EntityProviderChangeNotifier# interface.
-
-
- === [classname]#BatchableLocalEntityProvider#
-
- A simple non-caching implementation of the
- [interfacename]#BatchableEntityProvider# interface. It extends
- [classname]#MutableLocalEntityProvider# and simply passes itself to the
- [methodname]#batchUpdate()# callback method. This will work properly if the
- entities do not contain any references to other entities that are managed by the
- same container.
-
-
- === [classname]#CachingLocalEntityProvider#
-
- A read-only, lazy loading entity provider that caches both entities and query
- results for different filter/sortBy combinations. When the cache gets full, the
- oldest entries in the cache are removed. The maximum number of entities and
- entity IDs to cache for each filter/sortBy combination can be configured in the
- provider. The cache can also be manually flushed. When the cache grows full, the
- oldest items are removed.
-
- You can create the provider with [methodname]#makeReadOnly()# method in
- [classname]#JPAContainerFactory#.
-
-
- === [classname]#CachingMutableLocalEntityProvider#
-
- Just like [classname]#CachingLocalEntityProvider#, but with read-write access.
- For read access, caching works just like in the read-only provider. When an
- entity is added or updated, the cache is flushed in order to make sure the added
- or updated entity shows up correctly when using filters and/or sorting. When an
- entity is removed, only the filter/sortBy-caches that actually contain the item
- are flushed.
-
- This is perhaps the most commonly entity provider that you should consider using
- for most tasks. You can create it with the [methodname]#make()# method in
- [classname]#JPAContainerFactory#.
-
-
- === [classname]#CachingBatchableLocalEntityProvider#
-
- This provider supports making updates in __batches__. You need to implement a
- [interfacename]#BatchUpdateCallback# that does all the updates and execute the
- batch by calling [methodname]#batchUpdate()# on the provider.
-
- The provider is an extension of the
- [classname]#CachingMutableLocalEntityProvider# that implements the
- [interfacename]#BatchableEntityProvider# interface. This will work properly if
- the entities do not contain any references to other entities that are managed by
- the same container.
-
- You can create the provider with [methodname]#makeBatchable()# method in
- [classname]#JPAContainerFactory#.
-
-
-
- [[jpacontainer.entityprovider.jndi]]
- == Using JNDI Entity Providers in JEE6 Environment
-
- JPAContainer 2.0 introduced a new set of entity providers specifically for
- working in a [literal]#++JEE6++# environment. In a JEE environment, you should
- use an entity manager provided by the application server and, usually,
- [literal]#++JTA++# transactions instead of transactions provided by JPA. Entity
- providers in [package]#com.vaadin.addon.jpacontainer.provider.jndijta# package
- work mostly the same way as the normal providers discussed earlier, but use JNDI
- lookups to get reference to an [interfacename]#EntityManager# and to a JTA
- transaction.
-
- The JNDI providers work with almost no special configuration at all. The
- [classname]#JPAContainerFactory# has factory methods for creating various JNDI
- provider types. The only thing that you commonly need to do is to expose the
- [interfacename]#EntityManager# to a JNDI address. By default, the JNDI providers
- look for the [interfacename]#EntityManager# from "
- java:comp/env/persistence/em". This can be done with the following snippet in
- [filename]#web.xml# or with similar configuration with annotations.
-
-
- ----
- <persistence-context-ref>
- <persistence-context-ref-name>
- persistence/em
- </persistence-context-ref-name>
- <persistence-unit-name>MYPU</persistence-unit-name>
- </persistence-context-ref>
- ----
-
- The " [literal]#++MYPU++#" is the identifier of your persistence unit defined in
- your [filename]#persistence.xml# file.
-
- If you choose to annotate your servlets (instead of using the
- [filename]#web.xml# file as described above), you can simply add the following
- annotation to your servlet.
-
-
- ----
- @PersistenceContext(name="persistence/em",unitName="MYPU")
- ----
-
- If you wish to use another address for the persistence context, you can define
- them with the [methodname]#setJndiAddresses()# method. You can also define the
- location for the JTA [classname]#UserTransaction#, but that should be always
- accessible from " java:comp/UserTransaction" by the JEE6 specification.
-
-
- [[jpacontainer.entityprovider.ejb]]
- == Entity Providers as Enterprise Beans
-
- Entity providers can be Enterprise JavaBeans (EJB). This may be useful if you
- use JPAContainer in a Java EE application server. In such case, you need to
- implement a custom entity provider that allows the server to inject the entity
- manager.
-
- For example, if you need to use Java Transaction API (JTA) for JPA transactions,
- you can implement such entity provider as follows. Just extend a built-in entity
- provider of your choise and annotate the entity manager member as
- [literal]#++@PersistenceContext++#. Entity providers can be either stateless or
- stateful session beans. If you extend a caching entity provider, it has to be
- stateful.
-
-
- ----
- @Stateless
- @TransactionManagement
- public class MyEntityProviderBean extends
- MutableLocalEntityProvider<MyEntity> {
-
- @PersistenceContext
- private EntityManager em;
-
- protected LocalEntityProviderBean() {
- super(MyEntity.class);
- setTransactionsHandledByProvider(false);
- }
-
- @Override
- @TransactionAttribute(TransactionAttributeType.REQUIRED)
- protected void runInTransaction(Runnable operation) {
- super.runInTransaction(operation);
- }
-
- @PostConstruct
- public void init() {
- setEntityManager(em);
- /*
- * The entity manager is transaction-scoped, which means
- * that the entities will be automatically detached when
- * the transaction is closed. Therefore, we do not need
- * to explicitly detach them.
- */
- setEntitiesDetached(false);
- }
- }
- ----
-
- If you have more than one EJB provider, you might want to create an abstract
- super class of the above and only define the entity type in implementations. You
- can implement an entity provider as a managed bean in Spring Framefork the same
- way.
-
-
-
|