java/src/main/com/google/appengine/api/mail/MailService.java

   1 // Copyright 2008 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.mail;
   4
   5 import java.io.IOException;
   6 import java.util.Arrays;
   7 import java.util.Collection;
   8
   9 /**
  10  * The {@code MailService} provides a way for user code to send emails
  11  * to arbitrary destinations.
  12  *
  13  */
  14 public interface MailService {
  15
  16   public class Attachment {
  17     private final String fileName;
  18     private final byte[] data;
  19     private final String contentID;
  20
  21     /**
  22      * Attachments are an optional part of messages, but if present, all
  23      * information about them must be provided.
  24      *
  25      * @param fileName The attachment must have a filename associated with it.
  26      * The extension on that filename must be present and white-listed, or
  27      * there will be a failure at send time.
  28      *
  29      * @param data An array with arbitrary byte content. The array must be
  30      * be present, but may be of zero length.
  31      *
  32      * @throws IllegalArgumentException if either fileName or data are missing.
  33      */
  34     public Attachment (String fileName, byte[] data) {
  35       this(fileName, data, null);
  36     }
  37
  38      /**
  39      * Attachments are an optional part of messages, but if present, all
  40      * information about them must be provided.
  41      *
  42      * @param fileName The attachment must have a filename associated with it.
  43      * The extension on that filename must be present and white-listed, or
  44      * there will be a failure at send time.
  45      *
  46      * @param data An array with arbitrary byte content. The array must be
  47      * be present, but may be of zero length.
  48      *
  49      * @param contentID The attachment's content ID. May be null.
  50      *
  51      * @throws IllegalArgumentException if either fileName or data are missing.
  52      */
  53     public Attachment(String fileName, byte[] data, String contentID) {
  54       if (data == null || fileName == null || fileName.length() == 0) {
  55         throw new IllegalArgumentException("Attachment needs content and name");
  56       }
  57       this.fileName = fileName;
  58       this.data = data;
  59       this.contentID = contentID;
  60     }
  61
  62     /**
  63      * Gets the file name of this attachment.
  64      *
  65      * @return The file name of this attachment.
  66      */
  67     public String getFileName() {
  68       return fileName;
  69     }
  70
  71     /**
  72      * Gets the content of this attachment.
  73      *
  74      * @return The raw data of this attachment.
  75      */
  76     public byte[] getData() {
  77       return data;
  78     }
  79
  80     public String getContentID() {
  81       return contentID;
  82     }
  83   }
  84
  85   public class Header {
  86     private final String name;
  87     private final String value;
  88
  89     /**
  90      * Headers are an optional part of messages, but if present, all
  91      * information about them must be provided.
  92      *
  93      * @param name The name of the header. It must be present and white-listed.
  94      *
  95      * @param value The value of the header. It must be present, and it's
  96      * content cannot be of zero length.
  97      *
  98      * @throws IllegalArgumentException if either name or data are missing.
  99      */
 100     public Header(String name, String value) {
 101       if (name == null || value == null ||
 102           name.length() == 0 || value.length() == 0) {
 103         throw new IllegalArgumentException("Header needs name and value");
 104       }
 105       this.name = name;
 106       this.value = value;
 107     }
 108
 109     /**
 110      * Gets the name of this header.
 111      *
 112      * @return The name of this header.
 113      */
 114     public String getName() {
 115       return name;
 116     }
 117
 118     /**
 119      * Gets the value of this header.
 120      *
 121      * @return The value of this header.
 122      */
 123     public String getValue() {
 124       return value;
 125     }
 126   }
 127
 128   /**
 129    * Messages are prepared by the caller, and then submitted to the Mail service
 130    * for sending. Different fields are subject to different constraints, as
 131    * enumerated in the {@code send} and {@code sendToAdmins} methods.
 132    */
 133   public class Message {
 134     private String sender;
 135     private String replyTo;
 136     private Collection<String> to;
 137     private Collection<String> cc;
 138     private Collection<String> bcc;
 139     private String subject;
 140     private String textBody;
 141     private String htmlBody;
 142     private Collection<MailService.Attachment> attachments;
 143     private Collection<MailService.Header> headers;
 144
 145     public Message() {}
 146
 147     /**
 148      * Convenience constructor for simple messages
 149      * @param sender The sender's email address.
 150      * @param to The recipient's email address or null for empty to address.
 151      * @param subject The message subject.
 152      * @param textBody The text body of the message.
 153      */
 154     public Message(String sender, String to, String subject, String textBody) {
 155       this.sender = sender;
 156       if (to == null) {
 157         this.to = Arrays.asList();
 158       } else {
 159         this.to = Arrays.asList(to);
 160       }
 161       this.subject = subject;
 162       this.textBody = textBody;
 163     }
 164
 165     /**
 166      * Gets the sender of this message.
 167      *
 168      * @return The sender of this message.
 169      */
 170     public String getSender() {
 171       return sender;
 172     }
 173
 174     /**
 175      * {@code sender} must correspond to the valid email address of one of
 176      * the admins for this application, or to the email address of the
 177      * currently logged-in user. Sender is really the From: field of the email.
 178      */
 179     public void setSender(String sender) {
 180       this.sender = sender;
 181     }
 182
 183     /**
 184      * Gets the reply to field of this message.
 185      *
 186      * @return The reply to field of this message.
 187      */
 188     public String getReplyTo() {
 189       return replyTo;
 190     }
 191
 192     /**
 193      * {@code replyTo} may be {@code null}, or must be a valid email
 194      * address otherwise.
 195      */
 196     public void setReplyTo(String replyTo) {
 197       this.replyTo = replyTo;
 198     }
 199
 200     /**
 201      * Gets the recipients in the 'to' field of this message.
 202      *
 203      * @return A collection containing the 'to' field recipients.
 204      */
 205     public Collection<String> getTo() {
 206       return to;
 207     }
 208
 209     /**
 210      * Sets the 'to' field of this message. Each string in the collection
 211      * represents exactly one email address. Having null (or invalid addresses)
 212      * will lead to eventual failure during the send process.
 213      * @param to A collection containing the email addresses to set as the 'to'
 214      * field.
 215      */
 216     public void setTo(Collection<String> to) {
 217       this.to = to;
 218     }
 219
 220     /**
 221      * Sets the 'to' field of this message. Each string represents exactly one
 222      * email address. Having null (or invalid addresses) will lead to eventual
 223      * failure during the send process.
 224      *
 225      * @param to The email addresses to set as the 'to' field.
 226      */
 227     public void setTo(String... to) {
 228       this.to = Arrays.asList(to);
 229     }
 230
 231     /**
 232      * Gets the recipients in the 'cc' field of this message.
 233      *
 234      * @return A collection containing the 'cc' field recipients.
 235      */
 236     public Collection<String> getCc() {
 237       return cc;
 238     }
 239
 240     /**
 241      * Sets the 'cc' field of this message. Each string in the collection
 242      * represents exactly one email address. Having null (or invalid addresses)
 243      * will lead cc eventual failure during the send process.
 244      * @param cc A collection containing the email addresses cc set as the 'cc'
 245      * field.
 246      */
 247     public void setCc(Collection<String> cc) {
 248       this.cc = cc;
 249     }
 250
 251     /**
 252      * Sets the 'cc' field of this message. Each string represents exactly one
 253      * email address. Having null (or invalid addresses) will lead cc eventual
 254      * failure during the send process.
 255      *
 256      * @param cc The email addresses cc set as the 'cc' field.
 257      */
 258     public void setCc(String... cc) {
 259       this.cc = Arrays.asList(cc);
 260     }
 261
 262     /**
 263      * Gets the recipients in the 'bcc' field of this message.
 264      *
 265      * @return A collection containing the 'bcc' field recipients.
 266      */
 267     public Collection<String> getBcc() {
 268       return bcc;
 269     }
 270
 271     /**
 272      * Sets the 'bcc' field of this message. Each string in the collection
 273      * represents exactly one email address. Having null (or invalid addresses)
 274      * will lead bcc eventual failure during the send process.
 275      * @param bcc A collection containing the email addresses bcc set as the
 276      * 'bcc' field.
 277      */
 278     public void setBcc(Collection<String> bcc) {
 279       this.bcc = bcc;
 280     }
 281
 282     /**
 283      * Sets the 'bcc' field of this message. Each string represents exactly one
 284      * email address. Having null (or invalid addresses) will lead bcc eventual
 285      * failure during the send process.
 286      *
 287      * @param bcc The email addresses bcc set as the 'bcc' field.
 288      */
 289     public void setBcc(String... bcc) {
 290       this.bcc = Arrays.asList(bcc);
 291     }
 292
 293     /**
 294      * Gets the subject of this message.
 295      *
 296      * @return The subject of this message.
 297      */
 298     public String getSubject() {
 299       return subject;
 300     }
 301
 302     /**
 303      * Sets the subject of this message. A null or empty subject will lead to
 304      * eventual failure during the send process.
 305      *
 306      * @param subject A string containing the new subject of this message.
 307      */
 308     public void setSubject(String subject) {
 309       this.subject = subject;
 310     }
 311
 312     /**
 313      * Gets the text body of this message.
 314      *
 315      * @return The text body.
 316      */
 317     public String getTextBody() {
 318       return textBody;
 319     }
 320
 321     /**
 322      * Sets the text body of this message. At least one of {@code textBody} and
 323      * {@code htmlBody} must not be {@code null}.
 324      * @param textBody A string containing the new text body of this message.
 325      */
 326     public void setTextBody(String textBody) {
 327       this.textBody = textBody;
 328     }
 329
 330     /**
 331      * Gets the html body of this message.
 332      *
 333      * @return The html body.
 334      */
 335     public String getHtmlBody() {
 336       return htmlBody;
 337     }
 338
 339     /**
 340      * Sets the html body of this message. At least one of {@code textBody} and
 341      * {@code htmlBody} must not be {@code null}.
 342      * @param htmlBody A string containing the new text body of this message.
 343      */
 344     public void setHtmlBody(String htmlBody) {
 345       this.htmlBody = htmlBody;
 346     }
 347
 348     /**
 349      * Gets the attachments of this message.
 350      *
 351      * @return A collection containing the attachments of this message.
 352      */
 353     public Collection<MailService.Attachment> getAttachments() {
 354       return attachments;
 355     }
 356
 357     /**
 358      * Sets the attachments of this message. {@code attachments} may be
 359      * {@code null}, otherwise each attachment must have a corresponding file
 360      * name with one of the white-listed extensions.
 361      * @param attachments A collection of attachments.
 362      */
 363     public void setAttachments(Collection<MailService.Attachment> attachments) {
 364       this.attachments = attachments;
 365     }
 366
 367     /**
 368      * Sets the attachments of this message. {@code attachments} may be
 369      * {@code null}, otherwise each attachment must have a corresponding file
 370      * name with one of the white-listed extensions.
 371      * @param attachments Attachments to attach to this message.
 372      */
 373     public void setAttachments(MailService.Attachment... attachments) {
 374       this.attachments = Arrays.asList(attachments);
 375     }
 376
 377     /**
 378      * Gets the headers of this message.
 379      *
 380      * @return A collection containing the headers of this message.
 381      */
 382     public Collection<MailService.Header> getHeaders() {
 383       return headers;
 384     }
 385
 386     /**
 387      * Sets the headers of this message. {@code headers} may be {@code null},
 388      * otherwise each header name must be one of the white-listed names.
 389      * @param headers A collection of headers.
 390      */
 391     public void setHeaders(Collection<MailService.Header> headers) {
 392       this.headers = headers;
 393     }
 394
 395     /**
 396      * Sets the headers of this message. {@code headers} may be {@code null},
 397      * otherwise each header name must be one of the white-listed names.
 398      * @param headers A collection of headers.
 399      */
 400     public void setHeaders(MailService.Header... headers) {
 401       this.headers = Arrays.asList(headers);
 402     }
 403   }
 404
 405   /**
 406    * Sends a mail that has been prepared in a MailService.Message.
 407    * <p>
 408    * The message will be delivered asynchronously, and delivery problems
 409    * will result in a bounce to the specified sender.
 410    * <p>
 411    * {@code Sender} and at least one of the collections for {@code to, cc, bcc}
 412    * must not be {@code null}.
 413    *
 414    * @param message The message to be sent.
 415    * @throws IllegalArgumentException when incorrect arguments are passed.
 416    * @throws IOException on internal delivery errors.
 417    */
 418   public void send(MailService.Message message) throws IOException;
 419
 420   /**
 421    * Send an email alert to all admins of an application.
 422    * <p>
 423    * The message will be delivered asynchronously, and delivery problems
 424    * will result in a bounce to the admins.
 425    * <p>
 426    * The content of the {@code to, cc, bcc} fields should be {@code
 427    * null}.
 428    *
 429    * @param message The message to be sent.
 430    * @throws IllegalArgumentException when incorrect arguments are passed.
 431    * @throws IOException on internal delivery errors.
 432    */
 433   public void sendToAdmins(MailService.Message message) throws IOException;
 434 }