This tutorial is a guide to developing enterprise applications for the Java Platform, Enterprise Edition 5 (Java EE 5). Here we cover all the things you need to know to make the best use of this tutorial.
Who Should Use This Tutorial
This tutorial is intended for programmers who are interested in developing and deploying Java EE 5 applications on the Sun Java System Application Server Platform Edition 9.
Before proceeding with this tutorial, you should have a good knowledge of the Java programming language. A good way to get to that point is to work through The Java™ Tutorial, Fourth Edition, Sharon Zakhour et al. (Addison-Wesley, 2006). You should also be familiar with the relational database features described in JDBC API Tutorial and Reference, Third Edition, Maydene Fisher et al. (Addison-Wesley, 2003).
How to Read This Tutorial
The Java EE 5 platform is quite large, and this tutorial reflects this. However, you don't have to digest everything in it at once. The tutorial has been divided into parts to help you navigate the content more easily.
This tutorial opens with an introductory chapter, which you should read before proceeding to any specific technology area. Chapter 1 covers the Java EE 5 platform architecture and APIs along with the Sun Java System Application Server Platform Edition 9.
When you have digested the basics, you can delve into one or more of the five main technology areas listed next. Because there are dependencies between some of the chapters, Figure 1 contains a roadmap for navigating through the tutorial.
Figure 1. Roadmap to This Tutorial
After you have become familiar with some of the technology areas, you are ready to tackle the case studies, which tie together several of the technologies discussed in the tutorial. The Coffee Break Application describes an application that uses the web application and web services APIs. The Duke's Bank Application describes an application that employs web application technologies, enterprise beans, and the Java Persistence API.
Finally, the appendix contains information about Java encoding schemes that may be helpful to the Java EE 5 application developer.
About the Examples
This section tells you everything you need to know to install, build, and run the examples.
The following software is required to run the examples.
The tutorial example source is contained in the tutorial bundle. If you are viewing this online, you need to click on the Download link at the top of any page.
After you have installed the tutorial bundle, the example source code is in the <INSTALL>/javaeetutorial5/examples/ directory, with subdirectories for each of the technologies discussed in the tutorial.
The Sun Java System Application Server Platform Edition 9 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run the examples, you need a copy of the Application Server and Java 2 Platform, Standard Edition 5.0 (J2SE 5.0). If you already have a copy of the J2SE SDK, you can download the Application Server from:
You can also download the Java EE 5 SDKwhich contains the Application Server and the J2SE SDKfrom the same site.
Application Server Installation Tips
In the Admin configuration pane of the Application Server installer:
In the Installation Options pane, check the Add Bin Directory to PATH checkbox so that Application Server scripts (asadmin, wsimport, wsgen, xjc, and schemagen) override other installations.
The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise applications. NetBeans 5.5 supports the Java EE 5 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans 5.5, which you can download at http://www.netbeans.org/downloads/index.html. For information on creating enterprise applications in NetBeans 5.5, see http://www.netbeans.org/kb/55/index.html.
Ant is a Java technology-based build tool developed by the Apache Software Foundation (http://ant.apache.org), and is used to build, package, and deploy the tutorial examples. Ant is included with the Application Server. To use the ant command, add <JAVAEE_HOME>/lib/ant/bin to your PATH environment variable.
You need a registry server to run the examples discussed in Chapter 19. Instructions for obtaining and setting up a registry server are provided in Chapter 19.
Building the Examples
The tutorial examples are distributed with a configuration file for either NetBeans 5.5 or Ant. Directions for building the examples are provided in each chapter. Either NetBeans 5.5 or Ant may be used to build, package, deploy, and run the examples.
Building the Examples Using NetBeans 5.5
To run the tutorial examples in NetBeans 5.5, you must register your Application Server installation as a NetBeans Server Instance. Follow these instructions to register the Application Server in NetBeans 5.5.
Building the Examples on the Command-Line Using Ant
Build properties common to all the examples are specified in the build.properties file in the <INSTALL>/javaeetutorial5/examples/bp-project/ directory. You must create this file before you can run the examples. We've included a sample file, build.properties.sample, that you should rename to build.properties and edit to reflect your environment. The tutorial examples use the Java BluePrints (http://java.sun.com/reference/blueprints/) build system and application layout structure.
To run the Ant scripts, you must set common build properties in the file <INSTALL>/javaeetutorial5/examples/bp-project/build.properties as follows:
Tutorial Example Directory Structure
To facilitate iterative development and keep application source separate from compiled files, the tutorial examples use the Java BluePrints application directory structure.
Each application module has the following structure:
Examples that have multiple application modules packaged into an enterprise application archive (or EAR) have submodule directories that use the following naming conventions:
The Ant build files (build.xml) distributed with the examples contain targets to create a build subdirectory and to copy and compile files into that directory; a dist subdirectory, which holds the packaged module file; and a client-jar directory, which holds the retrieved application client JAR.
This tutorial includes the basic information that you need to deploy applications on and administer the Application Server.
See the Sun Java™ System Application Server Platform Edition 9 Developer's Guide at http://docs.sun.com/doc/819-3659 for information about developer features of the Application Server.
See the Sun Java™ System Application Server Platform Edition 9 Administration Guide at http://docs.sun.com/doc/819-3658 for information about administering the Application Server.
For information about the Java DB database included with the Application Server see the Apache web site at http://db.apache.org/derby.
Table 1 lists the typographical conventions used in this tutorial.
Menu selections indicated with the right-arrow character , for example, FirstSecond, should be interpreted as: select the First menu, then choose Second from the First submenu.
The Java EE tutorial team would like to thank the Java EE specification leads: Bill Shannon, Linda DeMichiel, Sekhar Vajjhala, Jan Luehe, Gregory Murray, Arun Gupta, Doug Kohlert, Ed Burns, V B Kumar Jayanti, Binod P. G., Sankara Rao, Dhiru Pandey, Rajiv Mordani, Farrukh Najmi, and Ron Monzillo. We would also like to thank the Java EE 5 SDK team members: Anil Gaur, Tony Ng, Inderjeet Singh, Carla Carlson, Nazrul Islam, Jerome Dochez, Jean-Francois Arcand, Chinmay Mehta, Suveen Nadipalli, Vipin Rajan, and Chinmayee Srivathsa.
The chapters on custom tags and the Coffee Break and Duke's Bank applications use a template tag library that first appeared in Designing Enterprise Applications with the J2EE™ Platform, Second Edition, Inderjeet Singh et al., (Addison-Wesley, 2002).
The JavaServer Faces technology and JSP Documents chapters benefited greatly from the invaluable documentation reviews and example code contributions of these engineers: Ed Burns, Roger Kitain, Jan Luehe, Craig McClanahan, and especially Ryan Lubke and Jayashri Visvanathan.
The EJB technology and Java Persistence API chapters were written with extensive input from Sun's EJB and Persistence teams. We'd like to thank Marina Vatkina, Ken Saks, Geoff Halliwell, Shelly MacGowan, Linda DeMichiel, Markus Fuchs, Rochelle Raccah, Lance Andersen, Vince Kraemer, Michael Bouschen, and Tim Quinn for their contributions to the material and code examples.
The security, JAXB, and StAX chapter writers greatly appreciate the input of Raja Perumal, Joseph Fialli, Ryan Shoemaker, Kohsuke Kawaguchi, Rebecca Searls, and Neeraj Bajaj, who were a key contributors both to the chapters and to the examples.
We'd like to thank the NetBeans engineering and documentation teams, particularly Petr Jiricka, Jan Chalupa, Ludovic Champenois, Petr Blaha, Peter Williams, Geertjan Wielenga, Jesse Glick, Tomasz Slota, John Jullion-Ceccarelli, and Patrick Keegan, for their help in enabling NetBeans support for the code examples.
Stephanie Bodoff and Dale Green contributed much content to the first and second editions of The J2EE Tutorial, and much of that content has been carried forward to the current edition.
We are extremely grateful to the many internal and external reviewers who provided feedback on the tutorial. Their feedback helped improve the technical accuracy and presentation of the chapters and eliminate bugs from the examples.
We would like to thank our manager, Alan Sommerer, for his support and steadying influence.
We also thank Dwayne Wolff for developing and updating the illustrations in record time and our editor, Julie Bettis, for improving the readability and flow of the book. Thanks are also due to our copy editor, Hartley Ferguson, for helping this multiauthor project achieve a common style.
Finally, we would like to express our profound appreciation to Greg Doench, Elizabeth Ryan, and the production team at Addison-Wesley for graciously seeing our large, complicated manuscript to publication.
To send comments, broken link reports, errors, suggestions, and questions about this tutorial to the tutorial team, please use the feedback form at http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html.