An Adventure with J2EE 1.4 Blueprints

Learn the pros and cons betweeen Petstore and Petshop on the J2EE server and find which one fits best for your platform.

Have you heard of Java Blue Prints program? Java Petstore and Java Smart Ticket fall under this category. If you haven't heard of Adventure Builder the latest addition to the Java blue prints then you are not alone. However, if you have not heard of Java Petstore then probably you are not in the J2EE community for too long. Petstore reached its height of popularity during penultimate phase of the .COM boom era. You would find Petstore everywhere prominently from each booth of JavaOne to home pages of J2EE tools and application server vendors with their published and unpublished modifications. Even the guys in the .Net camps loved this application and not too long ago they created the fiasco with their Petstore vs. Petshop benchmark.

Under this program, Sun outlines application programming model for java platform and hence creates best practices and guidelines for building Java applications. You can find details about Java Blue Prints at at

Why A Blueprint application

Unequivocally Java Petstore was one of the earliest applications that provided a nice design pattern and guideline for building scalable and portable applications. In my opinion, Petstore is the most popular application built by Sun after Java and J2EE. Petstore went through several revisions between J2EE 1.2 and J2EE 1.4.

What do you really care of a Java Blue Application? If you are a hardcore and experienced developer and always ahead of the curve then probably you do not. However this is one of the nicest things Sun deliver to make J2EE popular among the developers.

The following are some benefits from Java Blueprint applications:

  • Act a sample application for new technology that be used by developers to learn the new technology
  • Define the application-programming model for the J2EE platform, thus it provides best practices/design guidelines
  • Provides architectural recommendations for real-world application scenarios
  • May be used as a sample application to test J2EE compatibility of your application server vendor

Adventure Builder - An introduction

The Adventure Builder application 1.0 is a nice application that demonstrates J2EE 1.4 technology and simple design patterns.

The concept of buying Adventure online is more realistic than the vague idea of buying Pets online. The details about the Java Adventure Builder can be found at This application uses JAX-RPC, JAXP, Servlet 2.4, JSP 2.0, JSTL and EJB. Unfortunately the documentation is still for the early access 3.1 release and does not live up to the expectation.
The Adventure Builder application consists of six modules and here is a little description of this application.
The Adventure Builder web module (ConsumerWebsite.ear) provides a web interface to search and submit orders for adventure packages.
The Order Processing Center module (OPC.ear) - is the main order-processing module that receives and fills customer oders by coordinating with other suppliers. It uses web services to interact with the suppliers and bank.
ActivitySupplier - receives and fulfills Activity orders from OPC.
AirlineSupplier - receives and fulfills flight bookings from OPC.
LodgingSupplier - receives and fulfills Lodging orders from OPC.

The supplier applications are fairly simple and have very similar structure. The main purpose is to demonstrate inter application communication using web service so the suppliers and hence do not have a lot of internal business logic.

Each supplier receives a web service request for a purchase order from OPC, does some business logic, and later sends an invoice document to OPC.
Bank - authorizes credit card request from OPC.

Architecture Review of Adventure Builder

The detailed architecture guide for Adventure Builder can be found at Unfortunately the architecture guide is not updated with information on the back-end modules.

Data Access Objects for Persistence from web modules
The Adventure Builder web module (ConsumerWebsite.ear) uses a lightweight persistence model and use Data Access Objects to browse Adventures and put an order for an adventure. Unlike its predecessor Petstore application it does not use entity beans.

Custom framework to use implement MVC
It uses a custom framework named Web Application Framework (WAF) instead of using a popular framework like Struts.

Web service as interaction between application modules
This application uses web services heavily for interaction between web modules. For example, the web module invokes web services to submit an order or to retrieve an order. The stateless EJBs are exposed as web service using the JAX-RPC endpoint interface.

Entity beans for persistence in the back-end modules
The Order Processing Center module (OPC.ear), ActivitySupplier, AirlineSupplier and LodgingSupplier have CMP entity beans for persisting the order/invoice information.

JMS and MDBs for asynchronous communication
The OPC module uses JMS for asynchronous communication internally for fulfilling an order and hence there are few MDBs are used.

A Showcase for J2EE Technologies

Adventure Builder is undoubtedly one the earliest and best application that I've seen that uses a myriad of J2EE 1.4 technology. The application has also great user interface that is much better than the earlier versions of blueprint application.

  • Web Service endpoint with JAX-RPC. Relies on web service heavily and demonstrates use of web services using JAX-RPC
  • JSP 2.0 features such as Expression Language, Tag files, JSTL, Custom tags, etc.
  • Use of a custom MVC framework
  • Data Access Objects for persistence from the web tier
  • CMP entity beans for persistence in the business logic tier
  • MDBs for asynchronous communication

Minor Problems in the application

Following are the few issues that need to be addressed to make this application as popular as Petstore

  • Improve documentation and include
  • Avoid packaging with J2EE 1.4 Samples like Petstore that can be downloaded standalone
  • Make build scripts are simpler and remove too much dependency on Sun Application Server
  • Use a framework like Struts that is popular
  • Provide documentation to make this run on your database of choice
  • Create scripts for tables for CMP entity beans
  • Hard coding of web URIs in the application
  • Use a popular persistence framework

Minor Portability Issues

We found few portability issues when trying to port the application to run on OC4J. There were a few places where assumptions were made in code that were based on this application running on the Sun J2EE Reference Implementations. To address these portability issues, a couple of minor code changes are required in the ConsumerWebsite Web module to make it fully portable. We have communicated these changes to the Java Blueprints team and will be addressed in the next release of Java Adventure Builder application.

1) TLD issue

The waftags.tld in WEB-INF/ has in the ConsumerWebsite been changed from a version JSP 1.1/DTD based TLD to a version JSP 2.0/XSD based version. There are few issues in this file:

  • <shortname> is valid for 1.1 but for 2.0 it requires <short-name>
  • <description> tag (the one that says BluePrints Web Application Framework Tags) needs to be removed. The first description is valid, but the second one is not.
  • All occurrences of <tagclass> needs to be changed to <tag-class>
  • Finally, the order is significant in schema, so the order needs to be changed in the <tag> such that the <description> element comes first, before the <name>
2) consumerwebsite/waf/src/java/com/sun/j2ee/blueprints/taglibs/smart/

This class was modified to make JSP 2.0 compliant.

public class OptionTag extends BodyTagSupport {
Old:    public int doAfterBody() throws JspTagException {
New:    public int doEndTag() throws JspTagException {
        BodyContent bc = getBodyContent();
        String text = bc.getString();
<waf:option value="United States">United States</waf:option>
<waf:option value="Canada" />

if (bc == null ) { return SKIP_BODY; }

3) Avoid ClassCastException in

The following code snippet in updateActivityHeadCounts() method in is illegal and depends upon the specific feature on Tomcat and is not portable. This will result in ClassCastException in any other web container that does not rely on Tomcat.

HashMap params = (HashMap)request.getParameterMap();
Map params = request.getParameterMap();

The enter_oder_information.jsp has a number of tags that use this lib in the form of that work correctly. However, it also has: When calling OptionTag's doEndTag a null pointer exception is thrown on the above bc.getString() line because the bodyContent (bc) is null. It can be fixed by adding: after getBodyContent(), line number 58. The modified code should look like:

Configuring and deploying in our J2EE server

The Adventure Builder application is really a nice application that is portable with only few minor code issues. Here are few steps that you can use to make this work on your application server of your choice:

Rebuild with your vendor deployment descriptors

  1. Changes in the ejb-jar.xml in the opc-ejb.jar to modify the end-point URL for web services
  2. Package vendor deployment descriptors for web services, EJB and Web modules to include web services end point definitions, environment references and web services references, etc
  3. Make changes in the build scripts to include the vendor specific deployment descriptors
  4. Make code changes as outline in the earlier section
  5. Rebuild the application with your vendor specific deployment descriptors

Configure your application server

  1. Change the database scripts to make this portable to your database as the PointBase uses "char" whereas Oracle uses "varchar2" for variable character data types
  2. Create a database schema and run the scripts in your database
  3. Make a data-source named "jdbc/adventure/AdventureDB" to point to your database
  4. Create JMS queues and connection factories required by the application
  5. Deploy your application and run your application

You can look at Oracle Technology Network at for detailed steps required to configure and deploy in OC4J 10.0.3.


Java Blueprint applications provide a nice example of demonstrating Java technology. The latest blueprint application is an excellent application that demonstrates use of J2EE 1.4.


Java Adventure Builder 1.0 documentation (

Dig Deeper on Web application framework and Java middleware

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.