org.jivesoftware.util

Class EmailService

java.lang.Object

org.jivesoftware.util.EmailService

public class EmailService
extends Object

A service to send email.

This class has a few factory methods you can use to return message objects or to add messages into a queue to be sent. Using these methods, you can send emails in the following couple of ways:

   EmailService.sendMessage(
     "Joe Bloe", "jbloe@place.org",
     "Jane Doe", "jane@doe.com",
     "Hello...",
     "This is the body of the email...",
     null
   );
 

or

   Message message = EmailService.createMimeMessage();
   // call setters on the message object
   // .
   // .
   // .
   emailService.sendMessage(message);
 

This class is configured with a set of Jive properties:

• mail.smtp.host -- the host name of your mail server, i.e. mail.yourhost.com. The default value is "localhost".
• mail.smtp.port -- an optional property to change the smtp port used from the default of 25.
• mail.smtp.username -- an optional property to change the username used to connect to the smtp server. Default is no username.
• mail.smtp.password -- an optional property to change the password used to connect to the smtp server. Default is no password.
• mail.smtp.ssl -- an optional property to set whether to use SSL to connect to the smtp server or not. Default is false.
• mail.debugEnabled -- true if debug information should written out. Default is false.

Method Summary

Modifier and Type	Method and Description
javax.mail.internet.MimeMessage	createMimeMessage() Factory method to return a blank JavaMail message.
String	getHost() Returns the SMTP host (e.g.
static EmailService	getInstance()
String	getPassword() Returns the password used to connect to the SMTP server.
int	getPort() Returns the port number used when connecting to the SMTP server.
String	getUsername() Returns the username used to connect to the SMTP server.
boolean	isDebugEnabled() Returns true if SMTP debugging is enabled.
boolean	isSSLEnabled() Returns true if SSL is enabled for SMTP connections.
void	sendMessage(javax.mail.internet.MimeMessage message) Sends a JavaMail message.
void	sendMessage(String toName, String toEmail, String fromName, String fromEmail, String subject, String textBody, String htmlBody) Sends a message, specifying all of its fields.
void	sendMessages(Collection<javax.mail.internet.MimeMessage> messages) Send a collection of messages.
void	sendMessagesImmediately(Collection<javax.mail.internet.MimeMessage> messages) Sends a collection of email messages.
void	setDebugEnabled(boolean debugEnabled) Enables or disables SMTP transport layer debugging.
void	setHost(String host) Sets the SMTP host (e.g.
void	setPassword(String password) Sets the password that will be used when connecting to the SMTP server.
void	setPort(int port) Sets the port number that will be used when connecting to the SMTP server.
void	setSSLEnabled(boolean sslEnabled) Sets whether the SMTP connection is configured to use SSL or not.
void	setUsername(String username) Sets the username that will be used when connecting to the SMTP server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static EmailService getInstance()

createMimeMessage

public javax.mail.internet.MimeMessage createMimeMessage()

Factory method to return a blank JavaMail message. You should use the object returned and set desired message properties. When done, pass the object to the addMessage(Message) method.

Returns:

a new JavaMail message.

sendMessage

public void sendMessage(javax.mail.internet.MimeMessage message)

Sends a JavaMail message. To create a message, use the createMimeMessage() method.

Parameters:

message - the message to send.

sendMessages

public void sendMessages(Collection<javax.mail.internet.MimeMessage> messages)

Send a collection of messages. To create a message, use the createMimeMessage() method.

Parameters:

messages - a collection of the messages to send.

sendMessage

public void sendMessage(String toName,
                        String toEmail,
                        String fromName,
                        String fromEmail,
                        String subject,
                        String textBody,
                        String htmlBody)

Sends a message, specifying all of its fields.

To have more advanced control over the message sent, use the sendMessage(MimeMessage) method.

Both a plain text and html body can be specified. If one of the values is null, only the other body type is sent. If both body values are set, a multi-part message will be sent. If parts of the message are invalid (ie, the toEmail is null) the message won't be sent.

Parameters:

toName - the name of the recipient of this email.

toEmail - the email address of the recipient of this email.

fromName - the name of the sender of this email.

fromEmail - the email address of the sender of this email.

subject - the subject of the email.

textBody - plain text body of the email, which can be null if the html body is not null.

htmlBody - html body of the email, which can be null if the text body is not null.

sendMessagesImmediately

public void sendMessagesImmediately(Collection<javax.mail.internet.MimeMessage> messages)
                             throws javax.mail.MessagingException

Sends a collection of email messages. This method differs from sendMessages(Collection) in that messages are sent before this method returns rather than queueing the messages to be sent later.

Parameters:

messages - the messages to send.

Throws:

javax.mail.MessagingException - if an error occurs.

getHost

public String getHost()

Returns the SMTP host (e.g. mail.example.com). The default value is "localhost".

Returns:

the SMTP host.

setHost

public void setHost(String host)

Sets the SMTP host (e.g. mail.example.com). The default value is "localhost".

Parameters:

host - the SMTP host.

getPort

public int getPort()

Returns the port number used when connecting to the SMTP server. The default port is 25.

Returns:

the SMTP port.

setPort

public void setPort(int port)

Sets the port number that will be used when connecting to the SMTP server. The default is 25, the standard SMTP port number.

Parameters:

port - the SMTP port number.

getUsername

public String getUsername()

Returns the username used to connect to the SMTP server. If the username is null, no username will be used when connecting to the server.

Returns:

the username used to connect to the SMTP server, or null if there is no username.

setUsername

public void setUsername(String username)

Sets the username that will be used when connecting to the SMTP server. The default is null, or no username.

Parameters:

username - the SMTP username.

getPassword

public String getPassword()

Returns the password used to connect to the SMTP server. If the password is null, no password will be used when connecting to the server.

Returns:

the password used to connect to the SMTP server, or null if there is no password.

setPassword

public void setPassword(String password)

Sets the password that will be used when connecting to the SMTP server. The default is null, or no password.

Parameters:

password - the SMTP password.

isDebugEnabled

public boolean isDebugEnabled()

Returns true if SMTP debugging is enabled. Debug information is written to System.out by the underlying JavaMail provider.

Returns:

true if SMTP debugging is enabled.

setDebugEnabled

public void setDebugEnabled(boolean debugEnabled)

Enables or disables SMTP transport layer debugging. Debug information is written to System.out by the underlying JavaMail provider.

Parameters:

debugEnabled - true if SMTP debugging should be enabled.

isSSLEnabled

public boolean isSSLEnabled()

Returns true if SSL is enabled for SMTP connections.

Returns:

true if SSL is enabled.

setSSLEnabled

public void setSSLEnabled(boolean sslEnabled)

Sets whether the SMTP connection is configured to use SSL or not. Typically, the port should be 465 when using SSL with SMTP.

Parameters:

sslEnabled - true if ssl should be enabled, false otherwise.