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