~ubuntu-branches/ubuntu/trusty/libstruts1.2-java/trusty-proposed

This article is meant to introduce a new user to Struts by "walking through" an application. See the <a href="http://jakarta.apache.org/struts/">Struts Users Guide and Strut's API</a> for more documentation.

The MailReader application is based on the 1.2.0 build of Struts. To follow along, you should install the MailReader application on your own development workstation (e.g. localhost).

The article assumes the reader has a basic understanding of the Java language, JavaBeans, web applications, and JavaServer Pages. For background on these technologies, see the <a href="http://jakarta.apache.org/struts/userGuide/preface.html">Preface to the Struts User Guide</a>.

<hr />

<ul>

<li>

<a href="#index.jsp">index.jsp</a>

<ul>

<li><a href="#web.xml">web.xml and ApplicationResources.properties</a></li>

<li><a href="#DatabaseServlet.java">DatabaseServlet.java</a></li>

</ul>

</li>

<li>

<a href="#logon.jsp">logon.jsp</a>

<ul>

<li><a href="#struts-config.xml">struts-config.xml</a></li>

<li><a href="#struts-config.xml">LogonForm.java</a></li>

<li><a href="#LogonAction.java">LogonAction.java</a></li>

<li><a href="#struts-config.xml/2">struts-config.xml 2</a></li>

</ul>

</li>

<li>

<a href="#mainMenu.jsp">mainMenu.jsp</a>

<ul>

<li><a href="#CheckLoginTag.java">CheckLoginTag.java</a></li>

<li><a href="#editRegistrationAction.java">editRegistrationAction.java</a></li>

</ul>

</li>

<li>

<a href="#subscription.jsp">registration.jsp</a>

<ul>

<li><a href="#RegistrationForm.java">RegistrationForm.java</a></li>

<li><a href="#EditRegistrationAction.java">EditRegistrationAction.java</a></li>

<li><a href="#LinkSubscriptionTag.java">LinkSubscriptionTag.java</a></li>

<li><a href="#LinkUserTag.java">LinkUserTag.java</a></li>

<li><a href="#EditSubscriptionAction.java">EditSubscriptionAction.java</a></li>

</ul>

</li>

<li>

<a href="#subcription.jsp">subscription.jsp</a>

<ul>

<li><a href="#SubscriptionForm.java">SubscriptionForm.java</a></li>

<li><a href="#SaveSubscriptionAction.java">SaveSubscriptionAction.java</a></li>

</ul>

</li>

<li><a href="#Summary">Summary</a></li>

</ul>

<hr />

The Struts distribution bundles four applications: struts-documentation, tiles-documentation, struts-example, and struts-examples. This document walks through the struts-example, also known as the "MailReader Demonstration Application".

The premise of the MailReader is that it is the first iteration of a portal application. This version allows users to register themselves and maintain a set of accounts with various mail servers. When completed, the application would let users read mail from their accounts.

The MailReader application demonstrates registering with an application, logging into an application, maintaining a master record, and maintaining child records. This document walks through the JSP pages, Struts Java classes, and Struts configuration elements needed to do these things.

Note that for compatability and ease of deployment, the MailReader uses "application-based" authorization. However, use of the standard Java Authentication and Authorization Service (JAAS) is recommended for most applications. (See the <a href="http://jakarta.apache.org/struts/userGuide/preface.html">Preface to the Struts User Guide</a> for more about authentification technologies.)

</blockquote>

The walkthrough starts with how the initial welcome page is displayed, and then steps through logging in, adding and editing subscriptions, and creating a new registration.

100

101

<h3><a name="index.jsp" id="index.jsp">index.jsp</a></h3>

102

103

A web application, like any other web site, can specify a list of welcome pages. When you open a web application without specifying a particular page, a welcome page is used by default.

104

105

Struts allows developers to manage an application through "virtual pages" called actions. An accepted practice in Struts is to never link directly to server pages, but only to these actions. The actions are listed in a configuration file. By linking to actions, developers can "rewire" an application without editing the server pages.

106

107

108

"Link actions not pages."

109

</blockquote>

110

111

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?

112

113

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:

114

<hr />

115

<pre>

116

117

<logic:redirect action="/Welcome"/></code>

118

</pre>

119

<hr />

120

121

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?

122

123

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:

124

<hr />

125

<pre>

126

127

128

</pre>

129

<hr />

130

131

If someone asked for the Welcome action ("/Welcome.do"), the welcome.jsp page would be displayed in return.

132

133

<h4><a name="WelcomeAction.java" id="WelcomeAction.java">WelcomeAction.java</a></h4>

134

135

But if we peek at the configuration file for the MailReader, we find a slightly more complicated XML element for the Welcome action:

136

<hr />

137

<pre>

138

139

<action path="/Welcome"

140

type="org.apache.struts.webapp.example.WelcomeAction">

141

142

143

</action></code>

144

</pre>

145

<hr />

146

147

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".

148

149

OK ... but why would a WelcomeAction want to choose between success and failure?

150

151

The MailReader application retains a list of users along with their email accounts. The application stores this information in a database. If the application can't connect to the database, the application can't do its job. So before displaying the welcome page, the class checks to see if the database is available. The MailReader is also an internationalized application. So, the WelcomeAction checks to see if the message resources are available too. If both resources are available, the class forwards to the "success" path. Otherwise, it forwards to the "failure" path so that the appropriate error messages can be displayed.

152

153

<h4><a name="MemoryDatabasePlugIn.java" id="MemoryDatabasePlugIn.java">MemoryDatabasePlugIn.java</a></h4>

154

155

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?

156

157

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.

158

<hr />

159

<pre>

160

161

<set-property property="pathname" value="/WEB-INF/database.xml"/>

162

</plug-in></code>

163

</pre>

164

<hr />

165

166

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.

167

168

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:

169

<hr />

170

<pre>

171

172

173

</subscription>

174

175

</subscription>

176

</user></code>

177

</pre>

178

<hr />

179

180

This creates a registration record for "John Q. User", with the detail for his hotmail account (or "subscription").

181

182

<h4><a name="MessageResources.properties" id="MessageResources.properties">MessageResources.properties</a></h4>

183

184

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.

185

<hr />

186

<pre>

187

188

</pre>

189

<hr />

190

191

This is a standard properties text file. Here are the entries used by the welcome page:

192

<hr />

193

<pre>

194

<code>index.heading=MailReader Demonstration Application Options

195

index.logon=Log on to the MailReader Demonstration Application

196

index.registration=Register with the MailReader Demonstration Application

197

index.title=MailReader Demonstration Application (Struts 1.2.1-dev)

198

index.tour=A Walking Tour of the MailReader Demonstration Application</code>

199

</pre>

200

<hr />

201

202

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.

203

<hr />

204

<pre>

205

206

</pre>

207

<hr />

208

209

<h3><a name="welcome.jsp" id="welcome.jsp">welcome.jsp</a></h3>

210

211

After confirming that the necessary resources exist, the WelcomeAction forwards to the welcome.jsp page.

212

<hr />

213

<pre>

214

215

<%@ taglib uri="/tags/struts-bean" prefix="bean" %>

216

<%@ taglib uri="/tags/struts-html" prefix="html" %>

217

218

<html>

219

<head>

220

221

222

</head>

223

224

225

<ul>

226

227

<bean:message key="index.registration"/></html:link></li>

228

229

</ul>

230

231

<h3>Change Language</h3>

232

<ul>

233

<li><html:link action="/Locale?language=en">English</html:link></li>

234

<li><html:link action="/Locale?language=ja" useLocalEncoding="true">Japanese</html:link></li>

235

<li><html:link action="/Locale?language=ru" useLocalEncoding="true">Russian</html:link></li>

236

</ul>

237

238

<hr />

239

240

<html:img bundle="alternate" pageKey="struts.logo.path" altKey="struts.logo.alt"/>

241

242

<html:link action="/Tour"><bean:message key="index.tour"/></html:link>

243

244

</body>

245

</html></code>

246

</pre>

247

<hr />

248

249

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".

250

251

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.

252

253

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.

254

255

256

If you turn cookies off in your browser, and then reload your browser and this page, you will see the links with the Java session id information attached. (If you are using Internet Explorer and try this, be sure you reset cookies for the appropriate security zone, and that you disallow "per-session" cookies.)

257

</blockquote>

258

259

The html:img tag renders an img tag. When necessary, the src URI is encoded as it is with the link tag. In this case, the tag inserts the src path from the "alternate" MessageResource bundle, along with the text for the alt element.

260

261

In the span of a single request, Struts has done quite a bit already:

262

263

<ul>

264

<li>Confirmed that required objects were created during initialization.</li>

265

266

<li>Written all the page headings and labels from internationalized message resources.</li>

267

268

<li>Automatically URL-encoded paths as needed.</li>

269

</ul>

270

271

When rendered, the welcome page lists two menu options: one to register with the application and one to login in (if you have already registered). Let's follow the login link first.

272

273

<h3><a name="logon.jsp" id="logon.jsp">logon.jsp</a></h3>

274

275

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.

276

277

Here's how the login.jsp is coded:

278

<hr />

279

<pre>

280

281

<%@ taglib uri="/tags/struts-bean" prefix="bean" %>

282

<%@ taglib uri="/tags/struts-html" prefix="html" %>

283

284

<html:xhtml/>

285

<html>

286

<head>

287

288

</head>

289

290

<html:errors/>

291

292

<html:form action="/SubmitLogon" focus="username"

293

onsubmit="return validateLogonForm(this);">

294

295

296

<tr>

297

298

<bean:message key="prompt.username"/>:

299

</th>

300

301

<html:text property="username" size="16" maxlength="18"/>

302

</td>

303

</tr>

304

305

<tr>

306

307

<bean:message key="prompt.password" bundle="alternate"/>:

308

</th>

309

310

<html:password property="password" size="16" maxlength="18"

311

redisplay="false"/>

312

</td>

313

</tr>

314

315

<tr>

316

317

<html:submit property="Submit" value="Submit"/>

318

</td>

319

320

<html:reset/>

321

</td>

322

</tr>

323

324

</table>

325

326

</html:form>

327

328

<html:javascript formName="LogonForm"

329

dynamicJavascript="true"

330

staticJavascript="false"/>

331

332

333

<jsp:include page="footer.jsp" />

334

</body>

335

</html></code>

336

</pre>

337

<hr />

338

339

We saw some of these tags on the welcome page. Let's focus on the new tags.

340

341

The first new tag on the logon page is "html:errors". The credentials you entered are processed by a "LogonAction" class. If the credentials are incorrect, the LogonAction posts an appropriate error message and forwards back to the input page. 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.

342

343

The second new tag is "html:form". This tag renders a html form tag. The "action" element tells the tag to use "SubmitLogon.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.)

344

345

Within the html:form tag, we see four other new tags: "html:text", "html:password", "html:submit", and "html:reset".

346

347

The html:text tag renders a "input type=text" tag. The "property" attribute becomes the input tag's "name" attribute.

348

349

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 render buttons of the corresponding types.

350

351

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.

352

353

354

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.

355

</blockquote>

356

357

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?

358

359

For the answers, we need to turn to the Struts configuration files, "struts-config.xml" and "validation.xml".

360

361

<h4><a name="struts-config.xml" id="struts-config.xml">struts-config.xml</a></h4>

362

363

In the struts-config.xml file, we find an element for the "/SubmitLogon" action

364

<hr />

365

<pre>

366

367

<action path="/SubmitLogon"

368

type="org.apache.struts.webapp.example.LogonAction"

369

name="LogonForm"

370

scope="request"

371

input="logon">

372

<exception

373

key="expired.password"

374

type="org.apache.struts.webapp.example.ExpiredPasswordException"

375

path="/ExpiredPassword.do"/>

376

</action></code>

377

</pre>

378

<hr />

379

380

We saw the path and type attributes in the Welcome action. Let's look at the new attributes.

381

382

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.

383

384

The ActionForms are defined in the "formbeans" section of the configuration file. Here's the formbean element for the "LogonForm".

385

<hr />

386

<pre>

387

<code><form-bean name="LogonForm"

388

type="org.apache.struts.validator.DynaValidatorForm">

389

<form-property name="username" type="java.lang.String"/>

390

<form-property name="password" type="java.lang.String"/>

391

</form-bean></code>

392

</pre>

393

<hr />

394

395

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.

396

397

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.

398

399

400

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.

401

</blockquote>

402

403

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.

404

<hr />

405

<pre>

406

407

</pre>

408

<hr />

409

410

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.

411

412

<h4><a name="validations.xml" id="validations.xml">validations.xml</a></h4>

413

414

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:

415

<hr />

416

<pre>

417

418

419

<field property="username"

420

depends="required">

421

422

</field>

423

424

<field property="password"

425

depends="required, minlength,maxlength">

426

427

<arg1 key="${var:minlength}" name="minlength"

428

resource="false"/>

429

<arg2 key="${var:maxlength}" name="maxlength"

430

resource="false"/>

431

<var>

432

<var-name>maxlength</var-name>

433

<var-value>16</var-value>

434

</var>

435

<var>

436

<var-name>minlength</var-name>

437

<var-value>3</var-value>

438

</var>

439

</field>

440

441

</form></code>

442

</pre>

443

<hr />

444

445

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.

446

447

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.

448

449

<h4><a name="LogonAction.java" id="LogonAction.java">LogonAction.java</a></h4>

450

451

If validation passes, the LogonForm object 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.

452

453

Here's the LogonAction (sans comments):

454

<hr />

455

<pre>

456

<code>package org.apache.struts.webapp.example;

457

import ...

458

459

public final class LogonAction extends BaseAction {

460

461

private static String USERNAME = "username";

462

private static String PASSWORD = "password";

463

464

User getUser(UserDatabase database, String username,

465

String password, ActionMessages errors)

466

throws ExpiredPasswordException {

467

468

User user = null;

469

if (database == null){

470

errors.add(

471

ActionMessages.GLOBAL_MESSAGE,

472

new ActionMessage("error.database.missing"));

473

}

474

else {

475

user = database.findUser(username);

476

if ((user != null) && !user.getPassword().equals(password)) {

477

user = null;

478

}

479

if (user == null) {

480

errors.add(

481

ActionMessages.GLOBAL_MESSAGE,

482

new ActionMessage("error.password.mismatch"));

483

}

484

}

485

486

return user;

487

488

}

489

490

void SaveUser(HttpServletRequest request, User user) {

491

492

HttpSession session = request.getSession();

493

494

session.setAttribute(Constants.USER_KEY, user);

495

if (log.isDebugEnabled()) {

496

log.debug(

497

"LogonAction: User '"

498

+ user.getUsername()

499

+ "' logged on in session "

500

+ session.getId());

501

}

502

503

}

504

505

public ActionForward execute(

506

ActionMapping mapping,

507

ActionForm form,

508

HttpServletRequest request,

509

HttpServletResponse response)

510

throws Exception {

511

512

UserDatabase database = getUserDatabase(request);

513

String username = (String) PropertyUtils.getSimpleProperty(form,

514

USERNAME);

515

String password = (String) PropertyUtils.getSimpleProperty(form,

516

PASSWORD);

517

ActionMessages errors = new ActionMessages();

518

519

User user = getUser(database,username,password,errors);

520

521

SaveUser(request,user);

522

523

if (!errors.isEmpty()) {

524

this.saveErrors(request, errors);

525

return (mapping.getInputForward());

526

}

527

528

return (findSuccess(mapping));

529

530

}</code>

531

</pre>

532

<hr />

533

534

<h4><a name="MainMenu.do" id="MainMenu.do">MainMenu.do and mainMenu.jsp</a></h4>

535

536

On a successful logon, the Main Menu page displays. If you logged in using the default account, the page title should be "Main Menu Options for John Q. User". Below this legend should be two links:

537

538

<ul>

539

<li>Edit your user registration profile</li>

540

541

<li>Log off MailReader Demonstration Application</li>

542

</ul>

543

544

If you check the address shown by your browser, you will see that it shows "/SubmitLogon.do" not "/MainMenu.do". The Java servlet platform supports the idea of server-side forwards. When control passed from the SubmitLogon action to the MainMenu action, everything occured server-side. All the browser knows is that we are looking at the result of submitting a form to "/LogonSubmit.do", so that's the address that shows. It doesn't know control passed from one action to another. The difference between server-side forwards and client-side redirects is subtle and often confuses new developers.

545

546

If you change the address to "/MainMenu.do" and press enter, the same page will display again.

547

548

Here's the JSP source for the "MainMenu" action and the "mainMenu.jsp".

549

550

<hr />

551

552

553

554

<hr />

555

556

557

<%@ taglib uri="/tags/app" prefix="app" %>

558

<%@ taglib uri="/tags/struts-bean" prefix="bean" %>

559

<%@ taglib uri="/tags/struts-html" prefix="html" %>

560

<app:checkLogon/>

561

<html>

562

<head>

563

564

565

</head>

566

567

<ul>

568

569

570

</ul>

571

</body>

572

</html></blockquote></code></pre>

573

574

<hr />

575

576

If you check the source for mainMenu.jsp, you will find two new tags: "app:checkLogon" and "bean:write". Let's look at the bean tag first.

577

578

579

When control passed through the LogonAction, it retrieved a "User" object from the database and stored a reference in "session" scope. This object is a JavaBean with several properties. One property is "fullName". The bean:write tag can find the User bean and print the fullName property for us.

580

581

But how can the page be sure that we are logged in and that the User object exists?

582

583

At the top of the page, above the "html" tag, is the other new tag, checkLogon. This tag, true to its name, checks to see of the user is logged on. If not, the tag forwards to the LogonAction. Let's have a look:

584

585

<hr />

586

587

<blockquote><pre><code>package org.apache.struts.webapp.example;

588

import ...

589

590

public final class CheckLogonTag extends TagSupport {

591

592

private String name = Constants.USER_KEY;

593

private static String LOGIN_PATH = "/Logon.do";

594

private String page = LOGIN_PATH;

595

596

public int doStartTag() throws JspException {

597

return (SKIP_BODY);

598

}

599

600

public int doEndTag() throws JspException {

601

boolean valid = false;

602

HttpSession session = pageContext.getSession();

603

if ((session != null) && (session.getAttribute(name) != null)) {

604

valid = true;

605

}

606

if (valid) {

607

return (EVAL_PAGE);

608

} else {

609

ModuleConfig config =

610

(ModuleConfig) pageContext.getServletContext().getAttribute(

611

org.apache.struts.Globals.MODULE_KEY);

612

613

try {

614

pageContext.forward(config.getPrefix() + page);

615

} catch (ServletException e) {

616

throw new JspException(e.toString());

617

} catch (IOException e) {

618

throw new JspException(e.toString());

619

}

620

621

return (SKIP_PAGE);

622

}

623

}

624

625

public void release() {

626

super.release();

627

this.name = Constants.USER_KEY;

628

this.page = LOGIN_PATH;

629

}

630

}</blockquote></code></pre>

631

632

<hr />

633

634

As tags go, CheckLogon is quite simple. It takes no attributes. It's just hardwired to check for a User object in session scope and forward to the LogonAction if the object is missing.

635

636

Simple but effective. Try following the logout link and then putting in the "/MainMenu.do" address by hand. If you do, the tag will automatically forward you to the logon page. For any page that requires a login, we simply need to add a checkLogon tag at the top (before any of the page is written).

637

638

639

Many Struts developers would frown on the CheckLogon tag solution. They might argue that a page should not need to know about logons. We shouldn't rely on people remembering to put a CheckLogon tag on every protected page. And "they" would be right! We do recommend that most applications use standard JAAS. Perhaps in the next iteration, the MailReader developers will do just that. But for now, the CheckLogon tag is a simple solution to a simple problem.

640

</blockquote>

641

642

The other links we've seen have either gone directly to a JSP file, or to a Struts action path, like Login.do. The "Edit your user registration profile" link is a little different, since it also uses a parameter, as in EditRegistration.do?action=Edit. When the Struts ActionServlet processes this link, it will ignore the parameter for the purpose of matching the request, but still pass the parameter along to action's object.

643

644

645

This means that in Struts, an action object must be able to handle every valid parameter for it's base path. (In the Example, EditRegistration must handle both Edit and Create.)

646

647

You may want to check for invalid parameters too. (And be careful of differences in case if your comparisons are not case insensitive!)

648

</blockquote>

649

650

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.

651

652

653

654

<form-bean name="RegistrationForm"

655

type="org.apache.struts.webapp.example.RegistrationForm"/></code>

656

657

658

<action path="/EditRegistration"

659

type="org.apache.struts.webapp.example.EditRegistrationAction"

660

name="RegistrationForm"

661

scope="request"

662

validate="false"

663

input="/registration.jsp">

664

665

</action></code>

666

667

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>.

668

</blockquote>

669

670

<h4><a name="EditRegistrationAction.java" id="EditRegistrationAction.java">EditRegistrationAction.java</a></h4>

671

672

Many objects in an application may do double-duty. For example, EditRegistrationAction not only lets you update a registration, but is also used to create a new one. Which task the object performs is determined by the action passed to it. In the case of EditRegistrationAction, it can either edit or create a registration, the default being create if a task is not specified. To select between tasks, simply add ?create or ?edit to the hyperlink or form action.

673

674

675

Like most classes in the example application, editRegistration makes good use of the log to track it's progress. Note that ActionServlet has had a new log method added since the Example was written. You can now specify both the message and a minimum logging (or debug) level. For more, see the Javadoc in your struts-documentation application.

676

</blockquote>

677

678

<h3><a name="registration.jsp" id="registration.jsp">registration.jsp</a> and <a name="RegistrationForm.java" id="RegistrationForm.java">RegistrationForm.java</a></h3>

679

680

If you follow the "Edit your user registration profile" link from the mainMenu, we will finally reach the heart of the Example application, the registration page. This page displays everything the Example application knows about you (or at least your login), while demonstrating several interesting techniques.

681

682

You'll remember that mainMenu.jsp wanted to be sure that everyone was logged in, and used the CheckLogin tag to enforce that. The registration.jsp is a little different. First it uses a Struts logic tag to see if the task at hand is to register a new User. If not (e.g. action != "Create"), the logic tag exposes a CheckLoginTag to be sure we have a user (and therefore a registration) to edit.

683

684

685

<code><logic:equal

686

name="RegistrationForm"

687

property="action"

688

scope="request"

689

value="Edit"

690

>

691

<app:checkLogon/>

692

</logic:equal></code>

693

694

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).

695

</blockquote>

696

697

registation.jsp continues to use logic tags throughout the page so that a single JSP can be used to perform more than one task. For example, if you are editing the form (action == "Edit"), the page inserts your username from the RegistrationForm bean. If you are new user (action == "Create"), the page creates an empty field, so you can pick your username.

698

699

700

The Struts logic tags are a very convenient way to express application logic within your pages. This prevents user error and reduces the number of JSPs your application needs to maintain, among other benefits.

701

</blockquote>

702

703

The page also uses logic tags to display a list of subscriptions for the given user. If the user enters this page with an edit action in the request context, the lower part of the page listing the subscriptions is exposed by this logic tag:

704

705

706

<code><logic:equal

707

name="RegistrationForm"

708

property="action"

709

scope="request"

710

value="Edit"

711

></code>

712

</blockquote>

713

714

Otherwise, the page just contains the top portion -- a blank data-entry form for creating the user's registration.

715

716

<h4><a name="logic:iterate" id="logic:iterate">logic:iterate</a></h4>

717

718

Beside making the usual conditional tests, you can also use logic tags to forward control to other actions, to redirect control to another path, and to iterate over collections. The registration page includes a good example of using the logic:iterate tag to display the user's subscriptions.

719

720

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.

721

722

723

<logic:iterate name="user" property="subscriptions" id="subscription">

724

725

</logic:iterate>

726

</blockquote>

727

728

The three parameters to the iterate tag ( name, property, and id) tell it to

729

730

<ol>

731

<li>Check this context for an attribute (e.g. object) named "user",</li>

732

733

<li>Snag the property of user named "subscriptions",</li>

734

735

<li>In the block to iterate, use "subscription" (singular) as the name for each member of the collection.</li>

736

</ol>

737

738

So, to list the host for each subscription in a HTML unordered list, we could write:

739

740

741

742

<logic:iterate name="user" property="subscriptions" id="subscription">

743

<li>

744

<bean:write name="subscription" property="host" filter="true" />

745

</li>

746

</logic:iterate>

747

</ul></code>

748

749

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;.

750

</blockquote>

751

752

In registration.jsp, iterate is used to create a menu of subscriptions, each linked with an edit and delete action.

753

754

755

756

<tr>

757

758

<bean:write name="subscription" property="host" filter="true"/>

759

</td>

760

761

<bean:write name="subscription" property="username" filter="true"/>

762

</td>

763

764

<bean:write name="subscription" property="type" filter="true"/>

765

</td>

766

767

<bean:write name="subscription" property="autoConnect"/>

768

</td>

769

770

<app:linkSubscription page="/EditSubscription.do?action=Delete">

771

<bean:message key="registration.deleteSubscription"/>

772

</app:linkSubscription>

773

<app:linkSubscription page="/EditSubscription.do?action=Edit">

774

<bean:message key="registration.EditSubscription"/>

775

</app:linkSubscription>

776

</td>

777

</tr>

778

</logic:iterate></code>

779

780

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.

781

</blockquote>

782

783

You'll note that the hyperlinks to the edit and delete action for each subscription are written with another custom tag, app:linkSubscription. Writing a hyperlink to an action is not difficult, but it can be ugly, and makes an excellent case for encapsulation. If you trace through the app.tld, you will find that the source code for the linkSubscription tag lives in (come on, take a guess) LinkSubscriptionTag.java.

784

785

<h4><a name="LinkSubscriptionTag.java" id="LinkSubscriptionTag.java">LinkSubscriptionTag.java</a></h4>

786

787

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:

788

789

790

<code><A HREF=[path]EditSubscription.do?action=[action]&username=[user]&host=[host]">[action]

791

</A></code>

792

</blockquote>

793

794

based on input block like:

795

796

797

<code><app:linkSubscription

798

page="/EditSubscription.do?action=Delete">Delete

799

</app:linkSubscription></code>

800

</blockquote>

801

802

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

803

804

Here are a few annotated highlights from LinkSubscriptionTag.java:

805

806

<ol>

807

<li>Create a string buffer, and ask the request for the relative path to the application

808

<code>StringBuffer url = new StringBuffer(request.getContextPath());</code></li>

809

810

<li>Snag a reference to the subscription bean (for this iteration) <code>subscription = (Subscription) pageContext.findAttribute(name);</code></li>

811

812

<li>Append the username and host from the bean to the path request. <code>url.append("&username="); url.append(BeanUtils.filter(subscription.getUser().getUsername()));

813

url.append("&host=");

814

url.append(BeanUtils.filter(subscription.getHost()));</code></li>

815

</ol>

816

817

These are the essentials, but be sure to see the full source in LinkSubscriptionTag.java for the rest of the error and logic checking that a working application needs to succeed.

818

819

Meanwhile, back on registration.jsp, there is one more link on the page. This uses yet another custom tag, the app:linkUser tag.

820

821

822

823

<bean:message key="registration.addSubscription"/>

824

</app:linkUser></code>

825

</blockquote>

826

827

By this time, you must be ready to flip directly to LinkUserTag.java with nary a glance at the configuration file ...

828

829

<h4><a name="LinkUserTag.java" id="LinkUserTag.java">LinkUserTag.java</a></h4>

830

831

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!

832

833

834

835

<bean:message key="registration.addSubscription"/>

836

</app:linkUser></code>

837

</blockquote>

838

839

When rendered, this displays a HTML hypertext link like:

840

841

842

843

Add

844

</a></code>

845

846

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>).

847

</blockquote>

848

849

Let's follow that "Add" link now and see what's up with the EditSubcription action anyway.

850

851

<h4><a name="EditSubscriptionAction.java" id="EditSubscriptionAction.java">EditSubscriptionAction.java</a></h4>

852

853

Predictably, we find a some now-familiar mappings in struts-config.xml

854

855

856

857

<form-bean

858

name="SubscriptionForm"

859

type="org.apache.struts.webapp.example.SubscriptionForm"

860

/></code>

861

862

863

<action path="/EditSubscription"

864

type="org.apache.struts.webapp.example.EditSubscriptionAction"

865

name="SubscriptionForm"

866

scope="request"

867

validate="false"

868

>

869

870

871

</action></code>

872

873

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?)

874

</blockquote>

875

876

Following what was specified by struts-config.xml, the controller makes sure that a SubscriptionForm bean exists, along with the SubscriptionAction object, and then calls the action object's perform method. The perform method first checks to see that the user is logged-in. If not, control is forwarded to the Login action. EditSubscriptionAction.perform then either creates a new subscription object (if the task is Create), or searches the user's subscription hashtable for a matching hostname (if the task is Edit).

877

878

Finally, EditSubscriptionAction conforms the ActionForm bean with the database bean. There may be several subscriptions in the database, but in EditSubscriptionAction we expose the one selected (or just created) for this request to use. Once the Action form (called "subform" in the code) is created and populated from the database, the bean's action is set to either Create or Edit, and control is forwarded to our "success" form, subscription.jsp .

879

880

881

Note that the servlet only creates one object for each action. Each request is handled as a separate thread, and passed to the single action object instance. This means your action objects must be multi-thread safe.

882

</blockquote>

883

884

But before turning to our final JSP, a word about our database model ...

885

886

<h4><a name="User.java" id="User.java">User.java</a> and <a name="Subscription.java" id="Subscription.java">Subscription.java</a></h4>

887

888

If you're used to working with relational databases, the links between the user and subscription objects may be confusing. A conventional relational database would create two distinct tables, one for the users and another for the subscriptions, and link them together with a user ID. The Example application implements a different model, a hierarchical database. Here a "table" of subscriptions is stored within each user object, something like the way a filing system stores documents within folders.

889

890

In addition to the usual getters and setters, the user object also has two methods for working with subscription objects. findSubscription takes a hostname and returns the subscription object for that host. getSubscriptions returns an array of all the subscriptions for the user (ready-made for the iterate tag!). Besides the fields needed to manage the SubscriptionForm data, the object also maintains a runtime link to its user object.

891

892

To create a new subscription, EditSubscriptionAction.java simply creates a new subscription object, and sets its user to the object found in the request, and then forwards control to its input form, subscription.jsp.

893

894

<h3><a name="subcription.jsp" id="subcription.jsp">subscription.jsp</a></h3>Saving the best for last, subscription.jsp demonstrates use of some interesting Struts custom form tags, html:options and html:checkbox.

895

896

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

897

898

899

900

<html:options

901

collection="serverTypes"

902

property="value"

903

labelProperty="label"

904

/>

905

</html:select></code>

906

</blockquote>

907

908

Struts outputs a block like

909

910

911

912

<option value="imap" selected>IMAP Protocol</option>

913

<option value="pop3">POP3 Protocol</option>

914

</select></code>

915

</blockquote>

916

917

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.

918

919

For demonstrations purposes, the serverTypes array is created at the top of this page. Usually, the html:options tag would be used to list valid items from a database maintained elsewhere. For example, if the application needed you to select a default subscription, a form might list the subscriptions in an options tag.

920

921

922

The LabelValueBean used to create the demonstration array is also a good example of simple but useful bean object.

923

</blockquote>

924

925

A particularly tricky HTML control is the checkbox. A problem with a checkbox is that it is only sent in the request if it is checked. If it is not checked, it is not sent (i.e. null). This can be problematic when trying to validate the form's data after it has been translated to a bean. The autoconnect property for a subscription demonstrates how to handle validation of a checkbox.

926

927

<h4><a name="SubscriptionForm.java" id="SubscriptionForm.java">SubscriptionForm.java</a></h4>

928

929

Struts validation is handled by the reset and validate methods of the ActionForm bean. When creating your own form beans, you should subclass ActionForm, add your own fields and their getters/setters, and implement the reset and validate methods.

930

931

Struts calls reset before populating the form, and calls validate after populating it but before the perform method of the action. Reset should assign default values to each of your form fields, usually null. But in the case of checkboxes, the default value should usually be false instead of null.

932

933

934

For more examples of validating forms, take another look at LoginForm.java and RegistrationForm.java.

935

</blockquote>

936

937

Back in subscription.jsp, we have one more block to cover. Although the same basic form can be used to created, edit, or delete a subscription, people might expect the buttons to be labeled differently in each case. subscription.jsp accommodates by using a logic tag to output a different set of buttons for each case. This doesn't really change the way subscription.jsp works, but it does make things less confusing for the user.

938

939

940

<code><logic:equal

941

name="SubscriptionForm"

942

property="action"

943

scope="request"

944

value="Create">

945

<html:submit>

946

<bean:message key="button.save"/> </html:submit>

947

</logic:equal></code>

948

</blockquote>

949

950

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.

951

952

The actual action property is placed into the form as a hidden field, and SaveSubscriptionAction checks that property to execute the appropriate task.

953

954

<h4><a name="SaveSubscriptionAction.java" id="SaveSubscriptionAction.java">SaveSubscriptionAction.java</a></h4>

955

956

Our final stop has the job of finishing what EditSubscriptionAction.java and subscription.jsp started. After the usual logic and error checking, SaveSubscriptionAction either deletes or updates the subscription object being handled by this request, and cleans up the bean, just to be tidy. By now, you should be very comfortable reading through the source on your own, to pickup the finer points.

957

958

This concludes our tour. To review, you may wish to trace the path a new user takes when they register with the application for the first time. You should also read over each of the .java and JSP files carefully, since we only covered the high points here.

959

960

<h3><a name="Summary" id="Summary">Summary</a></h3>

961

962

<ul>

963

<li>Struts uses a single controller servlet to route HTTP requests.</li>

964

965

<li>The requests are routed to action objects according to path (or URI).</li>

966

967

<li>Each request is handled as a separate thread</li>

968

969

<li>There is only one object for each action (URI), so your action objects must be multi-thread safe.</li>

970

971

<li>The configuration of action objects are loaded from a XML resource file, rather than hardcoded.</li>

972

973

<li>Action objects can respond to the request, or ask the controller to forward the request to another object or to another page, such as an input form.</li>

974

975

<li>A library of custom tags works with the rest of the framework to enhance use of JavaServer Pages.</li>

976

977

<li>The Struts form tag can work closely with an action objects via a Struts ActionFormBean to retain the state of a data-entry form, and validate the data entered.</li>

978

979

<li>ActionForm beans can be automatically created by the JSP form or controller servlet.</li>

980

981

<li>Struts supports a message resource for loading constants strings. Alternate message resources can be provided to internationalize an application.</li>

982

</ul>

983

<hr />

984

</blockquote>

985

</body>

986

</html>

Older »