Installing the Software

Before you begin, you need to install the following software on your computer:

• NetBeans IDE 5.5 or above. (This tutorial was written and tested under NetBeans IDE 5.5.)
• Java Standard Development Kit (JDK™) version 1.4.2 (download) or 5.0 (download)
• The NetBeans module (NBM) file that constitutes the WebWork Support Module for NetBeans IDE (download). Use the Update Center wizard under the Tools menu to install the NBM file in the IDE. Choose "Install Manually Downloaded Modules (.nbm Files)" in the first page of the Update Center wizard, browse to the downloaded NBM file, and complete the wizard.
• Currently, all the basic WebWork JAR files are provided by the module, including those needed for Spring. Therefore, for the basic scenarios, you do not need to download the JAR files from the WebWork site. However, for more advanced scenarious, you will need other JARs, provided by the WebWork 2.2.4 distribution.

Directory Structure and Project Setup

The source structure of our application must include the WebWork JAR files, the registration of the WebWork servlet in the web.xml file, as well as some standard artifacts such as the home page. Since we are using an IDE, we shouldn't need to create all these files by hand. Instead, we have a wizard to do the work for us. Specifically, the final panel of the Web Application wizard will be very useful in the context of our WebWork application.

1. Choose File > New Project. Under Categories, select Web. Under Projects, select Web Application. Click Next.
2. In the Name and Location panel, type HelloWebWork in Project Name. Change the Project Location to any directory on your computer.

3. Leave all the other settings unchanged. Or, if you like, you can change them. WebWork supports J2EE 1.4 as well as Java EE 5. Click Next.

4. In the Frameworks panel, choose WebWork. You will see the following options in the first tab of the lower part of the WebWork Configuration panel:

   

   Leave all the defaults unchanged. The fields in the panels above provide the following:

   • Main Package. Specifies the package where the action class will be generated. This field cannot be empty.
   • Action Class Name. Specifies the name of an example class, which will extend WebWork's ActionSupport class. This field cannot be empty.
   • Generate xwork.xml. Specifies whether the xwork.xml file, with some defaul settings, should be generated. By default, this checkbox is selected.
   • Support Hibernate. Specifies that a source root named "Hibernate" will be generated, and also whether a library called "Hibernate" will be retrieved from the Library Manager and put on the application's classpath.
   • Support Spring. Specifies that a source root named "Spring" will be generated, and also whether a library called "Spring" will be retrieved from the Library Manager and put on the application's classpath.

5. The second tab lets you select a library that will be put on the application's classpath. The drop-down shows all libraries that are registered in the Library Manager, so long as their names begin with "WebWork". If none are found, the drop-down is greyed out. You can either select from the drop-down, if possible, or browse to a folder that must contain the main WebWork JAR file, WebWork-2.2.4. That JAR will then be added to the Library Manager, in a new library named "WebWork". In addition, all the libraries in WebWork's lib/default folder, except the JavaMail.jar are also added to your new WebWork library. Alternatively, you can select the final radio button, which will result in no library being put on the classpath. That might make sense if you already have the necessary JARs on the classpath.

   

   Click Finish.

The IDE creates the HelloWebWork project. The project contains all of your sources and project metadata, such as the project's Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1):

Without any programming whatsoever, you can already run your application. Right-click the project node and choose Run Project. The server starts, if it is not running already, and the application is deployed. The IDE's default browser starts up, displaying the index.jsp page, with the message retrieved via the xwork.xml file:

Examining the Sources

Our simple Hello World WebWork application is deployed. But, how does it work? First, the application is deployed and HelloWorld.action is specified as the URL relative to the context path, as follows:

http://localhost:8084/HelloWebWork/HelloWorld.action

The WebWork filter is defined in the web.xml file as follows:

<filter>
    <filter-name>webwork</filter-name>
    <filter-class>com.opensymphony.webwork.dispatcher.FilterDispatcher</filter-class>
</filter>
<filter-mapping>
    <filter-name>webwork</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

So, the /* WebWork filter mapping maps the WebWork filter to every request, which includes HelloWorld.action. WebWork passes the request on to its ActionMapper and lets this ActionMapper handle the request for a "HelloWorld" action. Using the xwork.xml file, the ActionMapper finds the class registered with the HelloWorld action:

<action name="HelloWorld" class="com.acme.action.HelloWorld">
    <result name="success">index.jsp</result>
</action>

By default, the execute() method in the action is called. We have overridden that method as follows:

public String execute() {
    message = "Hello World!";
    return SUCCESS;
}

The execute() method sets a String called message to "Hello World" and then returns a String called SUCCESS. WebWork again looks in xwork.xml for the result that is registered with the returned "SUCCESS" name. It finds the result, which, in xwork.xml, maps to index.jsp:

<action name="HelloWorld" class="com.acme.action.HelloWorld">
    <result name="success">index.jsp</result>
</action>

The page index.jsp is found, in the root of the web folder, and processed. Within its BODY tags, the following is found:

<p>WebWork says:
<h1><font color="red"><ww:property value="message"/></font></h1>

The <ww:property> tag is resolved by the WebWork tag library, declared at the top of the file as follows:

<%@taglib prefix="ww" uri="/webwork"%>

The WebWork tag uses OGNL to call the getter getMessage() in the HelloWorld class. The getter's result is sent back to the browser.

Extending the Sources

In this section, we extend our application with a Login form. If a name—any name—is entered in our index.jsp page, a "Hello" message will appear for the entered name. If no name is entered, an error message will be displayed, prompting the user to try again. While we add this new functionality to our application, we will note several useful features provided by NetBeans IDE, specifically for WebWork. At the end of this section, the Projects window will look as follows:

Note: The highlighted files above are the ones we will add or change in this section.

Do the following to add the Login functionality:

1. Use the Form item in the Palette's HTML Form category to add a new form to the index.jsp file, as shown below:

   

   Similarly, add two Text Input items and tweak the tags until they are as follows:

   <form action="Login.action" method="post">
        <input type="text" name="yourName">
        <input type="submit" value="Submit"/>
   </form>

   Alternatively, you can use the WebWork tag library, to end up with the same result as the above:

   <ww:form action="Login">
       <ww:textfield name="name"/>
       <ww:submit/>
   </ww:form>

   To use the WebWork tag library, you must add the following directive to the top of the index.jsp file:

   <%@taglib prefix="ww" uri="/webwork"%>

2. Create two JSP files, one called success.jsp and the other error.jsp. Insert the following within the BODY tags of success.jsp:

   <h1><font color="red">Hello <ww:property value="yourName"/>!</font></h1>

   To use the WebWork tag library in the success.jsp file, you must add the following directive to the top of the file:

   <%@taglib prefix="ww" uri="/webwork"%>

   Note: Because of the WebWork tag library directive, when you click Ctrl-Space in a ww tag, the WebWork tags are shown, together with their documentation, as shown below:

   

   Within the BODY tags of the error.jsp file, put the following:

   <h1><font color="red">No name entered!</font></h1>

3. Right-click the HelloWebWork project node, choose New > File/Folder. In the Web category, choose the WebWork Login Action, as shown below:

   

   Click Next, name the class Login, and specify that the class should be housed in the com.acme.action package.

   After you click Finish, you should see the following code in the Login template:

   package com.acme.action;
   
   import com.opensymphony.xwork.ActionSupport;
   
   public class Login extends ActionSupport {
   
       String yourName;
   
       public void setYourName(String p_yourName) {
           yourName = p_yourName;
       }
   
       public String getYourName() {
           return yourName;
       }
   
       public String execute() throws Exception {
           if (yourName == null || yourName.length() == 0)
               return ERROR;
           else
               return SUCCESS;
       }
   
    }

   This code is sufficient for purposes of our example. Next, we are going to register the action in the xwork.xml file.

4. Right-click the Login node and choose Register as WebWork Action. The Register New Action dialog box appears. Fill it out so that the Success result will be handled by the success.jsp page, and the Error result by the error.jsp page, as shown below:

   

   When you click OK, the following tags are added to the xWork.xml file, to wire your JSP pages to the Login class:

   <action name="Login" class="com.acme.action.Login">
       <result name="success" type="dispatcher">success.jsp</result>
       <result name="error" type="dispatcher">error.jsp</result>
   </action>

   Note: When you hold down the Ctrl key and move the mouse over an action element in the xWork.xml file, the name of the class becomes blue and turns into a hyperlink, and the cursor becomes a hand, as shown below:

   

   When you click the hyperlink, the referenced class opens in the Source Editor, so that you do not need to look for it in the Projects window.

   When you hold down the Ctrl key and move the mouse over a result element, the name of the JSP file becomes and turns into a hyperlink, which can be clicked to open the referenced document. However, if the document is not found, you can choose to let the IDE generate the file for you, as shown below:

   

   Note: When you click Ctrl-Space, code completion pops up, only showing those elements or attributes that can be filled in the current context:

   

   When you press Enter, the currently selected item in the code completion popup is entered at the cursor.

   Note: When you select an element and you then click Ctrl-Shift-Space, documentation for the selected element is shown:

   

5. Deploy the application. You should now see the following:

   

   When you enter a name, any name at all, and click the Login button, you should see the following, with "Norah Jones" replaced by the name that you entered:

   

   However, when nothing is entered, the following is shown instead:

   

Next Steps

This is the end of the introduction to web development using WebWork in NetBeans IDE. Note that the WebWork Support Module offers a lot more functionality than is described here. For details, see http://nbwebworksupport.dev.java.net/.

You are encouraged to continue your journey in the WebWork framework by working through other tutorials described on the WebWork Home Page.