A Java Web application project typically consists of Java source files, XML configuration files, JSP files, and Web assets, such as HTML and image files. Using a consistent directory structure for all your Java Web application projects helps speed development by separating these various pieces into well-known areas. It also helps you reuse Ant build files by allowing you to put common, generic paths into your build files and separating out project-specific settings into a properties file that the build file can import.

The Web application projects in this book all use a consistent directory structure. Some projects may have pieces that others don't, but they all share a few basic pieces. Figure 6.2 shows the project directory structure for the simple Web application you write in this chapter. This structure is created for you by Eclipse when you start developing your Web application.

Typically, the top-level directory has the same name as your application. Below this directory, there are three other directories:

Figure 6.2. A typical Java Web application directory structure contains folders for Java source code, Web application code, and compiled Java class files. Using a standardized directory structure is a best practice when developing a Java Web application.

Now that you've seen what the directory structure for a Java Web application project looks like, you can set up a project in Eclipse.

Although you can create this directory structure on your own, because you're using the Eclipse IDE, you can let Eclipse set up this directory structure for you by creating a new project in Eclipse. Eclipse creates much of the necessary directory structure by using a wizard. Once the project has been created, you can add any other needed folders and files as necessary within the Eclipse environment.

To create a new project in Eclipse, follow these steps:

In the New Spring Project dialog box, the default values in the Source Folder Name and Output Folder Name text fields are src and bin, respectively. These names match the names discussed in the previous section. Eclipse creates these directories for you when you create a new project, and Eclipse can also automatically compile the Java code in the src directory and then output the compiled Java class files to the bin directory as you work.

Figure 6.3. The New Project dialog box in Eclipse is the first step in creating a new project. Eclipse supports many different types of projects out of the box, and you can add more types by using plug-ins.

Take a few minutes to explore the newly created project. Click the arrow to the left of the project name in the Project Explorer view to expand the project, as shown in Figure 6.5.

When you create a new Spring project in Eclipse, it adds a few elements to the project automatically:

Even though the New Spring Project dialog box contains an item for an output folder named bin, this item doesn't appear in the expanded project. This is because Java class files are binary and won't ever be edited.

Figure 6.4. The New Spring Project dialog box contains settings for creating a new Spring project. The default values conform to standard Spring project development practices and shouldn't be changed for most applications.

Figure 6.5. Eclipse automatically adds a few necessary elements to newly created projects.

Before diving into coding, you have some project configuration steps to do. Once the project has been configured, you can write, compile, deploy, and test your first application.

To configure the Eclipse project, follow these steps in Eclipse:

Figure 6.12. Click the spring.jar and spring-webmvc.jar libraries to be imported from the dist and distmodules folders, respectively, under the extracted Spring Framework folder.

Although you added the Spring libraries to your project, Eclipse doesn't use them to compile your Java code unless you explicitly configure it to do so. Eclipse uses a setting called the Java Build Path to tell it where Java source code is kept, where Java class files should be output, and where libraries needed to compile the Java source code into Java class files can be found. The Java Build Path in Eclipse is essentially the same as the classpath that needs to be set when compiling Java classes manually by using the JDK's Java compiler. You need to configure this setting next.

Figure 6.13. Choose the jstl.jar library to be imported from the libj2ee folder under the extracted Spring Framework folder.

Figure 6.14. Choose the standard.jar library to be imported from the libjakarta-taglibs folder under the extracted Spring Framework folder.

Figure 6.15. After you drag the library JAR files from their subfolders into the webWEB-INFlib folder and then delete the emptied subfolders, the Project Explorer view should look like this.

To configure the Java Build Path for your project, follow these steps:

Figure 6.17. The JRE System Library from your installed JDK is automatically added to the JAR files and class folders list in the Library tab.

Figure 6.18. Click the jstl.jar, spring-webmvc.jar, spring.jar, and standard.jar files in the JAR Selection dialog box to add them to the build library path for your project.

Figure 6.19. The JAR files now appear in the build library path.

Figure 6.20. The servlet-api.jar is added to the build library path. The entry shows the full path to the JAR on your computer. This indicates that the JAR file hasn't been copied into the project but instead is referenced externally.

Now that the Eclipse project has been configured, it's time to start writing the application. Using the Spring Framework Web MVC module, this application follows the Model-View-Controller (MVC) pattern. Here's how the pieces of the application fit into the pattern:

The Model and Controller

Spring's Controller interface contains a single method, handleRequest, that receives requests from the user interface and responds with the requested data. Eclipse can create the stub of a controller for you by using a wizard.

In Java development, classes are divided into smaller groups of related functionality called packages. Packages for Web applications are typically named following a pattern that describes the company or organization the code is being written for, the specific project the code is part of, and what functionality the code provides. For example, the application in this chapter uses the package com.wiley.jfib.ch06.helloworld.service for the controller. Controllers are often referred to as services, as they service the requests of clients.

Note

For more on packages and other Java concepts, see Chapter 1.

To create the controller class, follow these steps:

1. Right-click the src folder of your project in the Project Explorer view and then choose New

   
   Package from the popup menu. The New Java Package dialog box opens.

2. Type com.wiley.jfib.ch06.helloworld.service in the Name text field, as shown in Figure 6.21, and then click Finish. The new package appears under the project's src folder in the Project Explorer, as shown in Figure 6.22.

3. Right-click the newly created package and then choose New

   
   Class from the popup menu. The New Java Class dialog box, as shown in Figure 6.23, opens. The Source folder and Package text fields are already filled in for you with the correct values.

4. Type HelloWorldService in the Name text field.

   

   Figure 6.21. Type the package name in the Name text field of the New Java Package dialog box.

   

   Figure 6.22. The newly created package appears under the src folder of your project in the Project Explorer view.

   

   Figure 6.23. The New Java Class dialog box, with the Source folder and Package text fields already filled in with the correct values

5. Click the Add button next to the Interfaces list box. The Implemented Interfaces Selection dialog box opens.

6. Type Controller in the Choose interfaces text field. As you type, the Matching items list box fills in potential matches, as shown in Figure 6.24.

7. Choose Controller - org.springframework.web.servlet.mvc from the list box and then click OK. The Implemented Interfaces Selection dialog box closes, and the Controller interface is added to the Interfaces list box in the New Java Class dialog box, as shown in Figure 6.25.

8. Click the Generate comments check box and then click Finish. The New Java Class dialog box closes, and the newly created HelloWorldService class opens in the editor, as shown in Figure 6.26.

Figure 6.24. As you type in the Choose interfaces text field of the Implemented Interfaces Selection dialog box, the Matching items list begins to fill in with interfaces that match what you type.

It's worth taking a look at the various pieces of this Java class before moving on. It may help you to display the line numbers for the file to make it easier to follow along. To show the line numbers, right-click the left margin of the editor and then choose Show Line Numbers from the popup menu. The line numbers appear in the left margin of the editor.

Eclipse also has a feature called folding, which allows you to expand or collapse sections of the file, such as import statements, comment blocks, and code blocks. This feature makes working with large Java files easier. When you're interested in only one particular piece of code, you can use folding to collapse the rest. Folded blocks of code have a small + button next to them, which can be clicked to expand them. Expanded blocks can be folded again by clicking the small – button next to them. In this case, being able to see all the code in this small file is more useful for walking through the various pieces. You can quickly expand all folded sections in a Java file by right-clicking the left margin of the editor again and then choosing Folding

Figure 6.25. After you select an interface in the Implemented Interfaces Selection dialog box, it appears in the Interfaces list box in the New Java Class dialog box. A Java class can have multiple interfaces.

Figure 6.26. Once you've finished with the New Java Class dialog box, the newly created Java class stub is opened in the editor.

Line 4 of the HelloWorldService Java class is the package statement, which lets Java know what package the class is in. Lines 6 through 10 are import statements. Import statements are used to inform this class of the locations of other classes it needs. On its own, a class has access only to other classes in the same package and any classes in the standard java.lang package that's part of the JDK. For HelloWorldService, four other classes are also needed:

• javax.servlet.HttpServletRequest. This class represents the request coming from an HTTP client, such as a Web browser, to the server. It contains information about the client's locale, any cookies relevant to the application, authentication information, and other information the server may need to know about the client. An instance of this class is passed as a parameter to HelloWorldService's handleRequest method.

• javax.servlet.HttpServletResponse. This class represents the response going from the server to the HTTP client. This typically includes things that a Web browser might need to know, such as server status codes and HTTP headers. An instance of this class is passed as a parameter to HelloWorldService's handleRequest method.

• org.springframework.web.servlet.ModelAndView. This class is a convenient container for both the model data packaged up for use by the view and a reference to the view itself. An instance of this class is returned by HelloWorldService's handleRequest method.

• org.springframework.web.servlet.mvc.Controller. This interface is implemented by HelloWorldService.

Line 16 is the class declaration. The class declaration contains the name of the class, the name of the class it extends (optional), and the names of any interfaces it implements (optional). Extending a class means adding functionality to or modifying functionality in an existing class. When a Java class extends another class, it has access to all the public member variables and methods in the extended class and can override those public methods with its own implementations. Unless otherwise specified, all Java classes extend the Object class in the java.lang package. HelloWorldService extends Object, so there's no extends statement in the class declaration. An interface in Java is a set of one or more methods without implementations. When a Java class implements an interface, it's then required to provide an implementation for any methods in the interface. In this example, HelloWorldService implements the Controller interface from the org.springframework.web.servlet.mvc package. The Controller interface has one method: handleRequest. Because HelloWorldService implements Controller, it needs to provide an implementation for the handleRequest method. Eclipse provides a default implementation of handleRequest when it generates the stub class file.

Note

For more on Java syntax, see Chapter 1.

You can now change the default implementation of handleRequest with code that returns a "Hello, World!" message to the client. To do this, you change the handleRequest method so that it looks like this:

/* (non-Javadoc)
 * @see org.springframework.web.servlet.mvc.
   Controller#handleRequest(javax.servlet.http.HttpServletRequest,
   javax.servlet.http.HttpServletResponse)
 */
@Override
public ModelAndView handleRequest(HttpServletRequest arg0,
          HttpServletResponse arg1) throws Exception {
     // the message for the client
     return new ModelAndView("WEB-INF/jsp/hello-world.jsp",
          "message","Hello, World!");
}

The Spring Web MVC module's ModelAndView object holds both the model and the view and allows the controller to return both at once. The constructor used here for the ModelAndView object has three parameters. The first parameter is the location of the view. The view for HelloWorldService is a JSP page named hello-world.jsp located in the WEB-INF/jsp folder. The second parameter is the name of the model. The view uses this name to retrieve the model. The model for this request is named message. The final parameter is the model itself. The data being returned to the client in this case is the string "Hello, World!"

The View

Now that you've got a controller that can handle a request and return data, you need to create the view that displays the data. For this example, you write a simple JSP page to act as the view.

To create the JSP page for the view, follow these steps:

1. Right-click the web/WEB-INF folder in the Project Explorer view and then choose New

   
   Folder from the popup menu. The New Folder dialog box opens.

2. Type jsp in the Folder name text field and then click Finish. The New Folder dialog box closes, and the newly created folder appears below the WEB-INF folder in the Project Explorer view.

3. Right-click the web/WEB-INF/jsp folder in the Project Explorer view and then choose New

   
   Other from the popup menu. The Select a wizard dialog box opens.

4. Click the arrow next to Web to expand it, click JSP, and then click Next. The New JavaServer Page wizard, as shown in Figure 6.27, opens.

5. Type hello-world.jsp in the File name text field and then click Next. The Select JSP Template screen, as shown in Figure 6.28, opens.

   

   Figure 6.27. The first screen of the New JavaServer Page wizard is where you give the JSP file a name.

   

   Figure 6.28. The second screen of the New JavaServer Page wizard allows you to choose a template for your JSP. Templates include many of the required HTML tags and JSP directives, allowing you to concentrate on filling in the details.

6. Click New JSP File (xhtml) in the JSP template list and then click Finish. The New JavaServer Page wizard closes, and the newly created JSP is opened in the editor, as shown in Figure 6.29.

A JSP is basically just a regular HTML or XHTML file with a few special tags that have meaning to the server. When a JSP is requested, the server actually compiles the JSP into a Java class file in much the same way that a regular Java file is compiled. The code in the compiled JSP then outputs HTML or XHTML to a browser to be displayed.

Take a look at lines 2 and 3 of the hello-world.jsp file. These lines are referred to as a JSP directive. A JSP directive is a special tag that begins with the characters <%@. There are many types of JSP directives. This one is called a page directive, which tells the server what language the code on the page is written in (java, in this case), what the returned content MIME type is (text/html), and the character set used by the page (ISO-8859-1). Page directives can also be used to import Java classes into the page, much like the import statement in a Java file.

Now that you have a JSP stub, you need to get your model data into it and display it. You do that by adding some more JSP directives to the page to retrieve the data and then another to output it in the page.

Figure 6.29. After you complete the New JavaServer Page wizard, the newly created JSP appears in the editor. The template chosen in the last step of the wizard provides the basic HTML tags and JSP directives, allowing you to concentrate on filling in the details.

Add the following line of code immediately after the page directive in the JSP file:

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

This is a tag library (taglib) directive. A tag library is a set of custom tags that provides extended functionality to JSP pages outside the built-in functionality. This example uses the Java Server Pages Standard Tag Library (JSTL) to add tags that allow you to access and output data in the model more easily. The prefix attribute of the taglib directive specifies the namespace prefix that the tag libraries' tags use. This is necessary because different tag libraries might include tags with the same name. The prefix ensures that the server knows which tag library a given tag belongs to. This JSP uses the prefix c to identify tags contained in the JSTL tag library. The uri attribute tells the server where the description of the tag library can be found. The server uses this description to validate that tags used in the JSP follow the correct syntax. The code for the JSTL tag library itself is contained in the jstl.jar file you previously imported into the project. The JAR file needs to be deployed to the server with the application in order for the JSTL tag libraries to be available to the application at runtime.

Change the text in the title tag to something more descriptive than Insert title here and then add this line of code to the empty space between the start and end <body> tags:

<c:out value="${message}"/>

The c prefix indicates that this is a tag from the JSTL tag library: the out tag. The out tag simply outputs the contents of its value attribute to the JSP. The value attribute of this tag is a variable reference to a variable named message. A variable reference contains the name of some variable surrounded by ${}. Notice that message is also the name you gave your model in the HelloWorldService controller. This tag reads the value of message from the model and then outputs its value to the JSP view.

Wiring the pieces together

You now have a controller that provides model data to a JSP view. To get everything working together, you need to create and edit some configuration files.

The first configuration file is web.xml. This file is the application descriptor file used by all Java Web applications. Among other things, web.xml contains entries for any Java servlets in the Web application and the URL patterns that map to those servlets.

In standard Spring Web MVC applications, you generally don't need to write servlets yourself. Spring provides a servlet, the DispatcherServlet, that receives incoming requests and passes those along to the appropriate controller. The controllers do the work of gathering the data into the model and then packaging it up for the view.

The Spring DispatcherServlet is configured in web.xml. The controllers are configured in one or more Spring configuration files. These are additional XML files that provide definitions for the controller classes and URL mappings that tell the DispatcherServlet which controller is responsible for which URL.

To create the web.xml configuration file, follow these steps:

1. Right-click the web/WEB-INF/ folder in the Project Explorer view and then choose New

   
   Other from the popup menu. The Select a wizard dialog box opens.

2. Click the arrow next to XML to expand it, click XML in the submenu, and then click Next. The New XML File wizard, as shown in Figure 6.30, opens.

3. Type web.xml in the File name text field and then click Next. The Create XML File From screen, as shown in Figure 6.31, opens.

4. Click the Create XML file from an XML template radio button and then click Next. The Select XML Template screen, as shown in Figure 6.32, opens.

5. Click the xml declaration template in the list and then click Finish. The New XML File wizard closes, and the newly created web.xml file opens in the editor.

The XML schema definition for web.xml can be found online at http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd. There are a number of tags and attributes that can be found in a web.xml file, too numerous to go through in their entirety here. For the HelloWorld application, only the following basic structure is required:

<web-app>
     <servlet>
          <servlet-name></servlet-name>
          <servlet-class></servlet-class>
          <load-on-startup></load-on-startup>
     </servlet>
     <servlet-mapping>
          <servlet-name></servlet-name>
          <url-pattern></url-pattern>
     </servlet-mapping>
</web-app>

Figure 6.30. The first screen of the New XML File wizard is where you give the XML file a name.

Figure 6.31. The second screen of the New XML File Wizard allows you to create a new XML file from a template.

The <web-app> tag is the topmost tag of the web.xml file and is required. It has attributes for the Web application version and the XML schema definition location. The <web-app> tag contains two child tags:

• The <servlet> tag contains child tags that define the servlet name, Java class, and whether the servlet should be loaded when the server starts up.

• The <servlet-mapping> tag contains child tags that map a servlet name to a URL pattern.

Figure 6.32. The Select XML Template screen allows you to choose an XML template.

The entire web.xml file for the HelloWorld application is shown in the listing below. Add this code to the web.xml file in your project and then save the file:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
 xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
 http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" >
 <servlet>
 <servlet-name>spring-dispatcher</servlet-name>
 <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
 <load-on-startup>1</load-on-startup>
 </servlet>

 <servlet-mapping>
 <servlet-name>spring-dispatcher</servlet-name>
 <url-pattern>*.htm</url-pattern>
 </servlet-mapping>
</web-app>

One servlet is being defined in the <servlet> tag, and that servlet is being mapped to a single URL pattern in the <servlet-mapping> tag. The servlet is named spring-dispatcher and is a Spring DispatcherServlet. The servlet is mapped to the URL pattern *.htm. This pattern matches any incoming server request that ends in .htm. Wildcard characters such as * are allowed in mappings, and you can make a mapping as general or as specific as necessary for your application. For the HelloWorld application, all requests ending in .htm go through the DispatcherServlet. It's possible to simply use * for the URL pattern. However, mapping specific suffixes to specific servlets makes adding more servlets easier.

Now that configuration of the DispatcherServlet in web.xml is complete, you need a Spring beans configuration file to tell the DispatcherServlet which requests to map to your controller. Follow the same steps you just used to create web.xml to create another XML file in the webWEB-INF directory. Name the file spring-dispatcher-servlet.xml. This file derives its name from the value of the <servlet-name> tag for the DispatcherServlet in web.xml, followed by –servlet.xml.

The XML schema definition for the Spring beans configuration file can be found at www.springframework.org/schema/beans/spring-beans-2.5.xsd. As with web.xml, there are too many tags and attributes to fully cover here. For the HelloWorld application, only the following basic structure is required:

<beans>
     <bean></bean>
</beans>

The <beans> tag is the topmost tag of the spring-dispatcher-servlet.xml file and is required. It has attributes for the XML schema definition location. The <beans> tag contains one <bean> tag for each controller to be mapped to a URL. The name attribute maps to the URL the controller should handle, and the class attribute maps to the controller Java class.

The entire spring-dispatcher-servlet.xml file for the HelloWorld application is shown in the following listing. Add this code to the spring-dispatcher-servlet.xml file in your project and then save the file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.springframework.org/schema/beans
 http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
     <bean name="/hello-world.htm"
     class="com.wiley.jfib.ch06.helloworld.service.HelloWorldService"/>
</beans>

In this file, the HelloWorldService class is mapped to the URL /hello-world.htm by using the name attribute. When a request comes into the server for /hello-world.htm, it's first passed to the DispatcherServlet, as it matches the *.htm pattern mapped to that servlet. The DispatcherServlet then looks up which controller should handle the specific request by using the information in spring-dispatcher-servlet.xml. Because /hello-world.htm is mapped to the HelloWorldService controller, the request is handed off to that controller, which packages the requested data into the model and then sends it off to be displayed in the view.

All the application code and configuration is now complete. The last step is to create an Ant build script to compile, package, and deploy the application. After that, the application is ready to run under JBoss.

Although it's possible to compile, package, and deploy your Web application manually by using tools included with the JDK, such an approach doesn't provide an easily adaptable and maintainable build strategy. If more library JAR files are added to your application's build path or the Web application becomes part of a larger Java enterprise application that needs to be deployed to many different application servers, keeping up with long compilation commands, multiple batch files, and deployment paths becomes an error-prone process. Fortunately, thanks to Apache Ant, it's not necessary to manually build your application.

Ant uses an XML build file that contains one or more projects, each of which in turn contains one or more targets. An Ant target is a grouping of related tasks, which are individual units of work in an Ant target. For example, many Ant build files contain a target named build. The build target might contain tasks that create output directories and compile Java code.

Projects in an Ant build file are groupings of targets for a particular application. In addition to the targets for building and deploying the application, projects can contain properties that can be substituted into targets and tasks by using variables. Properties can also be defined in a separate properties file that can be included in the build file. This makes it easier to change the value of a property if needed, as you need to change the value in only one place rather than throughout the build file. Projects can also contain path resources that group sets of files under a single ID, which can then be referenced by other parts of the build file.

The Ant build file for the HelloWorld application contains a couple of properties, a path resource, and two targets. One of the properties is a reference to an external properties file, which you create now. The properties file simply contains a set of name-value pairs.

To create the build.properties file, follow these steps:

The code listing for the helloworld-build.properties file is as follows:

# Ant build properties for helloworld
src.dir=src
web.dir=web
build.dir=${web.dir}/WEB-INF/classes

name=helloworld

appserver.home=${env.JBOSS_HOME}/server/default
appserver.lib=${appserver.home}/lib
deploy.path=${appserver.home}/deploy

The first three properties are related to the compiling of the Java code. The src.dir property tells the build script where the source code for the application can be found. The web.dir property tells the build script where the Web code and configuration files can be found. Finally, the build.dir property tells the build scripts where to output the compiled Java classes. This property makes use of the previously defined web.dir property by using the ${} variable substitution notation.

The final four properties are related to packaging and deploying the compiled application to the JBoss server. The name property defines the name of the application; the build script packages the application into a WAR file called ${name}.war. The appserver.home property tells the build script where to locate the base of the JBoss installation. There are two things to notice about this property. First, notice the ${env.JBOSS_HOME} variable substitution used here. It's possible to set a build file property that allows you to access environment variables on your computer. This property accesses the value of the JBOSS_HOME environment variable you set when you configured JBoss. Second, notice that you're setting appserver.home to the default server instance under the JBoss installation.

It's possible to have multiple server configurations configured under JBoss, and applications need to be deployed to one or more of these specific configurations rather than just deployed to JBoss in general. The appserver.lib property uses the appserver.home property to tell the build script where the JBoss server libraries are. Remember that the application needs JBoss's servlet-api.jar file to build. Finally, the deploy.path property tells the build script where to place the built and packaged application. The JBoss server configuration deploys any applications in its deploy directory when it starts up.

Now that the properties file is in place, the Ant build file can be created. By convention, Ant build files are always named build.xml.

To create the build.xml file, follow these steps:

The code listing for the build.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<project name="helloworld" basedir="." default="usage">
     <property environment="env"/>
     <property file="helloworld-build.properties"/>

     <path id="cp">
          <fileset dir="${web.dir}/WEB-INF/lib">
               <include name="*.jar"/>
          </fileset>
          <fileset dir="${appserver.lib}">
               <include name="servlet-api.jar"/>
          </fileset>
          <pathelement path="${build.dir}"/>
     </path>

     <target name="usage">
          <echo message=""/>
          <echo message="${name} build file"/>
          <echo message="-----------------------------------"/>
          <echo message=""/>
          <echo message="Available targets are:"/>
          <echo message=""/>
          <echo message="build --> Build the application"/>
          <echo message="deploy      --> Deploy application as a WAR file"/>
          <echo message=""/>
     </target>

     <target name="build" description="Compile main source tree java files">
          <mkdir dir="${build.dir}"/>
          <javac destdir="${build.dir}" source="1.5" target="1.5"
          debug="true" deprecation="false" optimize="false"
          failonerror="true">
               <src path="${src.dir}"/>
               <classpath refid="cp"/>
          </javac>
     </target>

     <target name="deploy" depends="build" description="Deploy application as a WAR file">
          <war destfile="${name}.war"
                webxml="${web.dir}/WEB-INF/web.xml">
               <fileset dir="${web.dir}">
                      <include name="**/*.*"/>
               </fileset>
          </war>
          <copy todir="${deploy.path}" preservelastmodified="true">
               <fileset dir=".">
                      <include name="*.war"/>
               </fileset>
        </copy>
  </target>
</project>

This listing looks long, but it's really fairly simple when broken down into its basic parts:

To run the Ant build script from within Eclipse, you need to add it to the Ant view in your project. To add the build script to the Ant view, follow these steps:

Figure 6.35. Choose the build.xml file for your project in the Buildfile Selection dialog box to add it to the Ant view.

Click the arrow next to the build file entry in the Ant view to expand it and see the available build targets. The three targets you saw in the build.xml file appear here. Double-click the usage target to run it. Eclipse switches to the Console view, and the messages defined in the <echo> tags in the usage target print out in the console, as shown in Figure 6.37. Click the Ant tab to switch back to the Ant view.

Now double-click the deploy target to run it. Study the output of the console, as shown in Figure 6.38, and notice that because the build target has never been run, the deploy target launches the build target first. The ability to chain dependencies like this in your build files is a very powerful advantage over building manually. Using dependencies like this, you can ensure that you never deploy outdated code to your application server.

Figure 6.36. The build file appears in the Ant view with the name of the project as defined in build.xml.

Figure 6.37. The console output from running the usage target of the Ant build

Figure 6.38. The console output from the deploy target demonstrates its dependency on the build target. Because the build target had not yet been run, the deploy target launched it before proceeding with its own tasks.

Once the application has been successfully deployed, you can start up JBoss and see the application in action. To start JBoss and test your application, follow these steps:

Figure 6.39. Once the JBoss server has started successfully, the Servers view shows its state as Started.

Figure 6.40. This screen indicates that the HelloWorld application has been successfully deployed to JBoss.

You may be curious about the URL. Web applications are deployed to their own application context on the server. That way, multiple applications can be run on the same server without having conflicting resource names (index.html, for example). By default, the application context URL path is the name of the application. In this case, the application is deployed as helloworld.war, so the application context name is helloworld. Therefore, it can be said that the URL points to the resource hello-world.htm within the application context helloworld on the localhost server.

If for some reason you receive an error instead of the screen in Figure 6.40, there are a couple of things you can do to check your work and see what went wrong:

While the HelloWorld application builds, deploys, and runs, it's otherwise not very interesting. Adding the ability to accept input from the user interface is the next logical step for this application.

Open the HelloWorldService file by double-clicking it in the Project Explorer view. Replace the existing handleRequest method with the following:

/**
 *
 */
package com.wiley.jfib.ch06.helloworld.service;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.mvc.Controller;

/**
 * @author Chuck
 *
 */
public class HelloWorldService implements Controller {

/* (non-Javadoc)
      * @see org.springframework.web.servlet.mvc.
      Controller#handleRequest(javax.servlet.http.HttpServletRequest,
      javax.servlet.http.HttpServletResponse)
       */
      @Override
      public ModelAndView handleRequest(HttpServletRequest arg0,
                   HttpServletResponse arg1) throws Exception {
             // Receive the language parameter from the client
             String language = arg0.getParameter("lang");
             String message = "";

             // customize the message based on the language
             if(language == null)
                    message = "I don't know what language you speak!";
             else if("english".equalsIgnoreCase(language))
                    message = "Hello, World!";
             else if("spanish".equalsIgnoreCase(language))
                    message = "Hola, mundo!";
             else if("french".equalsIgnoreCase(language))
                    message = "Bonjour, monde!";
             else if("german".equalsIgnoreCase(language))
                    message = "Hallo, Welt!";
             else if("italian".equalsIgnoreCase(language))
                    message = "Ciao, mondo!";
             else
                    message = "I'm sorry. I don't speak your language.";

             // return the message for the client
             return new ModelAndView("WEB-INF/jsp/hello-world.jsp",
             "message",message);
      }

 }

The handleRequest method now attempts to retrieve a parameter named lang from the client's request. The message returned to the client is customized based on the language received, if any.

Save the file and then click the Ant tab below the editors to switch back to the Ant view. Double-click the deploy target to rebuild and redeploy the application.

If you didn't stop the JBoss server, you may notice that the Console view switches back to the JBoss server console after a few moments. JBoss is able to detect applications that have been updated and then reload them on the fly. This means you don't have to stop and restart JBoss to deploy changes to your application. If you had previously stopped JBoss, restart it by switching to the Servers view and then clicking the Start the Server button.

Open your Web browser and then type the same URL you used previously: http://localhost:8080/helloworld/hello-world.htm. Instead of the "Hello, World!" message, you see a message stating, "I don't know what language you speak!" Now change the URL by adding ?lang=spanish to the end and then press Enter. The part of the URL after the question mark is called the query string. The query string is one way of passing parameters to the server. The application now greets you in Spanish, as shown in Figure 6.41.

Figure 6.41. The application is now able to display a dynamic message based on the lang parameter of the query string.