basebo.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.businessobject;

import java.util.ArrayList;
import java.util.List;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import net.sf.irunninglog.util.ConversionException;
import net.sf.irunninglog.util.DTO;
import net.sf.irunninglog.util.FatalRuntimeException;
import net.sf.irunninglog.validation.ValidationException;

/**
 * Base business object (BO) class for all BOs within the application.  This
 * class provides a basic implementation of the <code>IBusinessObject</code>
 * interface.  These methods are declared as final 'template' methods in this
 * class, and the actual work is delegated to various protected methods that
 * subclasses may override.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.2 $ $Date: 2005/06/29 02:48:07 $
 * @since iRunningLog 1.0
 * @see IBusinessObject
 */
public abstract class BaseBO implements IBusinessObject {

    /** <code>Log</code> instance for this class. */
    private static final Log LOG = LogFactory.getLog(BaseBO.class);

    /** Protect the default constructor. */
    protected BaseBO() {
        super();
    }

    /**
     * Retrieve the BO's values.  This will return a <code>DTO</code>
     * populated with <code>String</code> representations of any values that
     * the BO wishes to expose.
     *
     * @return A transfer object representing the BO's state
     */
    public final DTO getValues() {
        DTO valueObject = getValuesInternal();

        if (LOG.isDebugEnabled()) {
            LOG.debug("getValues: Contents of the value object "
                      + valueObject);
        }

        return valueObject;
    }

    /**
     * Retrieve the BO's values.  This method is invoked from the final
     * <code>getValues</code> method to allow subclasses to determine which
     * values to return.  The implementation at this level simply returns a new
     * <code>DTO</code>.
     *
     * @return A transfer object representing the BO's state
     * @see #getValues()
     */
    protected DTO getValuesInternal() {
        DTO valueObject = new DTO();

        if (LOG.isDebugEnabled()) {
            LOG.debug("getValuesInternal: Contents of the value object "
                      + valueObject);
        }

        return valueObject;
    }

    /**
     * Update the BO's values.  This will pass the supplied
     * transfer object to the BO, which is then responsible for
     * updating any internal values based on the contents of the
     * transfer object.
     *
     * @param valueObject Value object containing the new values
     *                    to be applied to the BO
     * @throws ValidationException If the transfer object contains invalid
     *                             values that the BO is unable to
     *                             use
     */
    public final void setValues(DTO valueObject) throws ValidationException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("setValues: Using the following DTO " + valueObject);
        }

        if (valueObject == null) {
            LOG.error("Unable to set values using a null DTO");
            throw new NullPointerException("Unable to set values using a null "
                                           + "DTO");
        }

        if (LOG.isDebugEnabled()) {
            LOG.debug("setValues: Value object before defaulting "
                      + valueObject);
        }

        defaultValues(valueObject);

        if (LOG.isDebugEnabled()) {
            LOG.debug("setValues: Value object after defaulting "
                      + valueObject);
        }

        if (LOG.isDebugEnabled()) {
            LOG.debug("setValues: Invoking validations");
        }

        List errors = validateValues(valueObject);

        if (LOG.isDebugEnabled()) {
            LOG.debug("setValues: Validations complete, found "
                      + errors.size() + " error(s)");
        }

        if (errors.size() == 0) {
            try {
                if (LOG.isDebugEnabled()) {
                    LOG.debug("setValues: Value object has no errors, calling"
                              + "setValuesInternal");
                }
                setValuesInternal(valueObject);
            } catch (ConversionException ex) {
                LOG.fatal("setValues: Unable to convert value(s)", ex);
                throw new FatalRuntimeException(ex);
            }
        } else {
            if (LOG.isDebugEnabled()) {
                LOG.debug("setValues: Error(s) found during validation,"
                          + " a validation exception");
            }
            throwValidationException(errors);
        }
    }

    /**
     * Default the values of a transfer object.  This method is invoked to
     * allow busines objects the opportunity to default or modify the values of
     * a transfer object before the persistent fields are updated.  The
     * implementation at this level does nothing.
     *
     * @param valueObject The transfer object whose values are to be defaulted
     */
    protected void defaultValues(DTO valueObject) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("defaultValues: Contents of the value object "
                      + valueObject);
        }
    }

    /**
     * Update the BO's values.  This method is invoked from the final
     * <code>setValues</code> to allow subclasses to control the setting of
     * their values.  The implementation at this level does nothing.
     *
     * @param valueObject Transfer object containing values to be used in
     *                    updating this BO's values
     * @throws ConversionException If a conversion error occurrs while setting
     *                             the fields
     * @see #setValues(DTO)
     */
    protected void setValuesInternal(DTO valueObject)
                                                 throws ConversionException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("setValuesInternal: Contents of the value object "
                      + valueObject);
        }
    }

    /**
     * Validate the values contained in a data transfer object.  This is called
     * automatically by <code>setValues</code> prior to calling <code>
     * setValuesInternal</code>.  This method should always be invoked on a
     * transfer object prior to calling the BO's setter methods to ensure that
     * no errors occur while updating the BO's values.  The implementation
     * here returns an empty list.
     *
     * @param valueObject Transfer object containing values to be validated
     * @return A list of errors containing any errors encountered during
     *         validation.  Each item in the list should be an instance of
     *         <code>ValidationError</code>
     * @see #setValues(DTO)
     * @see #setValuesInternal(DTO)
     * @see net.sf.irunninglog.validation.ValidationError
     */
    protected List validateValues(DTO valueObject) {
        List errors = new ArrayList();

        if (LOG.isDebugEnabled()) {
            LOG.debug("validateValues: Returning a list with "
                      + errors.size() + " error(s)");
        }

        return errors;
    }

    /**
     * Throw a validation exception to indicate that validations have failed,
     * rolling back the current transaction.  This method will create a new
     * exception using the list of error provided and throw a
     * <code>ValidationException</code>.
     *
     * @param errors List of validation errors encountered during validation.
     *               Each item in the list should be an instance of
     *               <code>ValidationError</code>
     * @throws ValidationException After rolling back the transaction
     * @see net.sf.irunninglog.validation.ValidationError
     * @see ValidationException
     */
    private void throwValidationException(List errors)
                                          throws ValidationException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("throwValidationException: "
                      + "Throwing a new validation exception with "
                      + errors.size() + "error(s)");
        }
        throw new ValidationException(errors);
    }

}