<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
    <header>
        <title>NetUI Overview</title>
    </header>
    <body>
        <section id="introduction">
            <title>Introduction</title>
            <p>
                NetUI is the piece of Beehive used to build the
                front-end of a web application. It contains two pieces:
                Page Flow and a powerful set of JSP tags.
            </p>
        </section>
        <section id="why">
            <title>Why Use NetUI?</title>
            <p>
                Simply put, NetUI (Page Flow and a powerful set of JSP
                tags) helps you build a well-structured web application
                using a simple programming model.
            </p>
            <p>
                First, because NetUI is an MVC framework (built on
                <a href="http://struts.apache.org">Apache Struts</a>
                ), it separates navigational control from presentation.
                This avoids:
            </p>
            <ul>
                <li>Limited reuse of navigational/flow logic.</li>
                <li>Cluttered, hard-to-maintain JSP source code.</li>
                <li>
                    Difficulty in understanding the flow of an
                    application.
                </li>
                <li>
                    Unintended exposure of controller-logic code to team
                    members who focus on other aspects of web
                    development, such as content writers and visual
                    designers.
                </li>
            </ul>
            <p>
                Second, NetUI provides the Page Flow programming model
                which allows you to create
                <em>modular</em>
                "page flows" that can be inserted (and reused) inside of
                other flows. At root, it unifies the controller
                logic, state, and metadata for a piece of your
                application into a single class. On the View side, it
                offers a rich set of tags, such as the
                <a href="site:pageflow_tag_tree">Tree</a>
                and the
                <a href="site:datagrid">Datagrid</a>
                .
            </p>
        </section>
        <section id="Page_Flow_Features">
            <title>NetUI Features</title>
            <p>
                NetUI makes building Java web applications easy and
                intuitive. When building applications with NetUI, the
                developer writes Java classes and pages --that's it.
                There is very little occasion to work with configuration
                files, or other components. NetUI also excels at
                separating presentation logic from data processing
                logic, resulting in uncluttered JSP code which is easy
                to understand and edit. Data processing and the web
                application configurables are handled in a single Java
                class using a simple declarative programming model.
            </p>
            <p>
                <strong>Declarative Programming</strong>
            </p>
            <p>
                Many common web app programming tasks are accomplished
                through a declarative programming model using
                "annotations", a new feature in Java 5. Annotations put
                configuration information (in general, "metadata") right
                alongside your code, alleviating the need for
                independent configuration files. Navigation, exception
                handling, validation, and other tasks are all defined in
                a single Java class: the Page Flow "controller" class
                that drives a piece of your web application.
            </p>
            <p>
                <strong>Stateful Page Flows</strong>
            </p>
            <p>
                When a user enters a page flow (by hitting an URL in the
                page flow's URL space), an instance of the page flow's
                controller class is created. While the user is in the
                page flow, the controller instance simply stores the
                flow-related state in member variables. Methods within
                the class -- particularly action methods and exception
                handlers -- have access to the member state. By default,
                the state is
                <em>automatically cleaned up</em>
                when the user leaves the page flow to enter another one.
                This behavior can be configured per-page flow, but
                auto-cleanup helps keep your session small, and focused
                on the task at hand.
            </p>
            <p>
                <strong>Modular Page Flows</strong>
            </p>
            <p>
                A single web application can have multiple page flows
                within it, allowing you to break up the application into
                separate, self-contained chunks of functionality. For an
                example, see the
                <a class="fork" href="site:samples/petstore">
                    Petstore Sample
                </a>
                , which has different page flows for browsing the
                Petstore, buying products, and handling user accounts.
            </p>
            <p>
                <strong>Inheritance and Shared Flow</strong>
            </p>
            <p>
                <a href="site:pageflow_inheritance">Page Flow inheritance</a> is a powerful way to share actions,
                exception handlers, configuration, etc. among controller classes.  It is normal Java inheritance,
                plus the ability to inherit/merge <em>annotations</em>.
            </p>
            <p>
                <a href="site:pageflow_sharedFlow">Shared Flow</a> provides an alternative way to make actions and
                exception handlers available to multiple page flows. The feature is useful for accessing shared state,
                for shared/templated user interface, and when you cannot change your controller class hierarchy.
            </p>
            <p>
                <strong>Nested Page Flows</strong>
            </p>
            <p>
                An entire page flow can be inserted, or "nested", inside of another page flow. At its heart,
                <a href="site:docs/pageflow/netuiBasic/nestedPageFlow">nesting</a>
                is a way of pushing aside the current page flow temporarily and transferring control to another (nested)
                page flow with the intention of coming back to the original one. Nesting is useful when you want to do
                one of the following tasks:
            </p>
            <ul>
                <li>
                    gather data from the user, for use in the current
                    page flow;
                </li>
                <li>
                    allow the user to correct errors or supply
                    additional information en route to executing a
                    desired action;
                </li>
                <li>
                    show an alternate view of data represented in the
                    current page flow;
                </li>
                <li>bring the user through a "wizard";</li>
                <li>
                    show the user information that will be useful in the
                    current page flow (e.g., help screens can be easily
                    implemented as nested page flows); and
                </li>
                <li>
                    in general, to further break up your application
                    into separate (and in many cases reusable) pieces.
                </li>
            </ul>
            <p>
                NetUI also offers special integration between nested
                page flows and
                <a href="site:pageflow_popups">popup windows</a>.
            </p>
            <p>
                <strong>
                    Declarative Exception Handling and Validation
                </strong>
            </p>
            <p>
                <a href="site:docs/pageflow/netuiBasic/actions">Exception handling</a> and
                <a href="site:docs/pageflow/netuiBasic/validation">data validation</a>
                are accomplished through a declarative programming
                model. The desired exception handling and validation
                behaviors are declared in the controller class
                (and additionally on form bean classes, for validation)
                alongside your Java code in the form of metadata
                annotations. This allows for single file editing and
                eliminates the need for separate configuration files.
            </p>
            <p>
                <strong>Powerful JSP Tags</strong>
            </p>
            <p>
                NetUI provides three <a href="site:pageflow_tag_overview">tag libraries</a>: (1) one library
                represents the core HTML tags, (2) another renders data
                grids and complex data sets as HTML, and (3) a third
                library provides page templating functionality.
            </p>
            <p>
                The NetUI tags also support <a href="site:databinding">data binding</a> (1) to JSP
                implicit objects (through the JSP 2.0 Expression
                Language) and (2) to other NetUI implicit objects. Note
                that many tags possess read-write access to these
                implicit objects.
            </p>
            <p>
                <strong>
                    First-class Integration with JavaServer Faces
                </strong>
            </p>
            <p>
                NetUI has solid integration with <a href="site:pageflow_jsf">JavaServer Faces</a>. It treats JSF as a
                first-class view tier, where, for example, JSF components and command handlers can raise Page Flow
                actions, can databind to NetUI implicit objects, etc.
            </p>
            <p>
                <strong>Struts Integration</strong>
            </p>
            <p>
                Page Flow is built on top of Apache Struts 1.1. Each
                Page Flow controller is compiled into a Struts module.
                As a result, NetUI and Struts applications can work
                closely together.
            </p>
            <p>
                Struts modules and page flows can co-habitate and
                interact with one another inside a web app. To forward
                from a page flow to a (pure) Struts module, simply
                reference the desired action within the Struts module.
                The same goes for the reverse direction: from a Struts
                module, simply configure an action to point to the
                desired method in the page flow.
                <!--[todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]-->
            </p>
            <p>
                You can also use the Struts merge feature to read
                configuration data from a pure Struts app into your Page
                Flow app's configuration files. Ordinarily, your Page
                Flow's configuration files are generated entirely from
                your application's JAVA source files (specifically from
                the
                <em>metadata annotations</em>
                that decorate the controller classes). But, in cases
                where you want to integrate a Struts module into your
                application, you can specify that the configuration
                files be generated from
                <em>both</em>
                the JAVA source files
                <em>and</em>
                the Struts module's configuration files, allowing you to
                change or add
                <em>any tag</em>
                in the generated configuration file. For example,
                suppose you want to override an action form's default
                scoping from request-scoping to session-scoping. To do
                this, you simply create a Struts configuration file that
                overrides the appropriate parts of the Page Flow's
                configuration file, and then refer to this override file
                from within the Page Flow's JAVA source file (= the
                controller class) using a special annotation. In
                particular, you would specify the override file to state
                that such-and-such an action form should have
                session-scope rather then request-scope (so that the
                action form can now be shared with the Struts app).
            </p>
        </section>
        <section id="logical_flow">
            <title>The Logical Flow</title>

            <p>
                Writing traditional web applications without a Page Flow
                controller class requires a fair amount of logic to be
                applied within the application's pages. For example, a
                site that provides a "My Page" functionality for logged
                in users would have to include logic on the home page to
                determine if the "My Page" link should take the user to
                the login form or directly to their customized page.
            </p>

            <p>
                Using a page flow, the home page of the application
                would not link directly to either the login page
                <strong>or</strong>
                the user's "My Page" location, but rather would point
                back into Java code that makes the decision.
            </p>

            <p>
                For the rest of this overview, the following
                <strong>logical page flow</strong>
                will be used:
            </p>

            <p>
                <img src="images/logical-flow-1.png"
                    alt="logical page flow" />
            </p>

            <p>
                This flow supports several routes from the home page of
                the application to the user's "My Page":
            </p>

            <ol>
                <li>
                    <p>
                        The user may directly navigate from
                        <code>index.jsp</code>
                        to
                        <code>mypage.jsp</code>
                        (by clicking a link), if the user is already
                        logged in.
                    </p>
                </li>
                <li>
                    <p>
                        If the user is not already logged in, attempts
                        to navigate from
                        <code>index.jsp</code>
                        to
                        <code>mypage.jsp</code>
                        will be intercepted and the user will be taken
                        to the
                        <code>login.jsp</code>
                        instead. After successfully logging in, the user
                        will be automatically taken to
                        <code>mypage.jsp</code>
                    </p>
                </li>
                <li>
                    <p>
                        The user may directly navigate from
                        <code>index.jsp</code>
                        to
                        <code>login.jsp</code>
                        (by clicking a link). After logging in, the user
                        will be automatically taken to
                        <code>mypage.jsp</code>
                        .
                    </p>

                    <p>
                        In the event of a login failure,
                        <code>login.jsp</code>
                        will be redisplayed to give them another
                        opportunity to authenticate themselves.
                    </p>
                </li>
                <li>
                    <p>
                        If the user desires to register with the site,
                        he can click a link that will take him to
                        <code>signup.jsp</code>
                        . One signed up, the
                        <code>thanks.jsp</code>
                        will be displayed which offers a link to the
                        <code>login.jsp</code>
                        page.
                    </p>
                </li>
            </ol>

        </section>

        <section id="implementation_of_flow">
            <title>
                The Implementation of the Flow: Controllers and Actions
            </title>

            <p>
                In the above
                <strong>logical flow</strong>
                there are several
                <em>if</em>
                statements that cause the user flow to vary depending on
                their previous actions and other state.
            </p>

            <ul>
                <li>
                    <em>If the user is not logged in...</em>
                </li>
                <li>
                    <em>If the user is logged in...</em>
                </li>
                <li>
                    <em>If the user's login attempt fails...</em>
                </li>
            </ul>

            <p>
                NetUI moves this condition logic out of the JSPs and
                into a Java class that controls the movement through the
                application. This Java class is the
                <strong>controller</strong>
                portion of the
                <strong>Model-View-Controller</strong>
                (MVC) pattern. This allows a page to be written, for
                example, that appears to link directly from the home
                page of the application to the user's "My Page". The
                controller is given the opportunity to intercept the
                navigation between the two and redirect the user to the
                login page, if required.
            </p>

            <p>
                Each of the interception points is an
                <strong>action</strong>
                of the particular controller class. Actions perform
                common application tasks. Here are some of the things
                that an action can do:
            </p>

            <ul>
                <li>navigate the user to a specified JSP</li>
                <li>perform conditional logic</li>
                <li>handle submitted data</li>
                <li>validate submitted data</li>
                <li>handle exceptions that arise in the application</li>
            </ul>

            <p>
                Note that controller classes, and the actions they
                contain, are
                <strong>URL addressable</strong>
                . Hitting the following URL creates an instance of the
                controller class
                <code>foo.MyControllerClass</code>
                and runs its
                <code>begin</code>
                action. (When no other action is specified, the
                <code>begin</code>
                method is run by default.)
            </p>

            <source>http://some.domain.com/foo/MyControllerClass.java</source>

            <p>
                Hitting the following URL creates an instance of
                <code>foo.MyControllerClass</code>
                (if it doesn't already exist) and invokes the
                <code>someAction</code>
                action. Note that the controller class isn't mentioned
                by name: it's assumed that only one controller class
                exists in the directory, so there is only one candidate
                controller class to instantiate.
            </p>

            <source>http://some.domain.com/foo/someAction.do</source>
            <note>
                To make a Page Flow controller handle a default
                directory URL, e.g.,
                <br />
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;http://some.domain.com/myApp/myPageFlow
                <br />
                <br />
                you will need to add the page flow's URL to the
                <code>welcome-file-list</code>
                in
                <code>/WEB-INF/web.xml</code>
                :
                <br />
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;&lt;welcome-file-list>
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;welcome-file>Controller.jpf&lt;/welcome-file>
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;welcome-file>index.jsp&lt;/welcome-file>
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;&lt;/welcome-file-list>
                <br />
                <br />
                This would cause the following URL to be hit for the
                above example:
                <br />
                <br />
                &nbsp;&nbsp;&nbsp;&nbsp;http://some.domain.com/myApp/myPageFlow/Controller.jpf
                <br />
                <br />
                On some servers (like Tomcat), you would also need to
                make sure that a
                <em>file</em>
                called
                <code>Controller.jpf</code>
                also exists in the web content under
                <code>/myPageFlow</code>
                , even though the class
                <code>myPageFlow.Controller</code>
                actually handles the request. (The file can be blank.)
            </note>

            <p>
                Actions may perform any required complex logic. For
                example, if a user clicks on the "My Page" link, the
                action may check if the user is logged in, and if so,
                navigate the user to the
                <code>mypage.jsp</code>
                page; otherwise it will navigate the user to the
                <code>login.jsp</code>
                page.
            </p>

            <p>
                With normal HTML pages, each page is linked directly to
                other pages.
            </p>

            <ul>
                <li>
                    <strong>page &gt; page &gt; page &gt; page</strong>
                </li>
            </ul>

            <p>
                When using page flows, pages and actions are interwoven,
                transparently.
            </p>

            <ul>
                <li>
                    <strong>
                        page &gt; action &gt; page &gt; action &gt; page
                        &gt; action &gt; page
                    </strong>
                </li>
            </ul>

            <p>
                The above
                <strong>logical page flow</strong>
                can be redrawn with Page Flow controller actions in
                mind, as:
            </p>

            <p>
                <img src="images/impl-flow-1.png"
                    alt="implementation page flow" />
            </p>

            <p>
                Now it is apparent that to navigate from
                <code>index.jsp</code>
                to
                <code>mypage.jsp</code>
                , the user traverses across the
                <code>myPage</code>
                action. This action performs the necessary check to
                determine if the user has already been authenticated. If
                the user has logged in already, it will direct the user
                straight to
                <code>mypage.jsp</code>
                ; otherwise it will direct the user to
                <code>login.jsp</code>
                .
            </p>
        </section>
        <section id="next">
            <title>Next...</title>

            <p>
                Next, learn about writing a
                <strong>controller</strong>
                class with actions.
            </p>

            <ul>
                <li>
                    <a class="jump" href="site:pageflow_controllers">
                        Controller Classes</a>
                </li>
            </ul>
        </section>
    </body>
    <footer>
        <legal>
            Java, J2EE, and JCP are trademarks or registered trademarks
            of Sun Microsystems, Inc. in the United States and other
            countries.
            <br />
            &copy; 2004, Apache Software Foundation
        </legal>
    </footer>
</document>
