5.11. Documenting Web Applications

More and more development environments are starting to provide explicit support for servlets and JSP. Examples include Borland JBuilder Enterprise Edition, Macromedia UltraDev, Allaire JRun Studio, and IBM VisualAge for Java.

A number of the web.xml elements are designed not for the server, but for the visual development environment. These include icon, display-name, and description.

Recall that it is important to declare the web-app subelements in the proper order within web.xml. Section 5.2 (The Order of Elements within the Deployment Descriptor) gives complete details on the required ordering. For now, however, just remember that icon, display-name, and description are the first three legal elements within the web-app element of web.xml.

icon

The icon element designates the location of either one or two image files that the GUI tool can use to represent the Web application. A 16 × 1 6 GIF or JPEG image can be specified with the small-icon element, and a 32 × 32 image can be specified with large-icon. Here is an example:

<icon> 
  <small-icon>/images/small-book.gif</small-icon> 
  <large-icon>/images/tome.jpg</large-icon> 
</icon> 

display-name

The display-name element provides a name that the GUI tools might use to label this particular Web application. Here is an example.

<display-name>Rare Books</display-name> 

description

The description element provides explanatory text, as below.

<description> 
This Web application represents the store developed for 
rare-books.com, an online bookstore specializing in rare 
and limited-edition books. 
</description>