Struts lesson 3: Utilizing the Action servlet of Struts

For this document and all references (links) please obey the hints and regulations concerning copyright, disclaimer and trademarks.

Last revision of this document:
2005-07-04

First a confession:
The two previous two lessons had 'Struts' in their title – but did not use any element of Struts.

They were build into the framework of Struts as a preparation for the more sophisticated lessons like this one.
The two previous lessons should have trained to build web-pages (either HTML or JSP) and pack the created web-site into WAR- and EAR-files.
(If the appreviations sound strange, it is recommended to work again through JS_Struts01 – HTML in a WAR and JS_Struts02 – JSP in an EAR.)

And now another confession – or better a warning:
There is no Intermediate Test within this lesson. So please be careful when typing the example as this lesson might be seeming pretty long and getting boring.

`Preface:`

A graphical scheme of the task:

This lesson utilizes the features of Struts.

* From the 'index.jsp' page the Struts-Action-Controller is triggered. * The Action-Servlet, written in this lesson, contains also business-logic ('Model' in Struts-terminology). * The code of the business-logic decides, which of 2 follow-up-pages is displayed. * From each of the follow-Up-pages the Struts-Action-Controller can be triggered again.

`Credits:`

I derived that lesson from a lot of sources found in the internet. I thank the numerous authors for their contribution.

Prerequisites:

JS_Struts02 – JSP in an EAR completed – and its prerequisites too.
Basic knowledge of Java programming language; particular the usage of libraries.

`Preparation:`

Create a new project (named JS_Struts03) by copying the Struts-framework (JS_Struts00):

Please see the instruction with screen shots at Preparation of JS_Struts02 – JSP in an EAR.

top.

`Writing the JSP-code:`

For instructions how to create JSP-files, please see the instruction with screen shots at Writing the JSP-code of JS_Struts02 – JSP in an EAR.

Create a file index.jsp (in folder 'src/web-pages') with the following code. <%@ page language=“java“ %> <%@ taglib uri=“/WEB-INF/struts-html.tld“ prefix=“html“ %> <%@ page import=“java.util.*, java.text.*“ %> <html:html locale=“true“> <head> <html:base/>> <title>JavaScout Struts-Tutorial lesson 03</title> </head> <body> <h1>Welcome at lesson 3 of the JavaScout Struts-Tutorial !</h1> <br> This is the <i>index.jsp</i> page.<br> <br> <html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> </html:form> <br> <br> Thank you for calling this Java-Server-Page ! <br> <br> <font color=“green“> This page was called from the machine with TCP/IP-address <B> <%out.println(request.getRemoteAddr());%></B> </font> </body> </html:html> The entered text can be saved by clicking the right mouse-button and selecting Save from the context menu.

A short explanation of the newly introduced elements in the code. These elements are interpreted by the Java-Application-Server as soon as the web-page is called.

<%@ taglib uri=“/WEB-INF/struts-bean.tld“ prefix=“bean“ %> <html:html locale=“true“> Directive to use the specified Taglib-Definition (/WEB-INF/struts-bean.tld) to parse commands after a Taglib-prefix (<html:).
<html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> </html:form> Definition of a 'Form' in the HTML-file. This form contains a button with label 'Get Time'. When the button is clicked, an action ('ShowTimeDate.do' is triggered. This action is processed by Struts methods. More about this handling is described later in this lesson.
Create a file timeodd.jsp (in folder 'src/web-pages') with the following code. <%@ page language=“java“ %> <%@ taglib uri=“/WEB-INF/struts-html.tld“ prefix=“html“ %> <%@ page import=“java.util.*, java.text.*“ %> <html:html locale=“true“> <head> <html:base/>> <title>JavaScout Struts-Tutorial lesson 03</title> </head> <body> <h1>Welcome at lesson 3 of the JavaScout Struts-Tutorial !</h1> <br> This is the <i>timeodd.jsp</i> page.<br> <br> <html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> <br> Time formatted by the servlet: <html:text property=“DateString“ size=“100“/> </html:form> <br> <br> Thank you for calling this Java-Server-Page ! <br> <br> <font color=“green“> This page was called from the machine with TCP/IP-address <B> <%out.println(request.getRemoteAddr());%></B> </font> </body> </html:html> The entered text can be saved by clicking the right mouse-button and selecting Save from the context menu.

A short explanation of the newly introduced elements in the code follows. These elements are interpreted by the Java-Application-Server as soon as the web-page is called.

<%@ taglib uri=“/WEB-INF/struts-bean.tld“ prefix=“bean“ %> <html:html locale=“true“> Please see the explanation for the file 'index.jsp'.
<html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> </html:form> Please see the explanation for the file 'index.jsp'.
<html:text property=“DateString“ size=“100“/> This is the definition of an input- / output-field for text within the forms-part of the web-site. Values of this field can be set or read using the set or get methods of the 'DynaValidatorForm' of the Struts-framework. The principle of the 'DynaValidatorForm' will be explained later. The property defines the unique name of the field - which is a key to set or get the value. This name appears again at Writing the servlet and Defining the Struts-mapping. The size defines the visible length of the field.
Create a file timeeven.jsp (in folder 'src/web-pages') with the following code. The text of this page is in German – so it is easy to determine which page is displayed. <%@ page language=“java“ %> <%@ taglib uri=“/WEB-INF/struts-html.tld“ prefix=“html“ %> <%@ page import=“java.util.*, java.text.*“ %> <html:html locale=“true“> <head> <html:base/>> <title>JavaScout Struts-Tutorial Lektion 03</title> </head> <body> <h1>Willkommen zur Lektion 3 des JavaScout Struts-Tutorials !</h1> <br> Das ist die <i>timeeven.jsp</i> Seite.<br> <br> <html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> <br> Durch das Servlet formatierte System-Zeit: <html:text property=“DateString“ size=“100“/> </html:form> <br> <br> Danke für den Aufruf dieser Java-Server-Page ! <br> <br> <font color=“green“> Diese Seite wurde von der Maschine mit TCP/IP-Adresse <B> <%out.println(request.getRemoteAddr());%></B> aufgerufen </font> </body> </html:html> The entered text can be saved by clicking the right mouse-button and selecting Save from the context menu.

A short explanation of the newly introduced elements in the code follows. These elements are interpreted by the Java-Application-Server as soon as the web-page is called.

<%@ taglib uri=“/WEB-INF/struts-bean.tld“ prefix=“bean“ %> <html:html locale=“true“> Please see the explanation for the file 'index.jsp'.
<html:form action=“ShowTimeDate.do“> <html:submit value=“Get Time“/> </html:form> Please see the explanation for the file 'index.jsp'.
<html:text property=“DateString“ size=“100“/> Please see the explanation for the file 'timeodd.jsp'.

top.

`Defining the Libraries in the Java Build Path:`

Here all the standard-libraries with classes called either by individual code or by Struts-functions are defined. These are defined now as otherwise errors are indicated when the Java-code for the servlet is written.

Right click onto the project 'JS_Struts03' and select >Properties

In the left window select 'Java Build Path'. Then select the tab 'Libraries'.
First, the JAR (Java-ARchive) with the general methods for a servlet is needed. This servlet is delivered with the JBoss-IDE plugin for Eclipse. The home-directory for Eclipse is already defined with the variable 'ECLIPSE_HOME'. Click the button [Add Variable ...] and select ECLIPSE_HOME on the window popping up. Then click the button [Extend...].
Manouvre to the 'plugins/org.eclipse.tomcat_4.1.xx' directory and select the file 'servlet.jar'. Then click the [ OK ] button.
Next, the JARs for the Struts framework have to be added to the build path. Click the button [Add Jars ...], manouvre to the 'JS_Struts03/WEB-INF/lib' folder and select all files. (Selecting a range of files is done by selecting the first file, then holding down the 'Shift'-key on the keyboard and clicking with the mouse onto the last file of the range.) Then click the [ OK ] button..
Verify, that the list of JARs in the Build Path looks like the screenshot. Then click the [ OK ] button..

top.

`Writing the Servlet:`

This is the Action-servlet as requiered by the Struts-framework. As the business-logic (the 'model' according to Struts-terminolgy) is pretty simple it is also incorporated in this servlet. The separation between 'Action' (Struts-'Controller') and 'Model' is done in the next lesson.

Right click onto the project 'JS_Struts03' and select >New>Class
Enter the Package (js_sl03), the (Class-)Name (ShowTimeDateAction) and the Superclass (org.apache.struts.action.Action), uncheck Constructors from superclass, leave all other values unchanged and press the [Finish] button.
Eclipse has already generated a template and the individual code can be entered. To shorten the list, comments from the template are not shown in the following code. package js_sl03; import org.apache.struts.action.*; import org.apache.struts.validator.*; import javax.servlet.http.*; import java.text.DateFormat; import java.util.*; public class ShowTimeDateAction extends Action { public ActionForward execute ( ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) { DynaValidatorForm dvf = (DynaValidatorForm) form; Date now = new Date(); int Second = now.getSeconds(); String formattedDate; String nextSite; if (Second%20 <= 9) { formattedDate = DateFormat.getDateInstance.(DateFormat.FULL, Locale.GERMANY).format(now); formattedDate += “, “; formattedDate = DateFormat.getTimeInstance.(DateFormat.FULL, Locale.GERMANY).format(now); nextSite = “odd“; } else { formattedDate = DateFormat.getDateInstance.(DateFormat.FULL, Locale.US).format(now); formattedDate += “, “; formattedDate = DateFormat.getTimeInstance.(DateFormat.FULL, Locale.US).format(now); nextSite = “even“; } dvf.set(“DateString“, formattedDate); return mapping.findForward(nextSite); } } The entered text can be saved by clicking the right mouse-button and selecting Save from the context menu.

A short explanation of the code. The elements are interpreted by the Java-Application-Server as soon as the web-page is called.

package js_sl03; Name of the package. This name is referred in the configuration file 'struts-config.xml' under the <action-mappings> and enables Struts to call the defined class when the 'action'-button of a 'form' in a JSP-page is clicked.
import org.apache.struts.action.*; import org.apache.struts.validator.*; import javax.servlet.http.*; Import directives for libraries with base-classes for Struts- and servlet-methods.
public class ShowTimeDateAction extends Action; Name of the class that Struts calls when the 'action'-button of a 'form' in a JSP-page is clicked.. This name is referred in the configuration file 'struts-config.xml' under the <action-mappings>. This class inherits methods from the 'org.apache.struts.action.Action' class.
public ActionForward execute ( . . . Inherited method from the 'org.apache.struts.action.Action' class. This method handles the request coming from the calling JSP including variables of the form, processes the data (or calls methods of other classes) and calls the following JSP (including transfer of variables to be displayed there).
if (....) { ..... } else { ..... } The 'business-logic' ('Model' in Struts-terminology). In the example the system-time is read and depending on the second a successing form either in German or English is called.
dvf.set(“DateString“, formattedDate) This command is using the 'set'-method of the Struts-DynaValidatorForm-class to insert the string 'formattedDate' into the form-property 'DateString' of the JSP-file displayed next.
return mapping.findForward(nextSite) This command is returning the symbolic name of the form to be displayed next. Struts derives out of a XML parameter-file the actual filename of the JSP-file to be displayed next.

top.

`Defining the Struts-mapping files 'web.xml' and 'struts-config.xml':`

In the JSP-files are 'forms' defined where the 'actions' trigger a process performed by the Struts-framework. The processing is partly defined by the 'struts-config.xml' file within the folder 'WEB-INF'..

The file 'web.xml' contains the mapping for the web-services. The template file provided with the Struts-framework contains all mappings for this lesson. Only the <display-name> (the identification shown in the list of the Java-Application-Server) is changed to reflect this specific lesson. Open the file web.xml under the folder 'WEB-INF' and find the <display-name> parameter. <web-app> <display-name>JavaScout Struts-Tutorial, lession 03</display-name>.
The file 'struts-config.xml' contains the mapping for all symbolic names to the real implemented names of forms, fields within forms and classes. The template file provided with the Struts-framework contains all mappings for this lesson. Only the <display-name> (the identification shown in the list of the Java-Application-Server) is changed to reflect this specific lesson. Open the file struts-config.xml under the folder 'WEB-INF' .
Find the <!-- sample form bean descriptor for a DynaActionForm , copy the <form-bean template before the sample and modify it to look like this: <form-bean name=“ShowTimeDateForm“ type=“org.apache.struts.validator.DynaValidatorForm“> <form-property name=“DateString“ type=“java.lang.String“> /> </form-bean> <!-- sample form bean descriptor for a DynaActionForm These parameters comprehend all JSP-files in the project under the form-name ShowTimeDateForm. Furthermore it is defined, that the class DynaValidatorForm, delivered with the Struts-framework, is used to check the input entered into fields of forms. Under form-property, the type of the allowed input defined. In this example, DateString is the name of a field defined in a JSP-file - see Writing the JSP-Code.
Find the  and change the existing mapping to the following values: <forward name=“ShowTimeDate“ path=“/ShowTimeDate.do“/> This gives the bunch of code (JSP and servlet) the symbolic name ShowTimeDate. The further mapping and additional parameters are defined and explained in the next step. The path=“/ShowTimeDate.do“ refers to the form-name in one or more JSP-file(s) - see Writing the JSP-Code - and forwards all requests to an Action-servlet defined under path=“/ShowTimeDate“ the in the next step.
Find the  and change the existing mapping to the following values: <action path=“/ShowTimeDate“ type=“js_sl03.ShowTimeDateAction“ name=“ShowTimeDateForm“/> scope=“request“/> validate=“true“/> > <forward name=“even“ path=“/timeeven.jsp“/> <forward name=“odd“ path=“/timeodd.jsp“/> This is the mapping for all 'things' (JSP and servlets) under the name ShowTimeDate. * This Action Mapping Definition is the next step Struts looks up after the Global Forward Definition. * path=“/ShowTimeDate“ corresponds to the path=“/ShowTimeDate.do“ in the Global Forward Definition. * type=“js_sl03.ShowTimeDateAction“ is the servlet written - see Writing the Servlet. It contains the re-'Actions' of the input in the calling JSP. In this lesson, it also contains the business-logic ('Model' in Struts-terminology). * name=“ShowTimeDateForm“ is the reference to the definition of this form (2 steps before) with the validation-class (org.apache.struts.validator.DynaValidatorForm in our lession) and the definition of the input-/output fields of the JSP-file ( DateString in this lesson). * scope=“request“ defines, that a new instance of the servlet is created for every request. In contrary there is scope=“session“, which uses one instance for more than one request. It is a design decision - if there is no persistant data kept in the class, “session“ would be ok. This tutorial stays on the save side * validate=“true“ is the reference to the definition of this form (2 steps before) with the validation-class (org.apache.struts.validator.DynaValidatorForm in our lession) and the definition of the input-/output fields of the JSP-file ( DateString in this lesson). The further mapping and additional parameters are defined and explained in the next step. The path=“/ShowTimeDate.do“ refers to the form-name in one or more JSP-file - see Writing the JSP-Code - and forwards all requests to an Action-servlet defined under path=“/ShowTimeDate“ the in the next step.

top.

`Making the packaging configuration and pack the HTML-files into a WAR (Web-ARchive):`

For instructions how to define the files to be packed into the WAR-file, please see the instruction with screen shots at Making the packaging configuration and pack the HTML-files into a WAR (Web-ARchive) of JS_Struts02 – JSP in an EAR.

Create a file named JS_Struts03.war and define the following files (with Prefixes as specified):

Name of the file or the folder to be packed into the JS_Struts03.war file	Prefix as to be entered on the window 'Folder Selection' or 'File Selection'	Reason
Folder 'src/web-pages'	none	Repeat the two previous lessons if you ask why this folder has to be packed !
File 'WEB-INF/struts-html.tld'	WEB-INF	TagLib-Definition for HTML-tags. This file contains definitions, how the text after the html: has to be translated into HTML-code.
Folder 'gen/classes'	WEB-INF/classes	Class after compiling the written Java-code for the ActionMethod.
Folder 'WEB-INF/struts-config.xml'	WEB-INF	Parameter-file for the mapping of the symbolic names used in this project toward the real file- or class-names.
Folder 'WEB-INF/web.xml'	WEB-INF	Parameter-file for the deployment of the 'web-services', i.e. the HTML- and JSP-files.

To verify, that the files of the selected folder and its sub-folders is in the Packaging Configuration, the 'Properties'-window should look like the following screenshot. To generate a file with the data to be packaged, click the [ OK ]-button.
That the WAR-file can be incorporated in the EAR-file, the packaging process has to be done now. Right-click onto the project (JS_Struts03) and select >Run Packaging . The build-process can be watched in the 'console'-window. For a detailed description with screenshots please see at Making the packaging configuration and pack the HTML-files into a WAR (Web-ARchive) of JS_Struts02 – JSP in an EAR.

`top.`

`Defining of the 'application.xml'-file as a prerequisite for an EAR (Enterprise-ARchive):`

As the project should be registered under another name (strutslesson03) than the name of the WAR-file (JS_Struts03.war), it is necessary to find out which parameter-file is responsible for that. As the concept of the WAR does not know a different registration-name, the WAR-file (and the parameter-file(s)) is packed into an EAR (Enterprise-ARchive) file. In one of the following lessons is also shown, that the EAR can contain other parameter-files, e.g. references to a database.

Define the (different) registration name (strutslesson03) under which the web-site will be registered in the Java-Application-Server. This parameter is set.

For a detailed description with screenshots please see at Defining of the 'application.xml'-file of JS_Struts02 – JSP in an EAR. Hint: Familialize with the 'Copy' and 'Paste' functions of Eclipse and copy the file of the previous lesson.

Edit the file to look like this:. <?xml version=“1.0“ encoding=“UTF-8“?> <!DOCTYPE application PUBLIC “-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN“ “http://java.sun.com/dtd/application_1_3.dtd“> <application> <display-name>JavaScout Struts-Tutorial, lesson 03</display-name> <module> <web> <web-uri>JS_Struts03.war</web-uri> <context-root>strutslesson03</context-root > </web> </module> </application> The entered text can be saved by clicking the right mouse-button and selecting Save from the context menu.

For a short explanation of the elements please see at Defining of the 'application.xml'-file of JS_Struts02 – JSP in an EAR. .

top.

`Making the packaging configuration and pack the files into an EAR (Enterprise-ARchive):`

This is the final packaging-configuration.

Pack the WAR-file and the 'application.xml' parameter-file into the EAR-file..

For instructions how to define the files to be packed into the EAR-file, please see the instruction with screen shots at Making packaging configuration and pack the files inta an EAR of JS_Struts02 – JSP in an EAR.

Create a file named JS_Struts03.ear and define the following files (with Prefixes is specified):

Name of the file or the folder to be packed into the JS_Struts03.war file	Prefix as to be entered on the window 'Folder Selection' or 'File Selection'	Reason
File 'JS_Struts03.war'	none	Archive with the files for the web-services.
File 'META-INF/application.xml'	META-INF	Parameter-file for the deployment of the whole project to an Java-Application-Server.

To verify, that the files of the selected folder and its sub-folders is in the Packaging Configuration, the 'Properties'-window should look like the following screenshot. To generate a file with the data to be packaged, click the [ OK ]-button.
To start the packaging process, right-click onto the project (JS_Struts02) and select >Run Packaging . The build-process can be watched in the 'console'-window. For a detailed description with screenshots please see at Making the packaging configuration and pack the files into an EAR of JS_Struts02 – JSP in an EAR.

The build-process can be watched in the 'console'-window.

`top.`

`Run / Test:`

This is the final verification if the generated 'JS_Struts03.ear' file (with an Enterprise ARchive structure) is running error-free within a Java-Application-Server.

For the conceptional background of deployment to a Java-Application-Server and the assumptions of the directories with the Eclipse-workspace and and the Java-Application-Server-deployment, please see Run / Test in JS_Struts01 – HTML in a WAR .

To deploy the EAR-file, open a 'Terminal'-window and enter the following command: cp /home/kurti-o/workspace/JS_Struts03/JS_Struts03.ear /opt/jboss/server/default/deploy . To monitor the deployment of the EAR-file in the Java-Application-Server please see Run / Test in JS_Struts01 – HTML in a WAR .
The result of lesson 3 can be seen on a web-browser. Enter the following URL: http://192.168.0.62:8080/strutslesson03 (In the example, the JBoss-Application-Server is running on a machine with the TCP/IP-address '192.168.0.62'.) and you can see: .
After clicking the button [ Get Time ] one of the two following pages is displayed. The selection of the page is based on the second of the system-time.

Note: There is also a functionality in Eclipse to define the Java-Application-Server and deploy and undeploy with an Eclipse-function. I was not pretty happy with that feature. My JBoss-Application-Server is running on another machine. When this machine is not running during the start of Eclipse, the Eclipse-function gets confused, reports that a changed WAR-file is deployed - but the old file is not overwritten. So I prefer to stay on the more secure side and copy the files using the 'Terminal'-window. top.

Struts lesson 3: Utilizing the Action servlet of Struts

Preface:

Credits:

Prerequisites:

Preparation:

Writing the JSP-code:

Defining the Libraries in the Java Build Path:

Writing the Servlet:

Defining the Struts-mapping files 'web.xml' and 'struts-config.xml':

Making the packaging configuration and pack the HTML-files into a WAR (Web-ARchive):

top.

Defining of the 'application.xml'-file as a prerequisite for an EAR (Enterprise-ARchive):

Making the packaging configuration and pack the files into an EAR (Enterprise-ARchive):

top.

Run / Test:

Related Documents:

`Preface:`

`Credits:`

`Preparation:`

`Writing the JSP-code:`

`Defining the Libraries in the Java Build Path:`

`Writing the Servlet:`

`Defining the Struts-mapping files 'web.xml' and 'struts-config.xml':`

`Making the packaging configuration and pack the HTML-files into a WAR (Web-ARchive):`

`top.`

`Defining of the 'application.xml'-file as a prerequisite for an EAR (Enterprise-ARchive):`

`Making the packaging configuration and pack the files into an EAR (Enterprise-ARchive):`

`top.`

`Run / Test:`

`Related Documents:`