18.4. Basic Use of JPAContainer

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.

// We need a factory to create entity manager
EntityManagerFactory emf =
    Persistence.createEntityManagerFactory("book-examples");

// We need an entity manager to create entity provider
EntityManager em = emf.createEntityManager();

// We need an entity provider to create a container        
CachingMutableLocalEntityProvider<Person> entityProvider =
    new CachingMutableLocalEntityProvider<Person>(Person.class,
                                                  em);

// And there we have it
JPAContainer<Person> persons =
        new JPAContainer<Person> (Person.class);
persons.setEntityProvider(entityProvider);

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

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 setWriteThrough(false) 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.

The isDeleted() method checks whether the item has been marked for deletion with removeItem() in a buffered 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.

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

Also, the current implementation does not support setChildrenAllowed(), which controls whether the user can expand a node by clicking a toggle. The toggle is by default visible for all nodes, even if they have no children. The method is not supported because it would require storing the information outside the entities. You can override areChildrenAllowed() to implement the functionality using a custom logic.

// Customize JPAContainer to define the logic for
// displaying the node expansion indicator
JPAContainer<CelestialBody> bodies =
        new JPAContainer<CelestialBody>(CelestialBody.class) {
    @Override
    public boolean areChildrenAllowed(Object itemId) {
        // Some simple logic
        return getChildren(itemId).size() > 0;
    }
};
bodies.setEntityProvider(
    new CachingLocalEntityProvider<CelestialBody>(
        CelestialBody.class, em));