runnerbo.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.Date;
import java.util.List;

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

import net.sf.irunninglog.canonical.Runner;
import net.sf.irunninglog.util.ConversionException;
import net.sf.irunninglog.util.Conversions;
import net.sf.irunninglog.util.DTO;
import net.sf.irunninglog.util.Utilities;
import net.sf.irunninglog.validation.ValidationUtilities;

/**
 * Business object representing a <em>Runner</em>.  This is a POJO business
 * object (BO) implementation that is used to represent <em>Runner</em>
 * entities within the application's business layer.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.2 $ $Date: 2005/06/25 15:18:19 $
 * @since iRunningLog 1.0
 */
public class RunnerBO extends HasRunnerIdBO {

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

    /** The runner's <em>name</em> field. */
    private String mName;
    /** The runner's <em>email</em> field. */
    private String mEmail;
    /** The runner's <em>date of birth</em> field. */
    private Date mDateOfBirth;
    /** The runner's <em>gender</em> field. */
    private String mGender;

    /**
     * Create a new business object instance.
     *
     * @deprecated Use the <code>BusinessObjectFactory</code> to obtain new
     *             instances
     * @see BusinessObjectFactory#newInstance(String)
     */
    public RunnerBO() {
        super();
    }

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

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

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

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

    /**
     * Get the value of the BO's <em>date of birth</em> field.
     *
     * @return The current value of the <em>date of birth</em> field
     */
    public Date getDateOfBirth() {
        return mDateOfBirth;
    }

    /**
     * Set the value of the BO's <em>date of birth</em> field.
     *
     * @param value The value to be set onto the <em>date of birth</em> field
     */
    public void setDateOfBirth(Date value) {
        mDateOfBirth = value;
    }

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

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

    /**
     * Get the value of the BO's <em>age</em> field.
     *
     * @return The current value of the <em>age</em> field
     */
    public String getAge() {
        Date dob = getDateOfBirth();

        return (dob == null) ? null
            : String.valueOf(Utilities.getTimeDiffInYears(new Date(), dob));
    }

    /**
     * Get a string representing the primary key value of this business object.
     *
     * @return The primary key of the business object
     */
    public String getPrimaryKey() {
        return getRunnerId();
    }

    /**
     * Update the object's primary key value based on the values contained
     * in a transfer object.
     *
     * @param valueObject The transfer object containing values to be used in
     *                    formulating the primary key value
     */
    public void setPrimaryKey(DTO valueObject) {
        String id = (valueObject == null) ? null
                                 : valueObject.getValue(Runner.FIELD_RUNNER_ID);
        setRunnerId(id);
    }

    /**
     * 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);
        }

        valueObject.setCanonicalId(Runner.CANONICAL_ID);

        value = getName();
        valueObject.setValue(Runner.FIELD_NAME, value);

        value = getEmail();
        valueObject.setValue(Runner.FIELD_EMAIL, value);

        value = Conversions.dateToString(getDateOfBirth());
        valueObject.setValue(Runner.FIELD_DATE_OF_BIRTH, value);

        value = getAge();
        valueObject.setValue(Runner.FIELD_AGE, value);

        value = getGender();
        valueObject.setValue(Runner.FIELD_GENDER, value);

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

        return 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;

        value = valueObject.getValue(Runner.FIELD_NAME);
        setName(value);

        value = valueObject.getValue(Runner.FIELD_EMAIL);
        setEmail(value);

        value = valueObject.getValue(Runner.FIELD_DATE_OF_BIRTH);
        setDateOfBirth(Conversions.stringToDate(value));

        value = valueObject.getValue(Runner.FIELD_GENDER);
        setGender(value);
    }

    /**
     * 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)");
        }

        validateNameValue(valueObject, errors);
        validateEmailValue(valueObject, errors);
        validateDateOfBirthValue(valueObject, errors);
        validateGenderValue(valueObject, errors);

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

        return errors;
    }

    /**
     * Validate the <code>name</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 validateNameValue(DTO valueObject, List errors) {
        // Name requiredness
        ValidationUtilities.executeRequiredFieldValidation(valueObject,
                                                           Runner.FIELD_NAME,
                                                           errors);
        //Name max length
        ValidationUtilities.executeMaxLengthValidation(valueObject,
                                                       Runner.FIELD_NAME,
                                                       errors);
    }

    /**
     * Validate the <code>email</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 validateEmailValue(DTO valueObject, List errors) {
        //Email max length
        ValidationUtilities.executeMaxLengthValidation(valueObject,
                                                       Runner.FIELD_EMAIL,
                                                       errors);
        //Email validity (a null email is valid)
        ValidationUtilities.executeEmailValidation(valueObject,
                                                   Runner.FIELD_EMAIL,
                                                   errors);
    }

    /**
     * Validate the <code>date of birth</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 validateDateOfBirthValue(DTO valueObject, List errors) {
        //Date validity (a null date is valid)
        ValidationUtilities.executeDateValidation(valueObject,
                                                  Runner.FIELD_DATE_OF_BIRTH,
                                                  errors);
    }

    /**
     * Validate the <code>gender</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 validateGenderValue(DTO valueObject, List errors) {
        //Ensure value is in the allowed values list (a null value is valid)
        ValidationUtilities.executeValidValuesValidation(valueObject,
                                                         Runner.FIELD_GENDER,
                                                         errors);
    }

}