<?xml version="1.0"?>
<!--
    $Id$

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>Building Model Components</title>
    </properties>

    <body>
        <section name="2. Building Model Components">

            <blockquote><p><em>
            "If I had a world of my own, everything would be nonsense. 
            Nothing would be what it is, because everything would be what it 
            isn't. And contrary wise, what is, it wouldn't be. And what it 
            wouldn't be, it would. You see?"
            </em></p></blockquote>

            <a name="overview"/>
            <subsection name="2.1 Overview">

                <p>
                    Many requirements documents used for building web
                    applications focus on
                    the
                    <em>View.</em>
                    However, you should ensure that the processing required
                    for each submitted
                    request is also clearly defined from the
                    <em>Model's</em>
                    perspective.
                    In general, the developer of the
                    <em>Model</em>
                    components will be focusing
                    on the creation of JavaBeans classes that support all of
                    the functional
                    requirements.
                    The precise nature of the beans required by a particular
                    application will
                    vary widely depending on those requirements, but they can
                    generally be
                    classified into several categories discussed below.
                    However, a brief review of the concept of "scope" as it
                    relates to beans
                    and JSP is useful first.
                </p>

            </subsection>

            <a name="javabeans"/>
            <subsection name="2.2 JavaBeans and Scope">

                <p>
                    Within a web-based application, JavaBeans can be stored in
                    (and accessed
                    from) a number of different collections of "attributes".
                    Each collection has different rules for the lifetime of
                    that collection,
                    and the visibility of the beans stored there.
                    Together, the rules defining lifetime and visibility are
                    called the
                    <em>scope</em>
                    of those beans.
                    The JavaServer Pages (JSP) Specification defines scope
                    choices using
                    the following terms (with the equivalent servlet API
                    concept defined in
                    parentheses):
                </p>

                <ul>

                    <li>
                        <strong>page</strong>
                        - Beans that are visible within a single JSP page,
                        for the lifetime of the current request.
                        (Local variables of the
                        <code>service</code>
                        method)
                    </li>

                    <li>
                        <strong>request</strong>
                        - Beans that are visible within a single JSP page,
                        as well as to any page or servlet that is included in
                        this page,
                        or forwarded to by this page.
                        (Request attributes)
                    </li>

                    <li>
                        <strong>session</strong>
                        - Beans that are visible to all JSP pages and
                        servlets that participate in a particular user
                        session, across one
                        or more requests.
                        (Session attributes)
                    </li>

                    <li>
                        <strong>application</strong>
                        - Beans that are visible to all JSP pages and
                        servlets that are part of a web application.
                        (Servlet context attributes)
                    </li>

                </ul>

                <p>
                    It is important to remember that JSP pages and servlets in
                    the same
                    web application share the same sets of bean collections.
                    For example, a bean stored as a request attribute in a
                    servlet like this:
                </p>

                <p>
                    <code>MyCart mycart = new MyCart(...);
                        <br/>
                        request.setAttribute("cart", mycart);
                    </code>
                </p>

                <p>
                    is immediately visible to a JSP page which this servlet
                    forwards to,
                    using a standard action tag like this:
                </p>

                <p>
                    <code>&lt;jsp:useBean id="cart" scope="request"
                        <br/>
                        class="com.mycompany.MyApp.MyCart"/&gt;
                    </code>
                </p>

            </subsection>

            <a name="actionform"/>
            <subsection name="2.3 ActionForm Beans">


                <p>
                    <strong>Note:</strong>
                    While ActionForm beans often have properties that
                    correspond to properties in your Model beans, the form
                    beans themselves
                    should be considered a Controller component.
                    As such, they are able to transfer data between the Model
                    and View layers.
                </p>

                <p>
                    The Struts framework generally assumes that you have
                    defined an
                    <code>ActionForm</code>
                    bean (that is, a Java class extending the
                    <code>ActionForm</code>
                    class) for the input forms in your
                    application.
                    <code>ActionForm</code>
                    beans are sometimes just called "form beans".
                    These may be finely-grained objects, so that there is one
                    bean for each form, or coarsely-grained so that one bean
                    serves
                    several forms, or even an entire application.
                </p>

                <p>
                    If you declare such beans in your Struts
                    configuration file 
                    <a href="building_controller.html#4_8_Writing_Action_Mappings">
                        (see Writing Action Mappings),</a>
                    the Struts controller servlet
                    will automatically perform the following services for you,
                    before
                    invoking the appropriate
                    <code>Action</code>
                    method:
                </p>

                <ul>

                    <li>
                        Check for an instance of a bean of the appropriate
                        class, under the appropriate key,
                        in the appropriate scope (request or session).
                    </li>

                    <li>
                        If there is no such bean instance available, a new one
                        is
                        automatically created and added to the appropriate
                        scope (request or session).
                    </li>

                    <li>
                        For every request parameter whose name corresponds to
                        the name
                        of a property in the bean, the corresponding setter
                        method will
                        be called. This operates in a manner similar to the
                        standard
                        JSP action
                        <code>&lt;jsp:setProperty&gt;</code>
                        when you use the
                        asterisk wildcard to select all properties.
                    </li>

                    <li>
                        The updated
                        <code>ActionForm</code>
                        bean will be passed to the
                        <code>execute</code>
                        method of an
                        <code>Action</code>
                        class
                        <code>[org.apache.struts.Action],</code>
                        so that the values can
                        be made available to your system state and business
                        logic beans.
                    </li>

                </ul>

                <p>
                    For more about coding
                    <code>Actions</code>
                    and
                    <code>ActionForm</code>
                    beans, see the 
                    <a href="building_controller.html">Building
                        Controller Components</a>
                    section.
                </p>

                <p>
                    You should note that a "form" (in the sense discussed
                    here) does not
                    necessarily correspond to a single JSP page in the user
                    interface.
                    It is common in many applications to have a "form" (from
                    the user's
                    perspective) that extends over multiple pages.
                    Think, for example, of the wizard style user interface
                    that is commonly
                    used when installing new applications.
                    Struts encourages you to define a single
                    <code>ActionForm</code>
                    bean that
                    contains properties for all of the fields, no matter which
                    page the field
                    is actually displayed on.
                    Likewise, the various pages of the same form should all be
                    submitted to
                    the same Action Class.
                    If you follow these suggestions, the page designers can
                    rearrange the
                    fields among the various pages, often without requiring
                    changes to the
                    processing logic.
                </p>

                <p>
                    Smaller applications may only need a single ActionForm to
                    service all of
                    its input forms.
                    Others applications might use a single ActionForm for each
                    major subsystem
                    of the application.
                    Some teams might prefer to have a separate ActionForm
                    class for each
                    distinct input form or workflow.
                    How many or how few ActionForms to use is entirely up to
                    you.
                    The framework doesn't care.
                </p>

            </subsection>

            <a name="system_state"/>
            <subsection name="2.4 System State Beans">

                <p>
                    The actual state of a system is normally represented as a
                    set of one or
                    more JavaBeans classes, whose properties define the
                    current state.
                    A shopping cart system, for example, will include a bean
                    that represents
                    the cart being maintained for each individual shopper, and
                    will (among
                    other things) include the set of items that the shopper
                    has currently
                    selected for purchase.
                    Separately, the system will also include different beans
                    for the user's
                    profile information (including their credit card and
                    ship-to addresses),
                    as well as the catalog of available items and their
                    current inventory
                    levels.
                </p>

                <p>
                    For small scale systems, or for state information that
                    need not be kept
                    for a long period of time, a set of system state beans may
                    contain all the
                    knowledge that the system ever has of these particular
                    details.
                    Or, as is often the case, the system state beans will
                    represent
                    information that is stored permanently in some external
                    database (such as
                    a
                    <code>CustomerBean</code>
                    object that corresponds to a particular row in
                    the CUSTOMERS table), and are created or removed from the
                    server's memory
                    as needed.
                    Entity Enterprise JavaBeans are also used for this purpose
                    in large scale
                    applications.
                </p>

            </subsection>

            <a name="business_logic"/>
            <subsection name="2.5 Business Logic Beans">

                <p>
                    You should encapsulate the functional logic of your
                    application as
                    method calls on JavaBeans designed for this purpose.
                    These methods may be part of the same classes used for the
                    system state
                    beans, or they may be in separate classes dedicated to
                    performing the
                    logic.
                    In the latter case, you will usually need to pass the
                    system state beans
                    to be manipulated to these methods as arguments.
                </p>

                <p>
                    For maximum code re-use, business logic beans should be
                    designed and
                    implemented so that they do
                    <strong>not</strong>
                    know they are being executed in a
                    web application environment.
                    If you find yourself having to import a
                    <code>javax.servlet.*</code>
                    class
                    in your bean, you are tying this business logic to the web
                    application
                    environment.
                    Consider rearranging things so that your
                    <code>Action</code>
                    classes (part
                    of the Controller role, as described below) translate all
                    required
                    information from the HTTP request being processed into
                    property setter
                    calls on your business logic beans, after which a call to
                    an
                    <code>execute</code>
                    method can be made.
                    Such a business logic class can be reused in environments
                    other than the
                    web application for which they were initially constructed.
                </p>

                <p>
                    Depending on the complexity and scope of your application,
                    business logic
                    beans might be ordinary JavaBeans that interact with
                    system state beans
                    passed as arguments, or ordinary JavaBeans that access a
                    database using
                    JDBC calls.
                    For larger applications, these beans will often be
                    stateful or stateless
                    Enterprise JavaBeans (EJBs) instead.
                </p>
                
                <p>
                    For more about using a database with your application, see
                    the
                    <a href="../faqs/db-howto.html">Accessing a Database
                        HowTo.</a>
                </p>

                <p>
                    For more about business logic and data access frameworks, 
                    see the <a href="http://struts.apache.org/primer.html">
                    key technologies primer</a>.
                </p>
                

            </subsection>
            
            
            <a name="dynabeans"/>
            <subsection name="2.5.1 DynaBeans">

                <p>
                    DynaBeans combine the extensibility of JavaBeans with the
                    flexibility of a Map.
                    Defining even the simplest JavaBean requires defining a
                    new class and coding a field and two methods for each
                    property.
                    The properties of a DynaBean can be configured via an XML
                    descriptor.
                    The virtual properties of a DynaBean can't be called by
                    standard Java methods,
                    but work well with components that rely on reflection and
                    introspection.
                </p>

                <p>
                    In your application, you can use DynaBeans to describe
                    your HTML forms.
                    This strategy can avoid creating a formal JavaBean
                    subclass to store a few simple properties.
                </p>

                <p>
                    For more about DynaBeans, see
                </p>

                <ul>
                    <li>
                        The Commons BeanUtils
                        <a href="http://commons.apache.org/beanutils/api/org/apache/commons/beanutils/package-summary.html#package_description">
                            Package Description</a>
                        and
                        <a href="http://commons.apache.org/beanutils/api/index.html">
                            Javadocs.</a>
                    </li>
                    <li>
                        <a href="https://formdef.dev.java.net/">Struts
                            FormDef</a>
                    </li>
                </ul>

            </subsection>            
                
            <a name="chain"/>
            <subsection name="2.6 Commons Chain">

                <p>
                    A popular technique for organizing the execution of
                    complex
                    processing flows is the "Chain of Responsibility" pattern,
                    as described (among many other places) in the classic
                    <a href="http://www.amazon.com/exec/obidos/tg/detail/-/0201633612/apachesoftwar-20/">
                        "Gang of Four" design patterns book.</a>
                    The GoF summarizes the Chain of Responsibility pattern as
                    "Avoid coupling the sender of a request to its receiver
                    by giving more than one object a chance to handle the
                    request.
                    Chain the receiving objects
                    and pass the request along the chain until an object
                    handles it."
                </p>

                <p>
                    The CoR pattern helps us keep software components loosely
                    coupled.
                    A component can call a Chain of Responsbility,
                    without knowing what objects are on the chain or how they
                    are
                    implemented.
                    Most importantly, we can adjust the Chain without changing
                    how callers invoke the Chain.
                    As of version 1.3,
                    the default Request Processor,
                    which acts as the framework's "kernel",
                    is a Chain of Responsiblity.
                </p>

                <p>
                    To implement its Chain, the Request Processor uses the
                    <a href="http://commons.apache.org/chain/">
                        Chain of Responsibility</a>
                    component in the Apache Commons
                    which provides a standard implementation of the CoR
                    pattern,
                    along with various implementations of the Context and
                    Command objects used by the Chain to service a request.
                </p>

                <p>
                    For more about Chain of Responsiblity, see
                </p>

                <ul>
                    <li>
                        <a href="http://commons.apache.org/chain/">
                            Commons Chain of Responsibility</a>
                    </li>
                    <li>
                        <a href="http://www.onjava.com/lpt/a/5671">
                            A look at Commons Chain</a>
                    </li>
                    <li>
                        <a href="http://www.infonoia.com/en/content.jsp?d=inf.05.06&amp;pr=1">
                            Better Code with Struts 1.3
                        </a>
                    </li>
                </ul>
                
                <p>
                    As of Struts 1.3, Commons Chain is used to construct the
                    default
                    Request Processor for the framework.
                </p>                 

            </subsection>                
        </section>

        <section>
            <p class="right">
                Next:
                <a href="building_view.html">Building View Components</a>
            </p>
        </section>

    </body>
</document>
