Source

webwork / docs / quickstart.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title>WebWork Documentation</title>
  <link type="text/css" href="main.css" rel="STYLESHEET"/>
</head>
<body>
  <div id="page-logo">
    <a href="index.html"><img src="logo-small.png" border="0"/></a>
  </div>
    <div class="snip-title">
	  <h1 class="snip-name">WebWork2 QuickStart Guide
  
  </h1>
  </div>
<div id="snip-content" class="snip-content">

 <div class="snip-attachments"></div>
 
 Webwork is a popular, easy-to-use MVC framework, for more information on the WebWork project, please visit <a href="index.html">WebWork2</a>. This guide should be helpful to seasoned Java developers with previous experience in MVC frameworks. We will briefly cover the three main components on a WebWork2 based application, the configuration the action classes, and the views.
<h3 class="heading-1">GETTING STARTED
</h3>
To use WebWork as your framework for writing Java-based web applications, you need to start by installing the various libraries:
<h3 class="heading-1-1">Core JAR files
</h3>
<ul class="star">
<li>webwork-2.0-beta.jar</li>
<li>xwork-1.0-beta.jar</li>
<li>ognl-2.5.1.jar</li>
<li>commons-logging.jar</li>
<li>oscore-2.2.1.jar</li>
<li>jstl.jar (needed for Standard Tag Libraries)</li>
<li>velocity-dep-1.3.1.jar</li>
</ul>
<h3 class="heading-1-1">Optional JAR files
</h3>
<ul class="star">
<li>cos-multipart.jar</li>
<li>pell-multipart.jar</li>
<li>standard.jar</li>
<li>mail.jar</li>
</ul>
<h3 class="heading-1">CONFIGURATION
</h3>
WebWork is built upon the Xwork framework. Xwork handles the translation of commands between requests, but let's not worry about that right now. You need to know this information in case you were curious about the xwork JAR file, and if you want to learn some of the more advanced features of the WebWork command structure, you can visit the <a href="http://wiki.opensymphony.com/space/Xwork">Xwork</a> site.
<h3 class="heading-1-1">Example web.xml file
</h3>
<div class="code"><pre>&#60;?xml version=<span class="xml&#45;quote">"1.0"</class> encoding=<span class="xml&#45;quote">"ISO&#45;8859&#45;1"</class>?&#62;
&#60;!DOCTYPE web&#45;app 
          PUBLIC 
          <span class="xml&#45;quote">"&#45;//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"</class> 
          <span class="xml&#45;quote">"http://java.sun.com/dtd/web&#45;app_2_3.dtd"</class>&#62;
&#60;web&#45;app&#62;
    &#60;display&#45;name&#62;WebWork 2.0 Quick Start&#60;/display&#45;name&#62;
    &#60;servlet&#62;
        &#60;servlet&#45;name&#62;webwork&#60;/servlet&#45;name&#62;
          &#60;servlet&#45;class&#62;com.opensymphony.webwork.dispatcher.ServletDispatcher&#60;/servlet&#45;class&#62;                                            
    &#60;/servlet&#62;
    &#60;servlet&#62;
        &#60;servlet&#45;name&#62;velocity&#60;/servlet&#45;name&#62;
          &#60;servlet&#45;class&#62;com.opensymphony.webwork.views.velocity.WebWorkVelocityServlet&#60;/servlet&#45;class&#62;
        &#60;load&#45;on&#45;startup&#62;1&#60;/load&#45;on&#45;startup&#62;
    &#60;/servlet&#62;<p class="paragraph"/>    &#60;servlet&#45;mapping&#62;
        &#60;servlet&#45;name&#62;webwork&#60;/servlet&#45;name&#62;
	&#60;url&#45;pattern&#62;&#42;.action&#60;/url&#45;pattern&#62;
    &#60;/servlet&#45;mapping&#62;
    &#60;servlet&#45;mapping&#62;
	 &#60;servlet&#45;name&#62;velocity&#60;/servlet&#45;name&#62;
	 &#60;url&#45;pattern&#62;&#42;.vm&#60;/url&#45;pattern&#62;
    &#60;/servlet&#45;mapping&#62;<p class="paragraph"/>
    &#60;welcome&#45;file&#45;list&#62;
        &#60;welcome&#45;file&#62;index.jsp&#60;/welcome&#45;file&#62;
        &#60;welcome&#45;file&#62;index.html&#60;/welcome&#45;file&#62;
    &#60;/welcome&#45;file&#45;list&#62;<p class="paragraph"/>    &#60;taglib&#62; 
        &#60;taglib&#45;uri&#62;webwork&#60;/taglib&#45;uri&#62; 
        &#60;taglib&#45;location&#62;/WEB&#45;INF/lib/webwork&#45;2.0&#45;beta.jar&#60;/taglib&#45;location&#62; 
    &#60;/taglib&#62;<p class="paragraph"/>&#60;/web&#45;app&#62;</pre></div>
<h3 class="heading-1-1">Servlet mappings
</h3>
<div class="code"><pre>&#60;servlet&#45;mapping&#62;
    &#60;servlet&#45;name&#62;webwork&#60;/servlet&#45;name&#62;
    &#60;url&#45;pattern&#62;&#42;.action&#60;/url&#45;pattern&#62;
&#60;/servlet&#45;mapping&#62;</pre></div>
The above section will map ANY servlet called with an extension of <b class="bold">.action</b> to the WebWork base servlet, and assume it is a WebWork action class.<p class="paragraph"/><div class="code"><pre>&#60;servlet&#45;name&#62;velocity&#60;/servlet&#45;name&#62;
&#60;servlet&#45;class&#62;com.opensymphony.webwork.views.velocity.WebWorkVelocityServlet&#60;/servlet&#45;class&#62;
&#60;load&#45;on&#45;startup&#62;1&#60;/load&#45;on&#45;startup&#62;
&#60;/servlet&#62;</pre></div>
The above section will startup the WebWorkVelocityServlet which is used to render Velocity pages. It also initializes the underlying Velocity templating subsystem which is required for using the WebWork UI tag libraries ( see below ).
<h3 class="heading-1-1">Taglibs
</h3>
<div class="code"><pre>&#60;taglib&#62; 
  &#60;taglib&#45;uri&#62;webwork&#60;/taglib&#45;uri&#62; 
  &#60;taglib&#45;location&#62;/WEB&#45;INF/lib/webwork&#45;2.0&#45;beta.jar&#60;/taglib&#45;location&#62; 
&#60;/taglib&#62;</pre></div>
The above section will load the standard WebWork tag libraries. To load more or different libraries, add more <b class="bold">&#60;taglib&#62;</b> calls.
<h3 class="heading-1-1">Example Xwork config file (xwork.xml)
</h3>
<div class="code"><pre>&#60;?xml version=<span class="xml&#45;quote">"1.0"</class> encoding=<span class="xml&#45;quote">"ISO&#45;8859&#45;1"</class>?&#62;
&#60;!DOCTYPE xwork 
          PUBLIC 
          <span class="xml&#45;quote">"&#45;//OpenSymphony Group//XWork 1.0//EN"</class> 
          <span class="xml&#45;quote">"http://www.opensymphony.com/xwork/xwork&#45;1.0.dtd"</class>&#62;
&#60;xwork&#62;
    &#60;include file=<span class="xml&#45;quote">"webwork&#45;default.xml"</class>/&#62;
    &#60;package name=<span class="xml&#45;quote">"default"</class> extends=<span class="xml&#45;quote">"webwork&#45;default"</class>&#62;
        &#60;interceptors&#62;
                &#60;interceptor name=<span class="xml&#45;quote">"security"</class> class=<span class="xml&#45;quote">"com.acme.LoginCheck"</class>/&#62;
                &#60;interceptor&#45;ref name=<span class="xml&#45;quote">"security"</class>/&#62;
        &#60;/interceptors&#62;<p class="paragraph"/>        &#60;default&#45;interceptor&#45;ref name=<span class="xml&#45;quote">"security"</class>/&#62;<p class="paragraph"/>        &#60;action name=<span class="xml&#45;quote">"showForm"</class> class=<span class="xml&#45;quote">"com.acme.FormAction"</class>&#62;
            &#60;result name=<span class="xml&#45;quote">"success"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
                &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/form.jsp&#60;/param&#62;
            &#60;/result&#62;
        &#60;/action&#62;<p class="paragraph"/>        &#60;action name=<span class="xml&#45;quote">"saveForm"</class> class=<span class="xml&#45;quote">"com.acme.FormAction"</class> method=<span class="xml&#45;quote">"processForm"</class>&#62;
            &#60;result name=<span class="xml&#45;quote">"success"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
                &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/form.jsp&#60;/param&#62;
            &#60;/result&#62;
             &#60;result name=<span class="xml&#45;quote">"missing&#45;data"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
                &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/form.jsp&#60;/param&#62;
            &#60;/result&#62;
            &#60;interceptor&#45;ref name=<span class="xml&#45;quote">"security"</class>/&#62;
        &#60;/action&#62;<p class="paragraph"/>    &#60;/package&#62;
&#60;/xwork&#62;</pre></div>
<h3 class="heading-1">ACTIONS
</h3>
<div class="code"><pre>&#60;action name=<span class="xml&#45;quote">"saveForm"</class> class=<span class="xml&#45;quote">"com.acme.FormAction"</class> method=<span class="xml&#45;quote">"processForm"</class>&#62;</pre></div><p class="paragraph"/>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. <b class="bold">saveForm.action</b>) and the corresponding "handler" class.<p class="paragraph"/>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 <b class="bold">execute()</b> by default. If there is no <b class="bold">execute()</b> method and no method specified in the xml file, WebWork will throw an exception.
<h3 class="heading-1">RESULTS
</h3>
<div class="code"><pre>&#60;result name=<span class="xml&#45;quote">"missing&#45;data"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
    &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/form.jsp&#60;/param&#62;
&#60;/result&#62;</pre></div><p class="paragraph"/>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:
<div class="code"><pre><span class="java&#45;object">String</span> SUCCESS = <span class="java&#45;quote">"success"</span>;
<span class="java&#45;object">String</span> NONE    = <span class="java&#45;quote">"none"</span>;
<span class="java&#45;object">String</span> ERROR   = <span class="java&#45;quote">"error"</span>;
<span class="java&#45;object">String</span> INPUT   = <span class="java&#45;quote">"input"</span>;
<span class="java&#45;object">String</span> LOGIN   = <span class="java&#45;quote">"login"</span>;</pre></div><p class="paragraph"/>You can extend these as you see fit. Most of the time you will have either <b class="bold">SUCCESS</b> or <b class="bold">ERROR</b>, with <b class="bold">SUCCESS</b> moving on to the next page in your application;
<div class="code"><pre>&#60;result name=<span class="xml&#45;quote">"success"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
    &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/thank_you.jsp&#60;/param&#62;
&#60;/result&#62;</pre></div><p class="paragraph"/>…and <b class="bold">ERROR</b> moving on to an error page, or the preceding page;
<div class="code"><pre>&#60;result name=<span class="xml&#45;quote">"error"</class> type=<span class="xml&#45;quote">"dispatcher"</class>&#62;
    &#60;param name=<span class="xml&#45;quote">"location"</class>&#62;/error.jsp&#60;/param&#62;
&#60;/result&#62;</pre></div><p class="paragraph"/>You can stack as many result tags within a single action tag as you wish.
<h3 class="heading-1">INTERCEPTORS
</h3>
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:
<ul class="star">
<li>Security Checking (ensuring the user is logged in)</li>
<li>Trace Logging (logging every action)</li>
<li>Bottleneck Checking (start a timer before and after every action, to check bottlenecks in your application)</li>
</ul><p class="paragraph"/>You can also chain Interceptors together to create "packages". 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 package.<p class="paragraph"/>For further Reading on Interceptors, see <a href="http://wiki.opensymphony.com/space/Xwork+Interceptors">Xwork Interceptors</a><br/>
For further Reading on Xwork configuration files, see <a href="http://wiki.opensymphony.com/space/Xwork+Configuration">Xwork Configuration</a>
<h3 class="heading-1">ACTION CLASSES
</h3>
The action classes do what they say, they handle the action. They are called by the actions specified in the <b class="bold">xwork.xml</b> file and initiated by the user in the "views".  To turn your class into an action class, you simply need to extend the class <b class="bold">ActionSupport</b> or implement the <b class="bold">Action</b> interface.<p class="paragraph"/>Here is what our <b class="bold">saveForm</b> action looks like in its Java form (NOTE: If you look in the <b class="bold">xwork.xml</b> file above, we've overridden the action to call the <b class="bold">processForm</b> method):<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">package</span> com.acme;
<span class="java&#45;keyword">import</span> com.opensymphony.xwork.&#42;;<p class="paragraph"/><span class="java&#45;keyword">public</span> class FormAction <span class="java&#45;keyword">extends</span> ActionSupport &#123;<p class="paragraph"/>    <span class="java&#45;keyword">private</span> FormBean myFormBean = <span class="java&#45;keyword">new</span> FormBean();<p class="paragraph"/>    <span class="java&#45;keyword">public</span> void setFormBean(FormBean inBean) &#123;
        myFormBean = inBean;
    &#125;<p class="paragraph"/>    <span class="java&#45;keyword">public</span> FormBean getFormBean() &#123;
        <span class="java&#45;keyword">return</span> myFormBean;
    &#125;<p class="paragraph"/>    <span class="java&#45;keyword">public</span> <span class="java&#45;object">String</span> processForm() &#123;<p class="paragraph"/>        FormParameters formParams = <span class="java&#45;keyword">this</span>.getFormBean();
        checkBizRules(formParams);
        <span class="java&#45;keyword">this</span>.saveParamsToDb(formParams);<p class="paragraph"/>        <span class="java&#45;keyword">return</span> SUCCESS;
    &#125;
...
&#125;</pre></div>
<h3 class="heading-1">VIEWS
</h3>
WebWork supports JSP and Velocity for your application presentation layer. For this example we will use a JSP file. 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 <b class="bold">form.jsp</b> page:
<div class="code"><pre>&#60;%@ taglib prefix=<span class="java&#45;quote">"ww"</span> uri=<span class="java&#45;quote">"webwork"</span> %&#62;
&#60;html&#62;
&#60;head&#62;&#60;title&#62;Webwork Form Example&#60;/title&#62;&#60;/head&#62;
&#60;body&#62;<p class="paragraph"/>&#60;ww:form name=<span class="java&#45;quote">"myForm"</span> action=<span class="java&#45;quote">"saveForm.action"</span> method=<span class="java&#45;quote">"POST"</span>&#62;
    &#60;table&#62;<p class="paragraph"/>    &#60;ww:textfield label=<span class="java&#45;quote">"First Name"</span> name=<span class="java&#45;quote">"'formBean.firstName'"</span> value=<span class="java&#45;quote">"formBean.firstName"</span>/&#62;
    &#60;ww:textfield label=<span class="java&#45;quote">"Last Name"</span> name=<span class="java&#45;quote">"'formBean.lastName'"</span> value=<span class="java&#45;quote">"formBean.lastName"</span>/&#62;<p class="paragraph"/>    &#60;/table&#62;
    &#60;input type=<span class="java&#45;quote">"submit"</span> value=<span class="java&#45;quote">"Save Form"</span>/&#62;
&#60;/ww:form&#62;
&#60;/body&#62;</pre></div><p class="paragraph"/>The process of events will go as follows:
<ol>
<li>WebWork will take notice since the URI ends in <b class="bold">.action</b> (defined in our <b class="bold">web.xml</b> files)</li>
<li>WebWork will look up the action <b class="bold">saveForm</b> in its action hierarchy and call any Interceptors that we might have defined.</li>
<li>WebWork will translate <b class="bold">saveForm</b> and decide we would like to call the method <b class="bold">processForm</b> in our class <b class="bold">com.acme.FormAction</b> as defined in our <b class="bold">xwork.xml</b> file.</li>
<li>Our method will process successfully and give WebWork the <b class="bold">SUCCESS</b> return parameter.</li>
<li>WebWork will translate the <b class="bold">SUCCESS</b> return parameter into the location <b class="bold">thank_you.jsp</b> (as defined in <b class="bold">xwork.xml</b>) and redirect us accordingly.</li>
</ol>
<h3 class="heading-1">SUMMARY
</h3>
The purpose of this guide is to provide the user with a quick-and-dirty understanding of WebWork2. I hope we successfully briefed you on the three most important components of any WebWork based application, the configuration (including <b class="bold">web.xml</b> and <b class="bold">xwork.xml</b>), the action classes, and the views. This information should give you a starting point to experiment and become more familiar with the rising star of the open source, Model2, web frameworks.<p class="paragraph"/>Matt Dowell<br/>
matt.dowell@notiva.com<br/>
September 15, 2003
  </div>
</body>
</html>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.