http://www.developer.com/

Back to article

Introducing Java Page Flow Architecture


August 31, 2005

This article pick up where our earlier article, Dissecting Java Page Flows ended. In the following sections, we'll talk about the basic architecture and components that make up Java Page Flows and the NetUI tags.

Page Flow Components

The different components of a Page Flow are as follows:

  • Controllers
  • Form classes
Controllers

The Jpf.Controller annotation is the meat of a Page Flow. It's just a file that contains Java code and annotations. The extension of this file is .jpf. As you saw in the previous example, a controller consists of several actions. This is unlike Struts—where one action is one class. You can think of a controller as a collection of action classes. The different annotations of a Page Flow are as follows:

  • Jpf.Catch []: Exceptions that the controller catches. We always recommend catching at least the Exception class to handle any unexpected/unhandled exceptions.
  • Jpf.Forward []: The different forwards. Each action has one or many forwards.
  • global forwards: Any global forwards. For example, when an exception is caught, you might need a global forward. We always recommend having at least one of these go to some error page when an exception is thrown, as described in the Jpf.Catch item.
  • boolean loginRequired: Does this controller require the user to be logged in to execute the actions defined in this Page Flow?
  • Jpf.MessageResource [] messageResources: Which message resources to use for error messages. This is similar to the Struts message resources.
  • Jpf.MultipartHandler multipartHandler: Does this controller need to access multipart forms?
  • boolean nested: Is this Page Flow a nested Page Flow?
  • boolean readOnly: The actions do not modify any member variables.
  • String [] rolesAllowed: The roles that can access actions in this Page Flow.
  • Jpf.SimpleAction [] simpleActions: The simple actions in this Page Flow.
  • boolean singleton: Is this Page Flow a singleton?
  • String strutsMerge: The location of the Struts merge file.
  • Jpf.ValidatableBean [] validatableBeans: The validation rules for the beans.
  • String validatorMerge: The location of the ValidatorPlugIn merge file.
Caution: Since Apache Beehive is still in early development, we recommend looking at the Javadocs online for the latest and greatest list of methods and functionality. See http://incubator.apache.org/beehive/apidocs/classref_pageflows/index.html.

The PageFlowController class provides more than just actions. Figure 1 shows the basic relations between the FlowController parent class and the PageFlowController class. (Note that the figure shows only some of the methods in the classes; see the Javadocs for a complete listing of all the methods available in these classes.)

Figure 1. Class diagram of FlowController and PageFlowController

Let's look at a few of the methods that you might use more regularly than others:

  • afterAction: This method is a callback that occurs after any user action method is invoked.
  • beforeAction: This method executes before any action executes. It's sort of a preProcess method for an action.
  • onCreate: This executes when the Page Flow is created; you can use it to initialize any instance variables for the Page Flow.
  • onDestroy: This executes when the Page Flow is destroyed; you can use it to clean up any variables.
  • onRefresh: This is specifically important in a portal environment when no action needs to be executed and you'd rather just render a previously displayed JSP.
  • isNestable: This determines whether this Page Flow can be nested.
  • isSingleton: This determines whether this Page Flow is a singleton.
Tip: As you start working with Page Flows, refer to the PageFlowUtils class. It provides a bunch of helper methods that you'll find useful.

Action and Forward Classes

Integral parts of using a Page Flow controller are the action classes and the forward classes. Let's quickly take a look at what they offer.

Action

The following are the annotations that are available for an action class:

  • Jpf.Catch []: The different exceptions caught by this action.
  • Jpf.Forward []: The different forwards defined by this action.
  • boolean loginRequired: Does this action require that the user be logged in?
  • boolean readOnly: A guarantee that this action does not change any Page Flow variables.
  • String [] rolesAllowed: The roles that can access this action.
  • String useFormBean: The form bean that this action class uses.
  • Jpf.ValidatableProperty [] validatableProperties: The properties of the form bean that need to be validated.
  • Jpf.Forward validationErrorForward: The forward to use when there is any validation error.
Forward

The following are the annotations offered by the forward classes:

  • Jpf.ActionOutput [] actionOutputs: List of action outputs.
  • boolean externalRedirect: Redirect to some external action
  • Jpf.NavigateTo navigateTo: The page or action to navigate to
  • String outputFormBean: Output form bean
  • Class outputFormBeanType: Output form bean type
  • String path: The path to forward too, usually a JSP
  • boolean redirect: Redirect or not
  • boolean restoreQueryString: Whether the original query string will be restored on a rerun of a previous action
  • String returnAction: The action to be executed on the original Page Flow
Tip: We recommend you look at the different methods on the Forward object. They will prove to be useful as you start building complex Page Flow applications.

NetUI Components

NetUI is a set of tag libraries that you will use as part of your JSPs. These tag libraries are JSP 2.0 complaint. Three tag libraries make up NetUI:

  • NetUI
  • NetUI-data
  • NetUI-template
Caution: The NetUI-data and NetUI-template tag libraries depend on the NetUI tag libraries. All the base classes for the three tag libraries are provided as part of the NetUI (HTML) tag library.

The basic functionality in these tag libraries is to simplify JSP development and provide automatic data binding between the view and controller layers. These tags come with JavaScript support, so you can work with them like you would the standard HTML tags (input, select, and so on).

NetUI

The NetUI name is a little misleading. Think of this tag library as NetUI-html. That makes it clearer, doesn't it? This tag library contains the tags similar to the struts-html tag library. Table 1, which comes straight from the Javadocs, shows the tags in this library. As you'll see, this library contains the standard tags that you might use with vanilla HTML development.

Note: The reason I've simply cut and paste the information from the Javadocs is because, at the time of writing this material, Apache Beehive is still in the beta stage. Therefore, some of these methods might change. Visit the Beehive documentation page for the latest Javadocs at http://incubator.apache.org/beehive/reference/taglib/index.html.

Table 1. NetUI Tag Library

Tag Description
<netui:anchor> Generates an anchor that can link to another document or invoke an action method in the controller file
<netui:attribute> Adds an attribute to the parent tag rendered in the browser
<netui:base> Provides the base for every URL on the page
<netui:bindingUpdateErrors> Renders the set of error messages found during the process of resolving data binding expressions ({pageFlow.firstname}, {request.firstname}, and so on)
<netui:body> Renders an HTML <body> tag with the attributes specified
<netui:button> Renders an HTML button with the specified attributes
<netui:checkBox> Generates a single HTML checkbox
<netui:checkBoxGroup> Handles data binding for a collection of checkboxes
<netui:checkBoxOption> Renders a single HTML checkbox within a group of checkboxes
<netui:content> Displays text or the result of an expression
<netui:error> Renders an error message with a given error key value if that key can be found in the ActionErrors registered in the PageContext at org.apache.struts.action.Action.ERROR_KEY
<netui:errors> Renders the set of error messages found in the ActionErrors registered in the PageContext at org.apache.struts.action.Action.ERROR_KEY
<netui:exceptions> Renders exception messages and stack traces inline on the JSP
<netui:fileUpload> Renders an HTML input tag with which users can browse, select, and upload files from their local machines
<netui:form> Renders an HTML form that can be submitted to a Java method in the controller file for processing
<netui:formatDate> Renders a formatter used to format dates
<netui:formatNumber> Renders a formatter used to format numbers
<netui:formatString> Renders a formatter used to format strings
<netui:hidden> Generates an HTML hidden tag with a given value
<netui:html> Renders an <html> tag
<netui:image> Renders an HTML <image> tag with the specified attributes
<netui:imageAnchor> Generates a hyperlink with a clickable image
<netui:imageButton> Renders an <input type="image"> tag with the specified attributes
<netui:label> Associates text with an input element in a form
<netui:parameter> Writes a name-value pair to the URL or the parent tag
<netui:parameterMap> Writes a group of name-value pairs to the URL or the parent tag
<netui:radioButtonGroup> Renders a collection of radio button options and handles the data binding of their values
<netui:radioButtonOption> Generates a single radio button option in a group of options
<netui:rewriteName> Allows a name, typically either an id or name attribute, to participate in URL rewriting
<netui:rewriteURL> Allows a tag name, typically either an id or name attribute, to participate in URL rewriting
<netui:scriptContainer> Acts as a container that will bundle JavaScript created by other <netui...> tags and outputs it within a single <script> tag
<netui:scriptHeader> Writes the <script> that JavaScript will include in the HTML <head> tag
<netui:select> Renders an HTML <select> tag containing a set of selectable options
<netui:selectOption> Renders a single <option>tag
<netui:span> Generates styled text based on a String literal or data binding expression
<netui:textArea> Renders an HTML <input> tag of type "text"
<netui:textBox> Renders an HTML <input type="text"> tag
<netui:tree>
<netui:treeContent>
<netui:treeHtmlAttribute>
<netui:treeItem>
<netui:treeLabel>
<netui:treePropertyOverride>
Renders a navigable tree of TreeElement tags

NetUI-data

The NetUI-data tag library is used to bind data from forms and the controller to the JSP. It allows you to quickly display lists of data (such as search results). See Table 2, which shows the Javadocs information about this tag library.

Table 2. NetUI-data Tag Library

Tag Description
<netui-data:anchorColumn>  
<netui-data:callMethod> Calls methods on any Java classes
<netui-data:callPageFlow> Calls methods on the controller file (which is a JPF file) in the same directory as the JSP
<netui-data:caption>  
<netui-data:cellRepeater> Renders individual cells of an HTML table
<netui-data:columns>  
<netui-data:configurePager>  
<netui-data:dataGrid>  
<netui-data:declareBundle> Declares a java.util.ResourceBundle as a source for displaying internationalized messages
<netui-data:declarePageInput> Declares variables that are passed from the controller file to the JSP
<netui-data:footer>  
<netui-data:getData> Evaluates an expression and places the result in the javax.servlet.jsp.PageContext object, where the data is available to JSP scriptlets
<netui-data:imageColumn>  
<netui-data:literalColumn>  
<netui-data:message> Provides a message schema, which can be parameterized to construct customizable messages
<netui-data:messageArg> Provides a parameter value to a message schema
<netui-data:methodParameter> Provides an argument to a method-calling tag
<netui-data:pad> Sets the number of items rendered by a tag
<netui-data:renderPager>  
<netui-data:repeater> Iterates over a data set to render it as HTML
<netui-data:repeaterFooter> Renders the footer of a Repeater tag
<netui-data:repeaterHeader> Renders the header of a Repeater tag
<netui-data:repeaterItem> Renders an individual item in the data set as it's iterated over by the Repeater tag
<netui-data:serializeXML> Serializes an XMLBean into the output of a JSP in order to move data to the browser for data binding

NetUI-template

The NetUI-template tag library is used to create subsections (or templates) from your JSPs. See Table 3, which displays the Javadocs information about this tag library.

Table 3. NetUI-template Tag Library

Tag Description
<netui-template:attribute> Defines a property placeholder within a template
<netui-template:divPanel> Creates an HTML <div> tag that may contain additional tags
<netui-template:includeSection> Defines a content placeholder within a template
<netui-template:section> Sets HTML content inside placeholders defined by an IncludeSection tag
<netui-template:setAttribute> Sets a property value in a template page
<netui-template:template> Points a content page at its template page

You've just seen a brief overview of Page Flows and NetUI. Now let's see how all this plays together.

Reviewing Page Flow Architecture

The best way to explain the overall architecture of Page Flows and NetUI is to map these to the standard MVC model, as shown in Figure 2.



Click here for a larger image.

Figure 2. MVC architecture of Page Flows and NetUI

Think of the controller bucket as being the Page Flow controllers. If you're familiar with Struts, this bucket is filled by Struts actions. The view is a collection of JSPs and some tag libraries, in this case the NetUI tag libraries. In Struts, it would be the Struts tag libraries. The model layer is not really predetermined by Page Flows. As part of the Apache Beehive project, there is a technology called Controls. This is a model layer technology.

However, for purposes of Java Page Flows, the model layer could be anything. You could obviously use Controls. Or, you could have a set of Java classes that serve as business delegates, which then interact with your EJBs, DAOs, and other classes.

Throughout the article, I've alluded to the real advantages of Page Flows over Struts:

  • Ease of use: The main development savings between Struts and Page Flows is the JSR 175 metadata support. While developing Page Flows, you don't need to manually maintain the struts-config files.
  • Data binding: With Page Flows and NetUI, you get automatic data binding between the form variables and the form fields in the JSP.
  • Exception handling: This goes back to the annotations. You can define how all your exceptions get handled using the annotations. As a best practice, we recommend always catching the Exception class at the Page Flow level. This allows you to handle any otherwise uncaught exceptions.
  • Nested Page Flows: The whole concept of nested Page Flows is new.
  • State management: Page Flows automatically maintain state. This feature is even more important if you're working with portals.
  • Portal use: Page Flows were originally developed for portal development. Thus, a lot of the features are targeted toward portal projects.
  • Service orientation: The integration of Page Flows with Java Controls leads to a more service-oriented approach for application development.

Conclusion

In this article, you saw the basic components that make up Java Page Flows and NetUI. You also looked at a quick example and then drilled down into the overall architecture of these technologies.

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