http://www.developer.com/

Back to article

Dissecting Java Page Flows


August 24, 2005

BEA originally launched the Java Page Flow technology with WebLogic Workshop. BEA also introduced a related technology, NetUI, which is a set of tag libraries that provide a binding between Java Page Flows (the controller layer) and Java Server Pages (the presentation layer). NetUI in Apache Beehive is a combination of the NetUI tag libraries and Java Page Flows. (In fact, we could have called this article "Dissecting NetUI.")

Note: In this article, we'll refer to these two components as separate pieces. So, whenever we say Page Flows, we simply mean Java Page Flows. Whenever we say NetUI, we mean the NetUI tag libraries.

In this article, from my book Pro Apache Beehive published by Apress, you'll look at the basic architecture of Java Page Flows and NetUI tags. You'll see the original Page Flows in WebLogic Workshop and then look at the Beehive version. You'll learn about the overall architecture, the classes, and the APIs you'll need to use to leverage Java Page Flows and NetUI.

The intent of this article, is to introduce you to these technologies. Even if you've already worked with Page Flows in WebLogic Workshop, we recommend at least skimming through this article to get a basic overview of the differences between the two versions (WebLogic Workshop Page Flows and Beehive Page Flows). Even if you're an expert on the WebLogic Workshop version, or even if you're an expert on Beehive itself, you'll find this article useful as a ready-to-use reference/refresher.

Introducing Java Page Flows

In the typical Model-View-Controller (MVC) design pattern, Java Page Flows form the controller layer. They're assisted by the NetUI tag libraries in the presentation layer. Java Page Flows are built on top of Struts—which, as you know, is one of the most widely adopted MVC frameworks available today. So, why not just use Struts?

Java Page Flows leverage the core functionality of Struts but remove a lot of the grunt work you have to do with Struts. By grunt work, we mean managing the deployment configuration files (such as the struts-config.xml file). The original version of Page Flows from BEA introduced a declarative programming language that was automatically generated and maintained by WebLogic Workshop. The Apache Beehive version of Page Flows uses JSR 175 for its metadata definition.

As mentioned, Page Flows leverage all the features of Struts, such as the validation framework. You can actually have a single Web application that has a combination of Struts and Page Flows.

So, let's actually look at a Page Flow.

Page Flows in WebLogic Workshop

This article is not about WebLogic Workshop, so we won't go into the details of how you start building Page Flows in WebLogic Workshop. Let's just assume that you built a simple HelloWorld Page Flow using WebLogic Workshop (see Listing 1).

Note: See the BEA Web site (http://www.bea.com) for information on how to download and install BEA WebLogic Workshop 8.1. See the documentation on the BEA developer site (http://edocs.bea.com) to learn how to work with BEA Page Flows.

Listing 1. helloworld.jpf in WebLogic Workshop

package helloworld;
import com.bea.wlw.netui.pageflow.Forward;
import com.bea.wlw.netui.pageflow.PageFlowController;
/**
 *@jpf:controller
 *@jpf:view-properties view-properties::
 *<!--This data is autogenerated.
 *Hand-editing this section is not recommended.-->
 *<view-properties>
 *<pageflow-object id="pageflow:/helloworld/
                       HelloWorldController.jpf"/>
 *<pageflow-object id="action:begin.do">
 *<property value="80" name="x"/>
 *<property value="100" name="y"/>
 *</pageflow-object>
 *<pageflow-object id="forward:path#success#helloworld.jsp
                       #@action:begin.do@">
 *   <property value="44,20,20,60" name="elbowsX"/>
 *   <property value="92,92,-4,-4" name="elbowsY"/>
 *   <property value="West_1" name="fromPort"/>
 *   <property value="North_1" name="toPort"/>
 *   <property value="success" name="label"/>
 *</pageflow-object>
 *<pageflow-object id="page:helloworld.jsp">
 *   <property value="60" name="x"/>
 *   <property value="40" name="y"/>
 *</pageflow-object>
 *</view-properties>
 *::
 */
public class HelloWorldController extends PageFlowController
{

   //Uncomment this declaration to access Global.app.
   //
   //protected global.Global globalApp;
   //
   //For an example of Page Flow exception handling,
   //see the example "catch"and "exception-handler"
   //annotations in {project}/WEB-INF/src/global/Global.app
   /**
    *This method represents the point of entry into the Page Flow
    *@jpf:action
    *@jpf:forward name="success" path="helloworld.jsp"
    */
   protected Forward begin()
   {
      return new Forward("success");
   }
}

Notice that this code snippet is mostly full of Java comments. These are the different annotations that support the execution of the actual Page Flow.

All Page Flows have a begin method. This is similar to the main method in a Java class. In this example, the begin method does only one thing: it directs you to the helloworld.jsp page. Listing 2 shows this JSP.

Listing 2. helloworld.jsp in WebLogic Workshop

<%@page language="java" contentType="text/html;charset=UTF-8"%>
<%@taglib uri="netui-tags-databinding.tld"prefix="netui-data"%>
<%@taglib uri="netui-tags-html.tld"prefix="netui"%>
<%@taglib uri="netui-tags-template.tld"prefix="netui-template"%>
<netui:html>
   <head>
      <title>
         WebLogic Workshop - Hello World
      </title>
   </head>
   <body>
      <p>
         Hello World !!
      </p>
   </body>
</netui:html>

This JSP is simple enough. You can easily compile and deploy this Page Flow from within WebLogic Workshop and see its execution.

Note: BEA WebLogic 9.x (http://e-docs.bea.com) will be based on the Apache Beehive version of Page Flows rather than the proprietary version of Page Flows you'll find in BEA WebLogic 8.1.

Now, let's see the same Page Flow in Apache Beehive.

Page Flows in Apache Beehive

The HelloWorld example in Beehive looks a little different from the WebLogic Workshop version. Let's first look at the controller in Listing 3.

Listing 3. helloworld.jpf in Apache Beehive

import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
import org.apache.beehive.netui.pageflow.Forward;
@Jpf.Controller (
   simpleActions={
      @Jpf.SimpleAction (name="cancel", path="begin.do")
      }
)
public class HelloWorldController extends PageFlowController
{
@Jpf.Action (
   forwards={
      @Jpf.Forward (name="success", path="helloworld.jsp")
      }
)
public Forward begin()
{
   return new Forward("success");}

You'll immediately notice that this version of the Java Page Flow is a lot shorter and crisper. All the Javadocs annotations at the beginning of the class code are no longer needed in the Apache Beehive version. Listing 4 shows the JSP that goes with this controller.

Listing 4. helloworld.jsp in Apache Beehive

<%@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>beehive - hello world</title>
      <netui:base/>
   </head>
   <netui:body>
      <p>
         Hello World !!
         <br>
      </p>
   </netui:body>
</netui:html>

The "How to Run the Sample Code" sidebar will show you how to set up and run this example in your own environment.

HOW TO RUN THE SAMPLE CODE

Use the following steps to set up and run the HelloWorld example in your own environment.

Make a Project Folder

First, make sure you've read Appendix A. Then, on your C: drive, create a directory named beehive-projects. In the beehive-projects directory, create a directory named helloworld. Before proceeding, confirm that the following directory structure exists:

C:\
   beehive-projects
      helloworld

Copy Runtime JARs to the Project Folder

Copy the folder BEEHIVE_HOME/samples/netui-blank/resources into your project folder, C:\beehive_projects \helloworld. BEEHIVE_HOME is the top-level folder of your Beehive installation, as explained in Appendix A.

Copy the folder BEEHIVE_HOME/samples/netui-blank/WEB-INF into your project folder, C:\beehive-projects \helloworld.

Now, assemble the runtime resources for your Page Flow application. The runtime JARs include the Page Flow runtime, the NetUI tag library, and so on. You can load these resources into your project's WEB-INF/lib folder using the following Ant command at the command prompt:

ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml
    -Dwebapp.dir=C:\beehive-projects
                   \helloworld deploy.beehive.webapp.runtime

This command will copy all JAR files to the WEB-INF/lib directory. Next, create the controller file, the central file for any Page Flow. Then, in the directory C:/beehive-projects/helloworld, create a file named HelloWorldController.jpf. In a text editor (or your IDE of choice), open the file HelloWorldController.jpf. In the directory C:/beehive-projects/helloworld, create a file named helloworld.jsp.

Compile and Deploy the Page Flow

You're now ready to compile the Page Flow and deploy it to Tomcat. Start the Tomcat server. Using the command shell opened in the previous step, at the command prompt, enter the following:

ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml
    -Dwebapp.dir=C:\beehive-projects \helloworld
    -Dcontext.path=helloworld build.webapp deploy

To undeploy the application, use the following Ant command:

ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml
    -Dwebapp.dir=C:\beehive-projects \helloworld
    -Dcontext.path=helloworld undeploy

Let's now look at a more detailed example. In this example, you'll extend the HelloWorld controller to actually have some basic "login" functionality.

Figure 1 shows the basic functionality you'll implement in the HelloWorld controller. For this example, you'll implement three actions—begin, processLogin, and showLogin—that go to three different JSPs. There's a login form where the user can fill in their username and password. When the user submits the form, they will be directed to success.jsp. Listing 5 shows the controller code for this simple Page Flow.

Figure 1. Basic login process in the HelloWorld controller

Listing 5. helloworld.jpf Extended for Login Functionality

import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
import org.apache.beehive.netui.pageflow.Forward;
import helloworld.forms.LoginForm;

@Jpf.Controller (
   simpleActions={
      @Jpf.SimpleAction (name="cancel", path="begin.do")
      }
   )
public class HelloWorldController extends PageFlowController
{
@Jpf.Action (
   forwards={
      @Jpf.Forward (name="success", path="helloworld.jsp")
      }
   )
public Forward begin()
{
   return new Forward("success");
}

@Jpf.Action (
      forwards={
         @Jpf.Forward (name="success", path="login.jsp")
         }
   )
public Forward showLoginPage()
{
   return new Forward("success");}
@Jpf.Action(
      forwards ={
         @Jpf.Forward(name ="success", path ="success.jsp")
      }
   )
   public Forward processLogin(LoginForm form)
   {
      System.out.println("User Name:"+form.getUsername());
      System.out.println("Password:"+form.getPassword());
      return new Forward("success");
   }
}

To make this work, add just one line of code to helloworld.jsp:

<netui:anchor action="showLoginPage">Login</netui:anchor>

This translates to a link that the user can click in helloworld.jsp. This will trigger the showLoginPage action and take the user to login.jsp. Listing 6 shows login.jsp.

Listing 6. login.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>Login</title>
      <netui:base/>
   </head>
   <netui:body>
      <p>
         <p>
            <netui:form action="processLogin">
            <p>User Name:
               <netui:textBox dataSource="actionForm.username"/>
            <p>Password:
               <netui:textBox dataSource="actionForm.password"
                              password="true"size="20"/>
               <dataSource="actionForm.name"/>
               <p>
                  <netui:button type="submit">Submit
               </netui:button>
               <netui:button action="cancel">Cancel
               </netui:button>
            </netui:form>
         </p>
      </p>
   </netui:body>
</netui:html>

The login JSP introduces the concept of a form. This is a basic form that looks a lot like a JavaBean or a Struts form class. It has basic getters and setters for the fields you've displayed in the JSP. NetUI and Page Flows provide automatic binding between the form variables and the JSP fields. Listing 7 shows the LoginForm class.

Listing 7. LoginForm.java

package helloworld.forms;
import org.apache.beehive.netui.pageflow.FormData;
public class LoginForm extends FormData
{
   private String username;
   private String password;
   public void setUsername(String name)
   {
      this.username =name;
   }
   public String getUsername()
   {
      return this.username;
   }
   public void setPassword(String password)
   {
      this.password=password;
   }
   public String getPassword()
   {
      return this.password;
   }
}

The example you've just seen is very basic. However, it will help you identify the different pieces of the Page Flow architecture.

Editor's Note: The second part of this article will appear after August 31st.

About the Authors

Kunal Mittal is a consultant specializing in Java technology, the J2EE platform, Web Services, and SOA technologies. He has coauthored and contributed to several books on these topics. Kunal works as an applications architect for the Domestic TV division of Sony Pictures Entertainment. In his spare time, he does consulting gigs for start-ups in the SOA space and for large companies looking to implement an SOA initiative. You can contact Kunal through his Web site at www.soaconsultant.com.

Srinivas Kanchanavally is a Software Architect with CoreObjects Software Inc. in Los Angeles, California. He has an in-depth under-standing of Java and J2EE. He also has vast experience designing large-scale J2EE application architectures. Srini has worked with Java, J2EE, Struts, WebLogic, and WebLogic Portal on client projects. And he has several years of experience working with various open-source frame-works and tools such as JBoss/Tomcat, MySQL, JUnit, and HTTPUnit.

Source of This Material

Pro Apache Beehive
By Kunal Mittal and Srinivas Kanchanavally



Published: August, 2005, Paperback: 240 pages
Published by Apress Press
ISBN: 1-59059-515-7
Retail price: $39.99
This material is from Chapter 4 of the book.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date