C H A P T E R 2

Getting Started

This chapter outlines the mechanics of using the Web Application Framework tools to build a J2EE web application.

This chapter contains the following topics:

Introduction

Writing Web Application Framework Applications

About the Web Application Framework Tutorial

Introduction

This document introduces developers to the mechanics and techniques used to build Web applications with the Web Application Framework tools.

It is intended for developers who are at least somewhat familiar with building web applications using existing J2EE web technologies (servlets and JSP pages), but new to building web applications using the Web Application Framework.

This document assumes Java expertise and familiarity with the development and deployment procedures for the specific servlet container and development tools being used.

Because the Web Application Framework is foremost a design pattern and a set of interfaces, the examples in this document show only the most basic way of creating a Web Application Framework application, by extending existing Web Application Framework implementation base classes and manually constructing certain application objects. This is only one possible way to create a Web Application Framework application.

There are two reasons for not showing more advanced techniques in this document. First, starting at a fundamental level is the most direct way to impart how the Web Application Framework works to someone new to the framework. Being able to see exactly how the framework interacts with the application is critical to getting the most out of the Web Application Framework.

Second, building an application using these fundamental techniques is a prerequisite to fully understanding the many possible ways to build Web Application Framework applications. Features that extend the Web Application Framework to add additional capabilities are built on the techniques demonstrated in this document. After understanding these basic examples, you have a greater understanding of how these features extend and complement the Web Application Framework core, and you are able to optionally decide not to use them and instead construct your own Web Application Framework extensions (or simply fall back to a more basic approach where necessary).

The ultimate goal of this document then is to introduce developers to the most fundamental way to build Web Application Framework applications, so they become familiar with Web Application Framework's interactions with applications built on top of the framework, and more fluent in the Web Application Framework itself.

Writing Web Application Framework Applications

Writing a Web Application Framework application consists of first laying out an application structure, and incrementally adding Web Application Framework objects to that structure. Although this can be done entirely by hand and from scratch, the task has been simplified by creating the Web Application Framework tools module for the Sun Java Studio Enterprise 7 that assists developers in writing their Web Application Framework applications. With the assistance of these tools, creating a Web Application Framework application becomes a simple process of generating Web Application Framework components using wizards, and customizing them to an application.

Before demonstrating the creation of a simple Web Application Framework application, you will cover the basics of how a Web Application Framework application is structured.

J2EE/Web Application Framework Terminology

There are terms in this document such as application, module, and components. These terms can be confusing, because they are also used in more general Web architecture and development discussions.

The following table contains a list of the most important terms found in this tutorial.

Term	Description
*J2EE component	Sometimes referred to as J2EE application components; concrete software components which are deployed, managed, and executed on a J2EE server including EJBs, Servlets, and Java Server PagesTM (JSPTM); there are components including HTML and Applets which are also J2EE components but these are not relevant to the Web Application Framework Web application discussion.
*J2EE module	Represents the basic unit of composition of a J2EE application. A J2EE module consists of one or more J2EE components and one component-level deployment descriptor. J2EE modules can be deployed as stand-alone units or can be assembled with a J2EE application deployment descriptor and deployed as a J2EE application. Servlet and/or JSP components are packaged as a J2EE module and deployed as a WAR file. EJB components are packaged as a J2EE module and deployed as a JAR file. An arbitrary number or WAR files and JAR files may be combined to form a J2EE application and deployed as an EAR file. WAR files (J2EE modules which are also known as J2EE Web applications) may be deployed stand-alone on a J2EE server.
*J2EE Web application	Stand-alone J2EE modules containing J2EE components deployable in a J2EE servlet container (Web application container). Depending on the context of the term application or J2EE application, the intent may be to refer to a J2EE Web application. There are products such as the Sun Java System Application Server Standard Edition 7 2004Q2 and Apache Tomcat that support J2EE Web applications, in that they can manage J2EE modules consisting of Servlets and JSPs, but they cannot manage a complete J2EE application which may have EJB J2EE modules.
*J2EE application	Consists of one or more J2EE modules and one J2EE application deployment descriptor, packaged using the Java archive (JAR) file format into a file with a `.ear` (enterprise archive) filename extension.
Web Application Framework module	Refers to both a logical and physical partition of content and components within a Web Application Framework application (not to be confused with a J2EE module).
Web Application Framework application	In informal terms, a Web Application Framework application is a J2EE web application that has been written using the Web Application Framework. It consists of at least one J2EE module (the Web application), but may also include other standard J2EE components or modules. A minimal Web Application Framework application is a J2EE web application consisting of one WAR file. In formal terms, a Web Application Framework application is a collection of related Web Application Framework modules, all running in the same servlet context. In this sense, Web Application Framework application refers only to this logical Web Application Framework abstraction.

* Refer to the Java 2 Platform Enterprise Edition Specification v1.2 (J2EE) section J2EE8.1 for a detailed explanation of this term.

How Web Application Framework Applications Are Organized

The Web Application Framework provides formal application and module entities. A Web Application Framework application is a base Java package that contains one or more sub-packages (Web Application Framework modules). It is perfectly acceptable for an application to consist of only one module, and it is likely be the common situation for smaller applications. Each module inherits behavior from its parent application-level components, and might also customize this behavior separately from other modules.

In J2EE web application container terms, a Web Application Framework application corresponds one-to-one with a servlet context, and thus is subject to the constraints enforced by the container for servlet contexts.

Before starting to develop your application, you should first decide how it should be organized:

Determine which modules will be grouped together into your Web Application Framework application.

Avoid over-categorizing your application into several modules simply because the Web Application Framework provides this capability. In many cases, one module is sufficient.

Decide on an application package name.

The application package name can be arbitrarily complex and will likely reflect your organization's packaging strategy. Each of your modules becomes a package beneath this application package.

Assign a deployment-time or published Web application name.

In Apache Tomcat, the directory immediately beneath the /webapps directory would bear this name. In the Sun Java System Application Server, the directory immediately beneath the $instance_dir/applications/j2ee-modules directory would bear this name. The deployed application name is the same as the name WAR file name.

For example, if you have two Application Framework modules (named module1 and module2) that comprise a Web Application Framework application, you would call this application myapp. The full application package name would be com.mycompany.myapp.

The application package would be com.mycompany.myapp

The module1 package would be com.mycompany.myapp.module1

The module2 package would be com.mycompany.myapp.module2

In general, the application package name should be different from that of any of its modules.

For example, your first instinct might be to name both your application and its primary module foo. This can easily lead to confusion for someone trying to understand your application and your application development tools. Instead, consider naming the application package something like fooapp, or calling the primary module something like main or module1. This makes your application structure much easier to understand, especially when you add to it in the future.

About the Web Application Framework Tutorial

You will now develop a simple application so you can experience using the Web Application Framework and its tools. This application consists of two pages: a login page, and a customer account page, and demonstrates the following:

Retrieving field values submitted by the user.

Returning a status message to the user.

Using a QueryModel to retrieve customer information.

Using a QueryModel to update customer information.

Coordinating user input with QueryModel SQL WHERE criteria.

Moving from one page to another.

Using a WebServiceModel to perform a Google Internet search.

Displaying the multiple search results of a WebServiceModel.

This tutorial is divided into sections and tasks the steps required to develop the application. Each section addresses a broad topic, at the end of which you have an application that you can run.

Each task within a chapter is a relatively self-contained topic and contains several more detailed steps.