husted 2004/03/11 18:44:34
Modified: web/example logon.jsp tour.html
web/example/WEB-INF struts-config.xml validation.xml
webtest.xml
Log:
Refactor login.jsp and LogonAction
Revision Changes Path
1.26 +4 -5 jakarta-struts/web/example/logon.jsp
Index: logon.jsp
===================================================================
RCS file: /home/cvs/jakarta-struts/web/example/logon.jsp,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- logon.jsp 9 Mar 2004 04:35:01 -0000 1.25
+++ logon.jsp 12 Mar 2004 02:44:34 -0000 1.26
@@ -2,12 +2,11 @@
<%@ taglib uri="/tags/struts-bean" prefix="bean" %>
<%@ taglib uri="/tags/struts-html" prefix="html" %>
-<html:html locale="true">
+<html:xhtml/>
+<html>
<head>
<title><bean:message key="logon.title"/></title>
-<html:base/>
</head>
-<body bgcolor="white">
<html:errors/>
@@ -36,7 +35,7 @@
<tr>
<td align="right">
- <html:submit value="Submit"/>
+ <html:submit property="Submit" value="Submit"/>
</td>
<td align="left">
<html:reset/>
@@ -54,4 +53,4 @@
<jsp:include page="footer.jsp" />
</body>
-</html:html>
+</html>
1.7 +405 -255 jakarta-struts/web/example/tour.html
Index: tour.html
===================================================================
RCS file: /home/cvs/jakarta-struts/web/example/tour.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- tour.html 10 Mar 2004 03:14:31 -0000 1.6
+++ tour.html 12 Mar 2004 02:44:34 -0000 1.7
@@ -103,35 +103,38 @@
<p>Unfortunately, actions cannot be specified as a welcome page. Since there
can be a list of pages, the web server looks for each page on the list before
selecting one. The web server doesn't see actions as pages and will never select one
as a welcome page. So, in the case of a welcome page, how do we follow the Struts best
practice of navigating through actions rather than pages?</p>
<p>One solution is to use a server page to "bootstrap" a Struts action. A Java
web application recognizes the idea of "forwarding" from one page to another page (or
action). We can register the usual "index.jsp" as the welcome page and have it forward
to a "welcome" action. Here's the MailReader's index.jsp:</p>
-
- <blockquote>
- <p><code><%@ taglib uri="/tags/struts-logic" prefix="logic" %><br />
- <logic:redirect action="/welcome"/></code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><%@ taglib uri="/tags/struts-logic" prefix="logic" %>
+<logic:redirect action="/welcome"/></code>
+</pre>
+ <hr />
<p>At the top of the page, we import the "struts-logic" JSP tag library.
(Again, see the <a
href="http://jakarta.apache.org/struts/userGuide/preface.html";>Preface to the Struts
User Guide</a> for more about the technologies underlying Struts.) The page itself
consists of a single tag that redirects to the "welcome" action. The tag inserts the
actual web address for the redirect when the page is rendered. But, where does the tag
find the actual address to insert?</p>
<p>The list of actions, along with other Struts components, are registered
through one or more Struts configuration files. The configuration files are written as
XML documents and processed when the application starts. If we just wanted to forward
to the welcome page, we could use a configuration element like this:</p>
-
- <blockquote>
- <p><code><!-- Display welcome page --><br />
- <action path="/welcome" forward="/welcome.jsp" /></code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><!-- Display welcome page -->
+<action path="/welcome" forward="/welcome.jsp" /></code>
+</pre>
+ <hr />
<p>If someone asked for the welcome action ("/welcome.do"), the welcome.jsp
page would be displayed in return.</p>
- <h4>WelcomeAction</h4>
+ <h4><a name="WelcomeAction.java"
id="WelcomeAction.java">WelcomeAction.java</a></h4>
<p>But if we peek at the configuration file for the MailReader, we find a
slightly more complicated XML element for the welcome action:</p>
-
- <blockquote>
- <p><code><!-- Display welcome page --><br />
- <action path="/welcome"<br />
- type="org.apache.struts.webapp.example.WelcomeAction"><br />
- <forward name="failure" path="/Error.jsp" /> <br />
- <forward name="success" path="/welcome.jsp" /> <br />
- </action></code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><!-- Display welcome page -->
+<action path="/welcome"
+ type="org.apache.struts.webapp.example.WelcomeAction">
+ <forward name="failure" path="/Error.jsp" />
+ <forward name="success" path="/welcome.jsp" />
+</action></code>
+</pre>
+ <hr />
<p>Here, the "WelcomeAction" Java class executes whenever someone asks for the
welcome action. As it completes, the Action class can select which page is displayed.
Two pages the class can select here are "Error.jsp" and "welcome.jsp". But the Action
class doesn't need to know the path to the pages. The class can select them just using
the names "success" or "failure".</p>
@@ -144,96 +147,100 @@
<p>The database is exposed to the application as an object stored in
application scope. The database object is based on an interface. Different
implementations of the database could be loaded without changing the rest of the
application. But how is the database object loaded in the first place?</p>
<p>One section of the Struts configuration is devoted to "PlugIns". When a
Struts application loads, it also loads whatever PlugIns are specified in its
configuration. The PlugIn interface is quite simple, and you can use PlugIns to do
anything that might need to be done when your application loads. The PlugIn is also
notified when the application shuts down, so you can release any allocated
resources.</p>
-
- <blockquote>
- <p><code><plug-in
className="org.apache.struts.webapp.example.memory.MemoryDatabasePlugIn"> <br />
- <set-property property="pathname"
value="/WEB-INF/database.xml"/> <br />
- </plug-in></code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><plug-in
className="org.apache.struts.webapp.example.memory.MemoryDatabasePlugIn">
+ <set-property property="pathname" value="/WEB-INF/database.xml"/>
+</plug-in></code>
+</pre>
+ <hr />
<p>By default, the MailReader application loads a "MemoryDatabase"
implementation of the UserDatabase. MemoryDatabase stores the database contents as a
XML document, which is parsed by the Digester and loaded as a set of nested
hashtables. The outer table is the list of user objects, each of which has its own
inner hashtable of subscriptions. When you register, a user object is stored in this
hashtable ... and when you login, the user object is stored within the session
context.</p>
<p>The database comes seeded with a sample user. If you check the database.xml
file under WEB-INF, you'll see the sample user described as:</p>
-
- <blockquote>
- <p><code>
- <user username="user" fromAddress="[EMAIL PROTECTED]"
fullName="John Q. User" password="pass"><br />
- <subscription host="mail.hotmail.com"
autoConnect="false" password="bar" type="pop3" username="user1234"><br />
- </subscription><br />
- <subscription host="mail.yahoo.com"
autoConnect="false" password="foo" type="imap" username="jquser"><br />
- </subscription><br />
- </user>
- </code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><user username="user" fromAddress="[EMAIL PROTECTED]" fullName="John Q.
User" password="pass">
+ <subscription host="mail.hotmail.com" autoConnect="false" password="bar"
type="pop3" username="user1234">
+ </subscription>
+ <subscription host="mail.yahoo.com" autoConnect="false" password="foo"
type="imap" username="jquser">
+ </subscription>
+</user></code>
+</pre>
+ <hr />
<p>This creates a registration record for "John Q. User", with the detail for
his hotmail account (or "subscription").</p>
<h4><a name="MessageResources.properties"
id="MessageResources.properties">MessageResources.properties</a></h4>
<p>Another section of the Struts configuration loads the message resources for
the application. If you change a message in the resource, and then reload the
application, the change will appear throughout the application. If you provide message
resources for additional locales, you can internationalize your application.</p>
-
- <blockquote>
- <p><code><message-resources
parameter="org.apache.struts.webapp.example.MessageResources" /></code></p>
- </blockquote>
+ <hr />
+ <pre>
+<code><message-resources
parameter="org.apache.struts.webapp.example.MessageResources" /></code>
+</pre>
+ <hr />
<p>This is a standard properties text file. Here are the entries used by the
welcome page:</p>
-
- <blockquote>
- <pre>
-index.heading=MailReader Demonstration Application Options
+ <hr />
+ <pre>
+<code>index.heading=MailReader Demonstration Application Options
index.logon=Log on to the MailReader Demonstration Application
index.registration=Register with the MailReader Demonstration Application
index.title=MailReader Demonstration Application (Struts 1.2.1-dev)
-index.tour=A Walking Tour of the MailReader Demonstration Application</pre>
- </blockquote>
+index.tour=A Walking Tour of the MailReader Demonstration Application</code>
+</pre>
+ <hr />
<p>The MailReader application uses a second set of message resources for
non-text elements. The "key" element can be used to access this resource bundle rather
than the default bundle.</p>
+ <hr />
+ <pre>
+<code><message-resources
parameter="org.apache.struts.webapp.example.AlternateMessageResources" key="alternate"
/></code>
+</pre>
+ <hr />
- <blockquote>
- <p><code><message-resources
parameter="org.apache.struts.webapp.example.AlternateMessageResources" key="alternate"
/></code></p>
- </blockquote>
-
-
- <h3>welcome.jsp</h3>
+ <h3><a name="welcome.jsp" id="welcome.jsp">welcome.jsp</a></h3>
<p>After confirming that the necessary resources exist, the WelcomeAction
forwards to the welcome.jsp page.</p>
-
- <blockquote><pre><code><%@ page contentType="text/html;charset=UTF-8"
language="java" %>
-<%@ taglib uri="/tags/struts-bean" prefix="bean" %>
-<%@ taglib uri="/tags/struts-html" prefix="html" %>
-
-<html>
-<head>
-<title><bean:message key="index.title"/></title>
-<link rel="stylesheet" type="text/css" href="base.css" />
-</head>
-
-<h3><bean:message key="index.heading"/></h3>
-<ul>
-<li><html:link action="/editRegistration?action=Create"><br
/><bean:message key="index.registration"/></html:link></li>
-<li><html:link action="/logon"><bean:message
key="index.logon"/></html:link></li>
-</ul>
-
-<h3>Change Language</h3>
-<ul>
-<li><html:link action="/locale?language=en">English</html:link></li>
-<li><html:link action="/locale?language=ja"
useLocalEncoding="true">Japanese</html:link></li>
-<li><html:link action="/locale?language=ru"
useLocalEncoding="true">Russian</html:link></li>
-</ul>
-
-<hr />
-
-<p><html:img bundle="alternate" pageKey="struts.logo.path"
altKey="struts.logo.alt"/></p>
-
-<p><html:link action="/tour"><bean:message
key="index.tour"/></html:link></p>
-
-</body>
-</html></code></pre>
-</blockquote>
+ <hr />
+ <pre>
+<code><%@ page contentType="text/html;charset=UTF-8" language="java" %>
+<%@ taglib uri="/tags/struts-bean" prefix="bean" %>
+<%@ taglib uri="/tags/struts-html" prefix="html" %>
+
+<html>
+<head>
+<title><bean:message key="index.title"/></title>
+<link rel="stylesheet" type="text/css" href="base.css" />
+</head>
+
+<h3><bean:message key="index.heading"/></h3>
+<ul>
+<li><html:link action="/editRegistration?action=Create"><br />
+<bean:message key="index.registration"/></html:link></li>
+<li><html:link action="/logon"><bean:message
key="index.logon"/></html:link></li>
+</ul>
+
+<h3>Change Language</h3>
+<ul>
+<li><html:link
action="/locale?language=en">English</html:link></li>
+<li><html:link action="/locale?language=ja"
useLocalEncoding="true">Japanese</html:link></li>
+<li><html:link action="/locale?language=ru"
useLocalEncoding="true">Russian</html:link></li>
+</ul>
+
+<hr />
+
+<p><html:img bundle="alternate" pageKey="struts.logo.path"
altKey="struts.logo.alt"/></p>
+
+<p><html:link action="/tour"><bean:message
key="index.tour"/></html:link></p>
+
+</body>
+</html></code>
+</pre>
+ <hr />
<p>At the top of the welcome.jsp page, there are several directives that load
the Struts tag libraries. These are just the usual red tape that goes with any JSP
file. The rest of the page demonstrates three Struts JSP tags: "bean:message",
"html:link", and "html:img".</p>
- <p>The bean:message tag inserts a message from the MessageResources file. The
MailReader comes with support for three locales: English (the default), Russian, and
Japanese. If the Struts locale setting is changed for a user, the bean:message tag
will render messages from that locale's property bundle instead. </p>
+ <p>The bean:message tag inserts a message from the MessageResources file. The
MailReader comes with support for three locales: English (the default), Russian, and
Japanese. If the Struts locale setting is changed for a user, the bean:message tag
will render messages from that locale's property bundle instead.</p>
<p>The html:link tag does double duty. First, you can refer to an action or
forward stored in the Struts configuration, and the tag will insert the corresponding
path when the page is rendered. This makes it easy to "rewire" an application without
touching all the pages. Second, the link tag will "URL encode" the hyperlink to
maintain the client session. Your application can maintain client state without
requiring cookies.</p>
@@ -257,128 +264,271 @@
<h3><a name="logon.jsp" id="logon.jsp">logon.jsp</a></h3>
- <p>If you choose the logon link, the container loads the logon.jsp file. You
can use the default username and password (user:pass) to login. (Note that both the
username and password are case sensitive.) Better yet, try omitting or misspelling the
login in various combinations and see how the application reacts.</p>
+ <p>If you choose the logon link, the Logon action forwards control to the
logon.jsp page. The logon page displays a form that accepts a username and password.
You can use the default username and password to logon (user and pass). Note that both
the username and password are case sensitive. Better yet, try omitting or misspelling
the username and password in various combinations and see how the application
reacts.</p>
- <p>If you do this, Struts will return you to the same JSP, but with three major
differences:</p>
+ <p>Once you enter the correct username and password combination, the
LogonAction will send you to the main menu. Note that whatever username you entered
before is defaulted on the form.</p>
- <ol>
- <li>The page address is now logon.do rather than login.jsp.</li>
-
- <li>Struts will display a validation-error above the logon form.</li>
+ <p>Now that we've gotten through a logon, let's backtrack and take a look at
the logon.jsp.</p>
+ <hr />
+ <pre>
+<code><%@ page contentType="text/html;charset=UTF-8" language="java" %>
+<%@ taglib uri="/tags/struts-bean" prefix="bean" %>
+<%@ taglib uri="/tags/struts-html" prefix="html" %>
+
+<html:xhtml/>
+<html>
+<head>
+<title><bean:message key="logon.title"/></title>
+</head>
+
+<html:errors/>
+
+<html:form action="/submitLogon" focus="username"
+ onsubmit="return validateLogonForm(this);">
+<table border="0" width="100%">
+
+ <tr>
+ <th align="right">
+ <bean:message key="prompt.username"/>:
+ </th>
+ <td align="left">
+ <html:text property="username" size="16" maxlength="18"/>
+ </td>
+ </tr>
+
+ <tr>
+ <th align="right">
+ <bean:message key="prompt.password" bundle="alternate"/>:
+ </th>
+ <td align="left">
+ <html:password property="password" size="16" maxlength="18"
+ redisplay="false"/>
+ </td>
+ </tr>
+
+ <tr>
+ <td align="right">
+ <html:submit property="Submit" value="Submit"/>
+ </td>
+ <td align="left">
+ <html:reset/>
+ </td>
+ </tr>
+
+</table>
+
+</html:form>
+
+<html:javascript formName="logonForm"
+ dynamicJavascript="true"
+ staticJavascript="false"/>
+<script language="Javascript1.1" src="staticJavascript.jsp"></script>
+
+<jsp:include page="footer.jsp" />
+</body>
+</html></code>
+</pre>
+ <hr />
+
+ <p>We saw some of these tags on the welcome page. Let's focus on the new
tags.</p>
+
+ <p>The first new tag on the logon page is html:errors. If a person enters
incorrect credentials, then the LogonAction will post an appropriate error message. If
the html:errors tag sees that one or more messages were posted, the tag ouputs the
messages to the page. The text of the messages can be specified in the MessageResource
bundle, making them easy to internationalize.</p>
+
+ <p>The second new tag is html:form. This tag renders a html form tag. The
"action" element tells the tag to use "logonSubmit.do" for the form's action. The
"focus" attribute tells the tag to generate a little Javascript after the form that
sets its focus to the "username" field. The "onsubmit" attribute tells the form to run
a Javascript when the form is submitted. (Just like the corresponding attribute on the
standard form tag.)</p>
+
+ <p>Within the html:form tag, we see four other new tags: "html:text",
"html:password", "html:submit", and "html:reset".</p>
+
+ <p>The html:text tag renders a "input type=text" tag. The "property" attribute
becomes the input tag's "name" attribute.</p>
+
+ <p>The html:password tag renders a "input type=password" tag. The "redisplay"
attribute tell the tag not to render the password back into the file, if the submit
fails. The html:submit and html:reset tags renders buttons of the corresponding
types.</p>
+
+ <p>Following the form is a html:javascript tag. This tag works with the Struts
Validator component to generate a JavaScript that can validate input before it is
submitted to the LogonAction.</p>
+
+ <blockquote>
+ <p><font class="note">Most of these tags have many more options than the ones
we use in this application. For the complete documentation for each tag, see the Tag
Developers Guides in the Struts documentation bundle.</font></p>
+ </blockquote>
+
+ <p>But, how do these tags know so much? How does the Javascript tag know what
scripts to write? How do the text and password tags know what values to redisplay?</p>
+
+ <p>For the answers, we need to turn to the Struts configuration files.</p>
+
+ <h4><a name="struts-config.xml"
id="struts-config.xml">struts-config.xml</a></h4>
+
+ <p>In the struts-config.xml file, we find an element for the "/logonSubmit"
action</p>
+ <hr />
+ <pre>
+<code><!-- Process a user logon -->
+<action path="/submitLogon"
+ type="org.apache.struts.webapp.example.LogonAction"
+ name="logonForm"
+ scope="request"
+ input="logon">
+ <exception
+ key="expired.password"
+ type="org.apache.struts.webapp.example.ExpiredPasswordException"
+ path="/expiredPassword.do"/>
+ </action></code>
+</pre>
+ <hr />
+
+ <p>We saw the path and type attributes in the welcome action. Let's look at the
new attributes.</p>
+
+ <p>The "name" attribute specifies something Struts calls an "ActionForm". The
ActionForm buffers input from a form and delivers it to an Action class as an object.
The ActionForm can also validate the input. If validation fails, the tags can rewrite
the input values from the ActionForm.</p>
+
+ <p>The ActionForms are defined in the "formbeans" section of the configuration
file. Here's the formbean element for the "logonForm".</p>
+ <hr />
+ <pre>
+<code><form-bean name="logonForm"
+ type="org.apache.struts.validator.DynaValidatorForm">
+ <form-property name="username" type="java.lang.String"/>
+ <form-property name="password" type="java.lang.String"/>
+</form-bean></code>
+</pre>
+ <hr />
+
+ <p>ActionForms can be "conventional" or "dynamic". Here, we are using a dynamic
ActionForm. Rather than cobble up an actual JavaBean class, we specify the properties
the ActionForm can accept in the configuration file. If the property is not specified
here, it is not captured, validated, or passed up to the Action class.</p>
+
+ <p>Struts creates the ActionForms automatically. The "scope" attribute in the
action element tells the controller wether to store the ActionForm in the request or
in the user's session.</p>
+
+ <blockquote>
+ <p><font class="note">The Struts best practice is to use request scope for
single-page forms that contain all the properties needed by the Action. There is
usually no need to maintain form data across requests.</font></p>
+ </blockquote>
+
+ <p>Struts can also validate the ActionForm automatically. If validation fails,
Struts looks for the forward specified by the "input" attribute. In this case, the
"logon" forward sends control back to the input.jsp page.</p>
+ <hr />
+ <pre>
+<code><forward name="logon" path="/logon.do"/></code>
+</pre>
+ <hr />
+
+ <p>Within the logon action element is another new element, "exception". When a
user logons on, it's possible that an "ExpiredPasswordException" will be thrown.
Should this happen, Struts will capture the exception and send control to the
"ExpiredPassword" action.</p>
+
+ <h4><a name="validations.xml" id="validations.xml">validations.xml</a></h4>
+
+ <p>In the logon.jsp, we mentioned that the html:javascript tag confers with the
Struts Validator components. The Validator is configured through another XML document,
the "validation.xml". Here's the element for our logonForm:</p>
+ <hr />
+ <pre>
+<code><form name="logonForm">
+
+ <field property="username"
+ depends="required">
+ <arg0 key="prompt.username"/>
+ </field>
+
+ <field property="password"
+ depends="required, minlength,maxlength">
+ <arg0 key="prompt.password"/>
+ <arg1 key="${var:minlength}" name="minlength"
+ resource="false"/>
+ <arg2 key="${var:maxlength}" name="maxlength"
+ resource="false"/>
+ <var>
+ <var-name>maxlength</var-name>
+ <var-value>16</var-value>
+ </var>
+ <var>
+ <var-name>minlength</var-name>
+ <var-value>3</var-value>
+ </var>
+ </field>
+
+</form></code>
+</pre>
+ <hr />
- <li>Whatever username you entered before is defaulted on the form.</li>
- </ol>
+ <p>The field elements correspond to the ActionForm properties. The "username"
field element says it depends on the "required" validator. If the username is blank or
absent, validation will fail and an error message is automatically generated.</p>
- <p>Pretty cool, but how does it work?</p>
+ <p>The "password" field (or property) is also required. In addition, it must
also pass the "maxlength" and "minlength" validations. Here, the minimum length is
three characters and the maximum length is sixteen. If the length of the password
doesn't meet these criteria, a corresponding error message is generated. Of course,
the messages are generated from the MessageResource bundles and are easy to
localize.</p>
- <h4><a name="struts-config.xml" id="struts-config.xml">struts-config.xml</a>
and <a name="LogonForm.java" id="LogonForm.java">LogonForm.java</a></h4>
-
- <p>First, the logon.jsp makes use of the custom-tag "form". This tag can scan
the application's properties for a form bean related to the path /logon.jsp (from the
link on the welcome page). In this case, Struts finds one, and then checks for an
instance of this particular form bean. Not finding one, Struts creates a new form
bean. When the form is submitted, Struts grabs the form fields from the HTTP request,
and updates the waiting bean.</p>
-
- <p>To enable all this, you can simply</p>
-
- <ol>
- <li>define a class for the form bean in your package (the form fields with
setters and getters),</li>
-
- <li>add the bean class to your application's configuration resource, and</li>
-
- <li>link the bean class to your action mapping by their name properties
(name="logonForm").</li>
- </ol>
+ <h4><a name="LogonAction.java" id="LogonAction.java">LogonAction.java</a></h4>
- <p>In addition to parameters representing standard HTML options, The form tag
can also take several handy parameters to add JavaScript features to a form. These
include focus, onsubmit, and onreset. There are even parameters for specifying
cascading stylesheets.</p>
+ <p>If validation passes, the logonForm is forwarded to the LogonAction. The
LogonAction interacts with the database to see if the credentials are valid. If so,
the user is logged on, and control passes to the "success" forward. Otherwise, control
is forwarded to the input page and the list of error messages displayed.</p>
- <p>Struts has tidy mechanisms for validating forms and printing error messages.
An action object can add as many messages as needed to a standard Struts collection.
The JSP can then print all the messages, and clear the queue, using a single custom
tag, <html:errors/>. There can be as many messages as your validation routine cares
to post.</p>
+ <p>Here's the LogonAction (sans comments):</p>
- <blockquote>
- <p><i>Struts labels this mechanism as an error message handler, though your
application could use it for other messages too. For example, to post a message than a
record was added or deleted.</i></p>
- </blockquote>
+ <hr />
- <p>To get the most out of your form beans, Struts provides a special class,
ActionForm, with built-in support for validation and message handling that you can use
as the base for your own form beans. Each of your JSP forms will probably have a
unique set of fields, and would have their own specific form bean.</p>
+<pre><code>package org.apache.struts.webapp.example;
+import ...
- <h4><a name="LogonAction.java" id="LogonAction.java">LogonAction.java</a></h4>
-
- <p>The initial JSP submits its form to logon.do. If you check the servlet
mappings in the example's web.xml you will see that requests for *.do files are
directed to the Struts "action" servlet (an instance of ActionServlet). In the
example, the ActionServlet refers to struts-config.xml for its own mappings (among
other things), which is where we find the reference to logon.do:</p>
-
- <blockquote>
- <p><code><!-- Process a user logon --><br />
- <action<br />
- path="/logon"<br />
- type="org.apache.struts.webapp.example.LogonAction"<br />
- name="logonForm"<br />
- scope="request"<br />
- input="/logon.jsp"<br />
- ><br />
- </action></code></p>
- </blockquote>
+public final class LogonAction extends BaseAction {
- <p>and a form bean to go with the "logonForm" action:</p>
+ private static String USERNAME = "username";
+ private static String PASSWORD = "password";
- <blockquote>
- <p><code><!-- Logon form bean --><br />
- <form-bean<br />
- name="logonForm"<br />
- type="org.apache.struts.webapp.example.LogonForm"<br />
- /></code></p>
- </blockquote>
+ protected User getUser(UserDatabase database, String username,
+ String password, ActionMessages errors)
+ throws ExpiredPasswordException {
- <p>In the action mapping, the path property tells the ActionServlet to forward
a request for logon.do to the LogonAction object. The input property tells the
LogonAction object where it can pass control to get information from the user.</p>
+ User user = null;
+ if (database == null){
+ errors.add(
+ ActionMessages.GLOBAL_MESSAGE,
+ new ActionMessage("error.database.missing"));
+ }
+ else {
+ user = database.findUser(username);
+ if ((user != null) && !user.getPassword().equals(password)) {
+ user = null;
+ }
+ if (user == null) {
+ errors.add(
+ ActionMessages.GLOBAL_MESSAGE,
+ new ActionMessage("error.password.mismatch"));
+ }
+ }
- <p>Before passing the request to LogonAction, the ActionServlet looks for the
LogonForm bean. If it finds it, the ActionServlet updates the bean by matching
properties named in the HTTP request with properties named in the form bean. If it
doesn't find the bean, ActionServlet creates it, so LogonAction can assume that it
already exists.</p>
+ return user;
- <p>When called by the ActionServlet, LogonAction retrieves the username and
password from the LogonForm bean. (If just created, the bean will return default
values.)</p>
+ }
- <p>In the example, LogonAction then checks with the DatabaseServlet to see if
the logon matches a registered user. If the logon doesn't match, LogonAction adds a
message key to an error list. At the end of the routine, if the error list is not
empty, LogonAction adds a User bean to the session context, and forwards control to
its input form (login.jsp).</p>
+ protected void SaveUser(HttpServletRequest request, User user) {
- <blockquote>
- <p><i>Note that direct access to the DatabaseServlet should really be handled
by a business-logic bean, and NOT by LogonAction. To quote the example's author "This
should be considered a bug in the example."</i></p>
- </blockquote>
+ HttpSession session = request.getSession();
- <p>If there are no errors, LogonAction places a user bean into the session
context (replacing any prior user bean), and forwards control to the "success" action.
Where that control actually goes is determined by the mappings in
struts-config.xml.</p>
+ session.setAttribute(Constants.USER_KEY, user);
+ if (log.isDebugEnabled()) {
+ log.debug(
+ "LogonAction: User '"
+ + user.getUsername()
+ + "' logged on in session "
+ + session.getId());
+ }
- <p>Before returning from a successful login, LogonAction also disposes of the
LogonForm bean. This way, if the user returns to the index.jsp form later, it will be
a clean form without the (old) login already entered. Note that LogonAction first
checks to see if the scope has been set to "request", and then removes the bean from
the request context, or otherwise from the default session context.</p>
+ }
- <blockquote>
- <p><i>The Struts best practice is to use request scope for single-page forms
that contain all of your relevant properties, because there is no need to maintain
such form beans across requests.</i></p>
+ public ActionForward execute(
+ ActionMapping mapping,
+ ActionForm form,
+ HttpServletRequest request,
+ HttpServletResponse response)
+ throws Exception {
- <p><i>Note that the example removes the LogonForm bean regardless of scope.
This is for backward compatibility with earlier configurations. In your application,
you should follow the advice of the configuration, and remove it only if the scope is
set to "request". This way, the behavior can be changed just by editing
struts-config.xml and reloading the application.</i></p>
- </blockquote>
+ UserDatabase database = getUserDatabase(request);
+ String username = (String) PropertyUtils.getSimpleProperty(form,
+ USERNAME);
+ String password = (String) PropertyUtils.getSimpleProperty(form,
+ PASSWORD);
+ ActionMessages errors = new ActionMessages();
- <p>Go ahead and login successfully now, using the default username and password
(user and pass).</p>
+ User user = getUser(database,username,password,errors);
- <h4><a name="struts-config.xml_2" id="struts-config.xml_2">struts-config.xml
2</a></h4>
+ SaveUser(request,user);
- <p>As mentioned, on a successful login, LogonAction forwards control to the
"success" action, and where control actually goes is determined by the mappings in
struts-config.xml. But if you check the mappings for LogonAction, you'll find this
block</p>
+ if (!errors.isEmpty()) {
+ this.saveErrors(request, errors);
+ return (mapping.getInputForward());
+ }
- <blockquote>
- <p><code><!-- Process a user logon --><br />
- <action<br />
- path="/logon"<br />
- type="com.husted.struts.example2.LogonAction"<br />
- name="logonForm"<br />
- scope="request"<br />
- input="/logon.jsp"><br />
- </action></code></p>
- </blockquote>
+ return (findSuccess(mapping));
- <p><i>Huh!? Where's the success mapping?</i> If you dig around, you'll also
find</p>
+ }</code></pre>
- <blockquote>
- <p><code><!-- Global Forward Definitions --><br />
- <global-forwards><br />
- <forward<br />
- name="logon"<br />
- path="/logon.jsp"<br />
- /><br />
- <forward<br />
- name="success"<br />
- path="/mainMenu.jsp"<br />
- /><br />
- </global-forwards></code></p>
- </blockquote>
+ <hr />
- <p>Which says, if somebody says forward to "success", and doesn't have a local
forward for "success", then forward using the path "/mainMenu.jsp". (Ditto for forward
to "logon", but forward to "/logon.jsp".)</p>
+ <h4><a name="mainMenu.jsp" id="mainMenu.jsp">mainMenu.jsp</a></h4>
- <p>And which is why you should be now be staring at the result of the
mainMenu.jsp now, offering the choices</p>
+ <p>On a successful logon, the main menu page displays, offering the choices</p>
<ul>
<li>Edit your user registration profile</li>
@@ -398,7 +548,7 @@
<h4><a name="CheckLoginTag.java"
id="CheckLoginTag.java">CheckLoginTag.java</a></h4>
- <p>This is an excellent example of using custom tags to encapsulate application
logic. CheckLoginTag.java looks to see if the user is logged in by checking for an
object named "User" in the session context. If not, control is forwarded to
"/login.jsp". So, whenever you want to be sure someone is logged in before they access
a page, just put "<app:checkLogon/>" at the top of the JSP.</p>
+ <p>This is an excellent example of using custom tags to encapsulate application
logic. CheckLoginTag.java looks to see if the user is logged in by checking for an
object named "User" in the session context. If not, control is forwarded to
"/login.jsp". So, whenever you want to be sure someone is logged in before they access
a page, just put "<app:checkLogon/>" at the top of the JSP.</p>
<blockquote>
<p><i>If you take a good look at the CheckLoginTag source, you will probably
see a quick and easy way the code could be made easier to maintain.</i></p>
@@ -423,19 +573,19 @@
<p>If you check the struts-config.xml, you'll see that the editRegistration
action is mapped to the (surprise again!), the EditRegistrationAction; it uses a
registrationForm bean, and registration.jsp for input.</p>
<blockquote>
- <p><code><!-- Registration form bean --><br />
+ <p><code><!-- Registration form bean --><br />
<form-bean name="registrationForm"<br />
- type="org.apache.struts.webapp.example.RegistrationForm"/></code></p>
+ type="org.apache.struts.webapp.example.RegistrationForm"/></code></p>
- <p><code><!-- Edit user registration --><br />
+ <p><code><!-- Edit user registration --><br />
<action path="/editRegistration"<br />
type="org.apache.struts.webapp.example.EditRegistrationAction"<br />
name="registrationForm"<br />
scope="request"<br />
validate="false"<br />
- input="/registration.jsp"><br />
- <forward name="success" path="/registration.jsp"/><br />
- </action></code></p>
+ input="/registration.jsp"><br />
+ <forward name="success" path="/registration.jsp"/><br />
+ </action></code></p>
<p><i>Hint: Consistent naming conventions, like the ones used throughout the
Example, make applications much easier to write and understand. Save your creativity
for the things that matter, and follow an established standard for source code
formatting, like the <a href="www.amazon.com/exec/obidos/ISBN=0521777682/">Elements of
Java Style</a>.</i></p>
</blockquote>
@@ -460,9 +610,9 @@
property="action"<br />
scope="request"<br />
value="Edit"<br />
- ><br />
- <app:checkLogon/><br />
- </logic:equal></code></p>
+ ><br />
+ <app:checkLogon/><br />
+ </logic:equal></code></p>
<p><i>Note that the Struts html:form tag will refer to properties set by
struts-config.xml and automatically create a registrationForm bean if one is not
present. However, that does not happen until the form tag is processed within the
page. Since this block appears before the html:form tag, a runtime error is exposed if
you try to access registration.jsp directly (rather then going through the
editRegistration.do action).</i></p>
</blockquote>
@@ -481,7 +631,7 @@
property="action"<br />
scope="request"<br />
value="Edit"<br />
- ></code></p>
+ ></code></p>
</blockquote>
<p>Otherwise, the page just contains the top portion -- a blank data-entry form
for creating the user's registration.</p>
@@ -493,9 +643,9 @@
<p>The subscriptions are stored in a hashtable object, which is in turn stored
in the user object. So to display each subscription, we have to reach into the user
object, and loop through the members of the subscription collection. Using the iterate
tag, this couldn't be easier.</p>
<blockquote>
- <p><logic:iterate name="user" property="subscriptions"
id="subscription"><br />
- <!-- block to repeat --><br />
- </logic:iterate></p>
+ <p><logic:iterate name="user" property="subscriptions"
id="subscription"><br />
+ <!-- block to repeat --><br />
+ </logic:iterate></p>
</blockquote>
<p>The three parameters to the iterate tag ( name, property, and id) tell it
to</p>
@@ -511,13 +661,13 @@
<p>So, to list the host for each subscription in a HTML unordered list, we
could write:</p>
<blockquote>
- <p><code><ul><br />
- <logic:iterate name="user" property="subscriptions" id="subscription"><br
/>
- <li><br />
- <bean:write name="subscription" property="host" filter="true" /><br />
- </li><br />
- </logic:iterate><br />
- </ul></code></p>
+ <p><code><ul><br />
+ <logic:iterate name="user" property="subscriptions"
id="subscription"><br />
+ <li><br />
+ <bean:write name="subscription" property="host" filter="true" /><br />
+ </li><br />
+ </logic:iterate><br />
+ </ul></code></p>
<p><i>This is another good example of how Struts works with the standard JSP
tags, like bean. The filter option says to use convert HTML commands to their
character entity. So a < would be output in the HTML as &lt;.</i></p>
</blockquote>
@@ -525,30 +675,30 @@
<p>In registration.jsp, iterate is used to create a menu of subscriptions, each
linked with an edit and delete action.</p>
<blockquote>
- <p><code><logic:iterate id="subscription" name="user"
property="subscriptions"><br />
- <tr><br />
- <td align="left"><br />
- <bean:write name="subscription" property="host" filter="true"/><br />
- </td><br />
- <td align="left"><br />
- <bean:write name="subscription" property="username" filter="true"/><br />
- </td><br />
- <td align="center"><br />
- <bean:write name="subscription" property="type" filter="true"/><br />
- </td><br />
- <td align="center"><br />
- <bean:write name="subscription" property="autoConnect"/><br />
- </td><br />
- <td align="center"><br />
- <app:linkSubscription page="/editSubscription.do?action=Delete"><br />
- <bean:message key="registration.deleteSubscription"/><br />
- </app:linkSubscription><br />
- <app:linkSubscription page="/editSubscription.do?action=Edit"><br />
- <bean:message key="registration.editSubscription"/><br />
- </app:linkSubscription><br />
- </td><br />
- </tr><br />
- </logic:iterate></code></p>
+ <p><code><logic:iterate id="subscription" name="user"
property="subscriptions"><br />
+ <tr><br />
+ <td align="left"><br />
+ <bean:write name="subscription" property="host" filter="true"/><br />
+ </td><br />
+ <td align="left"><br />
+ <bean:write name="subscription" property="username" filter="true"/><br
/>
+ </td><br />
+ <td align="center"><br />
+ <bean:write name="subscription" property="type" filter="true"/><br />
+ </td><br />
+ <td align="center"><br />
+ <bean:write name="subscription" property="autoConnect"/><br />
+ </td><br />
+ <td align="center"><br />
+ <app:linkSubscription page="/editSubscription.do?action=Delete"><br />
+ <bean:message key="registration.deleteSubscription"/><br />
+ </app:linkSubscription><br />
+ <app:linkSubscription page="/editSubscription.do?action=Edit"><br />
+ <bean:message key="registration.editSubscription"/><br />
+ </app:linkSubscription><br />
+ </td><br />
+ </tr><br />
+ </logic:iterate></code></p>
<p><i>The collection in an iterate tag can be any of the following: an array
of objects, an Iterator, a Collection (which includes Lists, Sets and Vectors), or a
Map (which includes Hashtables) whose elements will be iterated over.</i></p>
</blockquote>
@@ -560,16 +710,16 @@
<p>The Example application uses a subscription's host name (e.g. yahoo.com) as
a primary key, which means you can only have one subscription for each host. It also
means that to edit a subscription, all you need to know is the user and host. In fact,
the editSubscription action is designed to create, edit, or delete a subscription if
provided a user and host names in the request. The goal of LinkSubscriptionTag is then
to output a block like:</p>
<blockquote>
- <p><code><A
HREF=[path]editSubscription.do?action=[action]&username=[user]&host=[host]">[action]<br
/>
- </A></code></p>
+ <p><code><A
HREF=[path]editSubscription.do?action=[action]&username=[user]&host=[host]">[action]<br
/>
+ </A></code></p>
</blockquote>
<p>based on input block like:</p>
<blockquote>
<p><code><app:linkSubscription<br />
- page="/editSubscription.do?action=Delete">Delete<br />
- </app:linkSubscription></code></p>
+ page="/editSubscription.do?action=Delete">Delete<br />
+ </app:linkSubscription></code></p>
</blockquote>
<p>To reduce overhead, LinkSubscriptionTag uses "subscription" as the default
name (which the iterator refers to as "ID"), so that can be omitted from the tag
properties. The "action" portion of the will differ, and so that is given as the page
property to the tag</p>
@@ -592,9 +742,9 @@
<p>Meanwhile, back on registration.jsp, there is one more link on the page.
This uses yet another custom tag, the app:linkUser tag.</p>
<blockquote>
- <p><code><app:linkUser page="/editSubscription.do?action=Create"><br />
- <bean:message key="registration.addSubscription"/><br />
- </app:linkUser></code></p>
+ <p><code><app:linkUser page="/editSubscription.do?action=Create"><br />
+ <bean:message key="registration.addSubscription"/><br />
+ </app:linkUser></code></p>
</blockquote>
<p>By this time, you must be ready to flip directly to LinkUserTag.java with
nary a glance at the configuration file ...</p>
@@ -604,17 +754,17 @@
<p>Since they solve the same general problem, LinkUserTag and
LinkSubscriptionTag are quite a bit a like, except that LinkUserTag grabs the user
bean from the session context, instead of a subscription bean from the iteration. Like
the LinkSubscriptionTag, the name for the user bean (e.g. "user") is defaulted, and
can be omitted from the tag; all that's needed is the page property -- the rest is
automatic!</p>
<blockquote>
- <p><code><app:linkUser page="/editSubscription.do?action=Create"><br />
- <bean:message key="registration.addSubscription"/><br />
- </app:linkUser></code></p>
+ <p><code><app:linkUser page="/editSubscription.do?action=Create"><br />
+ <bean:message key="registration.addSubscription"/><br />
+ </app:linkUser></code></p>
</blockquote>
<p>When rendered, this displays a HTML hypertext link like:</p>
<blockquote>
- <p><code><a
href="/struts-example/editSubscription.do?action=Create&amp;username=user"><br />
+ <p><code><a
href="/struts-example/editSubscription.do?action=Create&amp;username=user"><br
/>
Add<br />
- </a></code></p>
+ </a></code></p>
<p><i>Note that anchor links with ampersands should use the character entity
&amp; as the LinkUserTag has done here (<a
href="http://www.w3.org/TR/html401/appendix/notes.html#h-B.2.2";>http://www.w3.org/TR/html401/appendix/notes.html#h-B.2.2</a>).</i></p>
</blockquote>
@@ -626,22 +776,22 @@
<p>Predictably, we find a some now-familiar mappings in struts-config.xml</p>
<blockquote>
- <p><code><!-- Subscription form bean --><br />
+ <p><code><!-- Subscription form bean --><br />
<form-bean<br />
name="subscriptionForm"<br />
type="org.apache.struts.webapp.example.SubscriptionForm"<br />
- /></code></p>
+ /></code></p>
- <p><code><!-- Edit mail subscription --><br />
+ <p><code><!-- Edit mail subscription --><br />
<action path="/editSubscription"<br />
type="org.apache.struts.webapp.example.EditSubscriptionAction"<br />
name="subscriptionForm"<br />
scope="request"<br />
validate="false"<br />
- ><br />
- <forward name="failure" path="/mainMenu.jsp"/><br />
- <forward name="success" path="/subscription.jsp"/><br />
- </action></code></p>
+ ><br />
+ <forward name="failure" path="/mainMenu.jsp"/><br />
+ <forward name="success" path="/subscription.jsp"/><br />
+ </action></code></p>
<p><i>When we've introduced these type of mappings before, and mentioned that
the struts-config.xml was parsed when the ActionServlet was initialized. But we should
make it clear that when the Struts digester parsed this file, it actually created
standard Java objects, linked as properties to the controller. This means you don't
have to edit Java source files just to add a bunch of "new" statements. (How cool is
that?)</i></p>
</blockquote>
@@ -669,22 +819,22 @@
<p>In registration.jsp, the Struts iteration tag was used to write a list of
subscriptions. Another place where iterations and collections are handy is the option
list for a HTML select tag. Since this is such a common situation, Struts offers a
html:options (plural) tag can take an array of objects as a parameter. The tag then
iterates over the members of the array (beans) to place each one inside an standard
option tag. So given a block like</p>
<blockquote>
- <p><code><html:select property="type"><br />
+ <p><code><html:select property="type"><br />
<html:options<br />
collection="serverTypes"<br />
property="value"<br />
labelProperty="label"<br />
- /><br />
- </html:select></code></p>
+ /><br />
+ </html:select></code></p>
</blockquote>
<p>Struts outputs a block like</p>
<blockquote>
- <p><code><select name="type"><br />
- <option value="imap" selected>IMAP Protocol</option><br />
- <option value="pop3">POP3 Protocol</option><br />
- </select></code></p>
+ <p><code><select name="type"><br />
+ <option value="imap" selected>IMAP Protocol</option><br />
+ <option value="pop3">POP3 Protocol</option><br />
+ </select></code></p>
</blockquote>
<p>Here, one collection contained both the labels and the values, from
properties of the same name. Options can also use a second array for the labels, if
they do not match the values. Options can use a Collection, Iterator, or Map for the
source of the list.</p>
@@ -714,10 +864,10 @@
name="subscriptionForm"<br />
property="action"<br />
scope="request"<br />
- value="Create"><br />
- <html:submit><br />
- <b><bean:message key="button.save"/><br /></b> </html:submit><br />
- </logic:equal></code></p>
+ value="Create"><br />
+ <html:submit><br />
+ <b><bean:message key="button.save"/><br /></b> </html:submit><br
/>
+ </logic:equal></code></p>
</blockquote>
<p>In the case of a request to delete a subscription, the submit button is
labeled "Confirm", since this view is meant to give the user a last chance to cancel,
before sending that task along to SaveSubscriptionAction.java.</p>
1.41 +10 -5 jakarta-struts/web/example/WEB-INF/struts-config.xml
Index: struts-config.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/web/example/WEB-INF/struts-config.xml,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- struts-config.xml 10 Mar 2004 03:14:31 -0000 1.40
+++ struts-config.xml 12 Mar 2004 02:44:34 -0000 1.41
@@ -89,12 +89,12 @@
<action path="/submitLogon"
type="org.apache.struts.webapp.example.LogonAction"
name="logonForm"
- scope="session"
+ scope="request"
input="logon">
<exception
key="expired.password"
type="org.apache.struts.webapp.example.ExpiredPasswordException"
- path="/changePassword.jsp"/>
+ path="/ExpiredPassword.do"/>
</action>
<!-- Process a user logoff -->
@@ -122,6 +122,11 @@
<forward name="subscription" path="/subscription.jsp"/>
<forward name="success" path="/editRegistration.do?action=Edit"/>
</action>
+
+ <!-- Display the change password page when a password expires -->
+ <action path="/ExpiredPassword"
+ forward="/changePassword.jsp">
+ </action>
<!-- Display the "walking tour" documentation -->
<action path="/tour"
1.12 +2 -14 jakarta-struts/web/example/WEB-INF/validation.xml
Index: validation.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/web/example/WEB-INF/validation.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- validation.xml 7 Feb 2004 00:09:33 -0000 1.11
+++ validation.xml 12 Mar 2004 02:44:34 -0000 1.12
@@ -19,20 +19,8 @@
<form name="logonForm">
<field property="username"
- depends="required, minlength,maxlength">
+ depends="required">
<arg0 key="prompt.username"/>
- <arg1 key="${var:minlength}" name="minlength"
- resource="false"/>
- <arg2 key="${var:maxlength}" name="maxlength"
- resource="false"/>
- <var>
- <var-name>maxlength</var-name>
- <var-value>16</var-value>
- </var>
- <var>
- <var-name>minlength</var-name>
- <var-value>3</var-value>
- </var>
</field>
<field property="password"
1.2 +62 -6 jakarta-struts/web/example/WEB-INF/webtest.xml
Index: webtest.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/web/example/WEB-INF/webtest.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- webtest.xml 9 Mar 2004 04:43:12 -0000 1.1
+++ webtest.xml 12 Mar 2004 02:44:34 -0000 1.2
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!DOCTYPE project SYSTEM "WebTest.dtd" [
- <!ENTITY config SYSTEM "entities/config.xml">
+ <!ENTITY config SYSTEM "entities/config-debug.xml">
<!ENTITY taskdef-webtest SYSTEM "entities/taskdef-webtest.xml">
]>
<!--
@@ -57,7 +57,7 @@
</classpath>
</taskdef>
- <target name="default" depends="welcome" />
+ <target name="default" depends="welcome,logon" />
<target name="welcome"
description="Welcome page">
@@ -83,7 +83,63 @@
<clicklink label="${index.title}" />
</steps>
</testSpec>
+ </target>
+ <target name="logon"
+ description="Logon page">
+
+ <testSpec name="Open logon action">
+ &config;
+ <steps>
+ <invoke
+ stepid="Pass logon"
+ url="/logon.do" />
+ <verifytitle
+ stepid="Logon page title"
+ text="${logon.title}" />
+ <setinputfield
+ stepid="username"
+ name="username"
+ value="user" />
+ <setinputfield
+ stepid="password"
+ name="password"
+ value="pass" />
+ <clickbutton
+ stepid="Submit"
+ name="Submit">
+ <form name="logonForm" />
+ </clickbutton>
+ </steps>
+ </testSpec>
+
+ <testSpec name="Fail logon">
+ &config;
+ <steps>
+ <invoke
+ stepid="Open logon action"
+ url="/logon.do" />
+ <verifytitle
+ stepid="Logon page title"
+ text="${logon.title}" />
+ <setinputfield
+ stepid="username"
+ name="username"
+ value="xxxx" />
+ <setinputfield
+ stepid="password"
+ name="password"
+ value="xxxx" />
+ <clickbutton
+ stepid="Submit"
+ name="Submit">
+ <form name="logonForm" />
+ </clickbutton>
+ <verifytitle
+ stepid="Logon page title"
+ text="${logon.title}" />
+ </steps>
+ </testSpec>
</target>
</project>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
