/*
 * blanco Framework
 * Copyright (C) 2004-2007 IGA Tosiki
 * 
 * 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.
 */
package blanco.mail.core;

import java.io.IOException;
import java.net.ConnectException;

import blanco.mail.core.valueobject.BlancoMailMessage;
import blanco.mail.core.valueobject.BlancoMailSetting;
import blanco.mail.core.valueobject.BlancoMailStatistics;

/**
 * メール受信インタフェース。
 * 
 * blancoMailCoreのメール受信のインタフェース仕様を示します。
 * クラス実装を取得するためには、BlancoMailReceiverFactory#getInstance を利用します。
 * 
 * @author IGA Tosiki
 */
public interface BlancoMailReceiver {
    /**
     * メールサーバから、最初のメールメッセージを受信します。
     * 
     * 受信したメールは メールサーバから削除されます。
     * 
     * @param argSetting
     *            blancoMailの各種設定情報をあらわすバリューオブジェクト。サーバ接続設定や送受信時のデフォルト値などが格納されます。(注意)このクラスのインスタンスは
     *            BlancoMailSettingFactory クラスから取得してください。
     * @return 受信したメール本体をあらわすバリューオブジェクト。このオブジェクトにメールの本文や宛先などの情報が入ります。１件もメールを受信しなかった場合には
     *         null が戻ります。
     * @throws ConnectException
     *             メールサーバへの接続失敗に関する例外。
     * @throws IOException
     *             メールデータの受信失敗に関する例外。
     */
    BlancoMailMessage receive(final BlancoMailSetting argSetting)
            throws ConnectException, IOException;

    /**
     * 統計情報取得のためのバリューオブジェクトをセットします。
     * 
     * @param argStatistics
     *            統計情報。
     */
    void setStatistics(final BlancoMailStatistics argStatistics);

    /**
     * 統計情報取得のためのバリューオブジェクトをゲットします。
     * 
     * @return 統計情報。
     */
    BlancoMailStatistics getStatistics();
}