This document contains recommended conventions for structuring applications developed using Java 2 Platform, Enterprise Edition (J2EE platform) technology (hereafter referred to as J2EE applications). The J2EE 1.4 Specification (which can be downloaded from http://java.sun.com/j2ee/1.4/download.html#platformspec ) indicates that certain files, such as deployment descriptors, class files, interface files, and other files, must be present as part of an application. However, this specification does not specify a recommended or required directory structure for these files. The guidelines in this document are intended to assist developers with organizing the files and directories associated with an application in a logical fashion. Organizing your applications as shown in these guidelines will make it easier to manage and maintain a project, especially when multiple developers contribute to the same project or projects are maintained during an extended lifetime. Having a predefined, consistent, standard workspace layout saves time, especially at the onset of a project.
Following these conventions will help developers establish an overall directory structure for applications. The conventions suggest where to place different types of files generally present in an application, such as ant files, test files, compiled code, Java and non-Java source code files, portable and application server-specific deployment descriptors, utility code, binary libraries, documentation files, configuration files, Enterprise Application archive (EAR) files, Web Application archive (WAR) files, copyright and license documents, etc. They also help developers determine how to best separate project files from files that are distributed as part of an application download.
Following these conventions will also help developers package J2EE applications into EAR or WAR files because consistent project structure is helpful for proper packaging using common ant
targets.
These conventions, which the Java BluePrints team has followed with its applications (which can be accessed from http://java.sun.com/blueprints/code/index.html ), assume that developers use the Ant
tool for building projects. Developers using other build tools may have to make slight modifications to the conventions.
The guidelines and conventions discussed in this document include the following types of projects:
The following figure shows the recommended structure for projects created with J2EE technology (J2EE projects) that contain one or more applications.
|
The directories and their contents as shown in Figure 1.1: J2EE Applications: Recommended Directory Structure are explained in Table 1.1: J2EE Applications: Recommended Directory Contents .
Table 1.1 : J2EE Applications: Recommended Directory Contents
Directory Name
Directory Contents
apps/
|
|
build/
|
|
components/
|
|
conf/
|
META-INF directory. Also includes configuration files that may require processing prior to being placed in the final module.
|
dist/
|
ant
dist task, structures under this directory represent the unzipped versions of the binary created by the project.
|
docs/
|
|
lib/
|
ant targets that download the correct versions of dependent binaries at build time.
|
web/
|
|
setup/
|
ant files containing shared
ant tasks, or any other files that are used to configure a container for a project or application.
|
web/WEB-INF/
|
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.
|
test/
|
test/ directory contains 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.
|
Specific files recommended for J2EE applications are shown in Figure 1.1: J2EE Applications: Recommended Directory Structure and are described in Table 1.2: Function of Recommended Files .
Table 1.2 : Function of Recommended Files
Refer to the Java Adventure Builder Reference application at http://java.sun.com/blueprints/code/index.html#java_adventure for an example that applies this directory structure to an application.
These conventions do not cover all possible directories, files, or artifacts that might be part of a project. In particular, optional files are not covered. For example, a project might rely on a setup.xml
file, which is an ant
file that sets up Java Naming and Directory Interface (J.N.D.I.) API references, databases, database pools, or other resources needed to deploy the project.
Some artifacts may not be present in every application, but may be necessary for other applications. These artifacts should be considered on a case-by-case basis. Some of those cases that are slight variations and some of the corner cases are discussed in the following paragraphs.
For example, you may want to include a docs/
directory at locations other than those shown in Figure 1.1: J2EE Applications: Recommended Directory Structure . An EJB module or a Web module may be sufficiently complex so that developers feel it warrants having a its own docs/
directory to describe how to use it, understand it, or run its tests. Or a project may contain multiple applications, and developers may include a separate docs/
directory for each application in addition to the top level docs/
directory.
Another issue to consider is that sometimes particular artifacts can be placed in the setup/
directory within an application module. Setup directories may not be present in every project, and sometimes a project will have multiple setup/
directories. There could be a top level setup/
directory, an individual setup/
directory for each application, and/or a setup/
directory for individual component modules, if needed.
The conventions put forth in Figure 1.1: J2EE Applications: Recommended Directory Structure can also be extended to support cases not shown. For example, you can extend these conventions to the case where an application has code that is shared by several modules within just the application. If you were to write a set of utility classes to be used by more than one module and that utility is just local to that application, where would you put it? In this case, treat this utility as another module. First, create a directory under myapp1
, at the same level as myapp1-ejb
, and named something like myapp1-utility
. Next, put the utility class inside that directory. When you build your application, jar these files up and include that JAR as a module within your EAR file.
Another example of extending the conventions is to consider how to construct a simple Web application, containing only an EAR file composed of just one WAR file. The Web application follows the Web application project structure as described in Strategy for Web Applications .
Another example of extending the conventions is to consider how to construct a Web application that is an EAR file composed of multiple WAR files. What would that case look like inside this larger project structure? Each Web application follows the Web application project structure. If individual Web applications require specific environment configuration, these applications may provide a setup/
directory specific to that application. The same would be true for a docs/
, lib/
, and test/
directories. For further description on this topic, read Strategy for Web Applications .
Figure 2.1: Web Applications: Recommended Directory Structure shows a recommended structure for Web projects that use J2EE Web technologies. This is useful for projects that only build a WAR file and may not plan to include it in an EAR file, or for projects that build WAR files as modules to be included in an EAR file, as shown in Strategy for J2EE Applications .
Figure 2.1: Web Applications: Recommended Directory Structure shows the simple case for an application with a single WAR file. For more complex projects containing more than one WAR file, refer to Strategy for Reusable J2EE Components and Modules .
|
Table 2.1: Web Applications: Recommended Directory Contents explains the various directories. Table 1.2: Function of Recommended Files explains the recommended files within these directories.
Table 2.1 : Web Applications: Recommended Directory Contents
Figure 3.1: Reusable J2EE Components: Recommended Directory Structure shows the recommended directory structure for developing a component or module that is delivered as a JAR file to another application. These conventions will help while designing and developing a reuseable component. Examples of such reusable components and modules include a Web framework (such as struts), a set of enterprise beans, a set of JavaServer Pages (JSP) tags, or an applet.
Figure 3.1 : Reusable J2EE Components: Recommended Directory Structure
|
The directory structure is shown in Table 3.1: Reusable J2EE Components: Recommended Directory Contents , and the files within the directories are shown in Table 1.2: Function of Recommended Files .
Table 3.1 : Reusable J2EE Components: Recommended Directory Contents
Refer to the Java Adventure Builder Reference application at http://java.sun.com/blueprints/code/index.html#java_adventure for an example that uses this form of the directory structure.
We welcome your feedback on this document and its contents. You can use either of the following methods for providing feedback to us: