The Java Persistence API is a new programming model under EJB3.0 specification (JSR220) for the management of persistence and object/relational mapping with Java EE and Java SE. With JPA, developers can easily develop java applications that perform operations on relational database management systems using java objects and mapping. In that way, java applications developed using JPA are not only portable across different platforms, but also applications can be easily developed using simple yet powerful programming model provided by JPA. This greatly improves application maintainability against ever changing database world. JPA insulates applications from all the complexity and non-portable boilerplate code involved in database connectivity and operations.

Apache geronimo uses OpenJPA for providing Java Persistence API to Java EE applications deployed in the server. Even though JPA is a part of EJB3.0 spec, it is independent of it. Hence, JPA can be used in JavaSE, web and ejb applications in the same uniform way.

Below tutorial illustrates the use of container managed entity manager object. When @PersistenceContext annotation is used, container injects EntityManager object to the reference. The persistence context of the entity manager is propagated along with any transaction that is currently active. If the transaction spans across components, all the entity manager object references that point to same persistence unit will have the same persistence context through out the transaction. Thus, any changes made to the entities through any entity manager reference, are seen through other entity manager references. The persistence scope of the container managed entity manager is Transaction by default. The transaction-type is always JTA. That is, entity manager object is always registered with the transaction which is active when entity manager is invoked. In summary, the life cycle of the entity manager and the associated persistence context is managed automatically by the container.

The tutorial creates an enterprise application that has an ejb module and a web module. The ejb module uses Account entity with AccountNumber as primary key along with OwnerName and Balance attributes to create accounts in the AccountDB database. The AccountDB is created in the embedded derby database. The AccountBean in the ejb module has the methods to create the Account entities, deposit amount into an account, withdraw amount from an account and retrieve the available balance in a account. The wed module has a servlet that retrieves source account number, destination account number and the amount from user, and performs transfer of the amount from source account to destination account.

The web module uses container injected EntityManager object to check whether the source account has enough available balance to perform the transfer. If yes, it invokes ejb to withdraw the amount from the source account and deposits the same amount in the destination account. Finally, the servlet uses the injected EntityManager object to print the balances in the source and destination accounts. All the above mentioned operations are performed within a JTA transaction. So, persistence context of the entity manager is propagated across web and ejb modules. Hence, any changes made to the entities in ejb module are seen in the web modules when the available balance values are printed.

In order to develop, deploy and run the application, the following environment is required.

Setting the Eclipse environment

1. Download Apache Geronimo2.1 and install it on the server. Look into the geronimo documentation for
instructions.

2. Install the eclipse IDE and download geronimo eclipse plugin and install it on top of eclipse. Look into the
geronimo eclipse plugin documentation for instructions.

3. Create a runtime environment for Apache Geronimo2.1 in the eclipse. Look into the geronimo eclipse plugin
documentation for instructions to install a runtime for Apache Geronimo2.1.

Creating ejb application with entities

1. Open the eclipse tool and change the perspective to Java EE by clicking on Windows => Open Perspective => Other. It will open up Open Perspective wizard.
Select Java EE from the list and click OK button.

2. Right click on the Package Explorer and select EJB Project.

3. This will open up the New EJB Project wizard. Provide the values for Project Name, Target Runtime as given in the screen shot below. Click on Next button.

If target runtime is not setup, create a new target runtime pointing to geronimo installation directory. For more information, look at the geronimo documentation that explains setting up eclipse plugin for geronimo and setting up runtime environment. This setup is required to resolve class dependencies during compilation.

4. Select the check boxes as given in the screen shot below and click on the Next button.

5. Select the checkboxes as given in the below screen shot and click on the Next button.

6. Provide the following values in textboxes and click on the Finish button.

7. Right click on the ContainerManagedJPA-EJB project and navigate to New => Class option. Provide the
following values in the New Java Class wizard and click on Finish button.

8. Copy the following contents into Account.java.

sample.jpa.Account.java

9. Similarly, create AccountInterface.java and copy the following contents.

sample.jpa.AccountInterface.java

10. Similarly, create AccountBean.java.java and copy the following contents.

sample.jpa.AccountBean.java

11. As outlined above, right click on the META_INF directory of ContainerManagedJPA-EJB project and
create persistence.xml. Copy the following contents into persistence.xml.

persistence.xml

12. Since we are going to use EJB annotations, the META-INF/ejb-jar.xml will not have any declarations. The contents of the META-INF/openejb-jar.xml file should be as below. Otherwise, modify it accordingly.

openejb-jar.xml

13. Finally the project ContainerManagedJPA-EJB should like as below.

Creating web application

1. Right click on the Project Explorer and select New => Project. This will popup New Project wizard.
Select Dynamic Web Project under option Web. Click on the Next button.

2. Provide the values as given in the screen shot below on the New Dynamic Web Project wizard. Please note that Add project to an EAR checkbox is check to add this web project to ContainerManagedJPA-EAR created during the creation of ContainerManagedJPA-EJB project.

3. In the next screen, select the Version values as given in the below figure and click on the Next button.

4. Check on the Generate Deployment Descriptor checkbox and click on the Next button. On the next screen, configure the deployment plan as follows. After this, click on the Finish button to complete creating web project

5. Right click on the WebContent folder of the web project and navigate to New => HTML to create the index.html file as given in the screen shot. Click on the Next button and on the next screen click on the Finish button. The content of the index.html is provided below the screen shot.

index.html

6. Right click on the web project and navigate to New => Servlet and click on it.

7. On the Create Servlet wizard, provide the values as given in the below screen shot and click on the Next button.

8. Select the defaults in the next screens and finally click on the Finish button.

9. Copy the below content into the servlet Test.java

Test.java

10. Right click on the ContainerManagedJPA-WEB project and click on Properties to open Properties for ContainerManagedJPA-WEB wizard. Click on the Java Build Path and Projects tab. Click on the Add button and add ContainerManagedJPA-EJB project. Finally, click on the OK button on Properties for ContainerManagedJPA-WEB wizard. This is required because, ContainerManagedJPA-WEB projects looks up AccountInterface ejb in the ContainerManagedJPA-EJB project. To resolve the dependency during compilation, the EJB project has to be added to the build path of the WEB project.

Setting up the database tables and the Datasource

3. On the Run SQL portlet on the right side, enter AccountDB in the Create DB textbox and click on the Create button.

4. The above step will create AccountDB database. On the same screen, enter the below SQL command on the SQL Command/s textarea and select AccountDB in the Use DB combo box and click on the Run SQL button. This will create ACCOUNTCME table in the AccountDB database.

5. Also insert two rows using the below SQL command.

After inserting the rows, table will look like the below screen shot.

6. We need to deploy datasource over AccountDB database for JPA. This datasource will be used by JPA to connect to database and perform DML operations. Admin console can be used to deploy a datasource over AccountDB. Click on the services => Database Pools in the Console => Navigation portlet. This will display the list of database pools currently running in the server.

7. Click on the Using the Geronimo database pool wizard link. This will open up the Database pools portlet as follows. Provide the value for Name of the Database pool as AccountDS and select Derby embedded as below and click on the Next button.

8. On the next screen, select the JAR file listed in the Driver JAR select box and provide AccountDB as the value for Database Name and click on the Deploy button at the bottom. This will deploy the data source and display the list of datasources currently deployed on the server.

9. In the eclipse, open the openejb-jar.xml and provide the dependency to the AccountDS. Finally, the openejb-jar.xml should be as below. This configuration is already done in the step-12 of Creating ejb application with entities above

1. Open a browser window and hit the URL as http://localhost:8080/ContainerManagedJPA-WEB/
This page displays a html form with input fields for Debit Account Number, Credit Account Number and Amount to be Transferred. Enter the values as given in the below screen shot and click on the Submit button.

2. On the next page, several messages are displayed as below. From the messages, it can seen that the persistence context is propagated along with the transaction and hence the changes made to Account balance in the ejb is observed in the servlet when account.getBalance(accountNumber) is called.

3. The values of the balance fields in the ACCOUNTCME table after the transaction are as follows.