In earlier articles we have discussed about using Java Persistence API in a web application and in a multi-tier Java EE application. In this article I shall talk about a few custom JSP tags (the links in that page are broken, but when you download the complete bundle it includes a page where links work.) that I have developed to use Java Persistence API in JSPs. Collectively the tags are referred to as jpa taglib here. It also shows how to inject persistence context into JSPs. A JSP tag library is a collection of custom tags where each tag abstracts out some functionality used by a JSP page. Not only allows a more natural use of that functionality within JSP pages, but also it allows separation of responsibilities.

Source code for the tag library and a sample web application that illustrates the use of the tag library as well as the binaries are available here. Downloaded bundle also include documentation about the tag library that is generated using tlddoc.

Detailed Steps:
Given below are the detailed steps to develop the tag library as well as a sample application that uses the same. Although I am using glassfish in this article, the tag library and the sample are completely portable and can be used in any Java EE 5 compatible application server with a little modification to the accompanying build.xml.

Step #1: Write custom tags

A tag library is a collection of tags. Prior to JSP 2.0, custom tags could only be developed using Java language, but JSP 2.0 allows custom tags to be developed using an Expression Language. I am using Java to develop custom tags. The source code for the tags are in jpa-tag-lib/src directory in package com.sun.jpatl package. of all the tags, jpa:tx tag is TryCatchFinally kind of tag. It is written such that it always ends the transaction, in case of no exception in the embedded JSP fragment, it commits the tx, else it rolls back the tx. All other tags are Simple Tags.

Step #2: Write a tag library descriptor jpa.tld

A tag library descriptor is an XML document describing the tags that are part of the library. Refer to the JSP Spec fpr mode details. As you can see from the tld file, I have given the URI as http://weblogs.java.net/ss141213/tags/jpa.

The tag classes along with tag library descriptor file(jpa.tld) are packaged in a file called jpa-tag-lib.jar which is bundled in WEB-INF/lib dir of the web application.

Step #3: Write a sample web application that uses jpa-tag-lib

Let's write a simple web application that uses these tags to do some database operation. The functionality of this web application is same as the one described in my earlier blog.

Step #3.1: Write entity bean UserCredential.java

Step #3.2: Define a persistence unit persistence.xml

The entity classes along with persistence.xml are packaged in entities.jar which is bundled in WEB-INF/lib dir of the web application.

Step #3.3: Write login.jsp

Points worth noting about this JSP are:
1) It expresses its dependency on jpa-tag-lib by using the following directive:

<%@ taglib uri="http://weblogs.java.net/ss141213/tags/jpa" prefix="jpa" %>

2) It uses custom tag called jpa:injectDefaultPC to inject a container managed entity manager. This entity manager instance is made available in a variable called em1.

3) It uses custom tag jpa:find passing it the entity manager that was earlier injected. Also note how it uses a request time expression to pass the value of the primary key. The searched object is stored in a variable called credential which is later on used by the JSP to compare password.

Step #3.4: Write registration.jsp

Points worth noting about this JSP are:

1) It uses jsp:useBean to initialise a bean called credential by reading attributes passed in request object.

2) It uses custom tag jpa:tx to mark the boundary of a transaction. Inside this transaction, it uses uses custom tag jpa:persist to persist the java bean.

Step #3.5: Write a couple of html files called login.html and registration.html. Note, there is no need to write any web.xml as it is optional in Java EE 5.

Step #4: Build using build.xml

This is a very simple build.xml just to demonstrate the compilation and packaging process. The build targets are:
build-jpa-tag-lib -- builds only the tag library.
build -- builds the tag library build/jpa-tag-lib.jar as well as the sample web app build/web-app6.war. The war file bundles the tag-lib.
clean -- cleans
doc-jpa-tag-lib -- generates documentation for the tag library using a free open source tool called tlddoc. To run this optional target, you need to download the tool from here.
verify -- verify uses a tool called verifier that checks compliance of the application against Java EE spec.
deploy -- deploys the ear file
undeploy -- undeploys the ear file

The last three targets are specific to Sun Java System Application Server 9 PE which is implementing Java EE 5 spec.

As you can see, to compile the sources, only library needed is javaee.jar which contains the Java EE 5 platform APIs.

Step #5: Set up a data source

By default in glassfish entity manager uses the default pre-configured data source with JNDI name jdbc/__default that glassfish comes with. This data source talks to a Derby database called sun-appserv-samples. Refer to the README where I have listed the command needed to start and stop the Derby database. Glassfish has a feature called Java2DB which can autocreate the database schema during deployment, so there is no need to create tables.

Step #6: See them in action
Type http://localhost:8080/web-app6/login.html in the browser. Replace localhost & 8080 by host and port as appropriate in your env.

Want to help?

This is my first attempt to write a tag library, so comments are most welcome. I plan to enhance the tag library and make them available in future. I am even thinking of starting an open source effort to make a production quality tag library for Java Persistence API. Interested readers are welcome to join me in this effort.

References:

Java Server Pages
Tutorial on developing custom tags by Qusay H. Mahmoud
Tutorial on how to use Java Persistence API in a web application
Tutorial on how to use Java Persistence API in a 3 tier (web->ejb->db) Java EE 5 application
Tag Library Documentation Generator Tool: A free open source tool in java.net.

More articles about glassfish persistence jsp.