package jp.sourceforge.mailagent;

import java.io.File;
import java.util.Map;
import org.apache.velocity.Template;


/**
 * メールエージェントインターフェース.
 * <br>メール作成・送信を行う。<br><br>
 * MailAgentBuilder より、インスタンスを生成して実行する。<br>
 * 送信を実行する前に、TO設定、CC設定、等を行う。
 * <pre>
 * 【使用例】
 * // MailAgentBuilderの為に、メール送信ＳＭＴＰ設定とテンプレート読み出し先設定を行う
 *
 * // メール送信ＳＭＴＰ設定
 * MailConfig mailConfig = new MailConfig();
 * mailConfig.setSmtphost("127.0.0.1");
 * mailConfig.setSmtpauth(false);
 * mailConfig.setEncode("Shift_JIS");
 * // テンプレート読み出し先設定
 * TemplateConfig templateConfig = new TemplateConfig();
 * templateConfig.setTemplateLoadpath(templateLoadpath);
 * templateConfig.setTemplateInEncode("Windows-31J");
 * templateConfig.setTemplateOutEncode("Windows-31J");
 *
 * // ビルダ生成
 * MailAgentBuilder mbuilder = new MailAgentBuilder(mailConfig,templateConfig);
 *
 * // テンプレートファイル名を指定して、MailAgent生成
 * MailAgent mailAgent = mbuilder.create("sample.vm");
 *
 * mailAgent.setFROM("uran@test.com");  // 送信者指定
 *
 * mailAgent.setTO("hoge@radish.com");  // 宛先（エイリアス付）
 *
 * mailAgent.setSubject("テスト");
 *
 * Map map = new HashMap();     // メールテンプレートとマージするＭａｐ
 * map.put("url","http://jakarta.apache.org/commons/");
 *
 * // メールテンプレートを使用してメール本文をセット
 * mailAgent.setBody(map);　
 *
 * mailAgent.post();    // メール送信
 *
 * </pre>
 */
public interface MailAgent{
   /**
    * メール送信.
    * <br>作成したメールの送信<br>
    * 内部でスレッド生成してスレッドで送信するために、送信結果は参照できない。
    * 送信結果を待つことなく戻ってくる。
    */
   public void post();

   /**
    * メール送信（結果参照）.
    * <br>作成したメールの送信<br>
    * メールの送信結果を参照できる。void send()と異なり送信終了まで待つ。
    * @return ResultMail＝メール送信結果
    */
   public ResultMail send();

   /**
    * TO：設定.
    * <br>送信実行するまでの間、callした分、TO:に設定される。
    * @param toary メール宛先TOを配列で指定
    */
   public void setTO(String[] toary);

   /**
    *  TO：設定（エイリアス指定）.
    * <br>複数宛先とエイリアス有り宛先を混在させる場合、本メソッドを実行する。<br>
    * パラメータのMapは、必ずしもvalue＝エイリアスを渡す必要がなく、
    * エイリアスが存在しない場合、key＝メールアドレスだけMapに格納して渡す、<br>
    * 即ち、エイリアス有り／無しを混在させることができる。
    * <br>送信実行するまでの間、callした分、TO:に設定される。
    * @param tomap key=メールアドレス、value=キーで指定したアドレスのエイリアス
    */
   public void setTO(Map<String,String> tomap);

   //==================================================================

   /**
    * CC：設定.
    * <br>送信実行するまでの間、callした分、CC:に設定される。
    * @param ccary メール宛先CCを配列で指定
    */
   public void setCC(String[] ccary);

   /**
    * CC：設定（エイリアス指定）.
    * <br>複数宛先とエイリアス有り宛先を混在させる場合、本メソッドを実行する。<br>
    * パラメータのMapは、必ずしもvalue＝エイリアスを渡す必要がなく、
    * エイリアスが存在しない場合、key＝メールアドレスだけMapに格納して渡す、<br>
    * 即ち、エイリアス有り／無しを混在させることができる。
    * <br>送信実行するまでの間、callした分、CC:に設定される。
    * @param ccmap key=メールアドレス、value=キーで指定したアドレスのエイリアス
    */
   public void setCC(Map<String,String> ccmap);

   //==================================================================

   /**
    * BCC：設定.
    * <br>送信実行するまでの間、callした分、BCC:に設定される。
    * @param bccary メール宛先BCCを配列で指定
    */
   public void setBCC(String[] bccary);

   /**
    * BCC：設定（エイリアス指定）.
    * <br>複数宛先とエイリアス有り宛先を混在させる場合、本メソッドを実行する。<br>
    * パラメータのMapは、必ずしもvalue＝エイリアスを渡す必要がなく、
    * エイリアスが存在しない場合、key＝メールアドレスだけMapに格納して渡す、<br>
    * 即ち、エイリアス有り／無しを混在させることができる。
    * <br>送信実行するまでの間、callした分、BCC:に設定される。
    * @param bccmap key=メールアドレス、value=キーで指定したアドレスのエイリアス
    */
   public void setBCC(Map<String,String> bccmap);

   //==================================================================
   /**
    * 送信者アドレス設定.
    * <br>本メソッドは宛先設定と異なり最後に実行されたものが有効値になる
    * @param from メール送信者メールアドレス設定
    */
   public void setFROM(String from);

   /**
    * 送信者アドレス＆エイリアス設定.
    * <br>本メソッドは宛先設定と異なり最後に実行されたものが有効値になる
    * @param from メール送信者メールアドレス設定
    */
   public void setFROM(String from,String alias);

   /**
    * 返信先アドレス設定.
    * @param replyTo 返信先アドレス
    */
   public void setReplyTo(String replyTo);

   /**
    * セットされた宛先、TO,CC,BCCをクリアする。
    */
   public void clearTo();

   /**
    * メール送信の為の宛先、送信者、メッセージ、全てをクリアする。
    */
   public void clearAll();

   /**
    * メール件名セット.
    * @param subject メール件名
    */
   public void setSubject(String subject);

   /**
    * メール本文セット（テンプレート有り）.
    * @param templateName メール本文テンプレート(*.vm)のファイルパス
    * @param map テンプレートに埋め込むデータ
    */
   public void setBody(Map<String,Object> map);

   /**
    * メール本文セット（テンプレートなし）.
    * @param body メール本文
    */
   public void setBody(String body);

   /**
    * 添付ファイルセット.
    * @param temps 添付File配列
    */
   public void setTempFiles(File... temps);

   /**
    * メール本文参照.
    * @return テンプレートで作成されたメール本文文字列を参照
    */
   public String getMessage();

   /**
    * メール設定.
    * 使用するSMTP情報を設定する。
    * MailAgentBuilderコンストラクタでSMTP情報を設定するのでMailAgent生成後は再設定として
    * 呼び出すべきでないが、特殊ケースで再設定できるようにするためにこのメソッドが存在する。
    * @param config SMTP情報
    */
   public void setMailConfig(MailConfig config);

   /**
    * テンプレート設定
    * @param template Velocity Template を指定
    */
   public void setTemplate(Template template);

}
