Beehive Page Flow Tutorial
Introduction
Tutorial Goals
In this tutorial, you will learn:
- How to create a basic Page Flow web application
- How to coordinate user navigation with Forward methods
- How to handle data submission and processing with data binding and Form Beans
- How to create a user interface with the <neuti> JSP tag library
- How Page Flows help to separate data processing and data presentation
Step 1: Begin the Page Flow Tutorial
To Set up the Development Environment
Complete all of the necessary and optional steps in the following topic: Beehive Installation and Setup
Open a command shell and confirm that you have the following variables have been set:
- ANT_HOME
- JAVA_HOME
- CATALINA_HOME
Also ensure that the following elements are on your PATH:
- ANT_HOME/bin
- JAVA_HOME/bin
Make a Project Folder
On your C: drive, create a directory named beehive_projects.
Copy the folder <BeehiveRoot>/samples/netui-blank into C:/beehive_projects. (<BeehiveRoot is the top level folder of your Beehive installation; a typical value might be C:/apache/apache-beehive-1.0.)
Rename the folder C:/beehive_projects/netui-blank to the name C:/beehive_projects/pageflow_tutorial
Before proceeding, confirm that the following directory structure exists:
C: beehive_projects pageflow_tutorial resources WEB-INF Controller.jpf error.jsp index.jsp
Edit the build.properties File
In this section you will edit the build.properties file--the file that sets the build-related properties for your web application.
Open the file C:/beehive_projects/pageflow_tutorial/WEB-INF/src/build.properties in a text editor.
Edit the beehive.home property points to the top-level folder of your beehive installation.
Add the line contextPath=pageflow_tutorial (as shown below).
For example, if your beehive installation resides at C:/apache/apache-beehive-1.0, then your build.properties file would appear as follows.
beehive.home=C:/apache/apache-beehive-1.0 contextPath=pageflow_tutorial servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar
To Start the Tomcat Server
At the command prompt, enter:
%CATALINA_HOME%\bin\startup.bat
Step 2: Create a New Page Flow Application
Introduction
In this step you will create a Controller file and a JSP page. These are the basic files in a Beehive Page Flow web application. Each Page Flow contains one Controller file and any number of JSP pages. A Controller file is a Java class (with the JPF file extension) that controls how your web application functions and what it does. The methods in the Controller file determines all of the major features of a web application: how users navigate from page to page, how user requests are handled, and how the web application accesses back-end resources. The JSP pages determine what a visitor to the web sees in the browser. (In terms of the Model-View-Controller paradigm for web applications: the Controller.jpf file is the Controller (naturally), and the JSP pages are the View. This web application's Model is very simple: it consists of two fields that represent the user's age and name. )
Controller files contain Action methods. An Action method may do something simple, such as forward a user from one JSP page to another; or it may do a complex set of tasks, such as receive user input from a JSP page, calculate and/or retrieve other data based on the user input, and forward the user to a JSP page where the results are displayed.
The Controller file you create in this step contains one simple Action method. This simple navigational Action method forwards users to the index.jsp page. In the next step, you will create a more complex Action method.
To Examine the Controller.jpf and index.jsp Files
There are no edits to make in this step. The point of this step is to learn about the code you are about to run.
Open the file C:/beehive_projects/pageflow_tutorial/Controller.jpf. [todo: explain]
Controller.jpf
import javax.servlet.http.HttpSession; import org.apache.beehive.netui.pageflow.Forward; import org.apache.beehive.netui.pageflow.PageFlowController; import org.apache.beehive.netui.pageflow.annotations.Jpf; @Jpf.Controller( simpleActions={ @Jpf.SimpleAction(name="begin", path="index.jsp") }, sharedFlowRefs={ @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class) } ) public class Controller extends PageFlowController { @Jpf.SharedFlowField(name="shared") private shared.SharedFlow sharedFlow; /** * Callback that is invoked when this controller instance is created. */ protected void onCreate() { } /** * Callback that is invoked when this controller instance is destroyed. */ protected void onDestroy(HttpSession session) { } }
Open the file C:/beehive_projects/pageflow_tutorial/index.jsp. [todo: explain]
index.jsp
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%> <netui:html> <head> <title>Web Application Page</title> <netui:base/> </head> <netui:body> <p> New Web Application Page </p> </netui:body> </netui:html>
To Compile and Deploy the Page Flow
You are now ready to compile the Page Flow and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\pageflow_tutorial.war %CATALINA_HOME%\webapps
To Test the Page Flow Web Application
Visit the following address:
http://localhost:8080/pageflow_tutorial
You will be directed to the index.jsp page.
Step 3: Navigation
To Create a Destination JSP Page
In the directory C:/beehive_projects/pageflow_tutorial, create a file named page2.jsp.
Edit page2.jsp so it appears as follows.
page2.jsp
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <netui:html> <head> <title>page2.jsp</title> <netui:base/> </head> <netui:body> <p> Welcome to page2.jsp! </p> </netui:body> </netui:html>
Save page2.jsp.
To Create a Link to the Destination Page
Open the file C:/beehive_projects/pageflow_tutorial/index.jsp.
Edit index.jsp so it appears as follows. Code to add appears in bold type.
index.jsp
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%> <netui:html> <head> <title>Web Application Page</title> <netui:base/> </head> <netui:body> <p> New Web Application Page </p> <p> <netui:anchor action="toPage2">Link to page2.jsp</netui:anchor> </p> </netui:body> </netui:html>
Save index.jsp.
To Add a Simple Action to Handle the Link
Open the file C:/beehive_projects/pageflow_tutorial/Controller.jpf.
Edit Controller.jpf so it appears as follows. Don't forget the comma after the first Jpf.SimpleAction(...) element!
Controller.jpf
import javax.servlet.http.HttpSession; import org.apache.beehive.netui.pageflow.Forward; import org.apache.beehive.netui.pageflow.PageFlowController; import org.apache.beehive.netui.pageflow.annotations.Jpf; @Jpf.Controller( simpleActions={ @Jpf.SimpleAction(name="begin", path="index.jsp"), @Jpf.SimpleAction(name="toPage2", path="page2.jsp") }, sharedFlowRefs={ @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class) } ) public class Controller extends PageFlowController { ... }
Save Controller.jpf.
To Compile and Deploy the Page Flow
You are now ready to compile the Page Flow and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\pageflow_tutorial.war %CATALINA_HOME%\webapps
If you are asked to overwrite the old WAR file, enter 'Yes'.
Wait a few seconds for Tomcat to redeploy the WAR file, then move on to the next step.
To Test the Page Flow Web Application
Visit the following link:
http://localhost:8080/pageflow_tutorial
You will be directed to the index.jsp page.
Click the link.
You will be directed to page2.jsp.
Step 4: Submitting Data
To Create a Submission Form
Edit the file C:/beehive_projects/pageflow_tutorial/page2.jsp so it appears as follows.
page2.jsp
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <netui:html> <head> <title>page2.jsp</title> <netui:base/> </head> <netui:body> <p> Welcome to page2.jsp! </p> <p> <netui:form action="processData"> Name:<netui:textBox dataSource="actionForm.name"/><br/> Age:<netui:textBox dataSource="actionForm.age"/><br/> <netui:button type="submit">Submit</netui:button> </netui:form> </p> </netui:body> </netui:html>
Save page2.jsp.
To Create a Server Side Representation of the Submission Form (a.k.a. Create a Form Bean)
In this step you will create a Java class that represents the submission form created in the previous task. When the form data is submitted, the Java class will be instantiated, and the form data will be loaded into the members of the Java class.
In the directory C:/beehive_projects/pageflow_tutorial/WEB-INF/src create a directory named forms.
In the directory C:/beehive_projects/pageflow_tutorial/WEB-INF/src/forms create a JAVA file named ProfileForm.java.
Edit C:/beehive_projects/pageflow_tutorial/WEB-INF/src/forms/ProfileForm.java so it appears as follows.
ProfileForm.java
package forms; public class ProfileForm implements java.io.Serializable { private int age; private String name; public void setName(String name) { this.name = name; } public String getName() { return this.name; } public void setAge(int age) { this.age = age; } public int getAge() { return this.age; } }
Save and close ProfileForm.java.
To Edit the Controller File to Handle the Submitted Data
Open the file C:/beehive_projects/pageflow_tutorial/Controller.jpf
Edit Controller.jpf so it appears as follows. Code to add appears in bold type.
Controller.jpf
import javax.servlet.http.HttpSession; import org.apache.beehive.netui.pageflow.Forward; import org.apache.beehive.netui.pageflow.PageFlowController; import org.apache.beehive.netui.pageflow.annotations.Jpf; import forms.ProfileForm; @Jpf.Controller( simpleActions={ @Jpf.SimpleAction(name="begin", path="index.jsp"), @Jpf.SimpleAction(name="toPage2", path="page2.jsp") }, sharedFlowRefs={ @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class) } ) public class Controller extends PageFlowController { @Jpf.Action( forwards = { @Jpf.Forward(name = "success", path = "page2.jsp") } ) public Forward processData(ProfileForm form) { System.out.println("Name: " + form.getName()); System.out.println("Age: " + form.getAge()); return new Forward("success"); } @Jpf.SharedFlowField(name="shared") private shared.SharedFlow sharedFlow; /** * Callback that is invoked when this controller instance is created. */ protected void onCreate() { } /** * Callback that is invoked when this controller instance is destroyed. */ protected void onDestroy(HttpSession session) { } }
Save Controller.jpf.
To Compile and Redeploy the Page Flow
You are now ready to compile the Page Flow and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\pageflow_tutorial.war %CATALINA_HOME%\webapps
If you are asked to overwrite the old WAR file, enter 'Yes'.
Wait a few seconds for Tomcat to redeploy the WAR file, then move on to the next step.
To Test the Page Flow Web Application
Visit the following link:
http://localhost:8080/pageflow_tutorial
You will be directed to the index.jsp page.
Click the link.
You will be directed to page2.jsp.
Enter values in the Name and Age fields, and click Submit.
Notice the name and age values you entered are displayed in the Tomcat console shell.
Step 5: Processing and Displaying Data
To Create a JSP Page to Display Submitted Data
In the directory C:/pageflow_tutorial Create a file named displayData.jsp.
Edit displayData.jsp so it appears as follows.
displayData.jsp
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <netui:html> <head> <title>displayData.jsp</title> <netui:base/> </head> <netui:body> <p> You submitted the following information: </p> <p> Name:<netui:content value="${requestScope.data.name}"/><br/> Age:<netui:content value="${requestScope.data.age}"/> </p> </netui:body> </netui:html>
Save and close displayData.jsp.
To Process the Submitted Data
Edit the processData method in the Controller.jpf file so it appears as follows. Code to add appears in bold.
Controller.jpf
... @Jpf.Action( forwards = { @Jpf.Forward(name = "success", path = "displayData.jsp") } ) public Forward processData(ProfileForm form) { System.out.println("Name: " + form.getName()); System.out.println("Age: " + form.getAge()); getRequest().setAttribute("data", form); return new Forward("success"); } ...
Save Controller.jpf.
To Compile and Redeploy the Page Flow
You are now ready to compile the Page Flow and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\pageflow_tutorial\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\pageflow_tutorial.war %CATALINA_HOME%\webapps
If you are asked to overwrite the old WAR file, enter 'Yes'.
Wait a few seconds for Tomcat to redeploy the WAR file, then move on to the next step.
To Test the Page Flow Web Application
Visit the following link:
http://localhost:8080/pageflow_tutorial
You will be directed to the index.jsp page.
Click the link.
You will be directed to page2.jsp.
Enter values in the Name and Age fields. Click the Submit button.
You will be forwarded to the displayData.jsp page. Notice the values you entered are displayed.