/*
 * COPYRIGHT (c) 1998-1999 Jan-Henrik Haukeland, http://www.tildeslash.com/
 */

package ts.mail;

import java.util.Enumeration;

/**  
 * Interface describing an object containing a general mail message
 * (a subset of RFC 822). The interface defines methods that are
 * necessary for handling the mail messsage, but <I>not</I>
 * particular to any transport mechanism.
 * 
 * @author  Jan-Henrik Haukeland &lt;hauk@tildeslash.com&gt;
 * @version $id: $
 *
 * @see DefaultMailModel 
 */
public interface MailModel
{

  /** Constant defining an empty field value */
  public static String NO_FIELD_VALUE= "";


  // ------------------------- Set methods ------------------------ //
  
  /**
   * Set the mail message id
   *
   * @param aId - The mail message id
   * @exception IllegalArgumentException  Is thrown if the parameter is null
   */
  public void setIdField(String id) throws IllegalArgumentException ;


  /**
   * Set the mail to-field
   *
   * @param aToField - The mail to-field
   * @exception IllegalArgumentException  Is thrown if the parameter is null
   */
  public void setToField(String aToField) throws IllegalArgumentException ;

  
  /**
   * Set the mail from-field
   *
   * @param aFromField - The mail from-field
   * @exception IllegalArgumentException  Is thrown if the parameter is null
   */
  public void setFromField(String aFromField) throws IllegalArgumentException ;


  /**
   * Set the mail date
   *
   * @param aDate - The mail date as a string
   */
  public void setDateField(String aDate) ;


  /**
   * Set the mail subject-field. No exception is thrown since
   * the subject field is allowed to be empty.
   *
   * @param aSubjectField - The mail subject-field
   */
  public void setSubjectField(String aSubjectField) ;



  /**
   * Set the mail Reply-to field. No exception is thrown 
   * since this field is allowed to be empty
   *
   * @param aReplyToField - The mail Reply-to field
   */
  public void setReplyToField(String aReplyToField) ;


  /**
   * Set the mail organization field. No exception is thrown 
   * since this field is allowed to be empty
   *
   * @param aOrganizationField The mail organization field
   */
  public void setOrganizationField(String aOrganizationField) ;


  /**
   * Set the mail content. No exception is thrown since
   * the mail body is allowed to be empty.
   *
   * @param aMailBody - The mail content
   */
  public void setMailBody(String aMailBody) ;


  /**
   * Set a Carbon-copy (cc:) address. This method could be
   * called repeatedly to store several cc: addresses.
   *
   * @param  aAddress The cc: mail address
   * @exception IllegalArgumentException  Is thrown if the parameter is null
   */
  public void setCCHeader(String aCopy) throws IllegalArgumentException ;


  /**
   * Set a X-something header. The method does no syntax checking
   * on the submitted header, because this class should not know
   * the format of any of it's fields. This method could be
   * called repeatedly to store several X-headers.
   *
   * @param  aXkey   The X-header name
   * @param  aXvalue The X-Header's value
   * @exception IllegalArgumentException  Is thrown if the parameter is null
   */
  public void setXHeader(String aXkey, 
			 String aXvalue) throws IllegalArgumentException ;


  
  // ------------------------- Get methods ------------------------ //

  /**
   * @return The mail message id
   */
  public String getIdField() ;


  /**
   * @return  Return the to field
   */
  public String getToField() ;


  /**
   * @return  Return the from field
   */
  public String getFromField() ;


  /**
   * @return The date as a String
   */
  public String getDateField() ;


  /**
   * @return  Return the subject field
   */
  public String getSubjectField() ;


  /**
   * @return  Return the reply-to field
   */
  public String getReplyToField() ;


  /**
   * @return  Return the organization field
   */
  public String getOrganizationField() ;


  /**
   * @return An enumeration of the Carbon-copy values
   */
  public Enumeration getCCHeaders() ;


  /**
   * @return An enumeration of the X-header keys
   */
  public Enumeration getXHeaderKeys() ;



  /**
   * @return The value for the given X-header key
   */
  public String getXHeaderValue(String aKey) ;



  /**
   * @return  Return the mail body 
   */
  public String getMailBody() ;



  // -------------------------------------------------------------- //

  /**
   * @return true if the mail has any cc headers
   */
  public boolean hasCCHeaders() ;


  /**
   * @return true if the mail has any X- headers
   */
  public boolean hasXHeaders() ;


  /**
   * This method validate the mail message fields. An exception is 
   * thrown if any of the required fields is empty. A warning is
   * printed if the subject-field or mail body are empty.
   *
   * @exception IllegalStateException Is thrown if invalid
   */
  public void validate() throws IllegalStateException ;


}

  

  

