MyEclipse Struts 1.x Tutorial

Outline

Preface
Introduction
Requirements
New Project Setup & Structure
Starting a Struts Project
1. Components of a Struts Project
2. Building our Application
Running the Demo
Summary
User Feedback

1. Preface

This document was written using MyEclipse 6.0 GA. All screenshots are based upon the default user interface settings for Eclipse, MyEclipse Enterprise Workbench, and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

2. Introduction

In this tutorial we will be walking through the development and testing of a simple Struts example application using MyEclipse Enterprise Workbench. Previous knowledge of Struts and/or MyEclipse is not necessary.

This tutorial, because of the framework's similarity and feature coverage, will be very similar to the JSF tutorial. We will follow the same project goals and outline so you can later compare JSF with Struts, once you've gotten a better understanding of how to use the Struts tools in MyEclipse.

3. Requirements

Below is a list of software used by this guide:

Java SE 5 (Sun or IBM)
http://java.sun.com/j2se/downloads/index.html

MyEclipse 6.0 GA (All-In-One Installer)
http://www.myeclipseide.com/ContentExpress-display-ceid-10.html

Tomcat 5.0.x (5.0.28 Preferred, or other compliant Servlet/EJB container)
http://www.axint.net/apache/jakarta/tomcat-5/v5.0.28/bin/jakarta-tomcat-5.0.28.exe

For this demo the User Name is "myeclipse" and the Password is "myeclipse" as well.

Note: After installing the JDK and restarting your computer, install Eclipse, MyEclipse, and Tomcat. For instructions on installing MyEclipse, please see the Installation Tutorial. After all the software has been installed, you'll need to setup the Tomcat 5 connector in MyEclipse as detailed in the Application Server Tutorial before you can deploy and execute the example application.

4. New Project Setup & Structure

To organize our development artifacts, we will need to create a new Web Module Project in MyEclipse that has Struts Capabilities added to it. You can create a web project using the wizard located at File > New > Other > MyEclipse > Java Enterprise Projects > Web Project , as shown in Figure 1, below.

Figure 1 - Web Project Wizard Dialog

Now enter in all the new project information, as shown in Figure 2:

Figure 2 - Web Project Settings

Once the Web Project is created, we need to add Struts Capabilities to it. This is done by right clicking on the root of our project in the Package Explorer View, and selecting MyEclipse > Add Struts Capabilities, as shown in Figure 3.

Figure 3 - Adding Struts Capabilities to a Web Project

The default values for the Struts dialog are fine for the purposes of this tutorial. However, you might want to change the Base package for new classes to reflect your desired location. In Figure 4 below, we will simply leave the default values.

Figure 4 - Configuring Struts Capabilities

After the wizard completes, the project structure will look like that shown in Figure 5.

Figure 5 - Project Layout After Configuration

Now that we are done creating our project, we can begin building our web content, as illustrated in the next section.

5. Starting a Struts Project

In this section we are going to focus on creating our example Struts application, which will mimic a simple website login screen. As a result, we will only need 2 JSP pages, one to prompt the user to login and the other to indicate that login was successful. We will call these pages userLogin.jsp and userLoginSuccess.jsp , respectively. For simplicity, if there is an authorization error during the login attempt, we will redirect the user back to the userLogin.jsp page and display an error message.

When beginning a Struts project, it's generally useful to lay out the flow of your application so that the development team will have a better idea how all the pieces will fit together. The easiest way to stub out the flow is to graphically create it using the Struts Editor's graphical design mode. The Struts Editor provides a pallet of drag-and-drop tools that enable you to begin building your application by quickly replicating the page flow from your design mockups. The flow of the the example login application looks like Figure 6 below.

Note: The screenshot of the application flow was built using the Struts Designer. We will go into detail on how to access it and use it in the next section..

Figure 6 - Example Application Flow

From this design layout, we can see that the application will start by displaying the userLogin.jsp page. The login page will call the userLogin action to perform the login operation. If we have any validation errors or problems, the userLogin action will forward the user back to the userLogin.jsp page. However, if the login was successful, the application will forward to the userLoginSuccess.jsp page.

5.1 Components of a Struts Project

A typical Struts project will consist of the following categories of development artifacts:

JSPs
Actions
ActionForwards*
ActionForms**
Struts deployment descriptor: struts-config.xml

* ActionForwards are <forward> entries in the struts-config.xml file defining what path an Action will take when it has completed. We are not referring to custom implementations of the ActionForward class, although these are possible and supported by the tools, for the advanced user.

** ActionForms can be replaced by the use of DynaForms if the user wishes not to create concrete ActionForm implementations to wrap page values.

In MyEclipse creating any or all of these components (except the struts-config.xml file) can be done via 3 different methods:

Method #1: Use the File > New > Other... > J2EE > Struts 1.1 (or 1.2 or 1.3) menu by selecting a Struts wizard as seen below in Figure 7:

Figure 7 - All Available Struts Wizards

The wizards are straight forward and will prompt you for all values that the given Struts component supports. Some of these wizards are more complex than others. For example, in the Struts Action wizard shown below in Figure 8, you can see comprehensive coverage of all the features supported by a Struts Action:

Figure 8 - New Struts Action Wizard

Method #2: Use the custom Outline View, available when displaying the Struts Editor's source view panel is the active editing context. From the Outline View, you can right-click on any of the root level nodes to activate a wizard to create new components of that type, or to edit existing ones using the wizards. Figure 9 displays an example of using these context wizards.

Figure 9 - Launching Struts Wizards from the Outline View

It is worth noting from this screenshot that some of actions are actually a series of logically related wizards that allow you to create an entire flow. The wizards are linked together to seamlessly reuse common values and minimize manual re-entry.

Method #3: The Struts Editor's design page, shown in Figure 10, is also a very convenient way of creating Struts artifacts. The designer is accessed by opening the struts-config.xml file. At the bottom of the editor you can click the Design tab to bring up the designer.

Figure 10 - Accessing the Struts Designer

After switching to the designer you should see a view that looks like Figure 11 below:

Figure 11 - Overview of Struts Designer

Now that we have covered how you go about creating the different components of a Struts project, we can now create the different portions of our login demo application, as shown in the next section.

5.2 Building the Application

We will begin the construction of the demo application by first focusing on creating the JSP pages. Since our demo application is going to mimic a login screen on a website, we will only need 2 JSP pages: userLogin.jsp and userLoginSuccess.jsp. As with most Struts apps, if something goes wrong during the login, we will send the user back to the userLogin.jsp page and display an error (which is why we don't need to make a loginUserFailure.jsp page).

We will start by creating our userLoginSuccess.jsp page first. This seems backwards by creating the last page first, but we are doing it this way so we can use the New Form, Action and JSP wizard to create the first JSP page along with the related Action and ActionForm.

Let's create the userLoginSuccess.jsp JSP page from our designer view by using the "JSP" palette tool by clicking it first then clicking our canvas. Follow Figure 12 below for guidance:

Figure 12 - Create a JSP Using the Designer

After clicking on the canvas, we will be prompted with the familiar New JSP dialog as shown in Figure 13.

Note: Be sure to select the "Standard JSP using Struts 1.1" template

Figure 13 - Configure the JSP Wizard

After clicking Finish, the design view, in Figure 14, will show the newly created page.

Note: After adding the new JSP page, MyEclipse will open the new JSP page in the JSP editor, in the screenshot below we have clicked back to the designer to show you what your application is starting to look like, don't get confused if this is not the flow you see when you create the JSP page.

Figure 14 - Struts Designer showing our JSP page

All that remains to complete the JSP page is to output a message to tell the user that the login was successful. The completed source code for the page is shown in Figure 14a, below.

Note: For the purposes of making this guide easier to follow (and the code snippets shorter) the JSP page below does not resemble the default JSP template you will have once you open the file for the first time, you are free to exactly copy the code we have here or adopt it to the default JSP template code that you have after creating the new JSP file.

userLoginSuccess.jsp

<%@ page language= "java"%>

<%@ taglib uri="http://jakarta.apache.org/struts/tags-bean" prefix="bean" %> <%@ taglib uri="http://jakarta.apache.org/struts/tags-html" prefix="html" %> <%@ taglib uri="http://jakarta.apache.org/struts/tags-logic" prefix="logic" %> <%@ taglib uri="http://jakarta.apache.org/struts/tags-tiles" prefix="tiles" %> <%@ taglib uri="http://jakarta.apache.org/struts/tags-template" prefix="template" %> <%@ taglib uri="http://jakarta.apache.org/struts/tags-nested" prefix="nested" %>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html:html locale="true"> <head> <title>My Struts 'userLoginSuccess.jsp' ending page</title> </head> <body> Hello <bean:write name="userName" scope="request" />, you successfully logged in! </body> </html:html>

Figure 14a - Code for userLoginSuccess.jsp

Notice that this page is very simple. The only thing important that we are doing here is the contents of the <body> tag, printing out the value of the variable userName that is stored in the request scope of our application. So, in our action that we will create later, we need to place an attribute by the name of userName in the request scope.

Now we still need to create the userLogin.jsp page, the ActionForm and the Action. This may sound like a lot of work, but MyEclipse can streamline this considerably by way of the New Form and New Form, Action and JSP wizards.

When creating the userLogin.jsp page we need to consider the fields we want to display in this page and map those fields to the respective ActionForm. The form will store the values and ensure they get passed to the proper Action. Both of the MyEclipse wizards mentioned above, when generating the Form, offer the ability to create a JSP page along with the form. This will take all the properties of the Form and generate a JSP page with all those form fields already in it and ready to use. In this situation since we also want to create an Action to process the login, we will use the New Form, Action and JSP wizard instead of just the New Form wizard.

To continue building the application, right click on the white canvas area of the Struts designer, select new and then the New Form, Action and JSP wizard as in Figure 15:

Figure 15 - Launch New Form, Action, JSP Wizard from Designer

You will first be presented with the New Form wizard, since it is the first of a three step wizard. Be sure to enter a use case name so the wizard can fill in good default values for you. Figure 16 shows how values will be filled in for you as you enter a use case :

Figure 16 - New Form Wizard

Now we need to add two form properties: userName and password. When adding the password field, choose password for the JSP input type field as shown in Figure 17.

Figure 17 - Add Properties to the Form

Figure 18 - Form Properties

Before selecting Next, be sure to click the JSP tab to tell the wizard that you wish MyEclipse to generate a skeleton JSP page having a form with these values in it. Figure 19 shows this below:

Note: The default behavior of the wizard is to place generated JSPs into a "/form" subdirectory, for the purpose of this demo application we are going to place all the JSPs in the webroot.

Figure 19 - Enable JSP Page Generation for Form

Lastly we need to click on the Methods tab to be sure to uncheck all the methods that the wizard can auto-generate for you in the new Form. Figure 20 shows this configuration.

Note: For the purposes of keeping this demo simple we won't generate custom reset or validate methods, but it is generally a good idea to make use of these methods when coding your own application.

Figure 20 - Disable Method Generation

After you click Next, you will be directed to the New Action wizard where you will notice that most all of the values are already filled in for you. Here is another place that MyEclipse saves you time, by tying together the Form you just created with the new Action. You are free to make any changes you want, but most likely the only thing you need to worry about now (certainly in this demo application) is to fill out the Forwards that this Action has available to it. Figure 21 gives you a screenshot of the wizard.

Figure 21 - Struts Action Wizard

You can specify the ActionForwards by clicking the Forwards tab as shown in Figure 22.

Figure 22 - Setting up the Action Forwards

After you are done adding the Forwards for this action, clicking finish will allow MyEclipse to create all the resources and update the struts-config.xml file (and Designer) with all the new information. Figure 23 displays the updated layout and structure of the application.

Note: Some manual layout was done to be able to show all the elements of the diagram clearly in a small screenshot. When you manually layout a diagram, your changes will be preserved for future edits.

Figure 23 - Overview of Struts Designer and our Application

Now that the application flow has been defined, we need to add logic to the Action to handle the "login" procedure for this demo application. We can quickly jump to any resource from the design by double clicking on it, as shown in Figure 24:

Figure 24 - Double-click on a Designer Resource to Open an Editor

When you open the UserLoginAction.java file for the first time, the generated code for our execute method will look like Figure 24a.

UserLoginAction.java


											public ActionForward execute(
											

											  ActionMapping mapping,
											

											  ActionForm form,
											

											  HttpServletRequest request,
											

											  HttpServletResponse response) {
											

											  UserLoginForm userLoginForm = (UserLoginForm)
											form;
											

											  throw new UnsupportedOperationException(
											

											   "Generated method 'execute(...)' not
											implemented.");
											

											 }

Figure 24a - Generated execute Method

We want to remove the default implementation, which simply throws an exception, and replace it with some simple login logic like that shown in Figure 24b.

UserLoginAction.java


											 public ActionForward execute(
											

											  ActionMapping mapping,
											

											  ActionForm form,
											

											  HttpServletRequest request,
											

											  HttpServletResponse response) {
											

											  UserLoginForm userLoginForm = (UserLoginForm)
											form;
											

											  
											

											  if(userLoginForm.getUserName().equals("myeclipse")
											&&
											userLoginForm.getPassword().equals("myeclipse"))
											

											  {
											

											   request.setAttribute("userName",
											userLoginForm.getUserName());
											

											   return
											mapping.findForward("success");
											

											  }
											

											  
											

											  return mapping.findForward("failure");
											

											 }

Figure 24a - Corrected execute Method

Here we are doing something very simple, just checking if the userName and password values are both "myeclipse". If they are, we store the userName in the request scope and return the success forward, so our userLoginSuccess.jsp page can display a personalized message. Otherwise, something went wrong and we return the failure forward. In a real application, you would typically add an ActionMessages or ActionErrors collection back to the request scope before returning a failure forward, in order to explain what happened.

6. Running the Demo

Now that the application is complete, we can deploy it to Tomcat 5 by opening the Manage Deployments Dialog and setting up a new deployment for this project. You can open the management dialog, shown in Figure 25, by either right clicking on your project in the Package Explorer view and selecting MyEclipse > Add and Remove Project Deployments, or by clicking the Deploy J2EE Project to Server button in the toolbar:

Note: It is assumed that you have already setup the Tomcat 5 (or other) application server connector in MyEclipse. If you have not and need help doing that, please see the Application Server Tutorial.

Figure 25 - Create a New Deployment

Its always a good idea to check the deployment status after deployment has completed to make sure no errors occurred. You can do this by following the instructions in Figure 26:

Figure 26 - Confirm Deployment Succeeded

Finally, we will launch Tomcat using the application server launch button shown in Figure 27.

Figure 27 - Start Application Server

When the server starts, its output will be directed into the Console View in Eclipse. Figure 28 shows a typical Tomcat startup so that we can check for two things:
1) Tomcat deployed our web application correctly
2) Tomcat started up correctly

Figure 28 - Confirm Application and Server started correctly

Once Tomcat 5 is running, we can test it by opening the MyEclipse Browser View. This can be done from the Open View dialog that is accessed by selecting Window > Show View > Other... then selecting the MyEclipse Web Browser View, as shown in Figure 29.

Open Browser
Figure 29 - Opening the Web Browser View

In the browser's address bar, enter http://localhost:8080/StrutsLoginDemo/userLogin.jsp to activate the example application, as shown in Figure 30.

Figure 30 - Login to Demo Application

Here we see that the application is available. We can now enter our userName and password as shown in Figure 31.

Note: The userName and password for this demo are 'myeclipse' and 'myeclipse' respectively.

After logging in, the form was validated and the application forwarded us to the successful login page. Figure 31 shows us our userLoginSuccess.jsp page that our Action correctly forwarded us to.

Figure 31 - Successful Login

7. Summary

In this demo we developed a simple Struts application using the Struts tools available in MyEclipse Enterprise Workbench.

This concludes your introduction to Struts. Additional Tutorial documents are available that introduce working with Web Projects, editing, application server configuration, enterprise application projects and database development. For more information visit the MyEclipse Tutorial library.

8. User Feedback

If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum.