Preface

WebWork is a popular, easy-to-use MVC framework, for more information on the WebWork project, please visit WebWork.
This site is geared towards developers that have an understanding towards certain technologies. Before diving into how Webwork works and running demos, it is recommended that you review the concepts below:

• Java
• Servlets, JSP, and Tag Libraries
• JavaBeans
• HTML and HTTP
• Web Containers (ex. Tomcat)
• XML

Distribution Download and Information Resources

Download Webwork Distribution

You can download the full WebWork distribution here. It contains the webwork.jar file as well as full documentation, sources, all required and optional dependent libraries and examples. For more information on how to build WebWork from source or even checkout from CVS, please refer to Building Webwork.

Information and Project Resources

This site is set up with many features. Here are links to help you around:

• Download Webwork - download Webwork Distribution
• Join the WebWork Forums - The forums are full of active developers, contributors, and power users - often even available for chat. This is the best and quickest way to get a question answered.
• Subscribe to Mailing List or browse Mail Archive or post a question. All posts from the forum are posted to the mailing lists, as well as your posts to the list will make it to the forum.
• CVS - Browse CVS and source at java.net
• Webwork Wiki - Powered by Confluence, the professional J2EE wiki
• Webwork Bugs & Issues - Powered by JIRA:Bug & Issue Traking System
• OpenSymphony Home

Distribution Quickstart

Overview

The distribution contains the following directory layout:

docs/
lib/
src/
src/java/template/
webapps/
README.txt
build.properties
build.xml
webwork-(VERSION)-src.jar
webwork-(VERSION).jar
webwork.jar

The docs directory contains the current Javadocs, the full user documentation including the document you are reading, taglib documentation, as well as Clover, JUnit and dependency reports for the build.

The lib directory contains the required as well as the optional dependencies for Webwork, organized in subdirectories to represent different optional configurations and thereby induced Dependencies:

lib/
      ajax/
      build/
      default/
      fileupload/
      fileupload-cos/
      fileupload-pell/
      freemarker/
      jasperreports/
      jfree/
      portlet/
      quickstart/
      sitemesh/
      spring/
      velocity/
      xslt/

Note that none of the optional packages are required to use Webwork. If you wish to use certain features such as JasperReports and FreeMarker results, you must include the optional packages.

Webwork also comes packaged with all the source files and the templates for the JSP tags.

Running demos with QuickStart

WebWork provides a quick way to get started called QuickStart. QuickStart is essentially a combination of a few technologies, including the possibility to run web applications such as the provided examples out of the box with a stripped Jetty container.

With that, running the demos is as easy as can be. You just need to call

java -jar webwork.jar quickstart:<application-name>

from the distribution's top directory, whereby <application-name> is to be replaced by one of the subdirectory names under webapps/, representing the various supplied demo applications. So if you want to start the shopping cart example, just type on your commandline

java -jar webwork.jar quickstart:shopping-cart

The packaged examples are:

Read Quickstart documentation to learn more about how it works and how you can utilize it for your own applications.

Running Demos with Your Favorite Webcontainer

TODO: Review / comment lastest changes

In order to run webwork applications and demos, you need to have a servlet/jsp engine. If you don't, we suggest you learn about Apache Tomcat, which is a free Servlet container from the Apache Jakarta Project, or Resin, from Caucho Technology, which is free for non-comercial use. Once you a Servlet container setup, you can install the webwork example applications (*.war) and any other demos by placing the .war file inside the containers webapp directory. Example of location with tomcat:

<TOMCAT_HOME>/webapps/webwork-example.war

After the war file is in the correct location, start your web container and access your application through a web browser with the following url.

*http://*??HOST:PORT??*/webwork-example*

Your first WebWork Application

Using the Starter Template

The distribution contains a simple webapp called starter in meant as a template for your webapplications. Just copy starter directory to a newly named destination and edit the configuration files as needed.

Setting up from Scratch

Structure of your Webapplication

The following illustrates how your web application should be set up. Copy the webwork-(VERSION).jar, all the *.jar files in /lib/core and any necessary optional *.jar files in /lib/optional to your webapp/lib directory. If you need to customize your own templates (how HTML is rendered from webwork UI tags), copy the /src/java/template directory into your webapp/ directory. Your webapp should look similar to this:

/mywebapp/
/mywebapp/template/
/mywebapp/META-INF/
/mywebapp/WEB-INF/
/mywebapp/WEB-INF/classes/
/mywebapp/WEB-INF/lib/
/mywebapp/WEB-INF/lib/CORE&OPTIONAL *.jar
/mywebapp/WEB-INF/web.xml

Minimum Set of Libraries and Config Files

The following files are a minium requirement for your application.

The library files (*.jar) needs to be copied to your /mywebapp/WEB-INF/lib/ directory. If you need optional functionalities inducing dependencies to optional jars, they need to be copied to this directory, too.

web.xml:

Create the following web.xml file in [webapp]/WEB-INF. If you already have a web.xml file, just add the content of the <web-app> tag below to your existing <web-app> tag.

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <display-name>My WebWork Application</display-name>
  <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>

  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

  <taglib>
    <taglib-uri>/webwork</taglib-uri>
    <taglib-location>/WEB-INF/lib/webwork.jar</taglib-location>
  </taglib>
</web-app>

This registers FilterDispatcher to induce webwork functionality in your requests. The ContextLoaderListener will take care of setting up Spring as your IoC container for WebWork. The taglib entry will help you use Tags in your JSP pages.

Read more: web.xml

xwork.xml:

Create the following file xwork.xml in [webapp]/WEB-INF/classes/.

<!DOCTYPE xwork PUBLIC "-//OpenSymphony Group//XWork 1.0//EN" 
"http://www.opensymphony.com/xwork/xwork-1.0.dtd">

<xwork>
	<!-- Include webwork defaults (from WebWork JAR). -->
	<include file="webwork-default.xml" />
	
	<!-- Configuration for the default package. -->
	<package name="default" extends="webwork-default">
	</package>
</xwork>

For now, this xwork.xml does only two things:

• It informs WebWork that it should import the configuration information from webwork-default.xml. (This file is located at the root of the webwork.jar, so it is sure to be found.)

• It defines a default package (with the <package> section) where WebWork elements like actions, results and interceptors are registered.

Read more: xwork.xml

Basic Concepts

We will briefly cover the three main components on a WebWork2 based application, the configuration the action classes, and the views. Especially the example in this section should be helpful to seasoned Java developers with previous experience in MVC frameworks.

Actions

<action name="saveForm" class="com.acme.FormAction" method="processForm">

Actions are the basic "unit-of-work" in WebWork, they define, well, actions. An action will usually be a request, (and usually a button click, or form submit). The main action element (tag is too synonymous with JSP) has two parts, the friendly name (referenced in the URL, i.e. saveForm.action) and the corresponding "handler" class.

The method parameter tells WebWork which method to call based upon this action. If you leave the method parameter blank, WebWork will call the method execute() from the Action Interface by default. Since every Action must implment the Action Interface, this method will always be available.

Results

<result name="missing-data" type="dispatcher">
    <param name="location">/form.jsp</param>
</result>

Result tags tell WebWork what to do next after the action has been called. There are a standard set of result codes built-in to WebWork, (in the Action interface) they include:

String SUCCESS = "success";
String NONE    = "none";
String ERROR   = "error";
String INPUT   = "input";
String LOGIN   = "login";

You can extend these as you see fit. Most of the time you will have either SUCCESS or ERROR, with SUCCESS moving on to the next page in your application;

<result name="success" type="dispatcher">
    <param name="location">/thank_you.jsp</param>
</result>

...and ERROR moving on to an error page, or the preceding page;

<result name="error" type="dispatcher">
    <param name="location">/error.jsp</param>
</result>

You can stack as many result tags within a single action tag as you wish.

For further reading on Result types, see Result Types.

Interceptors

Interceptors allow you to define code to be executed before and/or after the execution of an action. Interceptors can be a powerful tool when writing web applications. Some of the most common implementations of an Interceptor might be:

• Security Checking (ensuring the user is logged in)
• Trace Logging (logging every action)
• Bottleneck Checking (start a timer before and after every action, to check bottlenecks in your application)

You can also group Interceptors together to create "stacks". If you wanted to do a login check, security check, and logging all before an Action call, this could easily be done with an interceptor stack.

For further reading on interceptor configuration, as well as a discussion of WebWork's builtin interceptors, see Interceptors

Action Classes

The action classes do what they say, they handle the action. They are called by the actions specified in the xwork.xml file and initiated by the user in the "views". To turn your class into an action class, you simply need to extend the class ActionSupport or implement the Action interface.

Here is what our saveForm action looks like in its Java form:

package com.acme;
import com.opensymphony.xwork.*;

public class FormAction extends ActionSupport {
    
    private FormBean myFormBean = new FormBean();

    public void setFormBean(FormBean inBean) {
        myFormBean = inBean;
    }

    public FormBean getFormBean() {
        return myFormBean;
    }

    public String execute() {

        FormParameters formParams = this.getFormBean();
        checkBizRules(formParams);
        this.saveParamsToDb(formParams);

        return SUCCESS;
    }
...
}

Views

WebWork supports JSP, Velocity, and FreeMarker for your application presentation layer. For this example, we will use a JSP file. The appropriate presentation layer is denoted by the result type specified. For JSPs, the result type is the name mapped to the com.opensymphony.webwork.dispatcher.ServletDispatcherResult. Typically, this is "dispatcher".

WebWork comes packaged with a tag library (taglibs). You can use these taglibs as components in your JSP file. Here is an section of our form.jsp page:

<%@ taglib prefix="ww" uri="webwork" %>
<html>
<head><title>Webwork Form Example</title></head>
<body>

<ww:form name="'myForm'" action="'saveForm.action'" method="'POST'">
    <table>

    <ww:textfield label="'First Name'" name="'formBean.firstName'" value="formBean.firstName"/>
    <ww:textfield label="'Last Name'" name="'formBean.lastName'" value="formBean.lastName"/>

    </table>
    <input type="submit" value="Save Form"/>
</ww:form>
</body>

The process of events will go as follows:

1. WebWork will take notice since the URI ends in .action (defined in our web.xml files)
2. WebWork will look up the action saveForm in its action hierarchy and call any Interceptors that we might have defined.
3. WebWork will translate saveForm and decide we would like to call the method processForm in our class com.acme.FormAction as defined in our xwork.xml file.
4. Our method will process successfully and give WebWork the SUCCESS return parameter.
5. WebWork will translate the SUCCESS return parameter into the location thank_you.jsp (as defined in xwork.xml) and redirect us accordingly.

Onward to Configuration or the Webwork Tutorial