<?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>Introduction</title>
    </properties>

    <body>

        <section name="1. Introduction" href="introduction">

            <blockquote><p><em>
            "Read the directions and directly you will be directed in the right 
            direction."
            </em></p></blockquote>
            
                <p>
                    The framework documentation is written for active web 
                    developers and assumes a working
                    knowledge about how Java web applications are built.
                    For more about the underlying nuts and bolts,
                    see the <a href="http://struts.apache.org/primer.html">
                    Key Technologies Primer. 
                    </a>
                </p>
                                

            <a name="history"/>
            <subsection
                    name="1.1 Forward into the Past! (or a brief history of Struts)"
                    href="history">
                    
                <p>
                    When Java servlets were first invented, many programmers
                    quickly realized that they were a
                    Good Thing. They were faster and more powerful that
                    standard CGI, portable, and infinitely
                    extensible.
                </p>

                <p>
                    But writing HTML to send to the browser in endless
                    <code>println()</code>
                    statements was tiresome and
                    problematic. The answer to that was
                    <a href="http://java.sun.com/products/jsp/product.html">
                        JavaServer Pages,</a>
                    which turned
                    <a href="http://www.novocode.com/doc/servlet-essentials/">
                        Servlet</a>
                    writing inside-out.
                    Now developers could easily mix HTML with Java code, and
                    have all the advantages of servlets.
                    The sky was the limit!
                </p>

                <p>
                    Java web applications quickly became "JSP-centric". This
                    in-and-of itself was not a Bad
                    Thing, but it did little to resolve flow control issues
                    and other problems endemic to web
                    applications.
                </p>

                <p>Clearly, another paradigm was needed ...</p>

                <p>
                    Many clever developers realized that JavaServer Pages AND
                    servlets could be used
                    <strong>
                        together</strong>
                    to deploy web applications. The servlets could help with
                    the control-flow, and the
                    JSPs could focus on the nasty business of writing HTML. In
                    due course, using JSPs and servlets
                    together became known as
                    <a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">
                        Model 2</a>
                    (meaning, presumably, that using JSPs alone was Model 1).
                </p>

                <p>
                    Of course, there is nothing new under the Sun ... and many
                    have been quick to point out that
                    JSP's Model 2 follows the classic
                    <a href="http://java.sun.com/blueprints/patterns/j2ee_patterns/model_view_controller/">
                        Model-View-Controller</a>
                    design pattern abstracted from the venerable
                    <a href="http://st-www.cs.uiuc.edu/users/smarch/st-docs/mvc.html">
                        Smalltalk MVC framework.</a>
                    Java Web developers now tend to use the terms Model 2 and
                    MVC interchangeably. In this guide, we use
                    the MVC paradigm to describe the framework architecture,
                    which might be best termed a Model 2/MVC
                    design.
                </p>

                <p>
                    The Apache Struts Project was launched in May 2000 by Craig R.
                    McClanahan to provide a standard MVC
                    framework to the Java community. In July 2001, version 1.0
                    was released, and IOHO, Java
                    Model 2 development has never been quite the same.
                </p>

            </subsection>
            
            <a name="mvc"/>
            <subsection 
                    name="1.2 The Model-View-Controller ('MVC') Design Pattern"
                    href="mvc">

                <p>
                    The term "MVC" originated with the SmallTalk 
                    Model-View-Controller framework. Under MVC, 
                    an application is seen as having three distinct parts. The 
                    problem domain is represented by the Model. The output to 
                    the user is represented by the View. And, the input from the 
                    user is represented by Controller.
                </p>

            </subsection>

            <a name="modelConcepts"/>
            <subsection
                    name="1.2.1 The Model: System State and Business Logic JavaBeans"
                    href="modelConcepts">

                <p>
                    The
                    <em>Model</em>
                    portion of an MVC-based system can be often be divided
                    into
                    two major subsystems -- the
                    <strong>internal state</strong>
                    of the system
                    and the
                    <strong>actions</strong>
                    that can be taken to change that state.
                </p>

                <p>In grammatical terms, we might think about
                    state information as
                    <strong>nouns</strong>
                    (things) and actions as
                    <strong>verbs</strong>
                    (changes to the state of those things).
                </p>

                <p>
                    Many applications represent the internal state of the
                    system as a set of one or more JavaBeans. The bean
                    properties represent
                    the details of the system' state. Depending on your
                    application's complexity,
                    these beans may be self contained (and know how to persist
                    their own state),
                    or they may be facades that know how to retrieve the
                    system's state from another
                    component. This component may be a database, a search
                    engine, an Entity Enterprise
                    JavaBean, a LDAP server, or something else entirely.
                </p>

                <p>
                    Large-scale applications will often represent the set of
                    possible
                    business operations as methods that can be called on the
                    bean or beans
                    maintaining the state information. For example, you might
                    have a shopping
                    cart bean, stored in session scope for each current user,
                    with properties
                    that represent the current set of items that the user has
                    decided to
                    purchase. This bean might also have a
                    <code>checkOut()</code>
                    method
                    that authorizes the user's credit card and sends the order
                    to the
                    warehouse to be picked and shipped. Other systems will
                    represent the
                    available operations separately, perhaps as Session
                    Enterprise JavaBeans
                    (Session EJBs).
                </p>

                <p>
                    In a smaller scale application, on the other hand, the
                    available
                    operations might be embedded within the
                    <code>Action</code>
                    classes that are
                    part of the framework control layer. This can be useful when
                    the logic is very
                    simple or where reuse of the business logic in other
                    environments is not
                    contemplated.
                </p>

                <p>
                    The framework architecture is flexible enough to
                    support most any
                    approach to accessing the Model, but we
                    <strong>strongly</strong>
                    recommend that you
                    separate the business logic ("how it's done") from the
                    role that
                    <code>Action</code>
                    classes play ("what to do"). 'nuff said.
                </p>

                <p>
                    For more about adapting your application's Model to
                    the framework, see the
                    <a href="building_model.html">Building Model
                        Components</a>
                    chapter.
                </p>

            </subsection>

            <a name="presentationConcepts"/>
            <subsection
                    name="1.2.2 The View: JSP Pages and Presentation Components"
                    href="presentationConcepts">

                <p>
                    The
                    <em>View</em>
                    portion of a Struts-based application is most often
                    constructed using JavaServer Pages (JSP) technology. JSP
                    pages can
                    contain static HTML (or XML) text called "template text",
                    plus the
                    ability to insert dynamic content based on the
                    interpretation (at page
                    request time) of special action tags. The JSP environment
                    includes a
                    set of standard action tags, such as
                    <code>&lt;jsp:useBean&gt;</code>
                    whose purpose is described in the
                    <a href="http://java.sun.com/products/jsp/download.html">
                        JavaServer Pages Specification.</a>
                    In addition to the built-in actions, there is a standard
                    facility to
                    define your own tags, which are organized into "custom tag
                    libraries."
                </p>

                <p>
                    The framework includes a set of custom tag libraries that
                    facilitate
                    creating user interfaces that are fully internationalized
                    and
                    interact gracefully with
                    <code>ActionForm</code>
                    beans.
                    ActionForms capture and validate whatever input is
                    required by
                    the application.
                </p>

                <p>
                    For more about the Struts taglibs and using presentation
                    pages
                    with the framework, see the
                    <a href="building_view.html">Building View Components</a>
                    section.
                    Additional documentation regarding the taglibs is also
                    available in
                    the Taglibs subproject.
                </p>
            </subsection>

            <a name="controllerConcepts"/>
            <subsection
                    name="1.2.3 The Controller: ActionServlet and ActionMapping"
                    href="controllerConcepts">

                <p>
                    Struts provides the
                    <em>Controller</em>
                    portion of the application.
                    The Controller is focused on receiving
                    requests from the client (typically a user running a web
                    browser), deciding
                    what business logic function is to be performed, and then
                    delegating
                    responsibility for producing the next phase of the user
                    interface to
                    an appropriate View component. The primary component of
                    the
                    Controller in the framework is a servlet of class
                    <code>ActionServlet.</code>
                    This servlet
                    is configured by defining a set of
                    <code>ActionMappings.</code>
                    An ActionMapping defines a
                    <code>path</code>
                    that is matched against the
                    request URI of the incoming request and usually specifies
                    the
                    fully qualified class name of an Action class. All Actions
                    are subclassed from
                    <code>[org.apache.struts.action.Action].</code>
                    Actions
                    encapsulate calls to business logic classes, interpret the
                    outcome, and
                    ultimately dispatch control to the appropriate View
                    component to create the
                    response.
                    While the framework dispatches to a View, actually
                    rendering the
                    View is outside its scope.
                </p>

                <p>
                    The framework also supports the ability to use
                    <code>ActionMapping</code>
                    classes that have additional properties beyond the
                    standard ones required
                    to operate the controller. This allows you to store
                    additional information
                    specific to your application and still utilize the
                    remaining features of
                    the framework. In addition, the framework lets you define logical
                    "names" to which
                    control should be forwarded so that an action method can
                    ask for the
                    "Main Menu" page (for example), without knowing the
                    location of the
                    corresponding JSP page. These features greatly assist you
                    in separating
                    the control logic (what to do) with the view logic (how
                    it's rendered).
                </p>

                <p>
                    For more about the control layer, see the
                    <a href="building_controller.html">Building Controller
                        Components</a>
                    chapter.
                </p>

            </subsection>

            <a name="flow"/>
            <subsection name="1.3 Framework Control Flow" href="flow">

                <p>
                    The framework provides several components that make up the
                    <strong>Control</strong>
                    layer of a MVC-style application. These include a
                    controller component (servlet),
                    developer-defined request handlers, and several supporting
                    objects.
                </p>

                <p>
                    The Struts Taglib component provides direct
                    support for the
                    <strong>View</strong>
                    layer
                    of a MVC application. Some of these tags access the
                    control-layer objects.
                    Others are generic tags found convenient when writing
                    applications. Other
                    taglibs, including
                    <a href="http://java.sun.com/products/jsp/jstl/index.html">
                        JSTL,</a>
                    can also be used with the framework. Other presentation
                    technologies, like
                    <a href="http://jakarta.apache.org/velocity/index.html">
                        Velocity Templates</a>
                    and
                    <a href="http://www.w3.org/TR/xslt">XSLT</a>
                    can also be used with the framework.
                </p>

                <p>
                    The
                    <strong>Model</strong>
                    layer in a MVC application is often project-specific.
                    The framework is
                    designed to make it easy to access the business-end of
                    your application,
                    but leaves that part of the programming to other products,
                    like
                    <a href="http://java.sun.com/products/jdbc/index.html">
                        JDBC,</a>
                    <a href="http://java.sun.com/products/ejb/index.html">
                        Enterprise Java Beans,</a>
                    <a href="http://db.apache.org/ojb/">Object Relational
                        Bridge,</a>
                    or
                    <a href="http://ibatis.apache.org/">iBATIS,</a>
                    to name a few.
                </p>

                <p>
                    Let's step through how this all fits together.
                </p>

                <p>
                    When initialized, the controller parses a configuration
                    file <code>(struts-config.xml)</code>
                    and uses it to deploy other control layer objects.
                    Together, these objects form the
                    <strong>Struts Configuration.</strong>
                    The Configuration
                    defines (among other things) the collection of
                    <a href="../apidocs/org/apache/struts/action/ActionMapping.html">
                        ActionMappings</a>
                    <code>[org.apache.struts.action.ActionMappings]</code>
                    for an application.
                </p>

                <p>
                    The controller component consults the ActionMappings as it
                    routes HTTP
                    requests to other components in the framework. Requests
                    may be forwarded to JavaServer Pages or
                    <a href="../apidocs/org/apache/struts/action/Action.html">
                        Action</a>
                    <code>[org.apache.struts.action.Action]</code>
                    subclasses provided by the
                    application developer. Often, a request is first forwarded to
                    an Action and then to a JSP
                    (or other presentation page). The mappings help the
                    controller turn HTTP requests into application
                    actions.
                </p>

                <p>
                    An individual
                    <a href="../apidocs/org/apache/struts/action/ActionMapping.html">
                        ActionMapping</a>
                    <code>[org.apache.struts.action.ActionMapping]</code>
                    will usually contain a number of properties including:
                </p>
                <ul>
                    <li>a
                        <strong>request path</strong>
                        (or "URI"),
                    </li>
                    <li>the
                        <strong>object type</strong>
                        (Action subclass) to act upon the request, and
                    </li>
                    <li>other properties as needed.</li>
                </ul>
                <p>
                    The Action object can handle the request and respond to
                    the client (usually a Web
                    browser) or indicate that control should be forwarded
                    elsewhere. For example, if
                    a login succeeds, a login action may wish to forward the
                    request onto the
                    mainMenu page.
                </p>

                <p>
                    Action objects have access to the application's controller
                    component, and so have access
                    to that members's methods. When forwarding control, an
                    Action object can indirectly
                    forward one or more shared objects, including
                    <a href="http://java.sun.com/products/javabeans/">
                        JavaBeans,</a>
                    by placing them in one
                    of the standard contexts shared by Java Servlets.
                </p>

                <p>
                    For example, an Action object can create a shopping cart
                    bean, add an item to the
                    cart, place the bean in the session context, and then
                    forward control to
                    another mapping. That mapping may use a JavaServer Page to
                    display the contents of the user's cart.
                    Since each client has their own session, they will each
                    also have their own
                    shopping cart.</p>
                <p>
                    Most of the business logic in an application can be
                    represented using JavaBeans. An Action can call the
                    properties of a JavaBean
                    without knowing how it actually works. This encapsulates
                    the business logic,
                    so that the Action can focus on error handling and where
                    to forward control.
                </p>

                <p>
                    JavaBeans can also be used to manage input forms. A key
                    problem in designing
                    Web applications is retaining and validating what a user
                    has entered between
                    requests. You can define your own set of input bean
                    classes, by
                    subclassing
                    <a href="../apidocs/org/apache/struts/action/ActionForm.html">
                        ActionForm</a>
                    <code>[org.apache.struts.action.ActionForm].</code>
                    The ActionForm class makes it
                    easy to store
                    <strong>and validate</strong>
                    the data for your application's input forms.
                    The ActionForm bean is automatically saved in one of the
                    standard, shared context
                    collections, so that it can be used by other objects, like
                    an Action object or
                    another JSP.
                </p>

                <p>
                    The form bean can be used by a JSP to collect data from
                    the user ... by an
                    Action object to validate the user-entered data ... and
                    then by the JSP again to
                    re-populate the form fields. In the case of validation
                    errors, the framework has a
                    shared mechanism for raising and displaying error
                    messages.
                </p>

                <p>
                    Another element of the Configuration are the
                    <a href="../apidocs/org/apache/struts/action/ActionFormBeans.html">
                        ActionFormBeans</a>
                    <code>[org.apache.struts.action.ActionFormBeans].</code>
                    This is a collection of
                    <a href="../apidocs/org/apache/struts/action/ActionFormBean.html">
                        descriptor objects</a>
                    that are used to create instances of the ActionForm
                    objects at runtime.
                    When a mapping needs an ActionForm, the servlet looks up
                    the form-bean descriptor by name and uses
                    it to create an ActionForm instance of the specified type.
                </p>
                <p>
                    Here is the sequence of events that occur when a request
                    calls for an mapping that uses an ActionForm:
                </p>

                <ul>
                    <li>The controller servlet either retrieves or creates the
                        ActionForm bean instance.</li>
                    <li>The controller servlet passes the bean to the Action
                        object.</li>
                    <li>If the request is being used to submit an input page,
                        the Action object
                        can examine the data. If necessary, the data can be
                        sent back to the input
                        form along with a list of messages to display on the
                        page. Otherwise the data can
                        be passed along to the business tier.</li>
                    <li>If the request is being used to create an input page,
                        the Action object can
                        populate the bean with any data that the input page
                        might need.</li>
                </ul>

                <p>
                    The Struts Taglib component provides custom tags that can
                    automatically populate
                    fields from a JavaBean. All most JavaServer Pages really
                    need to know
                    is the field names to use and where to submit the form.
                </p>
                <p>
                    Other tags can automatically output messages queued by an
                    Action
                    or ActionForm and simply need to be integrated into the
                    page's markup.
                    The messages are designed for
                    <a href="http://developer.java.sun.com/developer/technicalArticles/Intl/IntlIntro/">
                        localization</a>
                    and will render the best available message for a user's
                    locale.
                </p>

                <p>
                    The framework and Struts Taglib were designed from the
                    ground-up
                    to support the internationalization features built into
                    the Java platform. All the field labels
                    and messages can be retrieved from a
                    <a href="../apidocs/org/apache/struts/util/MessageResources.html">
                        message resource.</a>
                    To provide messages for another language, simply add
                    another file to the resource bundle.
                </p>

                <p>
                    Internationalism aside, other benefits to the message
                    resources approach are consistent labeling
                    between forms, and the ability to review all labels and
                    messages from a central
                    location.
                </p>

                <p>
                    For the simplest applications, an Action object may
                    sometimes handle the business logic
                    associated with a request.
                    <strong>However, in most cases, an Action object should
                        invoke another object, usually a JavaBean, to perform
                        the actual business logic.</strong>
                    This lets the Action focus on error handling and control
                    flow, rather than
                    business logic. To allow reuse on other platforms,
                    business-logic JavaBeans should not refer to any Web
                    application objects. The Action object should translate
                    needed details from the
                    HTTP request and pass those along to the business-logic
                    beans as regular Java
                    variables.
                </p>

                <p>
                    In a database application, for example:
                </p>

                <ul>
                    <li>A business-logic bean will connect to and query the
                        database,</li>
                    <li>The business-logic bean returns the result to the
                        Action,</li>
                    <li>The Action stores the result in a form bean in the
                        request,</li>
                    <li>The JavaServer Page displays the result in a HTML
                        form.</li>
                </ul>

                <p>Neither the Action nor the JSP need to know (or care) from
                    where
                    the result comes. They just need to know how to package
                    and display it.
                </p>

                <p>
                    <a href="index.html">Other sections</a>
                    in this document cover the
                    various framework components in greater detail.
                    The Struts Taglib component includes several Developer
                    Guides
                    covering various aspects of the custom tags.
                    A number of sample applications are bundled with the 
                    distribution that show how it all comes together.
                </p>

                <p>
                    The framework is distributed under the
                    <a href="http://www.apache.org/licenses/">Apache Software
                        Foundation license.</a>
                    The code is copyrighted, but is free to use in any
                    application.
                </p>

            </subsection>

            <subsection>
                <p class="right">
                    Next:
                    <a href="building_model.html">Building Model
                        Components</a>
                </p>
            </subsection>

        </section>
    </body>
</document>
