<?xml version="1.0"?>
<!--
    $Id: works.xml 481833 2006-12-03 17:32:52Z niallp $

    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>How Does Struts Work?</title>
    </properties>
    <body>
        <section href="faq" name="How does Struts work?">

                                <blockquote>
                <p>
                    [From the <a href="kickstart.html#how">Kickstart FAQ</a>] <br/>
                    <em>"Java Servlets are designed to handle requests made by Web
                    browsers.
                    Server pages are designed to create dynamic Web pages that
                    can turn billboard sites into interactive applications.
                    Struts uses a special Servlet as a
                    switchboard to route requests from Web browsers to the
                    appropriate server page.
                    This makes Web applications much easier to design, create,
                    and maintain."</em>
                </p>
                                </blockquote>

                <p>
                    That's a good high-level description,
                    but let's describe the mechanisms and
                    dependencies of the framework in more detail.
                </p>

                <ul>
                    <li>
                        <p>
                        The web application that you develop has a deployment
                        descriptor
                        <code>(WEB-INF/web.xml)</code>
                        which you must write. This file describes
                        the configuration of your web application, including
                        welcome pages (the
                        file that is shown in a directory when none is
                        specified by the request),
                        mappings to servlets (path or extension name), and
                        parameters to those
                        servlets.
                        </p>
                        <p>
                        In the <code>web.xml</code> file, you configure the framework
                        <a href="../apidocs/org/apache/struts/action/ActionServlet.html">
                            <code>ActionServlet</code>
                        </a>
                        as the servlet that will handle all requests for a
                        given mapping (usually
                        the extension
                        <code>.do</code> is used).
                        The ActionServlet is the "switchboard" mentioned in the 
                        opening paragraph.
                        </p>
                        <p>
                        Also in the <code>web.xml,</code> you configure the
                        <code>ActionServlet</code>
                        to use
                        one or more configuration files for Struts itself.
                        </p>
                        <p>
                        For now, let's say we are installing the web
                        application on the server using
                        <code>/myapp</code> as a location, 
                        and we are using the simplest possible configuration
                        from there.
                        </p>
                        <p>
                        If you need more details on deployment descriptors,
                        read
                        the relevant Servlet Specification available from Sun
                        Microsystem's
                        <a href="http://java.sun.com">Java site.</a>
                        </p>
                    </li>
                    <li>
                          <p>
                        In the framework configuration file(s), you associate
                        paths with
                        the controller components of your application, known
                        as
                        <a href="../apidocs/org/apache/struts/action/Action.html">
                            <code>Action</code>
                        </a>
                        classes (i.e. "login" ==&gt; LoginAction class). This
                        tells the
                        <code>ActionServlet</code>
                        that for the incoming request 
                        <code>http://myhost/myapp/login.do</code>
                        it should invoke your controller component, 
                        <code>LoginAction.</code>
                        </p>
                        <p>
                        Note the extension
                        <code>.do</code>
                        in this URL. The extension causes
                        your container (i.e. Tomcat) to call the
                        <code>ActionServlet,</code>
                        which sees the word "login" as the thing you want to
                        do. The
                        configuration is referenced, and your
                        <code>LoginAction</code>
                        is
                        executed.
                        </p>
                    </li>
                    <li>
                        <p>
                        For each
                        <code>Action,</code>
                        you also configure the framework with the names of
                        the resulting page(s) that can be shown as a result of
                        that action. There
                        can be more than one view as the result of an action
                        (often, there are at
                        least two: one for "success", and one for "failure").
                        </p>
                        <p>
                        Your
                        <code>Action</code>
                        (the controller component you write) is based on
                        these
                        <em>logical</em>
                        result mapping names. It reports back to the
                        <code>ActionServlet</code>
                        using words like "success", "failure",
                        "ready", "ok", "UserError", et cetera. The framework
                        (through the
                        configuration that you wrote) knows how to forward to
                        the proper
                        <em>specific</em>
                        page. This has the added advantage of reconfiguration
                        of
                        the view layer by simply editing the XML configuration
                        file.
                        </p>
                        <p>
                        At this point, the framework knows how to delegate to
                        your controller components,
                        and what to show as a result of your controller
                        processing. The "model"
                        part of the application is completely up to you, and
                        is called from
                        within your controller components.
                        </p>
                    </li>
                    <li>
                        <p>
                        You may also associate a JavaBean with an action (or
                        set of actions) in
                        the framework's configuration file. The JavaBean is
                        used as a repository for
                        form or display data that can be communicated between
                        the view and
                        controller layer.
                        </p>
                        <p>
                        These Beans are automatically made visible to your
                        controller components
                        (like the 
                        <code>LoginAction</code>
                        class) 
                        and any view page that is associated with
                        that controller.
                        </p>
                        <p>
                        These Beans can also be validated with the help of the
                        framework to
                        help insure that the user is putting good data in the
                        form. They can be
                        carried along with a session, allowing forms to span
                        multiple pages of
                        the view, and Actions in the controller.
                        </p>
                        <p>
                        <strong>Note:</strong>
                        You must be using some sort of server-side
                        technology (JSP, Velocity, XSLT) for the view layer
                        (going
                        <em>to</em>
                        the
                        client) to see this data (plain HTML won't work). The
                        framework works on the
                        server side, so the client's view has to be composed
                        there.
                        </p>
                        <p>
                        The client feeds the data back through normal form
                        submission (POST/GET)
                        methods, and the framework updates that data in the
                        Bean before
                        calling your controller components.
                        </p>
                    </li>
                    <li>
                        <p>
                        Within your web application will be pages that
                        represent the view your
                        users will see. These can be JSP pages, Velocity
                        Templates,
                        XSLT pages, and so forth.
                        Sets of JSP and JSTL tags are available for the
                        framework so that you
                        can get started right away, but any standard
                        presentation technology
                        can be used with the framework.
                        </p>
                        <p>
                        Even plain HTML files can be used within your
                        application,
                        although they will not take full advantage of all of
                        the dynamic features.
                        </p>
                        <p>
                        Following the example of the Struts JSP taglibs,
                        several other
                        packages are available to make the framework easy to
                        use with your
                        favorite presentation technology.
                        For Velocity templates, there are the
                        <a href="http://jakarta.apache.org/velocity/">
                            Velocity</a>
                        ViewTools
                        for Struts.
                        If you want to use XSLT in you application, you can
                        choose between
                        <a href="http://www.openroad.ca/opencode/">stxx</a>
                        and
                        <a href="http://it.cappuccinonet.com/strutscx/">
                            StrutsCX.</a>
                        </p>
                        <p>
                        These packages make the standard Struts framework
                        elements look and
                        feel like a seamless part of the original presentation
                        technology.
                        Struts also makes it easy to mix and match.
                        If need be, you can use JSP, Velocity templates, and
                        XSLT all in the same application!
                        </p>
                        <p>
                        Since Struts relies on standard Servlet technologies,
                        you should be
                        able to use any Java presentation technology with
                        Struts.
                        </p>
                    </li>
                    <li>
                        <p>
                        While the focus of the Struts framework is on the
                        controller,
                        the presentation layer is a significant part of any
                        application.
                        The Struts JSP taglibs include a number of generic and
                        Struts-specific
                        tags to help you use dynamic data in your view.
                        </p>
                        <p>
                        The custom JSP tags account for a good deal of the
                        Struts code base. It
                        is educational to note that as of version 1.1b3 the
                        Java code for the
                        core of Struts was about 28,000 lines, and the Java
                        code for the tag
                        libraries (including tiles) was about 41,000 lines.
                        </p>
                        <p>
                        These tags help you glue your view layer to the
                        controller layer without
                        having to embed a lot of Java in the JSP. This gives
                        the page an XML
                        look, and can be easier for web designers to deal with
                        than a plain JSP. It
                        also helps minimize dependencies between the
                        controller and view.
                        </p>
                        <p>
                        The custom tags are used to create forms (and
                        invisibly interact with the
                        Bean mentioned previously), logically forward to other
                        pages, and invoke
                        other actions of the web application.
                        </p>
                        <p>
                        There are also tags that help you with
                        internationalization, error
                        messages, etc.
                        </p>
                        <p>
                        All of these abilities depend in some way on the
                        configuration files you
                        supplied to Struts.
                        </p>
                    </li>
                </ul>
                <p>
                    It is important for you to remember that the mechanism
                    described here is only in effect when the
                    <code>ActionServlet</code>
                    is handling the request.
                </p>
                <p>
                    Since this only happens when a request is submitted that
                    causes your
                    container (i.e. Tomcat, WebSphere, whatever) to call
                    <code>ActionServlet</code>
                    ,
                    you must be sure that any page that relies on Struts is
                    done through a request that will map to the
                    <code>ActionServlet</code>
                    (i.e. it has a
                    <code>.do</code>
                    extension).
                </p>
        </section>
    </body>
</document>
