basequeryaction.java

A Java web application, based on Struts and Hibernate, that serves as an online running log. Users m

/* @LICENSE_COPYRIGHT@ */
package net.sf.irunninglog.servlet.action;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.struts.action.ActionForm;
import org.apache.struts.action.ActionForward;
import org.apache.struts.action.ActionMapping;

import net.sf.irunninglog.servlet.RequestProcessor;
import net.sf.irunninglog.servlet.UserContainer;
import net.sf.irunninglog.servlet.formbean.ValueBean;
import net.sf.irunninglog.util.DTO;
import net.sf.irunninglog.util.ObjectFactory;

/**
 * Base action class used to perform query operations.  This class defines the
 * various methods that are used to perform query operations.  Subclasses must
 * override the <code>executeQuery</code> method, and may optionally override
 * the <code>executeBeforeQuery</code> and/or <code>executeAfterQuery</code>
 * methods to customize query behavior.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.1.1.1 $ $Date: 2005/06/23 01:48:59 $
 * @since iRunningLog 1.0
 */
public abstract class BaseQueryAction extends BaseAction {

    /** Log instance for this class. */
    private static final Log LOG = LogFactory.getLog(BaseQueryAction.class);

    /**
     * Execute a query.  This method makes use of the <code>executeQuery</code>,
     * <code>executeBeforeQuery</code>, and <code>executeAfterQuery</code>
     * methods to execute a query action.  Subclasses may override these methods
     * to customize query behavior.
     *
     * @param mapping The <code>ActionMapping</code> used to select this
     *                instance.
     * @param form The optional <code>ActionForm</code> bean for this request
     * @param request The HTTP request being processed
     * @param response The HTTP response being processed
     * @param container The <code>UserContainer</code> object for the current
     *                  user
     * @return The forward describing where/how to forward control
     * @exception Exception if the application business logic throws
     *            an exception
     */
    public final ActionForward executeAction(ActionMapping mapping,
                                             ActionForm form,
                                             HttpServletRequest request,
                                             HttpServletResponse response,
                                             UserContainer container)
                                                              throws Exception {

        executeBeforeQuery(mapping, form, request, container);

        Collection results = executeQuery(mapping, form, request, container);

        executeAfterQuery(mapping, form, request, container, results);

        return mapping.findForward(RequestProcessor.FORWARD_SUCCESS);
    }

    /**
     * Perform any work that needs to be done before the actual query
     * happens.
     *
     * @param mapping The <code>ActionMapping</code> used to select this
     *                instance.
     * @param form The optional <code>ActionForm</code> bean for this request
     * @param request The HTTP request being processed
     * @param container The <code>UserContainer</code> object for the current
     *                  user
     */
    protected void executeBeforeQuery(ActionMapping mapping,
                                      ActionForm form,
                                      HttpServletRequest request,
                                      UserContainer container) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("executeBeforeQuery: About to execute the query");
        }
    }

    /**
     * Execute the actual query.  This method is responsible for performing
     * the query (by whatever means) and returning a collection of query
     * results.
     *
     * @param mapping The <code>ActionMapping</code> used to select this
     *                instance.
     * @param form The optional <code>ActionForm</code> bean for this request
     * @param request The HTTP request being processed
     * @param container The <code>UserContainer</code> object for the current
     *                  user
     * @return The collection of objects found by the query
     * @exception Exception if the application business logic throws
     *            an exception
     */
    protected abstract Collection executeQuery(ActionMapping mapping,
                                               ActionForm form,
                                               HttpServletRequest request,
                                               UserContainer container)
                                                               throws Exception;

    /**
     * Perform any work that needs to be done before the actual query
     * happens.
     *
     * @param mapping The <code>ActionMapping</code> used to select this
     *                instance.
     * @param form The optional <code>ActionForm</code> bean for this request
     * @param request The HTTP request being processed
     * @param container The <code>UserContainer</code> object for the current
     *                  user
     * @param results The collection of objects returned from the
     *                <code>executeQuery</code> method
     */
    protected void executeAfterQuery(ActionMapping mapping,
                                     ActionForm form,
                                     HttpServletRequest request,
                                     UserContainer container,
                                     Collection results) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("executeAfterQuery: Query finished.");
        }
    }

    /**
     * Transform a list of transfer objects into a list of view objects.  This
     * will iterate over the input collection and transform each transfer
     * object into a value bean.  A new collection of value beans (identical in
     * size to the original collection) will be returned.
     *
     * @param mapping The <code>ActionMapping</code> used to select this
     *                instance.  Should contain the name of the value bean class
     *                that results should be returned as
     * @param input A collection of transfer objects
     * @return A collection (unmodifiable) of value beans
     */
    protected Collection createValueBeans(ActionMapping mapping,
                                          Collection input) {

        ObjectFactory factory = ObjectFactory.getInstance();
        ArrayList output = new ArrayList(input.size());
        DTO dto = null;
        ValueBean bean = null;

        if (LOG.isDebugEnabled()) {
            LOG.debug("createValueBeans: Converting this collection " + input);
        }

        for (Iterator i = input.iterator(); i.hasNext();) {
            dto = (DTO) i.next();

            bean = (ValueBean) factory.createObject(mapping.getParameter());
            bean.setValues(dto);

            if (LOG.isDebugEnabled()) {
                LOG.debug("createValueBeans: Converted " + dto + " into "
                          + bean);
            }

            output.add(bean);
        }

        return Collections.unmodifiableList(output);
    }

}