spring mail文档阅读

spring/spring email/spring email.md

@@ -0,0 +1,169 @@
+- [Email](#email)
+  - [使用示例](#使用示例)
+    - [MailSender使用和SimpleMailMessage使用](#mailsender使用和simplemailmessage使用)
+    - [使用JavaMailSender和MimeMessagePreparator](#使用javamailsender和mimemessagepreparator)
+    - [使用MimeMessageHelper](#使用mimemessagehelper)
+    - [发送附件和内联资源](#发送附件和内联资源)
+      - [附件](#附件)
+      - [inline resource](#inline-resource)
+  - [Spring Boot集成](#spring-boot集成)
+
+
+# Email
+spring framework提供了工具库用于发送邮件，并且并不依赖具体的底层邮件系统。  
+
+`org.springframework.mail`包是spring邮件系统的root package，用于发送邮件的接口为MailSender。封装邮件属性的对象为`SimpleMailMessage`，其封装了邮件主要的属性（例如from和to）。
+
+root package也包含了一套checked exception结构，root exception类型为`MailException`.
+
+`org.springframework.mail.javamail.JavaMailSender`接口则是添加了专门的JavaMail特性，例如对MIME消息的支持（从MailSender接口继承）。`JavaMailSender`也提供了一个回调接口`org.springframework.mail.javamail.MimeMessagePreparator`用于准备Mime信息。
+
+## 使用示例
+### MailSender使用和SimpleMailMessage使用
+```java
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailSender;
+import org.springframework.mail.SimpleMailMessage;
+
+public class SimpleOrderManager implements OrderManager {
+
+	private MailSender mailSender;
+	private SimpleMailMessage templateMessage;
+
+	public void setMailSender(MailSender mailSender) {
+		this.mailSender = mailSender;
+	}
+
+	public void setTemplateMessage(SimpleMailMessage templateMessage) {
+		this.templateMessage = templateMessage;
+	}
+
+	public void placeOrder(Order order) {
+
+		// Do the business calculations...
+
+		// Call the collaborators to persist the order...
+
+		// Create a thread safe "copy" of the template message and customize it
+		SimpleMailMessage msg = new SimpleMailMessage(this.templateMessage);
+		msg.setTo(order.getCustomer().getEmailAddress());
+		msg.setText(
+			"Dear " + order.getCustomer().getFirstName()
+				+ order.getCustomer().getLastName()
+				+ ", thank you for placing order. Your order number is "
+				+ order.getOrderNumber());
+		try {
+			this.mailSender.send(msg);
+		}
+		catch (MailException ex) {
+			// simply log it and go on...
+			System.err.println(ex.getMessage());
+		}
+	}
+
+}
+```
+### 使用JavaMailSender和MimeMessagePreparator
+如下示例通过MimeMessagePreparator来发送MimeMessage
+```java
+public class SimpleOrderManager implements OrderManager {
+
+	private JavaMailSender mailSender;
+
+	public void setMailSender(JavaMailSender mailSender) {
+		this.mailSender = mailSender;
+	}
+
+	public void placeOrder(final Order order) {
+		// Do the business calculations...
+		// Call the collaborators to persist the order...
+
+		MimeMessagePreparator preparator = new MimeMessagePreparator() {
+			public void prepare(MimeMessage mimeMessage) throws Exception {
+				mimeMessage.setRecipient(Message.RecipientType.TO,
+						new InternetAddress(order.getCustomer().getEmailAddress()));
+				mimeMessage.setFrom(new InternetAddress("mail@mycompany.example"));
+				mimeMessage.setText("Dear " + order.getCustomer().getFirstName() + " " +
+						order.getCustomer().getLastName() + ", thanks for your order. " +
+						"Your order number is " + order.getOrderNumber() + ".");
+			}
+		};
+
+		try {
+			this.mailSender.send(preparator);
+		}
+		catch (MailException ex) {
+			// simply log it and go on...
+			System.err.println(ex.getMessage());
+		}
+	}
+
+}
+```
+### 使用MimeMessageHelper
+通过使用`org.springframework.mail.javamail.MimeMessageHelper`，可以避免复杂的JavaMail API，通过其创建MimeMessage十分简单：
+```java
+// of course you would use DI in any real-world cases
+JavaMailSenderImpl sender = new JavaMailSenderImpl();
+sender.setHost("mail.host.com");
+
+MimeMessage message = sender.createMimeMessage();
+MimeMessageHelper helper = new MimeMessageHelper(message);
+helper.setTo("test@host.com");
+helper.setText("Thank you for ordering!");
+
+sender.send(message);
+```
+### 发送附件和内联资源
+多数邮件消息都允许使用附件和inline resource。inline resource包含图片、样式表等，但是不希望以附件的形式来显示inline resource。  
+
+#### 附件
+如下实例显示了如何通过`MimeMessageHelper`来发送带有图片附件的邮件：
+```java
+JavaMailSenderImpl sender = new JavaMailSenderImpl();
+sender.setHost("mail.host.com");
+
+MimeMessage message = sender.createMimeMessage();
+
+// use the true flag to indicate you need a multipart message
+MimeMessageHelper helper = new MimeMessageHelper(message, true);
+helper.setTo("test@host.com");
+
+helper.setText("Check out this image!");
+
+// let's attach the infamous windows Sample file (this time copied to c:/)
+FileSystemResource file = new FileSystemResource(new File("c:/Sample.jpg"));
+helper.addAttachment("CoolImage.jpg", file);
+
+sender.send(message);
+```
+#### inline resource
+如下示例显示了如何通过MimeMessageHelper来发送带有inline resource的邮件：
+```java
+JavaMailSenderImpl sender = new JavaMailSenderImpl();
+sender.setHost("mail.host.com");
+
+MimeMessage message = sender.createMimeMessage();
+
+// use the true flag to indicate you need a multipart message
+MimeMessageHelper helper = new MimeMessageHelper(message, true);
+helper.setTo("test@host.com");
+
+// use the true flag to indicate the text included is HTML
+helper.setText("<html><body><img src='cid:identifier1234'></body></html>", true);
+
+// let's include the infamous windows Sample file (this time copied to c:/)
+FileSystemResource res = new FileSystemResource(new File("c:/Sample.jpg"));
+helper.addInline("identifier1234", res);
+
+sender.send(message);
+```
+## Spring Boot集成
+如果`java.mail.host`和相应的库（`spring-boot-starter-mail`)存在，一个默认的JavaMailSender将会被自动创建（如果JavaMailSender不存在自己创建的bean对象）。
+
+某些timeout值默认情况下是无限的，应该手动为其指定值，避免在邮件服务器未响应时线程被阻塞：
+```properties
+spring.mail.properties[mail.smtp.connectiontimeout]=5000
+spring.mail.properties[mail.smtp.timeout]=3000
+spring.mail.properties[mail.smtp.writetimeout]=5000
+```