| /* |
| * 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(); |
| } |