/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cocoon.mail;

import javax.mail.MessagingException;
import javax.mail.internet.AddressException;

import org.apache.cocoon.environment.SourceResolver;

/**
 * A helper component used by the {@link org.apache.cocoon.acting.Sendmail}
 * action and the <code>sendmail.xsl</code> logicsheet for sending email messages.
 *
 * <p>Please note that this component is not (and can not) be
 * {@link org.apache.avalon.framework.thread.ThreadSafe}, so you need to lookup
 * new instance in each processing thread.
 *
 * @since 2.1.5
 * @version $Id$
 */
public interface MailSender {

    String ROLE = MailSender.class.getName();

    //
    // Configure Component
    //

    /**
     * Set SMTP hostname to use for mail sending.
     */
    void setSmtpHost(String hostname);

    /**
     * Set SMTP hostname, username, and password to use for mail sending.
     */
    void setSmtpHost(String hostname, String username, String password);

    //
    // Compose Message
    //

    /**
     * Set the <code>from</code> address of the message.
     *
     * @param from The address the message appears to be from.
     */
    void setFrom(String from);

    /**
     * Sets the destination address(es) for the message. The address
     * is in the format, that
     * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
     * (one or more email addresses separated by a commas).
     *
     * @param to the destination address(es)
     * @see javax.mail.internet.InternetAddress#parse(String)
     */
    void setTo(String to);

    /**
     * Sets the reply-to address(es) for the message. The address
     * is in the format, that
     * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
     * (one or more email addresses separated by a commas).
     *
     * @param replyTo the address(es) that replies should be sent to
     * @see javax.mail.internet.InternetAddress#parse(String)
     */
    void setReplyTo(String replyTo);

    /**
     * Sets the address(es), which should receive a carbon copy of the
     * message. The address is in the format, that
     * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
     * (one or more email addresses separated by a commas).
     *
     * @param cc the address(es), which should receive a carbon copy.
     * @see javax.mail.internet.InternetAddress#parse(String)
     */
    void setCc(String cc);

    /**
     * Sets the address(es), which should receive a black carbon copy of
     * the message. The address is in the format, that
     * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
     * (one or more email addresses separated by a commas).
     *
     * @param bcc the address(es), which should receive a black carbon copy.
     * @see javax.mail.internet.InternetAddress#parse(String)
     */
    void setBcc(String bcc);

    /**
     * Sets the subject line of the message.
     * @param subject the subject line of the message
     */
    void setSubject(String subject);

    //
    // Set the Body
    //

    /**
     * Sets the character set for encoding the message. This has effect
     * only on text set via {@link #setBody(String)}.
     *
     * @param charset the character set to be used for encoding the message
     * @deprecated Since 2.1.10. Use {@link #setBody(Object, String)}
     */
    void setCharset(String charset);

    /**
     * Sets the body text of the email message.
     * If both a text body and a body read from a source are set,
     * only the latter will be used.
     *
     * @param body The body text of the email message
     * @deprecated Since 2.1.10. Use {@link #setBody(Object)}
     */
    void setBody(String body);

    /**
     * Sets the body source URL of the email message.
     * If both a text body and a body read from a source are set,
     * only the latter will be used.
     *
     * @param src The body source URL of the email message
     * @deprecated Since 2.1.10. Use {@link #setBodyURL(String)}
     */
    void setBodyFromSrc(String src);

    /**
     * Sets the optional body source Mime Type of the email message.
     *
     * @param srcMimeType The optional body source Mime Type of the email message
     * @deprecated Since 2.1.10. Use {@link #setBodyURL(String, String)}
     */
    void setBodyFromSrcMimeType(String srcMimeType);

    /**
     * Sets the body content of the email message.
     *
     * <p>The body can be any of: {@link org.apache.excalibur.source.Source},
     * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
     * <code>byte[]</code>, {@link String}, or a subclass.
     *
     * @param body The body text of the email message
     */
    void setBody(Object body);

    /**
     * Sets the body content of the email message.
     *
     * <p>The body can be any of: {@link org.apache.excalibur.source.Source},
     * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
     * <code>byte[]</code>, {@link String}, or a subclass.
     *
     * @param body The body text of the email message
     * @param type mime type (optional)
     */
    void setBody(Object body, String type);

    /**
     * Sets the body content of the email message.
     *
     * @param url URL to use as message body
     * @see org.apache.excalibur.source.Source
     */
    void setBodyURL(String url);

    /**
     * Sets the body content of the email message.
     *
     * @param url URL to use as message body
     * @param type mime type (optional)
     * @see org.apache.excalibur.source.Source
     */
    void setBodyURL(String url, String type);

    //
    // Add Attachments
    //

    /**
     * Add an attachement to the message to be send.
     *
     * <p>The attachment can be any of: {@link org.apache.excalibur.source.Source},
     * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
     * <code>byte[]</code>, {@link String}, or a subclass.
     *
     * @param attachment to be send with the message
     */
    void addAttachment(Object attachment);

    /**
     * Add an attachement to the message to be send.
     *
     * <p>The attachment can be any of: {@link org.apache.excalibur.source.Source},
     * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
     * <code>byte[]</code>, {@link String}, or a subclass.
     *
     * @param attachment to be send with the message
     * @param type mime type (optional)
     * @param name attachment name (optional)
     */
    void addAttachment(Object attachment, String type, String name);

    /**
     * Add an attachement to the message to be send.
     *
     * @param url URL to attach to the message
     * @see org.apache.excalibur.source.Source
     */
    void addAttachmentURL(String url);

    /**
     * Add an attachement to the message to be send.
     *
     * @param url URL to attach to the message
     * @param type mime type (optional)
     * @param name attachment name (optional)
     * @see org.apache.excalibur.source.Source
     */
    void addAttachmentURL(String url, String type, String name);

    //
    // Send Message
    //

    /**
     * Assemble the message from the defined fields and send it. The source resolver
     * is obtained from the hosting component container.
     * @throws AddressException when problems with email addresses are found
     * @throws MessagingException when message could not be send.
     */
    void send()
    throws AddressException, MessagingException;

    /**
     * Assemble the message from the defined fields and send it.
     * @throws AddressException when problems with email addresses are found
     * @throws MessagingException when message could not be send.
     * @deprecated Since 2.1.5. Use {@link #send()} which doesn't require passing the source resolver
     */
    void send(SourceResolver resolver)
    throws AddressException, MessagingException;

    /**
     * Invokes the {@link #send()} method but catches any exception thrown. This
     * method is intended to be used from the sendmail logicsheet. The source
     * resolver is obtained from the hosting component container.
     * @return true when successful
     */
    boolean sendIt();

    /**
     * Invokes the {@link #send(SourceResolver)} method but catches any exception thrown.
     * This method is intended to be used from the sendmail logicsheet.
     * @return true when successful
     * @deprecated Since 2.1.5. Use {@link #sendIt()} which doesn't require passing the source resolver
     */
    boolean sendIt(SourceResolver resolver);

    /**
     * Accesses any Exception caught by {@link #sendIt(SourceResolver)}.
     * @return AddressException or MessagingException
     */
    Exception getException();
}