/*
    * Copyright (c) 2001 - 2005 ivata limited.
    * All rights reserved.
    * -----------------------------------------------------------------------------
    * ivata masks may be redistributed under the GNU General Public
    * License as published by the Free Software Foundation;
    * version 2 of the License.
    *
    * These programs are free software; you can redistribute them and/or
   * modify them under the terms of the GNU General Public License
   * as published by the Free Software Foundation; version 2 of the License.
   *
   * These programs are distributed in the hope that they will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   *
   * See the GNU General Public License in the file LICENSE.txt for more
   * details.
   *
   * If you would like a copy of the GNU General Public License write to
   *
   * Free Software Foundation, Inc.
   * 59 Temple Place - Suite 330
   * Boston, MA 02111-1307, USA.
   *
   *
   * To arrange commercial support and licensing, contact ivata at
   *                  http://www.ivata.com/contact.jsp
   * -----------------------------------------------------------------------------
   * $Log: HTMLFormatter.java,v $
   * Revision 1.3  2005/04/09 18:04:18  colinmacleod
   * Changed copyright text to GPL v2 explicitly.
   *
   * Revision 1.2  2005/01/06 22:41:01  colinmacleod
   * Moved up a version number.
   * Changed copyright notices to 2005.
   * Updated the documentation:
   *   - started working on multiproject:site docu.
   *   - changed the logo.
   * Added checkstyle and fixed LOADS of style issues.
   * Added separate thirdparty subproject.
   * Added struts (in web), util and webgui (in webtheme) from ivata op.
   *
   * Revision 1.3  2004/03/21 21:16:37  colinmacleod
   * Shortened name to ivata op.
   *
   * Revision 1.2  2004/02/01 22:07:32  colinmacleod
   * Added full names to author tags
   *
   * Revision 1.1.1.1  2004/01/27 20:59:47  colinmacleod
   * Moved ivata op to SourceForge.
   *
   * Revision 1.2  2003/10/15 14:13:39  colin
   * Fixes for XDoclet.
   *
   * Revision 1.1  2003/02/24 19:33:33  colin
   * Moved to new subproject.
   *
   * Revision 1.4  2003/02/04 17:43:46  colin
   * copyright notice
   *
   * Revision 1.3  2002/09/06 15:06:31  colin
   * added null checking on input format text
   *
   * Revision 1.2  2002/06/21 16:00:30  colin
   * added protected accessors (get/set) to the Vector of formats.
   *
   * Revision 1.1  2002/04/26 13:52:44  colin
   * move to EJB/JBuilder project
   *
   * Revision 1.12  2002/02/02 19:10:52  colin
   * changed formatEmail methods to just return null when you pass null
   * to them
   *
   * Revision 1.11  2002/01/25 18:04:06  colin
   * Formatted for JavaDoc.
   *
   * Revision 1.10  2002/01/20 19:40:24  colin
   * added tab and tree tags
   * implemented address book functionality
   *
   * Revision 1.9  2002/01/20 19:28:25  colin
   * added tab and tree tags
   * implemented address book functionality
   *
   * Revision 1.8  2001/12/20 17:11:44  colin
   * tidied up the HTMLFormatter code, and improved InternetAddress
   * handling
   * truncated email addresses which are too long in index.jsp
   * changed non-alphanumeric symbols (such as apostrophe ') to their
   * HTML equivalents in compose and display
   * made error messages in the compose window limited in width
   * (word-wrap)
   * converted URLs into links
   *
   * Revision 1.7  2001/12/12 20:24:57  colin
   * fixed the following bugs:
   * made display window same width as index
   * made leading spaces non-breaking
  * put a little header with from/to/subject information before
  * forwarded and replied to mails
  * stopped append re: to messages which are already re: (same applies
  * to forward)
  * convert people's email addresses into links (mailto)
  * word wrap the messages (replies) in compose
  * make the subject line spread right over the whole space in display
  *
  * Revision 1.6  2001/11/24 19:19:53  colin
  * display, compose, reply and forward features of webmail implemented
  *
  * Revision 1.5  2001/11/08 01:38:56  colin
  * implemented new Solero theme in shop
  *
  * Revision 1.4  2001/10/22 19:50:51  colin
  * commit everything before move from monifieth1 to lucenec1
  *
  * Revision 1.3  2001/10/16 17:52:02  colin
  * updated mail classes to set formatterName="nothing" instead of null
  * several rebuilds to avoid problem of classes not recompiling
  *
  * Revision 1.2  2001/10/14 18:01:02  colin
  * added '..' to shortened lines
  *
  * Revision 1.1  2001/10/07 00:30:16  colin
  * no message
  *
  * Revision 1.1.1.1  2001/10/06 15:40:20  colin
  * initial import into CVS
  * -----------------------------------------------------------------------------
  */
 package com.ivata.mask.web.format;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Vector;
 /***
  * <p>
  * This class defines a standard way of formatting HTML. It can be used as as a
  * parameter to methods from other classes indicating that output should be
  * truncated, spaces should be converted to non-breaking, or the string should
  * be parsed for URLs.
  * </p>
  * <p>
  * The actual conversions are achieved by add-in classes, with {@linkHTMLFormat
  * HTMLFormat} as their superclass. This means the formatter can provided a rich
  * selection of different formats without having knowledge of the processing of
  * each one.
  * <p>
  * <p>
  * To use this class, created an instance of the formats you wish to use, and an
  * instance of this class too. Call any methods on the formats to set up the
  * exact function of each one. Then call {@link #add add}for each format on the
  * <code>HTMLFormatter</code> instance. Passing a text to
  * {@link #format format}will ensure that each format is applied in the order
  * in which they were added to the formatter.
  * </p>
  *
  * @since ivata masks 0.2 (2001-10-03)
  * @author Colin MacLeod
  * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
  * @version $Revision: 1.3 $
  */
 public class HTMLFormatter extends Object {
     /***
      * <p>
      * Stores all of the formats which will be applied.
      * </p>
      */
     private List formats = new Vector();
     /***
      * Used to note the position of any link format, so it does not interfere
      * with character entity format.
      */
     private LinkFormat linkFormat = null;
     /***
      * Creates a new instance of HTMLFormatter with default settings.
      */
     public HTMLFormatter() {
         super();
     }
     /***
      * <p>
      * If the object is not null, fill the attribute with this value otherwise
      * return nothing.
      * </p>
      *
      * <p>
      * This is useful for HTML tags where you want to created an attribute value
      * only if the object <code>objectParam</code> is non-null.
      * </p>
      *
      * @param attribute
      *            the attribute name of the attribute to be set if
      *            <code>objectParam</code> is non-null
      * @param objectParam
      *            an Object to assign attribute to if it is non-null
      * @return if <code>objectParam</code> is not null, a string assigning the
      *         attribute sAttrubte to the value of
      *         <code>objectParam.toString()</code>, otherwise an empty
      *         string.
      * @see #getBooleanAttribute(String attribute, boolean check)
      * @see #getNotNull(Object o, String nullString)
      */
     public static final String getAttributeNotNull(final String attribute,
             final Object objectParam) {
         if (objectParam == null) {
             return "";
         } else {
             return " " + attribute + "='" + objectParam.toString() + "'";
         }
     }
     /***
      * <p>
      * If the boolean is true, fill the attribute with no value, otherwise
      * return nothing.
      * </p>
      *
      * <p>
      * This is useful for HTML tags where you want to create an attribute only
      * if the condition is <code>true</code>.
      * </p>
      *
      * @param attribute
      *            the attribute name of the attribute to be set if check is
      *            <code>true</code>.
      * @param check
      *            a boolean to evaluate.
      * @return if check is <code>true</code>, the attribute string, otherwise
      *         an empty string.
      * @see #getAttributeNotNull(String attribute, Object o)
      * @see #getNotNull(Object o)
      */
     public static final String getBooleanAttribute(final String attribute,
             final boolean check) {
         if (check) {
             return " " + attribute;
         } else {
             return "";
         }
     }
     /***
      * <p>
      * This is the most important method of all.
      * </p>
      *
      * <p>
      * First call the methods setConvert.... to specify how to convert the
      * string, then use this method to format the given string according to the
      * set rules
      * </p>.
      *
      * @param formatString
      *            String to format
      * @return String containing formatted text, according to the current state
      *         of this HTMLFormatter instance.
      * @see HTMLFormat#format
      */
     public String format(final String formatString) {
         // rubbish in, rubbish out...
         if (formatString == null) {
             return null;
         }
         String returnString = formatString;
         // go through all of the format objects provided and call each one
         for (Iterator i = formats.iterator(); i.hasNext();) {
             HTMLFormat format = (HTMLFormat) i.next();
             returnString = format.format(returnString);
         }
         return returnString;
     }
     /***
      * <p>
      * Adds the format to the internal list of <code>HTMLFormat</code>
      * instances this formatter holds.
      * </p>
      *
      * @param format
      *            the format instance to add. This will be processed after all
      *            existing formats.
      */
     public final void add(final HTMLFormat format) {
         // see if there is a convert character entities after the link format,
         // and warn it if there is
         if (linkFormat == null) {
             // see if this is a link format
             if (LinkFormat.class.isInstance(format)) {
                 linkFormat = (LinkFormat) format;
             }
         } else if (CharacterEntityFormat.class.isInstance(format)) {
             // warn the link format
             linkFormat.setConvertHTMLEntities(true);
         }
         formats.add(format);
     }
     /***
      * <p>
      * Locates a format in the object, identified by class.
      * </p>
      *
      * @param findClass
      *            the <code>Class</code> of the format to locate in the
      *            formatter's internal list.
      * @return first format found with the class specified, or <code>null</code>
      *         if no format with this class has been set in the formatter
      */
     public final HTMLFormat findFormat(final Class findClass) {
         HTMLFormat formatReturn = null;
         for (Iterator i = formats.iterator(); i.hasNext();) {
             HTMLFormat format = (HTMLFormat) i.next();
             // see if this instance matches the class we're looking for
             if (findClass.isInstance(format)) {
                 formatReturn = format;
                 break;
             }
         }
         return formatReturn;
     }
     /***
      * <p>
      * Get the internal list of all of the formats used by this formatter.
      * </p>
      *
      * @return a <code>Vector</code> containing all of the formats from this
      *         formatter.
      */
     public final List getFormats() {
         return formats;
     }
     /***
      * <p>
      * Set the internal list of all of the formats used by this formatter.
      * </p>
      *
      * @param formatsParam
      *            a <code>Vector</code> containing all of the formats from
      *            this formatter.
      */
     protected final void setFormats(final List formatsParam) {
         this.formats = formatsParam;
     }
 }