jfmemailheader.java

java邮件源程序

/*
 * Created on 2004.08.18
 * JFreeMail - Java mail component
 * Copyright (C) 2004 Dalibor Krleza
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 
package org.jfreemail.core;

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.text.DateFormat;
import java.text.DateFormatSymbols;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Locale;
import java.util.Vector;

/**
 * Java bean class as E-mail header container. Used to store important
 * information about E-mail like sender, receiver, CC list, subject,
 * character sets, mime/type of E-mail etc...<br><br>
 * Downloading E-mail header from POP3 server as first step of E-mail 
 * download is smart thing do to. Although you download header more 
 * than once (twice to be accurate), in today's world of spam is much
 * better to download 50 headers and 2 mails than download all 50 mails
 * from POP3 server.<br><br>
 * E-mail header class is separated from JfmEmail class, so you can spare
 * your memory and read only E-mail headers. No need to reserve memory
 * for 50 JfmEmail Java beans, when you can cut this down to 50 
 * JfmEmailHeader Java beans.
 */
public class JfmEmailHeader {
	private String __return_addr=null;
	private String __from=null;
	private Vector __to=null;
	private Vector __cc=null;
	private String __subject=null;
	private String __subject_charset=null;
	private String __content_type=null;
	private String __content_charset=null;
	private String __content_type_delimiter=null;
	private Date __email_date=null;
	private int __msg_no=0;
	private String __msg_id=null;
	private int __header_length=0;
	
	/**
	 * <strong>Very important constant array</strong><br>
	 * List of all supported date/time format from E-mail clients. Most of the
	 * client are in EEE,dd MMM yyyy HH:mm:ss format, but there are some
	 * exceptions like Ximian Evolution... If you need or have spoted E-mail
	 * client that uses strange formats when sending E-mails you can add this
	 * format in this array. There could be issues regarding locale of date format.
	 * Default locale is ENGLISH. If you need another locale report this, I'll
	 * add locale support to this array!
	 */
	private final String[] format=new String[]{
						"EEE, dd MMM yyyy HH:mm:ss",
						"dd MMM yyyy HH:mm:ss"};
	
	/**
	 * Basic constructor for E-mail header. Not recommended for use if you
	 * are not familiar with E-mail format. To create E-mail, use static
	 * instantiators in JfmEmail class. For reading E-mails, use POP3
	 * class.
	 *
	 */
	public JfmEmailHeader()  {
		__return_addr=new String();
		__from=new String();
		__to=new Vector();
		__cc=new Vector();
		__subject=new String();
		__subject_charset=new String();
		__content_type=new String();
		__content_charset=new String(JfmConsts.DEFAULT_CHARSET);
		__content_type_delimiter=new String();
		__email_date=new Date();
		__msg_id=new String("N/D");
	}
	
	/**
	 * Getter for E-mail return address. Created and maintained by SMTP
	 * server. Used for E-mail replying to origin E-mail address.
	 * @return Origin E-mail address.
	 */
	public String getReturnAddr() {
		return __return_addr;
	}
	/**
	 * Setter for E-mail return address. Set this before calling reply method in
	 * JfmEmail class to change E-mail address of new receiver. Do not use
	 * this method if you are not familiar with E-mail format.
	 * @param addr Return E-mail address.
	 */
	public void setReturnAddr(String addr) {
		__return_addr=addr;
	}
	
	/**
	 * Getter for sender E-mail address.
	 * @return Sender E-mail address.
	 */
	public String getFrom() {
		return __from;
	}
	/**
	 * Setter for sender E-mail address. When sending E-mail here goes your
	 * own E-mail address. Do not use this method if you are not familiar with
	 * E-mail format.
	 * @param emailFrom Sender E-mail address.
	 */
	public void setFrom(String emailFrom) {
		__from=emailFrom;
	}

	/**
	 * Getter for receiver E-mail list count. You can send E-mail to more than
	 * one person. Therefore I constructed list of receivers.
	 * When reading incoming E-mail, most probably you'll find only one 
	 * - yours E-mail address.
	 * @return Number of receiving E-mail addresses.
	 */
	public int getToCount() {
		return __to.size();
	}
	/**
	 * Getter for receiver E-mail address. Using this method you can read one
	 * of many receiver E-mail addresses.
	 * @param index Index of receiver E-mail address.
	 * @return E-mail address.
	 * @throws CoreException Thrown on index exception.
	 */
	public String getTo(int index) throws CoreException {
		if (index<0 || index>=__to.size()) throw new CoreException("COR_003:E-mail receiver index out of range");
		return (String)__to.elementAt(index);
	}
	/**
	 * Setter method used to add receiver E-mail address on list.
	 * @param emailTo Receiver E-mail address.
	 */
	public void addTo(String emailTo) {
		__to.addElement(emailTo);
	}
	/**
	 * Method used to clear receiver E-mail list. This method clears
	 * all E-mail addresses from list.
	 *
	 */
	public void clearTo() {
		__to.clear();
	}

	/**
	 * Getter for CC E-mail addresses list count. CC list is allso
	 * list of receiver E-mail addresses, but is not deleted when reading
	 * and replying E-mail. This method returns number of E-mail addresses
	 * in CC list.
	 * @return Number of E-mail addresses in CC list.
	 */
	public int getCCCount() {
		return __cc.size();
	}
	/**
	 * Getter for reading E-mail address from CC list. You can read E-mail
	 * address with particular index.
	 * @param index Index of E-mail address in CC list.
	 * @return E-mail address from CC list.
	 * @throws CoreException Thrown on index exception.
	 */
	public String getCC(int index) throws CoreException {
		if (index<0 || index>=__cc.size()) throw new CoreException("COR_003:E-mail CC index out of range");
		return (String)__cc.elementAt(index);
	}
	/**
	 * Setter for adding receiver E-mail address onto CC list.
	 * @param cc Receiver E-mail address.
	 */
	public void addCC(String cc) {
		__cc.addElement(cc);
	}
	/**
	 * Method used to clear all E-mail addresses from CC list.
	 *
	 */
	public void clearCC() {
		__cc.clear();
	}
	
	/**
	 * Getter for E-mail subject.
	 * @return E-mail subject.
	 */
	public String getSubject() {
		return __subject;
	}
	/**
	 * Setter for E-mail subject. String used to set subject must be in particular
	 * characterset. See getSubjectCharset and setSubjectCharset.
	 * @param subject E-mail subject.
	 */
	public void setSubject(String subject) {
		__subject=subject;
	}
	
	/**
	 * Getter for E-mail subject characterset.
	 * @return E-mail subject characterset.
	 */
	public String getSubjectCharset() {
		return __subject_charset;
	}
	/**
	 * Setter for E-mail subject characterset. When setting E-mail subject
	 * manually, you must set this character set either. E-mail subject
	 * must be encoded regarding this characterset!
	 * @param charset E-mail subject characetset.
	 */
	public void setSubjectCharset(String charset) {
		__subject_charset=charset;
	}
	
	/**
	 * Getter for E-mail content type. Here you can read general mime/type
	 * of E-mail. Typically you can read following mime/types:<br>
	 * multipart/mixed<br>
	 * plain/text<br>
	 * plain/html<br>
	 * When multipart mime/type, E-mail will contain more than one part. Parsing
	 * is adjusted for multi parts. Any other represents single part E-mail with
	 * exactly this mime/type.
	 * @return E-mail content type.
	 */
	public String getContentType() {
		return __content_type;
	}
	/**
	 * Setter for E-mail content type. Here you can set general mime/type
	 * of E-mail. Do not use this method if you are not familiar with E-mail
	 * format. Rather use static creators in JfmEmail class.
	 * @param contentType E-mail content type.
	 */
	public void setContentType(String contentType) {
		__content_type=contentType;
	}
	
	/**
	 * Getter for E-mail content charset. This value is set only when parsing
	 * E-mail with single part, otherwise filled with default character set.
	 * If this single part is text type, here you can read characterset of this 
	 * type. Character set could be read from E-mail part.
	 * @return E-mail characterset.
	 */
	public String getContentCharset() {
		return __content_charset;
	}
	/**
	 * Setter for E-mail content charset. This value should be set only when
	 * sending E-mail containing only one text part. Here you can set
	 * characterset of this part. <strong>Warning:</strong> When sending
	 * E-mail with exactly one text part, you need to set this value. From
	 * this value is created new E-mail header, not from characterset in
	 * JfmEmailTextPart.<br><br>
	 * Do not use this method if you are not familiar with E-mail format.
	 * @param contentCharset Characterset of single text part.
	 */
	public void setContentCharset(String contentCharset) {
		__content_charset=contentCharset;
	}
	
	/**
	 * Getter for part delimiter. Used only when parsing multipart incoming
	 * E-mail. This value is not important and doesn't bring any useful 
	 * information.
	 * @return E-mail part delimiter.
	 */
	public String getContentTypeDelimiter() {
		return __content_type_delimiter;
	}
	/**
	 * Setter for E-mail part delimiter. Doesn't affect this component at all.
	 * When sending E-mail, delimiter is calculated on creating new E-mail.
	 * This method is used internally for storing E-mail part delimiter when
	 * parsing incoming E-mail. 
	 * @param contentTypeDelimiter E-mail part delimiter. 
	 */
	public void setContentTypeDelimiter(String contentTypeDelimiter) {
		__content_type_delimiter=contentTypeDelimiter;
	}
	
	/**
	 * Getter for E-mail creation time.
	 * @return E-mail creation time.
	 */
	public Date getEmailDate() {
		return __email_date;
	}
	/**
	 * Getter for E-mail creation time in string form.
	 * @return E-mail creation time.
	 */
	public String getEmailDateStr() {
		SimpleDateFormat sdf=new SimpleDateFormat(format[0],Locale.ENGLISH);
		return sdf.format(__email_date);
	}
	/**
	 * Setter for E-mail creation time.
	 * @param email_date E-mail creation time.
	 */
	public void setEmailDate(Date email_date) {
		__email_date=email_date;
	}
	/**
	 * Setter for E-mail creation time. Time is created from input string. This
	 * setter is used when parsing incoming E-mail. E-mail date/time formats
	 * are mostly the same and depend on E-mail client. For more details
	 * on date format look array in this document.
	 * @param email_date E-mail creation time in string form.
	 * @throws CoreException Thrown on date/time parsing exception.
	 */
	public void setEmailDateStr(String email_date) throws CoreException {
		boolean decoded=false;
		for(int i=0;(i<format.length && !decoded);i++) {
			SimpleDateFormat sdf=new SimpleDateFormat(format[i],Locale.ENGLISH); 
			try {
				__email_date=sdf.parse(email_date);
				decoded=true;
			} catch(Exception exc) {
			}
		}
		if (!decoded) throw new CoreException("COR_008:Unsupported E-mail date format");
	}
	
	/**
	 * Getter for E-mail index number. When retrieving E-mail headers from
	 * POP3 server, headers are ascending indexed. Every header has it's
	 * own index. POP3 recognizes E-mail by this index. This information is
	 * useful only when performing manuall retrieving from POP3 server. In
	 * all other cases this is only internal information. 
	 * @return E-mail index.
	 */
	public int getMsgNo() {
		return __msg_no;
	}
	/**
	 * Setter for E-mail index number. Do not set this number on incoming
	 * E-mail. When sending E-mail, this number is ignored. 
	 * @param msg_no E-mail POP3 index.
	 */
	public void setMsgNo(int msg_no) {
		__msg_no=msg_no;
	}
	
	/**
	 * Getter for E-mail unique identification. Identification available only on
	 * incoming E-mails. This number uniquely identifies E-mail.
	 * @return E-mail identification.
	 */
	public String getMsgId() {
		return __msg_id;
	}
	/**
	 * Setter for E-mail unique identification. Do not set this number on incoming
	 * E-mail. When sending E-mail, this information is ignored.
	 * @param id E-mail identification.
	 */
	public void setMsgId(String id) {
		__msg_id=id;
	}
	
	/**
	 * Getter for E-mail header length. Length is expressed in lines. Every
	 * line ends with CRLF chars. Used when reading complete E-mail from
	 * POP3 server, otherwise not very useful.
	 * @return E-mail header length.
	 */
	public int getHeaderLength() {
		return __header_length;
	}
	/**
	 * Setter for E-mail header length. Do not set this number on incoming
	 * E-mail. When sending E-mail, this number is ignored.
	 * @param header_length E-mail header length.
	 */
	public void setHeaderLength(int header_length) {
		__header_length=header_length;
	}
}