RESOLVED - issue BATCH-1239: Add email-sending item writer

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/DefaultMailErrorHandler.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2006-2010 the original author or authors.
+ *
+ * Licensed 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.springframework.batch.item.mail;
+
+import javax.mail.MessagingException;
+
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailMessage;
+import org.springframework.mail.MailSendException;
+
+/**
+ * This {@link MailErrorHandler} implementation simply rethrows the exception it
+ * receives.
+ * 
+ * @author Dan Garrette
+ * @author Dave Syer
+ * 
+ * @since 2.1
+ */
+public class DefaultMailErrorHandler implements MailErrorHandler {
+
+	private static final int DEFAULT_MAX_MESSAGE_LENGTH = 1024;
+
+	private int maxMessageLength = DEFAULT_MAX_MESSAGE_LENGTH;
+
+	/**
+	 * The limit for the size of message that will be copied to the exception
+	 * message. Output will be truncated beyond that. Default value is 1024.
+	 * 
+	 * @param maxMessageLength the maximum message length
+	 */
+	public void setMaxMessageLength(int maxMessageLength) {
+		this.maxMessageLength = maxMessageLength;
+	}
+
+	/**
+	 * Wraps the input exception with a runtime {@link MailException}. The
+	 * exception message will contain the failed message.
+	 * 
+	 * @param message a failed message
+	 * @param exception a MessagingException
+	 * @throws MailException a translation of the MessagingException
+	 * @see MailErrorHandler#handle(MailMessage, MessagingException)
+	 */
+	public void handle(MailMessage message, MessagingException exception) throws MailException {
+		String msg = message.toString();
+		throw new MailSendException("Mail server send failed: "
+				+ msg.substring(0, Math.min(maxMessageLength, msg.length())), exception);
+	}
+}

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/MailErrorHandler.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2006-2010 the original author or authors.
+ *
+ * Licensed 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.springframework.batch.item.mail;
+
+import javax.mail.MessagingException;
+
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailMessage;
+
+/**
+ * This class is used to handle errors that occur when email messages are unable
+ * to be sent.
+ * 
+ * @author Dan Garrette
+ * @author Dave Syer
+ * 
+ * @since 2.1
+ */
+public interface MailErrorHandler {
+
+	/**
+	 * This method will be called for each message that failed sending in the
+	 * chunk. If an exception is thrown from this method, then it will propagate
+	 * to the caller.
+	 *  
+	 * @param message the failed message
+	 * @param exception the exception that caused the failure
+	 * @throws MailException if the exception cannot be handled
+	 */
+	public void handle(MailMessage message, MessagingException exception) throws MailException;
+
+}

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/SimpleMailMessageItemWriter.java

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2006-2010 the original author or authors.
+ *
+ * Licensed 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.springframework.batch.item.mail;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import javax.mail.MessagingException;
+
+import org.springframework.batch.item.ItemWriter;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailSendException;
+import org.springframework.mail.MailSender;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.util.Assert;
+
+/**
+ * <p>
+ * A simple {@link ItemWriter} that can send mail messages. If it fails there is
+ * no guarantee about which of the messages were sent, but the ones that failed
+ * can be picked up in the error handler. Because the mail protocol is not
+ * transactional, failures should be dealt with here if possible rather than
+ * allowing them to be rethrown (which is the default).
+ * </p>
+ * 
+ * <p>
+ * Delegates the actual sending of messages to a {@link MailSender}, using the
+ * batch method {@link MailSender#send(SimpleMailMessage[])}, which normally
+ * uses a single server connection for the whole batch (depending on the
+ * implementation). The efficiency of for large volumes of messages (repeated
+ * calls to the item writer) might be improved by the use of a special
+ * {@link MailSender} that caches connections to the server in between calls.
+ * </p>
+ * 
+ * <p>
+ * Stateless, so automatically restartable.
+ * </p>
+ * 
+ * @author Dave Syer
+ * 
+ * @since 2.1
+ * 
+ */
+public class SimpleMailMessageItemWriter implements ItemWriter<SimpleMailMessage>, InitializingBean {
+
+	private MailSender mailSender;
+
+	private MailErrorHandler mailErrorHandler = new DefaultMailErrorHandler();
+
+	/**
+	 * A {@link MailSender} to be used to send messages in {@link #write(List)}.
+	 * 
+	 * @param mailSender
+	 */
+	public void setMailSender(MailSender mailSender) {
+		this.mailSender = mailSender;
+	}
+
+	/**
+	 * The handler for failed messages. Defaults to a
+	 * {@link DefaultMailErrorHandler}.
+	 * 
+	 * @param mailErrorHandler the mail error handler to set
+	 */
+	public void setMailErrorHandler(MailErrorHandler mailErrorHandler) {
+		this.mailErrorHandler = mailErrorHandler;
+	}
+
+	/**
+	 * Check mandatory properties (mailSender).
+	 * 
+	 * @throws IllegalStateException if the mandatory properties are not set
+	 * 
+	 * @see InitializingBean#afterPropertiesSet()
+	 */
+	@Override
+	public void afterPropertiesSet() throws IllegalStateException {
+		Assert.state(mailSender != null, "A MailSender must be provided.");
+	}
+
+	/**
+	 * @param items the items to send
+	 * @see ItemWriter#write(List)
+	 */
+	public void write(List<? extends SimpleMailMessage> items) throws MailException {
+		try {
+			mailSender.send(items.toArray(new SimpleMailMessage[items.size()]));
+		}
+		catch (MailSendException e) {
+			@SuppressWarnings("unchecked")
+			Map<SimpleMailMessage, MessagingException> failedMessages = e.getFailedMessages();
+			for (Entry<SimpleMailMessage, MessagingException> entry : failedMessages.entrySet()) {
+				mailErrorHandler.handle(entry.getKey(), entry.getValue());
+			}
+		}
+	}
+
+}

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/javamail/MimeMessageItemWriter.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2006-2010 the original author or authors.
+ *
+ * Licensed 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.springframework.batch.item.mail.javamail;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import javax.mail.MessagingException;
+import javax.mail.internet.MimeMessage;
+
+import org.springframework.batch.item.ItemWriter;
+import org.springframework.batch.item.mail.DefaultMailErrorHandler;
+import org.springframework.batch.item.mail.MailErrorHandler;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailSendException;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.mail.javamail.MimeMailMessage;
+import org.springframework.util.Assert;
+
+/**
+ * <p>
+ * A simple {@link ItemWriter} that can send mail messages. If it fails there is
+ * no guarantee about which of the messages were sent, but the ones that failed
+ * can be picked up in the error handler. Because the mail protocol is not
+ * transactional, failures should be dealt with here if possible rather than
+ * allowing them to be rethrown (which is the default).
+ * </p>
+ * 
+ * <p>
+ * Delegates the actual sending of messages to a {@link JavaMailSender}, using the
+ * batch method {@link JavaMailSender#send(MimeMessage[])}, which normally uses
+ * a single server connection for the whole batch (depending on the
+ * implementation). The efficiency of for large volumes of messages (repeated
+ * calls to the item writer) might be improved by the use of a special
+ * {@link JavaMailSender} that caches connections to the server in between
+ * calls.
+ * </p>
+ * 
+ * <p>
+ * Stateless, so automatically restartable.
+ * </p>
+ * 
+ * @author Dave Syer
+ * 
+ * @since 2.1
+ * 
+ */
+public class MimeMessageItemWriter implements ItemWriter<MimeMessage> {
+
+	private JavaMailSender mailSender;
+
+	private MailErrorHandler mailErrorHandler = new DefaultMailErrorHandler();
+
+	/**
+	 * A {@link JavaMailSender} to be used to send messages in {@link #write(List)}.
+	 * 
+	 * @param mailSender
+	 */
+	public void setJavaMailSender(JavaMailSender mailSender) {
+		this.mailSender = mailSender;
+	}
+
+	/**
+	 * The handler for failed messages. Defaults to a
+	 * {@link DefaultMailErrorHandler}.
+	 * 
+	 * @param mailErrorHandler the mail error handler to set
+	 */
+	public void setMailErrorHandler(MailErrorHandler mailErrorHandler) {
+		this.mailErrorHandler = mailErrorHandler;
+	}
+
+	/**
+	 * Check mandatory properties (mailSender).
+	 * 
+	 * @throws IllegalStateException if the mandatory properties are not set
+	 * 
+	 * @see InitializingBean#afterPropertiesSet()
+	 */
+	public void afterPropertiesSet() throws IllegalStateException {
+		Assert.state(mailSender != null, "A MailSender must be provided.");
+	}
+
+	/**
+	 * @param items the items to send
+	 * @see ItemWriter#write(List)
+	 */
+	@Override
+	public void write(List<? extends MimeMessage> items) throws MailException {
+		try {
+			mailSender.send(items.toArray(new MimeMessage[items.size()]));
+		}
+		catch (MailSendException e) {
+			@SuppressWarnings("unchecked")
+			Map<MimeMessage, MessagingException> failedMessages = e.getFailedMessages();
+			for (Entry<MimeMessage, MessagingException> entry : failedMessages.entrySet()) {
+				mailErrorHandler.handle(new MimeMailMessage(entry.getKey()), entry.getValue());
+			}
+		}
+	}
+
+}