conversions.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.math.BigDecimal;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Locale;
import java.util.StringTokenizer;

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

/**
 * Class containing conversion methods useful for converting values from one
 * type to another.  Some methods may be called 'safely', while others may
 * throw a <code>ConversionException</code> if the conversion cannot be
 * performed successfully.
 *
 * @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 ConversionException
 */
public final class Conversions {

    /** <code>Log</code> instance for this class. */
    private static final Log LOG = LogFactory.getLog(Conversions.class);
    /** Int value representing the value '10'. */
    private static final int TEN = 10;
    /** Int value representing the value '100'. */
    private static final int ONE_HUNDRED = 100;
    /** String representing the value ':'. */
    private static final String COLON = ":";
    /** String representing the value '.'. */
    private static final String PERIOD = ".";

    /** Time format containing hours, minutes, and seconds. */
    private static final int FORMAT_H_M_S = 3;
    /** Time format containing hours and minutes. */
    private static final int FORMAT_M_S = 2;
    /** Time format containing only minutes. */
    private static final int FORMAT_M = 1;
    /** The size of the largest time that may be converted. */
    private static final int MAX_TIME = 86399999;

    /** Utility class - does not expose a constructor. */
    private Conversions() {
        super();
    }

    //////// Convert a java.util.Date into a java.lang.String

    /**
     * Convert a <code>java.util.Date</code> into a
     * <code>java.lang.String</code>.  If the data passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * the date is formatted into a string formatted according to the
     * <code>java.text.DateFormat.SHORT</code> style, using the default locale.
     *
     * @param date The date to be converted
     * @return A formatted string representation of the date
     */
    public static String dateToString(Date date) {
        return dateToString(date, DateFormat.SHORT);
    }

    /**
     * Convert a <code>java.util.Date</code> into a
     * <code>java.lang.String</code>.  If the data passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * the date is formatted into a string using the specified style using the
     * default locale.
     *
     * @param date The date to be converted
     * @param style The style into which the date should be formatted.  This
     *              should be one of the style constants defined in
     *              <code>java.text.DateFormat</code>
     * @return A formatted string representation of the date
     */
    public static String dateToString(Date date, int style) {
        return dateToString(date, style, Locale.getDefault());
    }

    /**
     * Convert a <code>java.util.Date</code> into a
     * <code>java.lang.String</code>.  If the data passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * the date is formatted into a string using the specified style using
     * the specified locale.
     *
     * @param date The date to be converted
     * @param style The style into which the date should be formatted.  This
     *              should be one of the style constants defined in
     *              <code>java.text.DateFormat</code>
     * @param locale The locale object to use while formatting
     * @return A formatted string representation of the date
     */
    public static String dateToString(Date date, int style, Locale locale) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("dateToString: Converting '" + date + "' to a String"
                      + " using the following Locale '" + locale + "'");
        }

        String convertedValue = (date == null) ? null
                                 : getDateInstance(style, locale).format(date);

        if (LOG.isDebugEnabled()) {
            LOG.debug("dateToString: The result of the conversion is '"
                      + convertedValue + "'");
        }

        return convertedValue;
    }

    //////// Convert a java.lang.String into a java.util.Date

    /**
     * Convert a <code>java.lang.String</code> into a
     * <code>java.util.Date</code>.  If the string passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * this method will attempt to convert the string to a date, and will throw
     * a <code>ConversionException</code> if it is unable to do so.  This
     * method will assume that the string is formatted in the
     * <code>java.text.DateFormat.SHORT</code> style, and will use the default
     * locale while converting.
     *
     * @param sDate The string to be converted to a date
     * @return The date that the string was converted into
     * @throws ConversionException If the string cannot be converted to a date
     * @see ConversionException
     */
    public static Date stringToDate(String sDate) throws ConversionException {
        return stringToDate(sDate, DateFormat.SHORT);
    }

    /**
     * Convert a <code>java.lang.String</code> into a
     * <code>java.util.Date</code>.  If the string passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * this method will attempt to convert the string to a date, and will throw
     * a <code>ConversionException</code> if it is unable to do so.  This
     * method will assume that the string is formatted in the specified style,
     * and will use the default locale while converting.
     *
     * @param sDate The string to be converted to a date
     * @param style The style in which the string is formatted.  This
     *              should be one of the style constants defined in
     *              <code>java.text.DateFormat</code>
     * @return The date that the string was converted into
     * @throws ConversionException If the string cannot be converted to a date
     * @see ConversionException
     */
    public static Date stringToDate(String sDate, int style)
                                    throws ConversionException {
        return stringToDate(sDate, style, Locale.getDefault());
    }

    /**
     * Convert a <code>java.lang.String</code> into a
     * <code>java.util.Date</code>.  If the string passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * this method will attempt to convert the string to a date, and will throw
     * a <code>ConversionException</code> if it is unable to do so.  This
     * method will assume that the string is formatted in the specified style,
     * and will use the specified locale while converting.
     *
     * @param sDate The string to be converted to a date
     * @param style The style in which the string is formatted.  This
     *              should be one of the style constants defined in
     *              <code>java.text.DateFormat</code>
     * @param locale The locale to use while converting
     * @return The date that the string was converted into
     * @throws ConversionException If the string cannot be converted to a date
     * @see ConversionException
     */
    public static Date stringToDate(String sDate, int style, Locale locale)
                                    throws ConversionException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("stringToDate: Converting '" + sDate + "' to a Date"
                      + " using the following Locale '" + locale + "'");
        }

        if (sDate == null) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDate: The result of the conversion is null");
            }
            return null;
        }

        try {
            Date returnValue = getDateInstance(style, locale).parse(sDate);
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDate: The result of the conversion is '"
                          + returnValue + "'");
            }
            return returnValue;
        } catch (Exception ex) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDate: Unable to convert '" + sDate
                          + "' into a Date");
            }
            throw new ConversionException(sDate, String.class, Date.class);
        }
    }

    //////// Convert a java.math.BigDecimal into a java.lang.String

    /**
     * Convert a <code>java.math.BigDecimal</code> into a
     * <code>java.lang.String</code> by invoking <code>BigDecimal</code>'s
     * <code>toString</code> method.  If the decimal passed in is
     * <code>null</code>, then <code>null</code> will be returned.
     *
     * @param dec The decimal to be converted to a string
     * @return A string representation of the decimal
     */
    public static String decimalToString(BigDecimal dec) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("decimalToString: Converting '" + dec + "' to a String");
        }

        String returnValue = (dec == null) ? null : dec.toString();

        if (LOG.isDebugEnabled()) {
            LOG.debug("decimalToString: Result of the conversion is '"
                      + returnValue + "'");
        }

        return returnValue;
    }

    //////// Convert a java.lang.String into a java.math.BigDecimal

    /**
     * Convert a <code>java.lang.String</code> into a
     * <code>java.math.BigDecimal</code>.  If the string passed in is
     * <code>null</code>, then <code>null</code> will be returned.  Otherwise
     * this method will attempt to convert the string to a decimal, and will
     * throw a <code>ConversionException</code> if it is unable to do so.
     *
     * @param sDec The string to be converted to a decimal
     * @return The decimal that the string was converted into
     * @throws ConversionException If the string cannot be converted to a date
     * @see ConversionException
     */
    public static BigDecimal stringToDecimal(String sDec)
                                                   throws ConversionException {
        if (LOG.isDebugEnabled()) {
            LOG.debug("stringToDecimal: Converting '" + sDec
                      + "' to a Decimal");
        }

        if (sDec == null) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDecimal: Result of the conversion is null");
            }
            return null;
        }

        try {
            BigDecimal dec = new BigDecimal(sDec);
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDecimal: Result of the conversion is '"
                          + dec + "'");
            }
            return dec;
        } catch (Exception ex) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("stringToDecimal: Unable to convert '" + sDec
                          + "' into a Decimal");
            }
            throw new ConversionException(sDec, String.class, BigDecimal.class);
        }
    }

    //////// Convert (b)Booleans into java.lang.Strings

    /**
     * Convert a <code>Boolean</code> (object) into a
     * <code>java.lang.String</code>. This will return either <code>
     * ConstantValues.STRING_TRUE</code> or <code>ConstantValues.STRING_FALSE
     * </code> based on the input parameter's value.
     *
     * @param bool The <code>Boolean</code> to be converted to a string
     * @return A string representation of the boolean
     * @see ConstantValues#STRING_FALSE
     * @see ConstantValues#STRING_TRUE
     */
    public static String booleanToString(Boolean bool) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("booleanToString: Converting '" + bool + "' to a String");
        }

        if (bool == null) {
            if (LOG.isDebugEnabled()) {
                LOG.debug("booleanToString: Result of the conversion is null");
            }
            return null;
        }

        return booleanToString(bool.booleanValue());
    }

    /**
     * Convert a <code>boolean</code> (primitive) into a
     * <code>java.lang.String</code>. This will return either <code>
     * ConstantValues.STRING_TRUE</code> or <code>ConstantValues.STRING_FALSE
     * </code> based on the input parameter's value.
     *
     * @param bool The <code>boolean</code> to be converted to a string
     * @return A string representation of the boolean
     * @see ConstantValues#STRING_FALSE
     * @see ConstantValues#STRING_TRUE