Basic Use of JPAContainer

    In this section, we look how to create and use JPAContainer instances. We assume that you have defined a domain model with JPA annotations, as described in the previous section.

    The JPAContainerFactory is the easy way to create [classname]#JPAContainer#s. It provides a set of make…​() factory methods for most cases that you will likely meet. Each factory method uses a different type of entity provider, which are described in “Entity Providers”.

    The factory methods take the class type of the entity class as the first parameter. The second parameter is either a persistence unit name (persistence context) or an EntityManager instance.

    See the .

    It’s that easy. In fact, if you run the above code multiple times, you’ll be annoyed by getting a new set of persons for each run - that’s how persistent the container is. The basic make() uses a CachedMutableLocalEntityProvider, which allows modifying the container and its entities, as we do above by adding new entities.

    When using just the persistence unit name, the factory creates an instance of EntityManagerFactory for the persistence unit and uses it to build entity managers. You can also create the entity managers yourself, as described later.

    The entity providers associated with the different factory methods are as follows:

    JPAContainerFactory holds a cache of entity manager factories for the different persistence units, making sure that any entity manager factory is created only once, as it is a heavy operation. You can access the cache to get a new entity manager with the createEntityManagerForPersistenceUnit() method.

    2. EntityManager em = JPAContainerFactory.
    3.     createEntityManagerForPersistenceUnit("book-examples");
    5. // Do a query
    6. em.getTransaction().begin();
    7. em.createQuery("DELETE FROM Person p").executeUpdate();
    8. em.persist(new Person("Jeanne Calment", 122));
    9. em.persist(new Person("Sarah Knauss", 119));
    10. em.persist(new Person("Lucy Hannah", 117));
    11. em.getTransaction().commit();
    13. ...

    See the on-line example.

    Notice that if you use update the persistent data with an entity manager outside a JPAContainer bound to the data, you need to refresh the container as described in .

    While it is normally easiest to use a JPAContainerFactory to create JPAContainer instances, you may need to create them manually. It is necessary, for example, when you need to use a custom entity provider or extend JPAContainer.

    First, we need to create an entity manager and then the entity provider, which we bind to a JPAContainer.

    1. // We need a factory to create entity manager
    2. EntityManagerFactory emf =
    3.     Persistence.createEntityManagerFactory("book-examples");
    4. // We need an entity manager to create entity provider
    5. EntityManager em = emf.createEntityManager();
    7. // We need an entity provider to create a container
    8. CachingMutableLocalEntityProvider<Person> entityProvider =
    10.                                                   em);
    12. // And there we have it
    13. JPAContainer<Person> persons =
    14.         new JPAContainer<Person> (Person.class);
    15. persons.setEntityProvider(entityProvider);

    See the on-line example.

    You could save the first step by asking the entity manager from the JPAContainerFactory.

    JPAContainer integrates with the JPA entity manager, which you would normally use to create and access entities with JPA. You can use the entity manager for any purposes you may have, and then JPAContainer to bind entities to user interface components such as Table, Tree, any selection components, or a Form.

    You can add new entities to a JPAContainer with the addEntity() method. It returns the item ID of the new entity.

    The item ID used by JPAContainer is the value of the ID property (column) defined with the @Id annotation. In our Country entity, it would have Long type. It is generated by the entity manager when the entity is persisted and set with the setter for the ID proeprty.

    Notice that the addEntity() method does not attach the entity instance given as the parameter. Instead, it creates a new instance. If you need to use the entity for some purpose, you need to get the actual managed entity from the container. You can get it with the item ID returned by addEntity().

    1. // Create a new entity and add it to a container
    2. Country france = new Country("France");
    3. Object itemId = countries.addEntity(france);
    5. // Get the managed entity
    6. france = countries.getItem(itemId).getEntity();
    8. // Use the managed entity in entity references
    9. persons.addEntity(new Person("Jeanne Calment", 122, france));

    The getItem() method is defined in the normal Vaadin Container interface. It returns an EntityItem, which is a wrapper over the actual entity object. You can get the entity object with getEntity().

    An EntityItem can have a number of states: persistent, modified, dirty, and deleted. The dirty and deleted states are meaningful when using container buffering, while the modified state is meaningful when using item buffering. Both levels of buffering can be used together - user input is first written to the item buffer, then to the entity instance, and finally to the database.

    The isPersistent() method tells if the item is actually persistent, that is, fetched from a persistent storage, or if it is just a transient entity created and buffered by the container.

    The isModified() method checks whether the EntityItem has changes that are not yet committed to the entity instance. It is only relevant if the item buffering is enabled with setBuffered(true) for the item.

    The isDirty() method checks whether the entity object has been modified after it was fetched from the entity provider. The dirty state is possible only when buffering is enabled for the container.

    In cases where you change JPAContainer items outside the container, for example by through an EntityManager, or when they change in the database, you need to refresh the container.

    The EntityContainer interface implemented by JPAContainer provides two methods to refresh a container. The refresh() discards all container caches and buffers and refreshes all loaded items in the container. All changes made to items provided by the container are discarded. The refreshItem() refreshes a single item.

    If you have a one-to-one or many-to-one relationship, you can define the properties of the referenced entity as nested in a JPAContainer. This way, you can access the properties directly through the container of the first entity type as if they were its properties. The interface is the same as with BeanContainer described in . You just need to add each nested property with addNestedContainerProperty() using dot-separated path to the property.

    1. // Have a persistent container
    2. JPAContainer<Person> persons =
    3.     JPAContainerFactory.make(Person.class, "book-examples");
    4. // Add a nested property to a many-to-one property
    5. persons.addNestedContainerProperty("country.name");
    7. // Show the persons in a table, except the "country" column,
    8. // which is an object - show the nested property instead
    9. Table personTable = new Table("The Persistent People", persons);
    10. personTable.setVisibleColumns("name", "age", "country.name");
    12. // Have a nicer caption for the country.name column
    13. personTable.setColumnHeader("country.name", "Nationality");

    See the on-line example.

    The result is shown in . Notice that the country property in the container remains after adding the nested property, so we had to make that column invisible. Alternatively, we could have redefined the toString() method in the country object to show the name instead of an object reference.

    Nested Properties

    You can use the * wildcard to add all properties in a nested item, for example, “ country.*“.

    JPAContainer implements the Container.Hierarchical interface and can be bound to hierarchical components such as a Tree or TreeTable. The feature requires that the hierarchy is represented with a parent property that refers to the parent item. At database level, this would be a column with IDs.

    The representation would be as follows:

    See the on-line example.

    You set up a JPAContainer to have hierarchy by calling setParentProperty() with the name of the property that refers to the parent. Coincidentally, it is named “ parent” in the example:

    1. // Create the container
    2. JPAContainer<CelestialBody> bodies =
    3.     JPAContainerFactory.make(CelestialBody.class, "my-unit");
    5. // Set it up for hierarchical representation
    6. bodies.setParentProperty("parent");
    8. // Bind it to a hierarhical component
    9. Tree tree = new Tree("Celestial Bodies", bodies);
    10. tree.setItemCaptionMode(Tree.ITEM_CAPTION_MODE_PROPERTY);
    11. tree.setItemCaptionPropertyId("name");

    See the .

    You can use the rootItemIds() to acquire the item IDs of the root elements with no parent.

    1. // Expand the tree
    2. for (Object rootId: bodies.rootItemIds())
    3.     tree.expandItemsRecursively(rootId);

    See the on-line example.

    Using setParent() in the container to define parenthood is not supported.

    See the .