org.apache.struts.action.ActionForm Maven / Gradle / Ivy
/*
* $Id: ActionForm.java 471754 2006-11-06 14:55:09Z husted $
*
* 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.
*/
package org.apache.struts.action;
import org.apache.struts.upload.MultipartRequestHandler;
import javax.servlet.ServletRequest;
import javax.servlet.http.HttpServletRequest;
import java.io.Serializable;
/**
* An ActionForm is a JavaBean optionally associated with
* one or more ActionMappings. Such a bean will have had its
* properties initialized from the corresponding request parameters before the
* corresponding Action.execute method is called.
*
* When the properties of this bean have been populated, but before the
* execute method of the Action is called, this
* bean's validate method will be called, which gives the bean a
* chance to verify that the properties submitted by the user are correct and
* valid. If this method finds problems, it returns an error messages object
* that encapsulates those problems, and the controller servlet will return
* control to the corresponding input form. Otherwise, the
* validate method returns null, indicating that
* everything is acceptable and the corresponding Action.execute
* method should be called.
*
* This class must be subclassed in order to be instantiated. Subclasses
* should provide property getter and setter methods for all of the bean
* properties they wish to expose, plus override any of the public or
* protected methods for which they wish to provide modified functionality.
*
*
* Because ActionForms are JavaBeans, subclasses should also implement
* Serializable, as required by the JavaBean specification. Some
* containers require that an object meet all JavaBean requirements in order
* to use the introspection API upon which ActionForms rely.
*
* @version $Rev: 471754 $ $Date: 2005-11-12 08:14:24 -0500 (Sat, 12 Nov 2005)
* $
*/
public abstract class ActionForm implements Serializable {
// ----------------------------------------------------- Instance Variables
/**
* The servlet instance to which we are attached.
*/
protected transient ActionServlet servlet = null;
/**
* The MultipartRequestHandler for this form, can be
* null.
*/
protected transient MultipartRequestHandler multipartRequestHandler;
// ------------------------------------------------------------- Properties
/**
* Return the servlet instance to which we are attached.
*
* @return The servlet instance to which we are attached.
*/
protected ActionServlet getServlet() {
return (this.servlet);
}
/**
* Return the controller servlet instance to which we are attached. as
* an ActionServletWrapper.
*
* @return An instance of {@link ActionServletWrapper}
* @see ActionServletWrapper
* @since Struts 1.0.1
*/
public ActionServletWrapper getServletWrapper() {
return new ActionServletWrapper(getServlet());
}
/**
* Return the MultipartRequestHandler for this form The
* reasoning behind this is to give form bean developers control over the
* lifecycle of their multipart requests through the use of the
* finish and/or rollback methods of
* MultipartRequestHandler. This method will return
* null if this form's enctype is not "multipart/form-data".
*
*
* @return The {@link org.apache.struts.upload.MultipartRequestHandler}
* for this form.
* @see org.apache.struts.upload.MultipartRequestHandler
*/
public MultipartRequestHandler getMultipartRequestHandler() {
return multipartRequestHandler;
}
/**
* Set the servlet instance to which we are attached (if
* servlet is non-null).
*
* @param servlet The new controller servlet, if any
*/
public void setServlet(ActionServlet servlet) {
this.servlet = servlet;
// :FIXME: Should this be releasing resources?
}
/**
* Set the Handler provided for use in dealing with file uploads.
*
* @param multipartRequestHandler The Handler to use for fileuploads.
*/
public void setMultipartRequestHandler(
MultipartRequestHandler multipartRequestHandler) {
this.multipartRequestHandler = multipartRequestHandler;
}
// --------------------------------------------------------- Public Methods
/**
* >Can be used to reset all bean properties to their default state.
* This method is called before the properties are repopulated by the
* controller.
*
* The default implementation attempts to forward to the HTTP version
* of this method.
*
* @param mapping The mapping used to select this instance
* @param request The servlet request we are processing
*/
public void reset(ActionMapping mapping, ServletRequest request) {
try {
reset(mapping, (HttpServletRequest) request);
} catch (ClassCastException e) {
; // FIXME: Why would this ever happen except a null
}
}
/**
* Can be used to reset bean properties to their default state, as
* needed. This method is called before the properties are repopulated by
* the controller.
*
* The default implementation does nothing. In practice, the only
* properties that need to be reset are those which represent checkboxes
* on a session-scoped form. Otherwise, properties can be given initial
* values where the field is declared.
*
* If the form is stored in session-scope so that values can be
* collected over multiple requests (a "wizard"), you must be very careful
* of which properties, if any, are reset. As mentioned, session-scope
* checkboxes must be reset to false for any page where this property is
* set. This is because the client does not submit a checkbox value when
* it is clear (false). If a session-scoped checkbox is not proactively
* reset, it can never be set to false.
*
* This method is not the appropriate place to
* initialize form value for an "update" type page (this should be done in
* a setup Action). You mainly need to worry about setting checkbox values
* to false; most of the time you can leave this method unimplemented.
*
*
* @param mapping The mapping used to select this instance
* @param request The servlet request we are processing
*/
public void reset(ActionMapping mapping, HttpServletRequest request) {
// Default implementation does nothing
}
/**
* Can be used to validate the properties that have been set for this
* non-HTTP request, and return an ActionErrors object that
* encapsulates any validation errors that have been found. If no errors
* are found, return null or an ActionErrors
* object with no recorded error messages.
*
* The default implementation attempts to forward to the HTTP version
* of this method.
*
* @param mapping The mapping used to select this instance
* @param request The servlet request we are processing
* @return The set of validation errors, if validation failed; an empty
* set or null if validation succeeded.
*/
public ActionErrors validate(ActionMapping mapping, ServletRequest request) {
try {
return (validate(mapping, (HttpServletRequest) request));
} catch (ClassCastException e) {
return (null);
}
}
/**
* Can be used to validate the properties that have been set for this
* HTTP request, and return an ActionErrors object that
* encapsulates any validation errors that have been found. If no errors
* are found, return null or an ActionErrors
* object with no recorded error messages.
*
* The default implementation performs no validation and returns
* null. Subclasses must override this method to provide any
* validation they wish to perform.
*
* @param mapping The mapping used to select this instance
* @param request The servlet request we are processing
* @return The set of validation errors, if validation failed; an empty
* set or null if validation succeeded.
* @see DynaActionForm
*/
public ActionErrors validate(ActionMapping mapping,
HttpServletRequest request) {
return (null);
}
}