Introduction:
This tutorial walks developers through a basic web application shell project, and will serve to familiarize developers with recommended web project structure. In addition, an introduction to the various web artifacts is provided.
Workshop Setup:
This step sets up the springtravel example project used for this tutorial in the workspace.
SpringTravel Application:
SpringTravel is the example application used for this tutorial. The application is a subset of a larger travel booking website. It can currently be used to search for hotels.
All of the paths referenced in this tutorial will begin with /springtravel. Paths for your projects will begin with their own project name.
Project root:
/springtravel
At the root of the springtravel project there are two key directories, src and targets. The source directory contains the files you will work with as an application developer. The targets directory is where compiled sources are prepared for deployment.
Other hidden files and directories are also at the project root. These files are used internally by Eclipse and other tools to manage project settings and preferences. Be careful modifying any of these files as it is easy to cause unintended issues with your project.
Source Directory:
/springtravel/src
Inside the project root is the src directory. This is where files go that you, as a developer, create.
There are two subdirectories, main and test. Core source files belong to main, while testing related items such as JUnit tests belong to test.
Main Source Directory:
The main directory contains core source and configuration files. All of the Java source files are placed in the java directory. Web application specific files are placed in the webapp directory.
/springtravel/src/main/java
Java source files go here. Inside this directory is the application specific package structure. For this application, the root package is com.springsource.springtravel.
Unit Tests:
/springtravel/src/test/java
No developer can write perfect code. All code contains bugs that can cause unintended side effects. It is important to test the code you write in order to minimize the number of bugs.
JUnit is a unit testing framework that helps to minimize the number of bugs. Unit tests written in Java are placed into the appropriate package structure.
The SpringTravel application has a JUnit test case, HotelsControllerTests that exercises actions provided by the HotelsController.
Webapp Source Directory:
/springtravel/src/main/webapp
The webapp directory contains web specific files. The contents of this directory will be exposed to the web. Be careful not to place files in this directory that should not be published. However, files in the WEB-INF directory are protected by the servlet container.
Static Web Resources:
/springtravel/src/main/webapp/images
/springtravel/src/main/webapp/scripts
/springtravel/src/main/webapp/styles
Even the most dynamic web applications contain static resources. Images, client side scripts and style resources are placed in these directories respectively.
Welcome File:
/springtravel/src/main/webapp/index.jsp
It is common to place a welcome file in the web root. The purpose of this file is typically to redirect users entering the application to a full fledged controller.
WEB-INF directory:
/springtravel/src/main/webapp/WEB-INF
The WEB-INF directory contains web sources that are protected from direct web access. Common protected resources include configuration files and JSP views dispatched from a controller.
Web.xml File:
/springtravel/src/main/webapp/WEB-INF/web.xml
The main configuration file for a Java web application is the web.xml file. This is the first file a servlet container uses to configure an application.
The SpringTravel web.xml file defines the Spring MVC Dispatcher Servlet mapping a URL pattern of /app/*. This will cause any web requests starting with /app/ to be routed to Spring, instead of directly mapped to resources in the webapp directory.
Also note the welcome-file is defined here, as discussed previously.
Libraries:
/springtravel/src/main/webapp/WEB-INF/lib
Web applications typically depend on many external libraries. The jars for these libraries are placed in the lib directory.
Note the Spring and Spring Web MVC jars are included here.
Many developers will choose to use a package management tool, such as Apache Maven, instead of manually including and maintaining libraries. Libraries are explicitly included here for simplicity.
Spring Configuration:
/springtravel/src/main/webapp/WEB-INF/web-application-config.xml
The Spring configuration file is also located in the WEB-INF directory. The specifics of this file will be discussed in the next tutorial.
Web Controllers:
/springtravel/src/java/com/springsource/springtravel/hotels/web/HotelsController.java
/springtravel/src/main/webapp/WEB-INF/controllers/hotels
Resources for web controllers are often split across multiple directories in the project structure. In the SpringTravel application the HotelsController is defined as a Java class. As such it is located in the appropriate Java sources directory. This controller also depends on several non Java resources to display the view back to the user. JSP files located in the appropriate WEB-INF/controllers directory are dispatched to render the view.
The HotelsController will be explained in much greater detail in the next tutorial.
Web Views:
/springtravel/src/main/webapp/WEB-INF/layouts
/springtravel/src/main/webapp/WEB-INF/controllers
Resources to render a view to the client, dispatched from the controller, are stored under two different directories under WEB-INF. The layouts directory is used to store common elements that are used by the entire application. The controllers directory has a sub directory for each controller in the application. Resources used by only that single controller are stored in the appropriate directory.
Views will be explained in much greater detail in the next tutorial.
Finish:
You should now understand the basic web application project structure. Feel free to browse the SpringTravel application to gain a fuller appreciation of a working application.
The next tutorial will go into much greater detail regarding the application specific configuration.
References:
- to download code please click here.
- https://springtravel.svn.sourceforge.net/svnroot/springtravel/springtravel/
- Spring Web Flow Reference Guide
struts2spring 