<?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>Release Notes (since 1.2.8)</title>
    </properties>
    <body>
        <section name="6.1 Release Notes - Version 1.3.1">

            <subsection>
                <p>
                    <strong>SPECIAL NOTE ON UPGRADING - README FIRST!</strong>
                    - If you use the standard
                    <strong>CANCEL BUTTON</strong>
                    in your application
                    and validate is set to true for that mapping, you
                    <strong>MUST</strong>
                    also specify "cancellable=true" in the mapping, otherwise,
                    an InvalidCancelException will be thrown if the Cancel button is
                    used. See the new
                    <a href="#opt-in">Opt-In Cancel Handling</a>
                    feature for more.
                </p>
                <p>
                    <source>
                        &lt;action path="/ActionThatCanBeCancelled"
                                validate="true"
                                <strong>cancellable="true"</strong>
                                ...
                         &lt;/action>
                    </source>
                </p>
            </subsection>

            <a name="release_notes"/>
            <subsection name="Introduction">
                <p>
                    This section contains release notes for changes that have
                    taken
                    place to the seven new subprojects known as "Struts Classic"
                    since
                    <a href="release-notes-1_2_9.html">Version 1.2.9</a>
                    .
                    To keep up-to-date on all changes to Struts, subscribe to
                    the
                    (commits at struts.apache.org) list.
                    To preview our plans for upcoming changes,
                    please visit the
                    <a href="../roadmap.html">Roadmap page</a>
                    .
                </p>
                <p>
                    <b>Notes on upgrading</b>
                    are maintained in the
                    <a href="http://wiki.apache.org/struts/StrutsUpgrade">Wiki
                        Upgrade pages</a>
                    .
                    The wiki is a community maintained resource - please feel
                    free to add your
                    input so that everyone can benefit from the collective
                    experience.
                </p>
                <p>
                    For the version requirements of each library, see the
                    <a href="installation.html">Installation chapter</a>
                    .
                </p>

            </subsection>

            <a name="Highlight"/>
            <subsection name="Highlights of Changes">
                <p>
                    The purpose of this section is to highlight the new
                    features since the
                    Version 1.2.8 release.
                    For more detail, see the Project Info reports for each
                    subproject,
                    which include a complete changelog and list of external
                    dependencies.
                </p>
                <p>
                    You can also access to the Apache Struts source repository and
                    change logs directly through both
                    <a href="http://svn.apache.org/viewcvs.cgi/struts/action/trunk/?root=Apache-SVN">
                        web browser</a>
                    and
                    <a href="http://www.apache.org/dev/version-control.html">
                        Subversion client</a>
                    interfaces.
                </p>

                <h3>People</h3>

                <p>
                    On the
                    <a href="http://struts.apache.org/volunteers.html">
                        volunteer</a>
                    front, eight new committers accepted invitations to join
                    us.
                    We welcome
                    <i>Wendy Smoak</i>
                    ,
                    <i>Gary VanMatre</i>
                    ,
                    <i>Sean Schofield</i>
                    ,
                    <i>Greg Reddin</i>
                    ,
                    <i>Laurie Harper</i>
                    ,
                    <i>Richard Feit</i>
                    ,
                    <i>Jason Carreira</i>
                    , and
                    <i>Patrick Lightbody</i>
                    .
                </p>
                <p>
                    We also welcome <i>Wendy Smoak</i> and <i>Gary VanMatre</i>
                    to the Apache Struts PMC (Project Management Committee).
                </p>

                <h3>Struts Library</h3>

                <p>
                    Since Struts 1.2.8, we have subdivided Struts into several
                    subprojects,
                    each with its own release cycle.
                    The set of seven subprojects derived from Struts 1.2 is
                    sometimes referred to as "Struts Classic".
                    The Struts Classic subprojects are Action, Applications,
                    EL, Extras, Site, Taglibs, and Tiles.
                    These subprojects will all inherit version 1.3.0, but,
                    thereafter,
                    subproject revisions will increment independently of each
                    other.
                </p>

                <p>
                    Since many teams will use Struts with one
                    or more extensions,
                    we are bundling the jars for extensions that utilize the
                    framework into a single distribution
                    called "Struts Library".
                </p>

                <p>
                    The Apache Struts subprojects, including the website, are being
                    built with Maven.
                    But, of course, you can continue to build your own
                    projects any way you like!
                </p>

                <h3>Dependency Changes</h3>

                <h4>Specification Changes</h4>
                <p>
                    The 1.3.x series of Struts now has
                    a minumum requirement of the following specification
                    versions:
                    <ul>
                        <li>
                            Java Servlet 2.3 and JavaServer Pages (JSP) 1.2
                        </li>
                        <li>
                            Java 2 Standard Platform Edition (J2SE) 1.4
                        </li>
                    </ul>
                </p>
                <h4>Software Component Changes</h4>
                <p>
                    A number of software dependency changes apply to this release:
                    <ul>
                        <li>
                            New dependency on Commons Chain 1.0 - see
                            <a href="http://jakarta.apache.org/commons/chain/">
                                Chain Website
                            </a>
                            .
                        </li>
                        <li>
                            Upgraded to Commons FileUpload 1.1 (previously 1.0) - see
                            <a href="http://jakarta.apache.org/commons/fileupload/changes-report.html">
                                FileUpload 1.1 Release Notes
                            </a>
                            .
                        </li>
                        <li>
                            New dependency on Commons IO 1.1 (required by FileUpload
                            1.1) - see
                            <a href="http://jakarta.apache.org/commons/io/">
                                IO Website
                            </a>
                            .
                        </li>
                        <li>
                            Upgraded to Commons Validator 1.2 (previously 1.1.4) -
                            see
                            <a href="http://jakarta.apache.org/commons/validator/changes-report.html">
                                Validator 1.2.0 Release Notes
                            </a>
                            .
                        </li>
                    </ul>
                </p>

                <h3>Struts Applications</h3>

                <p>
                    The applications have been moved into their own
                    subproject,
                    the builds have been "Mavenized",
                    but the set of example applications is essentially
                    unchanged.
                </p>

                <ul>
                    <li>
                        In MailReader, fix invalid password limit error.
                    </li>
                    <li>
                        The examples application's config files (struts
                        and validation) in the Validator module have been
                        split into up into one per example page.
                    </li>
                </ul>

                <ul>
                    <li>In taglib-exercises, add html-cancel page to demonstrate
                        new  <a href="#opt-in">Opt-In Cancel Handling</a>.</li>
                </ul>

                <ul>
                    <li>In all applications, update configuration for new
                        <strong>cancellable</strong>
                        property as needed.
                    </li>
                </ul>

                <h3>Struts</h3>

                <p>
                    Major changes to the framework include
                </p>

                <ul>
                    <li>
                        Composable Request Processor
                    </li>
                    <li>
                        Arbitrary configuration properties
                    </li>
                    <li>
                        Catalog and Command Elements
                    </li>
                    <li>
                        Opt-In Cancel Handling
                    </li>
                    <li>
                        Enhanced Global Exception Handlers
                    </li>
                    <li>
                        Extends attribute
                    </li>
                    <li>
                        "isCommitted" Exception Handling
                    </li>
                    <li>
                        Postback Actions
                    </li>
                    <li>
                        Wildcard ActionConfig properties
                    </li>
                </ul>

                <a name="composable-request-processor" />
                <h4>Composable Request Processor</h4>
                <p>
                    In prior versions, the request processing guantlet is
                    represented as a series
                    of methods.
                    While it was easy to override the methods to provide
                    different functionality,
                    it was not easy to use multiple extension that each wanted
                    to override
                    the request processor in a different way.
                </p>
                <source>
                    public void process(HttpServletRequest request,
                    HttpServletResponse response)
                    throws IOException, ServletException {

                    processLocale(request, response);
                    if (!processRoles(request, response, mapping)) {
                    return;
                    }
                    /// ...
                    ActionForward forward =
                    processActionPerform(request, response,
                    action, form, mapping);
                    processForwardConfig(request, response, forward);
                    }
                </source>
                <p>
                    For Action 1.3, we turned the request processor methods
                    into Commands
                    that are part of a flexible Chain of Commands.
                    Rather than subclassing a monolithic object,
                    we can now just replace Commands.
                    Commands can also be inserted or removed, if needed,
                    to extend or streamline the request processing gauntlet
                    to meets the needs of different kinds of applications.
                </p>
                <source>
                    &lt;chain name="process-action">
                    &lt;command className= "...SelectLocale"/>
                    &lt;command className= "...AuthorizeAction"/>
                    &lt;!-- ... -->
                    &lt;command className= "...CreateAction"/>
                    &lt;command className= "...ExecuteAction"/>
                    &lt;/chain>
                </source>
                <p>
                    We fully expect the Action 1.3 request processor to be
                    backwardly
                    compatible with earlier versions.
                    But, to be prudent, we wanted to release 1.3 with the
                    Composable
                    Request Processor before making additional changes.
                </p>
                <p>
                    We've made a few other changes and improvements in Action
                    1.3.x,
                    but the two big-ticket items are subprojects and the new
                    request processor.
                </p>
                <p>
                    If needed, the monolithic RequestProcessor from Struts 1.2 is
                    still available in the distribution and may be
                    configured via the controller element.
                </p>
                <source>
                    &lt;controller
                    processorClass="org.apache.struts.action.RequestProcessor"
                    /&gt;
                </source>
                <p>
                    However, we consider this RequestProcessor to be a legacy
                    class. Once the new ComposableRequestProcessor is more-widely
                    field tested, we expect that this class will be deprecated,
                    moved to the Extras subproject, and ultimately removed.
                    Accordingly, some new features, like Opt-In Cancel
                    Handling, are only supported by the new Composable Request
                    Processor.
                </p>

                <a name="arbitrary-config" />
                <h4>Arbitrary configuration properties</h4>
                <p>
                    Most every Struts configuration element now accepts a map
                    of key/value pairs.
                    Arbitrary configuration properties let us externalize more
                    of our configurations,
                    encouraging reuse.
                </p>

                <source>
                    &lt;action path="/EditSubscription"
                    extends="Editor">
                    &lt;set-property key="foo" value="bar"/>
                    &lt;/action>

                    public ActionForward execute(
                    ActionMapping mapping,
                    ActionForm form,
                    HttpServletRequest request,
                    HttpServletResponse response)
                    throws Exception {
                    string foo = getProperty("foo");
                    // ...
                </source>
                <p>
                    Arbitrary Configuration should make it easier for everyone
                    to write reusable chunks of code, for ActionMappings,
                    Exception Handlers,
                    and other members.
                </p>

                <a name="opt-in" />
                <h4>Opt-In Cancel Handling</h4>

                <p>
                    <strong>SPECIAL NOTE ON UPGRADING - README FIRST!</strong>
                    - If you use the standard
                    <strong>CANCEL BUTTON</strong>
                    in your application
                    and validate is set to true for that mapping, you
                    <strong>MUST</strong>
                    also specify "cancellable=true" in the mapping, otherwise,
                    an InvalidCancelException will be thrown if the Cancel button is
                    used. Here's why:
                </p>

                <p>
                    In Struts 1.2.8 and prior, any time the magic token generated by
                    the Cancel tag is found in the request, validation for the
                    ActionForm is skipped.
                    Accordingly, in Struts 1.2.8 and prior, any Action that relies on
                    validation should always observe the isCancelled method.
                </p>

                <p>
                    In Struts 1.3, the Cancel token is only honored if the
                    new property "cancellable" is set for the Action Mapping.
                    If the Cancel token is present, but cancellable is not set,
                    then an InvalidCancelException is thrown.
                    The InvalidCancelExeption may be caught by a Declarative
                    Exception Handler, like any other Exception.
                </p>

                <p>
                    <source>
                        &lt;action path="/ActionThatCanBeCancelled"
                                validate="true"
                                <strong>cancellable="true"</strong>
                                ... &gt;
                        &lt;exception
                                key="errors.invalidCancel"
                                type="org.apache.struts.action.InvalidCancelException"
                                path="/InvalidCancelException.jsp"/>
                         &lt;/action>
                    </source>
                </p>

                <p>
                    The declarative exception handler is optional. The Exception
                    will only be thrown when there is a programming error or
                    when a rogue client is trying to bypass validation.
                </p>

                <p>
                    Note that the Opt-In Cancel Handler is available for the
                    Composable Request Processor as well as
                    the legacy Request Processor included in Struts 1.3.
                </p>

                <a name="enhanced-exception" />
                <h4>Enhanced Global Exception Handlers</h4>
                <p>
                    We now support use of global exception handlers in cases
                    when no ActionConfig has yet been identified,
                    as in with "preprocessing" commands in a custom request
                    processing chain.
                    In the case when there is no ActionConfig,
                    the AbstractExceptionHandler will now call a new method in
                    ModuleConfig which
                    provides similar logic for finding a globally mapped
                    exception handler for the given exception class
                    or any of its superclasses.
                </p>

                <h4>Catalog and Command elements</h4>
                <p>
                    Available for both the Controller and any Action Mapping
                </p>
                <p>
                    catalog - The name of a commons-chain catalog in which to
                    look up a command
                    to be executed as part of servicing this request. Only
                    meaningful if "command"
                    is also specified.
                </p>
                <p>
                    command - The name of a commons-chain command which should
                    be looked up and
                    executed as part of servicing this request.
                </p>
                <source>
                    &lt;controller
                    inputForward="true"
                    catalog="Foo"
                    command="FooBar"
                    />
                </source>

                <a name="extends-attr" />
                <h4>Extends attribute</h4>
                <p>
                    In the Struts configuration file,
                    we can now use the
                    <b>extends</b>
                    attribute to adopt default settings from another element,
                    as we already can in the Tiles configuration files.
                </p>
                <source>
                    &lt;struts-config>
                    &lt;form-beans>
                    &lt;form-bean name="registrationForm"
                    type="org.apache.struts.action.DynaValidatorForm">
                    &lt;form-property name="firstName" type="java.lang.String"
                    />
                    &lt;form-property name="lastName" type="java.lang.String"
                    />
                    &lt;/form-bean>

                    &lt;form-bean name="managerRegistrationForm"
                    type="org.apache.struts.action.DynaValidatorForm"
                    extends="registrationForm">
                    &lt;form-property name="department"
                    type="java.lang.String" />
                    &lt;/form-bean>
                    &lt;/form-beans>
                    ...
                    &lt;/struts-config>
                </source>
                <p>
                    Extends makes using XML elements much more like
                    object-orientated programming.
                    You can setup a base element, and then only specify the
                    behavior that changes.
                    Extends lets us set default values and then "program by
                    difference".
                    When elements are not relentlessly chanting the same
                    things over and over,
                    it's easier to see the forest for the trees.
                </p>

                <a name="isCommitted" />
                <h4>"isCommitted" Exception Handling</h4>
                <p>
                    When using Tiles, sometimes the response is already
                    committed when an exception occurs.
                    Now, the ExceptionHandler tests
                    <code>response.isCommitted</code>
                    ,
                    and, if true, includes the configured view path, rather
                    than forwarding to it.
                    The updated ExceptionHandler accepts new configuration
                    attributes which let you
                    choose alternate behavior, or no behavior at all. See the
                    JavaDoc for details.
                </p>

                <source>
                    &lt;exception
                    key="GlobalExceptionHandler.default"
                    type="java.lang.Exception"
                    path="/ErrorPage.jsp">
                    <set-property key="INCLUDE_PATH" value="/error.jsp"/>
                    &lt;/exception>

                    &lt;exception
                    key="GlobalExceptionHandler.default"
                    type="java.lang.Exception"
                    path="/ErrorPage.jsp">
                    &lt;set-property key="SILENT_IF_COMMITTED" value="true" />
                    &lt;/exception>
                </source>

                <a name="postback" />
                <h4>Postback Forms</h4>
                <p>
                    The action attribute of the Form taglib is now optional.
                    If omitted, the original URI of the original request is
                    used.
                </p>
                <source>
                    &lt;html:form
                    onsubmit="return validateLogonForm(this);">
                </source>

                <a name="wildcard-props" />
                <h4>Wildcard ActionConfig properties</h4>
                <p>
                    Wildcards can now be used in the properties of an
                    ActionConfig.
                    This makes it easier to pass multiple request-time values
                    to the Action
                    without complicating the "parameter" attibute.
                </p>

                <source>
                    &lt;action path="/Save*"
                    name="Save{1}"
                    extends="BaseSave">
                    &lt;set-properties key="Save" value="{1}"/>
                    &lt;/action>
                </source>

                <h4>Other Miscellaneous Changes</h4>
                <ul>
                    <li>
                        Added support for resetting DynaActionForm property
                        values through configuration.
                    </li>
                    <li>
                        Changed the MultipartRequestWrapper to extend the
                        HttpServletRequestWrapper which was introduced in Servlet
                        2.3.
                        This fixed the issue that MultipartRequestWrapper didn't
                        support
                        Servlet 2.4 methods and means that mutlipart requests no
                        longer
                        have to be "un-wrapped" before forwarding - now making
                        parameters
                        parsed from the multipart request available after forwarding.
                    </li>
                    <li>
                        Added support for per-field character encoding in multipart
                        requests.
                    </li>
                    <li>
                        Resolved <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=38534">
                        Bug 38534</a> DOS attack, application hack.
                    </li>
                </ul>

                <h3>Struts EL</h3>

                <p>Aside from addressing deprecations, there were a few minor
                    changes to Struts EL.</p>
                <ul>
                    <li>
                        Remove reference to html:html's locale attr in
                        TestELHtmlTag
                    </li>
                    <li>
                        Fixed the "errorKey" being set incorrectly set to null
                        in the release() method (for HTML form field tags).
                    </li>
                    <li>
                        Added "onselect" attribute to TextTag and TextareaTag.
                    </li>
                </ul>

                <h3>Struts Extras</h3>

                <p>
                    This subproject was extracted from the Actions and Plugins
                    packages of Struts 1.2.
                    The code itself is unchanged except for one minor issue.
                </p>
                <ul>
                    <li>
                        ModuleConfigVerifier has been modified to use Commons
                        Logging in line with the rest of Struts.
                    </li>
                </ul>

                <h3>Struts Site</h3>

                <p>
                    The new Site subproject hosts the top-layer of the Struts
                    website,
                    and serves as a portal to the other subprojects.
                </p>

                <h3>Struts Taglibs</h3>

                <p>
                    We're changed the way we generate our reference
                    documentation for the taglibs,
                    but we think you will find the new reference just as
                    useful as the old.
                    Otherwise, we made only minor fixes to the trusty Struts
                    Taglibs.
                </p>

                <ul>
                    <li>
                        Update error message for when value is null to specify
                        the id of the bean being defined.
                    </li>
                    <li>
                        Updated tag to filter value field to prevent it from
                        breaking HTML if the value has reserved
                        characters in it.
                    </li>
                    <li>
                        Changed logic so that the "must specify only one
                        of..." message only get's thrown if the user is
                        specifying more than one of the available options.
                        The code was throwing the message if the user didn't
                        specify any at all and should be flowing
                        down to the "no value specified" error message.
                        Update "can contain only one of..." message to specify
                        which bean has the error.
                    </li>
                    <li>
                        Update FormTag to provide better debug message in the
                        scenario where an action mapping is missing a
                        form bean name.
                    </li>
                    <li>
                        Update TagUtils to provide a more specific error
                        message in the case where properties on a formbean
                        are not found. Basically this change handles the
                        scenario where the Constants.BEAN_KEY value was
                        being displayed as the bean name.
                        Now, the actualy bean name will be displayed.
                    </li>
                    <li>
                        Changing rendering of the form name to use the 'id'
                        attribute when in in XHTML strict mode.
                        If an 'id' is already identified with the 'tyleId'
                        attribute, an exception is thrown.
                    </li>
                    <li>
                        Changed dynamic focus javascript to choose form using
                        'id' attribute in XHTML mode
                    </li>
                    <li>
                        Changed the "action" attribute of the Form taglib to
                        be optional.
                        If omitted, the original URI of the request is used.
                    </li>
                    <li>
                        Filter anchors out when determining action mapping
                        name.
                    </li>
                    <li>
                        Fix MessagesTag so that non-resource messages are
                        possible for multiple messages,
                        instead of just the first one.
                    </li>
                    <li>
                        Fix MessagesTag so that it displays an error message
                        if a resource key is not found rather than throwing
                        a NullPointerException.
                    </li>
                    <li>
                        Added escape for single quotes and new lines in
                        javascript values.
                    </li>
                    <li>
                        Fixed the mis-leading warning message indicating a
                        missing form when dynamicJavascript is
                        <code>false</code>
                        in the JavascriptTag.
                    </li>
                    <li>
                        Added "onselect" attribute to TextTag and TextareaTag
                        (standard and nested versions).
                    </li>
                    <li>
                        Fixed indexed behaviour to check for JSTL's LoopTag rather
                        than LoopTagSupport to verify JSTL.
                    </li>
                </ul>

                <h3>Struts Tiles</h3>

                <p>
                    Tiles is being refactored into a standalone package that
                    can be used with or without Struts.
                    For more on how this affects Tiles users, see the Tiles
                    subproject site.
                </p>

            </subsection>

            <subsection>
                <p class="right">Next:
                    <a href="installation.html">Installation</a>
                </p>
            </subsection>
        </section>
    </body>
</document>
