/**
 * A simple representation of the headers of messages.  Rather than using a
 * setXXX and getXXX for each expected field (which limits the client to
 * prespecified fields), this class lets you set or get as many fields as
 * you'd like.  You can determine the names of the standard fields by looking at
 * standardFields and the names of the fields set in the current message
 * from activeFields.  Typically, headers will be created empty, and then filled
 * in with a lot of calls to setXXX or a call to parseHeader.
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of October 1999
 */
public interface MessageHeader {
  // +------------+----------------------------------------------
  // | Extractors |
  // +------------+
  
  /**
   * Get a list of the names of fields that are used by the current message.
   */
  public String[] activeFields();
  
  /**
   * Extract one field from the header.  
   * @exception FieldException
   *   If the field is not defined.
   */
  public String getField(String fieldName)
    throws Exception;
  
  /**
   * Get a list of the names of fields that are used by most messages.
   */
  public String[] standardFields();
  
  /** 
   * Convert the header to a printable string, useful for
   * printing or saving to a file.
   */
  public String toString();
  
  /**
   * Convert a selected set of fields to a printable string,
   * useful for printing or saving to a file.  If a field
   * is not defined, it is treated as the empty string.
   */
  public String toString(String[] fieldNames);
  
  
  // +-----------+-----------------------------------------------
  // | Modifiers |
  // +-----------+
  
  /**
   * Clear the header.  Afterwards, there are no fields with values in
   * the header.
   */
  public void clear();
  
  /**
   * Parse a header created by toString() or in the standard Internet
   * email format.  Fill in all the fields specified in that header.
   * If a field had a previous value and was not specified in the header,
   * it retains its value.  If a field had a previous value and is specified
   * in the header, it takes on the new value.  If a field did not have a
   * previous value and is specified in the header, it takes on that value.
   */
  public void parse(String head);
  
  /**
   * Restrict the header to a particular set of fields.  All other fields
   * are "deleted", marked as unused.  If we restrict the header to a particular
   * field, and that field is not set, it gets set to the empty string.
   */
  public void restrict(String[] fieldNames);
  
  /**
   * Set one field of the header.  Returns the old value of the field.
   * Returns null if the field was not previously set.
   */
  public String setField(String fieldName, String fieldValue);

} // interface MessageHeader