dto.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.util;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

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

/**
 * Generic data transfer object used to transport data between application
 * tiers.  This class can be used to provide a generic representation of any
 * application data.
 *
 * <p/>
 *
 * A <code>DTO</code> consists of a canonical ID (optional) and any number of
 * values.  The values of a <code>DTO</code> can be manipulated via tha <code>
 * getValue</code> and <code>setValue</code> methods.
 *
 * <p/>
 *
 * In addition, a <code>DTO</code> may contain a list of validation errors.
 * This list will be made up of <code>IError</code> instances, and
 * may be populated to indicate that there are problems with the data contained
 * in the object.
 *
 * @author <a href="mailto:[e-mail]">Allan Lewis</a>
 * @version $Revision: 1.1.1.1 $ $Date: 2005/06/23 01:49:03 $
 * @since iRunningLog 1.0
 * @see IError
 */
public class DTO implements Serializable {

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

    /** Canonical ID for this object. */
    private String mCanonicalId;
    /** Map containing the object's values. */
    private Map mValues;
    /** List of errors associated with the object. */
    private List mErrors;

    /**
     * Create a new data transfer object with no canonical ID.
     */
    public DTO() {
        super();
        mValues = new HashMap();
        mErrors = new ArrayList();
    }

    /**
     * Create a data transfer object with a specified canonical ID.
     *
     * @param canonicalId The canonical ID for the object
     */
    public DTO(String canonicalId) {
        this();
        setCanonicalId(canonicalId);
    }

    /**
     * Get the value of this object's canonical ID.
     *
     * @return The canonical ID value
     */
    public String getCanonicalId() {
        return mCanonicalId;
    }

    /**
     * Update the value of this object's canonical ID.
     *
     * @param canonicalId The new value for the canonical ID
     */
    public void setCanonicalId(String canonicalId) {
        mCanonicalId = canonicalId;
    }

    /**
     * Get the value stored in this object for a given key.
     *
     * @param key The key for the value being accessed
     * @return The value stored for the given key
     */
    public String getValue(String key) {
        return (String) mValues.get(key);
    }

    /**
     * Set the value stored in this object for a given key.  Note: a blank
     * value will be stored as <code>null</code>.
     *
     * @param key The key at which to store the value
     * @param value The value to store
     */
    public void setValue(String key, String value) {
        if (value != null && Utilities.isBlank(value)) {
            //Store null for blank values
            if (LOG.isDebugEnabled()) {
                LOG.debug("setValue: Storing null for a blank value");
            }
            value = null;
        }
        mValues.put(key, value);
    }

    /**
     * Get the list of errors associated with this object.
     *
     * @return An unmodifiable list of the errors for this object.
     */
    public List getErrors() {
        return Collections.unmodifiableList(mErrors);
    }

    /**
     * Add an error to this object's list of errors.
     *
     * @param error The error to add
     */
    public void addError(IError error) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("addError: Adding the following error " + error);
        }

        mErrors.add(error);
    }

    /**
     * Add a list of errors to the object's list of errors.  This will add
     * each element from the parameter list to the object's error list.
     *
     * @param errors The list of errors to add to the object's error list
     */
    public void addErrors(List errors) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("addErrors: Adding " + errors.size() + " errors");
        }

        for (int i = 0; i < errors.size(); i++) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("addErrors: Adding " + errors.get(i));
            }
            addError((IError) errors.get(i));
        }
    }

    /**
     * Rremove all errors from the object.  This will empty the object's error
     * list, and <code>hasErrors</code> will return <code>false</code>.
     */
    public void clearErrors() {
        if (LOG.isDebugEnabled()) {
            LOG.debug("clearErrors: Removing all errors");
        }

        mErrors = new ArrayList();
    }

    /**
     * Determine whether or not the object has any errors in its error list.
     *
     * @return True if the object has any errors, false otherwise
     */
    public boolean hasErrors() {
        return !mErrors.isEmpty();
    }

    /**
     * Custom toString override to provide a meaningful <code>String</code>
     * representation of this object.
     *
     * @return A <code>String</code> representation of this object
     */
    public String toString() {
        StringBuffer buff = new StringBuffer();

        buff.append("DTO[canonicalId='");
        buff.append(mCanonicalId);
        buff.append("' ");
        buff.append("values={");

        for (Iterator i = mValues.keySet().iterator(); i.hasNext();) {
            String key = (String) i.next();
            buff.append(key);
            buff.append("='");
            buff.append(mValues.get(key));
            buff.append("'");
            if (i.hasNext()) {
                buff.append(", ");
            }
        }

        buff.append("} ");
        buff.append("errors={");

        for (Iterator i = mErrors.iterator(); i.hasNext();) {
            buff.append(i.next());
            if (i.hasNext()) {
                buff.append(", ");
            }
        }

        buff.append("}");
        buff.append("]");

        return buff.toString();
    }

}