ActionForm xref

View Javadoc

    1   /*
    2    * $Id: ActionForm.java 471754 2006-11-06 14:55:09Z husted $
    3    *
    4    * Licensed to the Apache Software Foundation (ASF) under one
    5    * or more contributor license agreements.  See the NOTICE file
    6    * distributed with this work for additional information
    7    * regarding copyright ownership.  The ASF licenses this file
    8    * to you under the Apache License, Version 2.0 (the
    9    * "License"); you may not use this file except in compliance
    10   * with the License.  You may obtain a copy of the License at
    11   *
    12   *  http://www.apache.org/licenses/LICENSE-2.0
    13   *
    14   * Unless required by applicable law or agreed to in writing,
    15   * software distributed under the License is distributed on an
    16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    17   * KIND, either express or implied.  See the License for the
    18   * specific language governing permissions and limitations
    19   * under the License.
    20   */
    21  package org.apache.struts.action;
    22
    23  import org.apache.struts.upload.MultipartRequestHandler;
    24
    25  import javax.servlet.ServletRequest;
    26  import javax.servlet.http.HttpServletRequest;
    27
    28  import java.io.Serializable;
    29
    30  /**
    31   * <p>An <strong>ActionForm</strong> is a JavaBean optionally associated with
    32   * one or more <code>ActionMappings</code>. Such a bean will have had its
    33   * properties initialized from the corresponding request parameters before the
    34   * corresponding <code>Action.execute</code> method is called.</p>
    35   *
    36   * <p>When the properties of this bean have been populated, but before the
    37   * <code>execute</code> method of the <code>Action</code> is called, this
    38   * bean's <code>validate</code> method will be called, which gives the bean a
    39   * chance to verify that the properties submitted by the user are correct and
    40   * valid. If this method finds problems, it returns an error messages object
    41   * that encapsulates those problems, and the controller servlet will return
    42   * control to the corresponding input form. Otherwise, the
    43   * <code>validate</code> method returns <code>null</code>, indicating that
    44   * everything is acceptable and the corresponding <code>Action.execute</code>
    45   * method should be called.</p>
    46   *
    47   * <p>This class must be subclassed in order to be instantiated. Subclasses
    48   * should provide property getter and setter methods for all of the bean
    49   * properties they wish to expose, plus override any of the public or
    50   * protected methods for which they wish to provide modified functionality.
    51   * </p>
    52   *
    53   * <p>Because ActionForms are JavaBeans, subclasses should also implement
    54   * <code>Serializable</code>, as required by the JavaBean specification. Some
    55   * containers require that an object meet all JavaBean requirements in order
    56   * to use the introspection API upon which ActionForms rely.</p>
    57   *
    58   * @version $Rev: 471754 $ $Date: 2005-11-12 08:14:24 -0500 (Sat, 12 Nov 2005)
    59   *          $
    60   */
    61  public abstract class ActionForm implements Serializable {
    62      // ----------------------------------------------------- Instance Variables
    63
    64      /**
    65       * <p>The servlet instance to which we are attached.</p>
    66       */
    67      protected transient ActionServlet servlet = null;
    68
    69      /**
    70       * <p>The MultipartRequestHandler for this form, can be
    71       * <code>null</code>.</p>
    72       */
    73      protected transient MultipartRequestHandler multipartRequestHandler;
    74
    75      // ------------------------------------------------------------- Properties
    76
    77      /**
    78       * <p>Return the servlet instance to which we are attached.</p>
    79       *
    80       * @return The servlet instance to which we are attached.
    81       */
    82      protected ActionServlet getServlet() {
    83          return (this.servlet);
    84      }
    85
    86      /**
    87       * <p>Return the controller servlet instance to which we are attached. as
    88       * an <code>ActionServletWrapper</code>.</p>
    89       *
    90       * @return An instance of {@link ActionServletWrapper}
    91       * @see ActionServletWrapper
    92       * @since Struts 1.0.1
    93       */
    94      public ActionServletWrapper getServletWrapper() {
    95          return new ActionServletWrapper(getServlet());
    96      }
    97
    98      /**
    99       * <p>Return the <code>MultipartRequestHandler</code> for this form The
    100      * reasoning behind this is to give form bean developers control over the
    101      * lifecycle of their multipart requests through the use of the
    102      * <code>finish</code> and/or <code>rollback</code> methods of
    103      * <code>MultipartRequestHandler</code>.  This method will return
    104      * <code>null</code> if this form's enctype is not "multipart/form-data".
    105      * </p>
    106      *
    107      * @return The {@link org.apache.struts.upload.MultipartRequestHandler}
    108      *         for this form.
    109      * @see org.apache.struts.upload.MultipartRequestHandler
    110      */
    111     public MultipartRequestHandler getMultipartRequestHandler() {
    112         return multipartRequestHandler;
    113     }
    114
    115     /**
    116      * <p>Set the servlet instance to which we are attached (if
    117      * <code>servlet</code> is non-null).</p>
    118      *
    119      * @param servlet The new controller servlet, if any
    120      */
    121     public void setServlet(ActionServlet servlet) {
    122         this.servlet = servlet;
    123
    124         // :FIXME: Should this be releasing resources?
    125     }
    126
    127     /**
    128      * <p>Set the Handler provided for use in dealing with file uploads.</p>
    129      *
    130      * @param multipartRequestHandler The Handler to use for fileuploads.
    131      */
    132     public void setMultipartRequestHandler(
    133         MultipartRequestHandler multipartRequestHandler) {
    134         this.multipartRequestHandler = multipartRequestHandler;
    135     }
    136
    137     // --------------------------------------------------------- Public Methods
    138
    139     /**
    140      * <p>>Can be used to reset all bean properties to their default state.
    141      * This method is called before the properties are repopulated by the
    142      * controller.</p>
    143      *
    144      * <p>The default implementation attempts to forward to the HTTP version
    145      * of this method.</p>
    146      *
    147      * @param mapping The mapping used to select this instance
    148      * @param request The servlet request we are processing
    149      */
    150     public void reset(ActionMapping mapping, ServletRequest request) {
    151         try {
    152             reset(mapping, (HttpServletRequest) request);
    153         } catch (ClassCastException e) {
    154             ; // FIXME: Why would this ever happen except a null
    155         }
    156     }
    157
    158     /**
    159      * <p>Can be used to reset bean properties to their default state, as
    160      * needed.  This method is called before the properties are repopulated by
    161      * the controller.</p>
    162      *
    163      * <p>The default implementation does nothing. In practice, the only
    164      * properties that need to be reset are those which represent checkboxes
    165      * on a session-scoped form. Otherwise, properties can be given initial
    166      * values where the field is declared. </p>
    167      *
    168      * <p>If the form is stored in session-scope so that values can be
    169      * collected over multiple requests (a "wizard"), you must be very careful
    170      * of which properties, if any, are reset. As mentioned, session-scope
    171      * checkboxes must be reset to false for any page where this property is
    172      * set. This is because the client does not submit a checkbox value when
    173      * it is clear (false). If a session-scoped checkbox is not proactively
    174      * reset, it can never be set to false.</p>
    175      *
    176      * <p>This method is <strong>not</strong> the appropriate place to
    177      * initialize form value for an "update" type page (this should be done in
    178      * a setup Action). You mainly need to worry about setting checkbox values
    179      * to false; most of the time you can leave this method unimplemented.
    180      * </p>
    181      *
    182      * @param mapping The mapping used to select this instance
    183      * @param request The servlet request we are processing
    184      */
    185     public void reset(ActionMapping mapping, HttpServletRequest request) {
    186         // Default implementation does nothing
    187     }
    188
    189     /**
    190      * <p>Can be used to validate the properties that have been set for this
    191      * non-HTTP request, and return an <code>ActionErrors</code> object that
    192      * encapsulates any validation errors that have been found. If no errors
    193      * are found, return <code>null</code> or an <code>ActionErrors</code>
    194      * object with no recorded error messages.</p>
    195      *
    196      * <p>The default implementation attempts to forward to the HTTP version
    197      * of this method.</p>
    198      *
    199      * @param mapping The mapping used to select this instance
    200      * @param request The servlet request we are processing
    201      * @return The set of validation errors, if validation failed; an empty
    202      *         set or <code>null</code> if validation succeeded.
    203      */
    204     public ActionErrors validate(ActionMapping mapping, ServletRequest request) {
    205         try {
    206             return (validate(mapping, (HttpServletRequest) request));
    207         } catch (ClassCastException e) {
    208             return (null);
    209         }
    210     }
    211
    212     /**
    213      * <p>Can be used to validate the properties that have been set for this
    214      * HTTP request, and return an <code>ActionErrors</code> object that
    215      * encapsulates any validation errors that have been found. If no errors
    216      * are found, return <code>null</code> or an <code>ActionErrors</code>
    217      * object with no recorded error messages.</p>
    218      *
    219      * <p>The default implementation performs no validation and returns
    220      * <code>null</code>. Subclasses must override this method to provide any
    221      * validation they wish to perform.</p>
    222      *
    223      * @param mapping The mapping used to select this instance
    224      * @param request The servlet request we are processing
    225      * @return The set of validation errors, if validation failed; an empty
    226      *         set or <code>null</code> if validation succeeded.
    227      * @see DynaActionForm
    228      */
    229     public ActionErrors validate(ActionMapping mapping,
    230         HttpServletRequest request) {
    231         return (null);
    232     }
    233 }