Monday, September 1, 2008

Best Practice: Project Conventions - J2EE Web Application Development

This document gives a quick introductory article on recommended coding conventions for web application development. It is intended for people starting out with J2EE web development, and aims to provide enough detail to get started. These conventions do not cover all possible directories, files or artifacts that might be part of a project. However, it would be proven to be quite generally applicable guideline assisting every developer on how to best separate project files from files that are distributed as part of an application download.

A web application is defined as a hierarchy of directories and files in a standard layout. Such a hierarchy can be accessed in its "unpacked" form (exploded directory format), where each directory and file exists in the file system separately, or in a "packed" form known as a Web ARchive, or WAR file. The former format is more useful during development, while the latter is used when you distribute your application to be installed.

The top-level directory of your web application hierarchy is also the document root of your application. Here, you will place the HTML files and JSP pages that comprise your application's user interface. When the system administrator deploys your application into a particular server, he or she assigns a context path to your application. Thus, if the system administrator assigns your application to the context path /mywebapp, then a request URI referring to /mywebapp/index.html will retrieve the index.html file from your document root.

Standard Directory Layout

To facilitate creation of a Web Application Archive file in the required format, it is convenient to arrange the "executable" files of your web application in the same organization as required by the WAR format itself. To do this, you will end up with the following contents in your applications

* "Document root" directory - *.html, *.jsp, etc. - The HTML and JSP pages, along with other files that must be visible to the client browser (such as JavaScript, style sheet files, and images) for your application. In larger applications you may choose to divide these files into a subdirectory hierarchy, but for smaller apps, it is generally much simpler to maintain only a single directory for these files.

* /WEB-INF/web.xml - The Web Application Deployment Descriptor for your application. This is an XML file describing the servlets and other components that make up your application, along with any initialization parameters and container-managed security constraints that you want the server to enforce for you.

* /WEB-INF/classes/ - This directory contains any Java class files (and associated resources) required for a web application, including both servlet and non-servlet classes, that are not combined into JAR files. If your classes are organized into Java packages, you must reflect this in the directory hierarchy under /WEB-INF/classes/. For example, a Java class named com.mycomp.mypackage.MyServlet would need to be stored in a file named /WEB-INF/classes/com/mycomp/mypackage/MyServlet.class.

* /WEB-INF/lib/ - This directory contains JAR files that contain Java class files (and associated resources) required for your application, such as third party (external) class libraries or JDBC drivers.

Source Organization – Directory Structure

The first recommendation for building a web application would be to separate the directory hierarchy containing the source code from the directory hierarchy containing the deployable application. Maintaining these separations has the following advantages:

* Contents of the source directories can be more easily administered, moved, and backed up if the “executable” version of the application is not intermixed.

* Files that make up an installable distribution of the application are mush easier to select when the deployment hierarchy is separate.

Recommended directory structure for a web application:

/build -
Created by the build tasks and used to hold project-wide build items such as compiled source, assembled modules, or files generated by the Javadoc tool.
When deploying a Web module, consider building an unzipped view of the component to enable deployment as a directory structure directly to an application server.

/dist -
Created by the top-level ant dist task, structures under this directory represent the unzipped versions of the binary created by the project.

/docs -
Contains all the documentation for a project, including HTML files, installation and setup files, etc.

/conf -
Configuration or other set-up files, such as Web service configuration files needed by a component or module during the build process. Includes files that are placed in a module's META-INF directory. Also includes configuration files that may require processing prior to being placed in the final module.

/setup -
Contains files that are relevant to the environment for a project or application. This directory may contain database SQL files, ant files containing shared tasks, or any other files that are used to configure a container for a project or application.

/src -
Contains the java source files.

/test -
The top-level test/ directory contain project-wide tests. Each individual component or module should also include a unit test, which should be placed in the src/test directory for each component or module.

/web -
Contains the static content of the resulting WAR file.

/web/WEB-INF -
Contains the web.xml deployment descriptor and static configuration files, such as faces-config.xml. May also include vendor-specific runtime deployment descriptors, such as sun-web.xml. Generally, this directory contains files that are copied rather than changed during a build. Dynamic configuration files should be placed in the
conf/ directory.

/web/lib -
Holds specific versions of components of external libraries used by an application.
If you have multiple binaries in a project, it may be difficult for users with low bandwidth to download the application. Consider including ant targets that download the correct versions of dependent binaries at build time.

Pictorial representation for the recommended directory structure for a web application




References links

* http://java.sun.com/blueprints/code/projectconventions.html
Guidelines, Patterns, and Code for End-to-End Java Applications

No comments:

Post a Comment