This article focuses on constructing a lightweight Java Enterprise Edition (JEE) application by leveraging the Java Data Objects (JDO) persistence approach. The Google App Engine SDK and corresponding runtime implementation provide an excellent JDO implementation that you will use to help in designing a sample application.
Before you start
- Save the
AcmeMembersAppWeb.jarfile to a location of your choice on your file system.
- To develop this application quickly, we used IBM®
Rational® Software Architect for WebSphere®, Version 8.0.
Alternatively, you can also complete the steps in this article by
using these options:
- The Rational Application Developer 8.0 toolset.
- Any Eclipse development environment based on the Helios release (v3.6) with the appropriate Java and web development features included and a compatible JDK 1.6. You can download the free Helios release of the Eclipse IDE for Java EE Developers package from the Eclipse website.
If you are using the Rational Software Architect v8.0 or the IBM® Rational® Application Developer v8.0 environment, or another option, you will need to install a few additional items before you get started. Begin by installing the Google App Engine SDK, Version 1.3.8, and the Google Plug-in for Eclipse 3.6, Version 1.4, by following these steps:
- Start your Rational Software Architect software, using a workspace location of your choice. Start > IBM Software Delivery Platform > IBM Software Architect for WebSphere Software 8.0.
- When prompted to enter a workspace location, you can select the default location provided or enter another convenient location.
- If the Welcome window appears, close it.
- Follow the steps to install the Google App Engine SDK and Google
Plug-in using the instructions found here: http://code.google.com/eclipse/docs/install-eclipse-3.6.html.
You do not need to install the Google Web Toolkit package.
After you install the Google App Engine SDK and Google Plug-in and restart the Rational Software Architect IDE, you will notice that the buttons, shown in Figure 1, are now on your toolbar. Circled in Figure 1 is the New Web Application Project button, which you will use later.
Figure 1. The Google Plug-in for Eclipse toolbar icons
In addition to following those instructions, we run our application using the Mozilla Firefox web browser, Version 3.6. When we run our completed application, the browser prompts us to install the Google Web Toolkit Developer Plug-in for Firefox. At the time of writing, the version installed for this add-on was 1.0.7511.
Why Java Data Objects
For many who want to design and construct applications focused on business logic, maintainability, and portability, Java Data Objects (or just JDO for short) are quickly gaining popularity, along with several other options that leverage a growing NoSQL movement.
Although the Java Persistence Architecture (JPA) also strives to accomplish many of these objectives, for some software architects and developers, the need to map Plain Old Java Objects (POJOs) to relational tables is intrusive to the application. The reason is that this mapping exposes and couples the application too closely to the persistent data store's schema. Moreover, the need to map POJOs to tables leads to what some describe as the "persistent impedance mismatch" problem, where the mapping itself influences the application's overall implementation to a higher degree than is desirable.
JDO does not require the application to provide any explicit mappings. Instead, it requires the developer only to denote the attributes to be persisted and to identify the attribute to represent the object's unique identifier (or primary key).
The Acme membership system sample application
Figure 2. The Acme Membership domain model
To receive Acme Company's services and benefits, their clients must become members. They can choose from Single, Student, or Family memberships. Family memberships provide Acme's services to couples and any children that they have who are under the age of 18. To remain members in "good standing," clients must renew their memberships annually.
All correspondence between Acme Co. and its members occurs solely through the primary member. Acme collects the address and other contact information for the primary member for all memberships for this purpose.
The Acme domain model in Figure 2 illustrates the structure and relationships between of our entities. No part of this model gave any consideration either to an existing or to a to-be developed underlying persistent store.
Creating the Acme membership application project
To create an Acme membership application project, follow the steps outlined below.
- Start Rational Software Architect v8.0 using a workspace location of your choice. Start > IBM Software Delivery Platform > IBM Software Architect for WebSphere Software 8.0.
- From the menu bar, select File > New > Web Application Project or, alternatively, click the toolbar button labeled New Web Application Project.
- In the Create a Web Application Project wizard, enter these values:
- AcmeMembersAppWeb for Project name.
- org.acme.membership.web for Package.
- Then unselect the check box for "Use Google Web Toolkit."
- Finally, click Finish.
See Figure 3 for additional guidance on how to complete this dialog window.
Figure 3. The New Web Application Project wizard
You will now import the initial part of the Acme membership application into your newly created project.
First, we will focus on the steps required to enhance a standard Java class (POJO) to become capable of JDO persistence.
- Import the initial web project that you will build upon.
- From the menu bar, select File > Import > General > Archive File and then click Next.
- Click the Browse button and navigate to the location where you saved the file AcmeMembersAppWeb.jar and select it for import.
- Ensure the "Into folder" field is set to AcmeMembersAppWeb by clicking the Browse button, and then navigating to and selecting the project that you previously created.
- Check the box labeled Overwrite existing resources without warning.
- Click Finish. There is no need to proceed to the other pages in the Import wizard.
See Figure 4 for additional guidance on how to complete this wizard.
Figure 4. Importing the beginnings of the Acme membership application
After you have successfully imported the files, you will have a project layout, as Figure 5 shows. There will be three packages in your web project:
- org.acme.membership.domain, which holds the JDO enhanced business domain classes
- org.acme.membership.jdo, which holds a singleton JDO persistent manager factory used to retrieve JDO persistent managers
- org.acme.membership.web, which holds the servlet and other artifacts related to the web interface
Note: You will see one warning in the Problems view that you can safely ignore.
Figure 5. The project layout for the AcmeMembersAppWeb project
Enhancing a class with JDO persistence capabilities
The current version of the Google tooling for Eclipse does not offer much in the way of wizards to automatically transform a standard Java class into a JDO compliant class. Fortunately, there are only a few steps required to do this, and most of them involve using short annotations.
- Open AcmeMembership.java which can be found under AcmeMemberAppWeb > src > org.acme.membership.domain.
- Add the classes shown in Figure 6 to your import list.
Figure 6. Classes to add to the import list for a JDO-enhanced class
Once you have created your Google Web Project (AcmeMembersAppWeb), the addition of appropriate libraries and updates to the project classpath will happen automatically. The Rational Software Architect solution's Eclipse build environment will find the classes added to the import list (as shown in Figure 6).
- At the top of the class definition, add the annotation @PersistenceCapable as shown in Figure 7. This annotation instructs Google App Engine's persistence services to manage instances of this class.
Figure 7. Declaring a class to be persistence capable
- Our class will need to define an identifier to distinguish one
instance of our AcmeMembership class from another. The Google
JDO implementation has a particular Key class/type that we will use.
We will include this Key as an attribute of AcmeMembership, mark it as
a Primary Key, and specify the strategy the Google App Engine runtime
will use to populate it automatically with unique values.
- Add an attribute called id of type Key (see the import list for the fully qualified class name).
- On top of the declaration of id, add the annotation @PrimaryKey.
- Under the @PrimaryKey annotation, add another annotation as follows: @Persistent(valueStrategy = IdGenerator.IDENTITY)
- Add a getter and setter for the id attribute. For this step you can use the Quick Fix feature or you can highlight the id attribute, right click, and select Source->Generate Getters and Setters
Figure 8. Denoting an attribute as the primary key and its value population strategy
- Declare our intention to persist the remaining attributes of interest
using the annotation
@Persistent. The only attribute that we are not interested in persisting is INITIAL_FAMILY_SIZE.
- Add the annotation
@Persistenton top of the declaration for these items: acmeMembers, type, creationDate, and lastRenewed.
- Add the annotation
With nothing more than the @Persistent annotation, we were able to make a complex and diverse number of attribute types persistent, including a List (acmeMember), an enum (type), and a Date (creationDate).
The PersistenceManagerFactory and PersistentManager
To help the application generate a PersistenceManager, a JDO Application requires a class containing a singleton attribute of type PersistenceManagerFactory. A PersistentManager is required to obtain a Transaction. A JDO Transaction instance is the vehicle for carrying out a unit of work, according to the conventional definition of a transaction, against a persistence storage system (or database).
MembersAppDomainPMF (found under AcmeMemberAppWeb > src > org.acme.membership.jdo) is the class where we have placed our singleton PersistenceManagerFactory attribute.
Figure 9, which follows, shows a snippet of source code, CreateMembership.java (found under the package org.acme.membership.web) that demonstrates two things:
- How to obtain and use a transaction from a PersistenceManager.
- How to persist a (complex) object by invoking the makePersistent() method.
Figure 9. Source code for obtaining and running a JDO transaction
Run the application
Now you can run your sample Acme Membership application, which will add a single membership to the Acme membership system.
We ran our application using a locally hosted Google App Engine Web Application Server. You can also deploy, host, and run this application in the Google cloud.
- In the Package Explorer view, right-click the web application project, AcmeMembersAppWeb, and select Run As > Web Application.
Figure 10. Starting the Google App Engine test environment
- After the Google App Engine has successfully started, the console view will show an informational message indicating that the server is running (see Figure 11).
Figure 11. Console message indicating the Google App Engine test server is ready
- Launch a browser, and enter the following URL for the destination address:
- Click the link for AcmeMembersAppWeb, and it should return the output of a membership that we added to our system.
For this article, we used Rational Software Architect for WebSphere v8.0 to help rapidly design and enhance Java classes to make them "JDO-capable" and executable, using the Google App Engine as our JDO runtime implementation
Neither the relationships between our classes, nor the application logic took into consideration the characteristics or structure of an underlying persistence storage. We did not map any attributes to any relational or nonrelational database tables. Even so, by building an application with a design focused on business logic, not a pre-existing data store, we showed that how Rational Software Architect can help your team craft JDO-capable applications.
The author thanks Mike Reid for his thoughtful and thorough review of this article.
|Initial Web Application for developing||AcmeMembersAppWeb.zip||4KB|
- Read these articles for more helpful
- Google App Engine for Java, Part 1. Rev it up! Building scalable, Java-based killer apps with App Engine for Java by Richard Hightower (developerWorks, 2009)
- Google App Engine for Java, Part 2. Building the killer app: Build your own contact-management application in App Engine by Richard Hightower (developerWorks, 2009)
- Google App Engine for Java, Part 3. Persistence and relationships: Java-based persistence and the Google App Engine data store by Richard Hightower
- Java development 2.0: Gaelyk for Google App Engine. A Groovy-based framework makes rapid development on Google App Engine even faster by Andrew Glover (developerWorks, 2009)
- Java development 2.0: NoSQL, schemaless data modeling with Bigtable and Groovy's Gaelyk by Andrew Glover (developerWorks, 2010)
- Java development 2.0: Easy EC2. Quickly create a CRUD web application and run it on the Amazon Elastic Compute Cloud by Andrew Glover (developerWorks, 2009)
- Java development 2.0: Hello Google App Engine. Quick web application development leveraging Groovy, Eclipse, and JDO by Andrew Glover (developerWorks, 2009)
- Create bottom-up JPA entities with Rational Application Developer, DB2, and WebSphere Application Server by Ali Manji (developerWorks, 2010)
- Get the details:
- Visit the Rational software
area on developerWorks for technical resources and best practices
for Rational Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
- Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
Get products and technologies
- Download either or both versions for a trial:
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Join the discussion in the Rational Development Tools forum.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. You'll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website.
- Follow Rational software on Facebook and Twitter (@ibmrational), and add your comments and requests.
- Get involved in the Rational forums, groups, Rational Cafés, and Rational wikis.
- Connect with others who share your interests by joining the developerWorks community and responding to the developer-driven blogs.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.