Starting from release 5.3, Tapestry provides a built-in JPA integration which supersedes Tynamo's JPA integration.
Contents
Configuring JPA
The persistence.xml file is the standard configuration file in JPA used to define the persistence units. Tapestry reads this file to create the EntityManagerFactory. The following example demonstrates a persistence.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
version="2.0">
<persistence-unit name="DemoUnit"
transaction-type="RESOURCE_LOCAL">
<properties>
<property name="javax.persistence.jdbc.driver"
value="org.h2.Driver" />
<property name="javax.persistence.jdbc.url"
value="jdbc:h2:mem:test" />
<property name="javax.persistence.jdbc.username"
value="sa" />
<property name="eclipselink.ddl-generation"
value="create-tables"/>
<property name="eclipselink.logging.level"
value="fine"/>
</properties>
</persistence-unit>
</persistence>
By default, the persistence descriptor is named persistence.xml and is expected to be located on the classpath in the META-INF directory. If you want to place the persistence.xml file in an other directory or name it arbitrarily, you can make a contribution to the SymbolProvider service, as shown in the following example. This is a quite useful feature if you want to use a different persistence descriptor for tests.
public class AppModule {
@Contribute(SymbolProvider.class)
@FactoryDefaults
public static void provideFactoryDefaults(final MappedConfiguration<String, String> configuration) {
configuration.add(JpaSymbols.PERSISTENCE_DESCRIPTOR, "/org/example/persistence.xml");
}
}
XML-less JPA configuration
Configuring JPA with Tapestry is much more simple than defined in the JPA specification. Tapestry allows you to configure the EntityManagerFactory programmatically without writing XML configuration files. Imagine you want to use JDBC connections managed by the container and provided through JNDI. The resulting persistence descriptor might look like the following one.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
version="2.0">
<persistence-unit name="JTAUnit"
transaction-type="RESOURCE_LOCAL">
<non-jta-data-source>
jdbc/JPATest
</non-jta-data-source>
<properties>
<property name="eclipselink.ddl-generation"
value="create-tables"/>
<property name="eclipselink.logging.level"
value="fine"/>
</properties>
</persistence-unit>
</persistence>
Now let's see how to provide the same configuration without to write any single line of XML. The following example demonstrates an equivalent JPA configuration.
public class AppModule {
@Contribute(EntityManagerSource.class)
public static void configurePersistenceUnitInfos(MappedConfiguration<String,PersistenceUnitConfigurer> cfg) {
PersistenceUnitConfigurer configurer = new PersistenceUnitConfigurer() {
public void configure(TapestryPersistenceUnitInfo unitInfo) {
unitInfo.nonJtaDataSource("jdbc/JPATest")
.addProperty("eclipselink.ddl-generation",
"create-tables")
.addProperty("eclipselink.logging.level",
"fine");
}
};
cfg.add("JTAUnit", configurer);
}
}
In the example above you can see a contribution to the EntityManagerSource service. This service is responsible for creating EntityManagerFactory to be used to create EntityManager. When the service is initialized, it parses the persistence.xml file, if available. For any persistence unit defined in the XML descriptor an TapestryPersistenceUnitInfo is created. The TapestryPersistenceUnitInfo interface is a mutable extension of the PersistenceUnitInfo interface (defined in the JPA specification) that allows you to configure a persistence unit programmatically.
After parsing persistence descriptor, EntityManagerSource service applies its configuration to create further persistence units and/or update the existing. The service’s configuration is a map in which persistence unit names are associated with PersistenceUnitConfigurer instances. A PersistenceUnitConfigurer is used to configure a persistence unit programmatically that has been associated with it. In the example above you can see a contribution providing a PersistenceUnitConfigurer for the unit named JTAUnit.
Note that the TapestryPersistenceUnitInfo instance passed to the PersistenceUnitConfigurer is either empty or my contain the persistence unit metadata read from the persistence.xml file. What happens if you contribute a PersistenceUnitConfigurer for a persistence unit that has not been defined in the persistence.xml file? In this case Tapestry assumes that you want to configure the persistence unit programmatically and just creates a fresh TapestryPersistenceUnitInfo and passes it to the PersistenceUnitConfigurer.
Automatically adding managed classes
If only a single persistence unit is defined, Tapestry scans the application-root-package.entities package. The classes in that package are automatically added as managed classes to the defined persistence unit.
If you have additional packages containing entities, you may contribute them to the JpaEntityPackageManager service configuration.
public class AppModule {
@Contribute(JpaEntityPackageManager.class)
public static void providePackages(Configuration<String> configuration) {
configuration.add("org.example.myapp.domain");
configuration.add("com.acme.model");
}
}
As you can see, you may add as many packages as you wish.
Injecting the EntityManager
The created entity managers can be injected into page, component and other services.
Injecting the EntityManager into page and component classes
Depending on whether more than one persistence unit has been defined, the way to inject [EntityManager|http://download.oracle.com/javaee/6/api/javax/persistence/EntityManager.html] varies slightly. Let’s start with a simple scenario, where only a single persistence unit is defined. In this case, an EntityManager can be injected using the @Inject annotation.
public class CreateAddress {
@Inject
private EntityManager entityManager;
@Property
private Address address;
@CommitAfter
void onSuccess() {
entityManager.persist(address);
}
}
Alternatively, you can use the @PersistenceContext annotation to get the EntityManager_ _injected into a page or component, as shown in the following example.
public class CreateAddress {
@PersistenceContext
private EntityManager entityManager;
@Property
private Address address;
@CommitAfter
void onSuccess() {
entityManager.persist(address);
}
}
If you have multiple instances of persistence-unit defined in the same application, you need to explicitly tell Tapestry which persistence unit you want to get injected. This is what the @PersistenceContext annotation’ s name attribute is used for? The following example demonstrates how to inject the persistence unit named DemoUnit.
public class CreateAddress {
@PersistenceContext(unitName = "DemoUnit")
private EntityManager entityManager;
@Property
private Address address;
@CommitAfter
@PersistenceContext(unitName = "DemoUnit")
void onSuccess() {
entityManager.persist(address);
}
}
Injecting EntityManager into services
While component injection occurs only on fields, the injection in the IoC layer may be triggered by a field or a constructor. The following example demonstrates field injection, when a single persistence unit is defined in the persistence descriptor.
public class UserDAOImpl implements UserDAO {
@Inject
private EntityManager entityManager;
...
}
The constructor injection is demonstrated in the following example.
public class UserDAOImpl implements UserDAO {
private EntityManager entityManager;
public UserDAOImpl(EntityManager entityManager) {
this.entityManager = entityManager;
}
...
}
If multiple persistence units are defined in the same application, you need to disambiguate the unit to inject. This is done by placing the @PersistenceContext annotation, as shown in the following example. Because @PersistenceContext annotation must not be placed on constructor parameters, you can’t use constructor injection and must switch to field injection.
public class UserDAOImpl implements UserDAO {
@Inject
@PersistenceContext(unitName = "DemoUnit")
private EntityManager entityManager;
...
}
Transaction management
As you already know from the Hibernate integration library, Tapestry automatically manages transactions for you. The JPA integration library defines the @CommitAfter _annotation, which acts as the correspondent annotation from the Hibernate integration library. Let’s explore the _UserDAO interface to see the annotation in action.
public interface UserDAO {
@CommitAfter
@PersistenceContext(unitName = "DemoUnit")
void add(User user);
List<User> findAll();
@CommitAfter
@PersistenceContext(unitName = "DemoUnit")
void delete(User... users);
}
As you can see, the annotation may be placed on service method in order to mark that method as transactional. Any method marked with @CommitAfter annotation will have a transaction started before, and committed after it is called. Runtime exceptions thrown by by a transactional method will abort the transaction. Checked exceptions are ignored and the transaction will be committed anyway.
Note that EntityTransaction interface does not support two phase commit. Committing transactions of multiple EntityManagers in the same request might result in data consistency issues. That’s why @CommitAfter annotation must be accompanied by the @PersistenceContext annotation if multiple persistence unit are defined in an application. This way you can only commit the transaction of a single persistence unit. You should be very carefully, if you are committing multiple transactions manually in the same request.
After placing the @CommitAfter annotation on methods, you need to tell Tapestry to advise those methods. This is accomplished by adding the transaction advice, as shown in the following example.
public class AppModule {
@Match("*DAO")
public static void adviseTransactionally(
JpaTransactionAdvisor advisor,
MethodAdviceReceiver receiver) {
advisor.addTransactionCommitAdvice(receiver);
}
}