referencedatabo.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.Collection;
import java.util.Iterator;
import java.util.List;

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

import net.sf.irunninglog.canonical.ReferenceData;
import net.sf.irunninglog.transaction.IUnitOfWork;
import net.sf.irunninglog.transaction.TransactionException;
import net.sf.irunninglog.transaction.TransactionalSupport;
import net.sf.irunninglog.util.ConstantValues;
import net.sf.irunninglog.util.ConversionException;
import net.sf.irunninglog.util.Conversions;
import net.sf.irunninglog.util.DTO;
import net.sf.irunninglog.util.FatalRuntimeException;
import net.sf.irunninglog.util.Utilities;
import net.sf.irunninglog.validation.ValidationUtilities;

/**
 * Business object (BO) representaion of any application reference data.  This
 * BO contains the following fields: <em>id</em>, <em>description</em>,
 * and <em>default</em> fields.  Methods are also provided for accessing,
 * updating, and validating these fields.  In addition, the <em>id</em> field
 * is used as the (system-generated) primary key identifier.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.2 $ $Date: 2005/06/29 02:48:09 $
 * @since iRunningLog 1.0
 */
public abstract class ReferenceDataBO extends HasGeneratedIdBO {

    /** <code>Log</code> instance for this class. */
    private static final Log LOG = LogFactory.getLog(ReferenceDataBO.class);
    /** Query string used to find default records. */
    private static final String FIND_DEFAULT_BY_RUNNER_ID = "DefaultByRunnerId";

    /** The BO's <em>description</em> field. */
    private String mDescription;
    /** The BO's <em>default</em> flag. */
    private Boolean mDefault;

    /**
     * Get the value of the BO's <em>description</em> field.
     *
     * @return The current value of the <em>description</em> field
     */
    public String getDescription() {
        return mDescription;
    }

    /**
     * Set the value of the BO's <em>description</em> field.
     *
     * @param value The value to be set onto the <em>description</em> field
     */
    public void setDescription(String value) {
        mDescription = value;
    }

    /**
     * Get the value of the BO's <em>default</em> flag.
     *
     * @return The current value of the <em>default</em> flag
     */
    public Boolean isDefault() {
        return mDefault;
    }

    /**
     * Set the value of the BO's <em>default</em> flag.
     *
     * @param value The value to be set onto the <em>default</em> flag
     */
    public void setDefault(Boolean value) {
        mDefault = value;
    }

    /**
     * Get a data transfer objects containing values that represent the current
     * state of this BO.  This is a template method that is called from the
     * final method <code>getValues</code> in <code>BaseBO</code>.
     *
     * @return The data transfer object, populated with the appropriate values
     * @see BaseBO#getValues()
     */
    protected DTO getValuesInternal() {
        DTO valueObject = super.getValuesInternal();
        String value = null;

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

        value = getDescription();
        valueObject.setValue(ReferenceData.FIELD_DESCRIPTION, value);

        value = Conversions.booleanToString(isDefault());
        valueObject.setValue(ReferenceData.FIELD_DEFAULT, value);

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

        return valueObject;
    }

    /**
     * Default the values of a transfer object.
     *
     * @param valueObject The transfer object whose values are to be defaulted
     */
    protected void defaultValues(DTO valueObject) {
        super.defaultValues(valueObject);
        String value = null;

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

        value = valueObject.getValue(ReferenceData.FIELD_DEFAULT);
        if (Utilities.isBlank(value)) {
            valueObject.setValue(ReferenceData.FIELD_DEFAULT,
                                 ConstantValues.STRING_FALSE);
        }

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

    /**
     * Update the BO's fields with the values provided in a data transfer
     * object.  This is a template method that is called from the final
     * <code>setValue</code> method in <code>BaseBO</code>.
     *
     * @param valueObject The data transfer object containing values to be
     *                    used in updating this BO
     * @throws ConversionException If a conversion error occurrs while setting
     *                             the fields
     * @see BaseBO#setValues(DTO)
     */
    protected void setValuesInternal(DTO valueObject)
                                                  throws ConversionException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("setValuesInternal: Contents of the value object "
                      + valueObject);
        }

        super.setValuesInternal(valueObject);
        String value = null;
        Boolean oBool = null;

        value = valueObject.getValue(ReferenceData.FIELD_DESCRIPTION);
        setDescription(value);

        value = valueObject.getValue(ReferenceData.FIELD_DEFAULT);
        oBool = Conversions.stringToBoolean(value);
        setDefault(oBool);
        oBool = isDefault();
        if (oBool != null && oBool.booleanValue()) {
            // Only one piece of ref data per Runner can be the default
            handleDefaultFlag();
        }
    }

    /**
     * Update any Run Types for the current Runner (aside from this one) to
     * have a <code>false</code> value for their default flag.
     */
    private void handleDefaultFlag() {
        try {

            if (LOG.isDebugEnabled()) {
                LOG.debug("handleDefaultFlag: Setting object (id="
                          + getId() + ") as default");
            }

            ReferenceDataBO refData = null;
            IUnitOfWork unitOfWork = TransactionalSupport.getUnitOfWork();

            Collection allBOs = findDefaultRecordsByRunnerId(unitOfWork);
            for (Iterator i = allBOs.iterator(); i.hasNext();) {
                refData = (ReferenceDataBO) i.next();

                if (LOG.isDebugEnabled()) {
                    LOG.debug("handleDefaultFlag: Setting object (id="
                              + refData.getId() + ") as not default");
                }

                refData.setDefault(Boolean.FALSE);
                unitOfWork.update(refData);
            }
        } catch (TransactionException ex) {
            LOG.fatal("handleDefaultFlag: Error resetting default flag(s)", ex);
            throw new FatalRuntimeException(ex);
        }
    }

    /**
     * Find all default reference data records that are currently marked as
     * default.
     *
     * @param unitOfWork The transactional unit of work to be used to find the
     *                   appropriate business object(s).
     * @return The collection of business objects that are marked as default
     * @throws TransactionException If there is an error finding the records
     */
    private Collection findDefaultRecordsByRunnerId(IUnitOfWork unitOfWork)
                                                   throws TransactionException {

        Object [] params = new Object [] {getRunnerId(), getId()};
        return unitOfWork.find(getClass().getName() + FIND_DEFAULT_BY_RUNNER_ID,
                               params);
    }

    /**
     * Validate the values contained in a data transfer object.  This method
     * is reponsible for perofrming all validations on the transfer object, and
     * should be called before updating the BO's fields to avoid
     * bad data and/or errors.
     *
     * @param valueObject The data transfer object whose fields are to be
     *                    validated
     * @return A list consisting of any errors found while validating the
     *         transfer object
     */
    protected List validateValues(DTO valueObject) {
        List errors = super.validateValues(valueObject);

        if (LOG.isDebugEnabled()) {
            LOG.debug("validateValues: Before validations, error list contains"
                      + errors.size() + " error(s)");
        }

        validateDescriptionValue(valueObject, errors);
        validateDefaultValue(valueObject, errors);

        if (LOG.isDebugEnabled()) {
            LOG.debug("validateValues: After validations, error list contains"
                      + errors.size() + " error(s)");
        }

        return errors;
    }

    /**
     * Validate the <code>description</code> field value on a data transfer
     * object.
     *
     * @param valueObject The data transfer object containing the value(s) to
     *                    be validated
     * @param errors An error list, which this method may add to if there are
     *               any validation errors
     */
    private void validateDescriptionValue(DTO valueObject, List errors) {
        String fieldName = ReferenceData.FIELD_DESCRIPTION;

        ValidationUtilities.executeRequiredFieldValidation(valueObject,
                                                           fieldName,
                                                           errors);

        ValidationUtilities.executeMaxLengthValidation(valueObject,
                                                       fieldName,
                                                       errors);
    }

    /**
     * Validate the <code>default</code> field value on a data transfer
     * object.
     *
     * @param valueObject The data transfer object containing the value(s) to
     *                    be validated
     * @param errors An error list, which this method may add to if there are
     *               any validation errors
     */
    private void validateDefaultValue(DTO valueObject, List errors) {
        String fieldName = ReferenceData.FIELD_DEFAULT;

        ValidationUtilities.executeRequiredFieldValidation(valueObject,
                                                           fieldName,
                                                           errors);

        ValidationUtilities.executeBooleanValidation(valueObject,
                                                     fieldName,
                                                     errors);
    }

}