| Red Hat Docs > Manuals > Red Hat Web Application Framework > |
|
The mail service acts as a Mail Transport Agent (MTA) for other Red Hat Web Application Framework applications. It provides a simple mechanism to send plain or rich text messages to any entity with a valid email address. This service is not typically accessed directly, but rather as a building block for higher-level services like Notification. Note that it has no dependencies on Red Hat Web Application Framework and exists primarily as a wrapper for the more cumbersome JavaMail API.
Who should use the Mail API directly? If you are writing an application that sends simple plain-text alerts to users, and you do not require those alerts to be recorded in the database, then it makes sense to use the Mail API. Also, if you are dealing with raw email addresses rather than Red Hat Web Application Framework Parties (Users and Groups), you probably want to use the Mail API directly. Otherwise, you should consider using the higher-level notification service.
The following examples explain how to configure the Mail service and use it for email transport.
Before configuring the mail service, you must have access to a working SMTP server. SMTP is the only supported transport protocol. To test your setup, try using telnet to connect to the server on port 25, type 'HELLO', and verify that it responds as an SMTP server:
telnet smtp.mydomain.net 25 Trying 1.1.1.1... Connected to smtp.mydomain.net Escape character is '^]'. HELO localhost 220 MYDOMAIN.NET ESMTP sendmail (8.11.0/8.11.0) at Thu, 13 Sep 7:02:56 -0400 (EDT) 500 smtp.mydomain.net Hello [1.1.1.1], pleased to meet you |
Once you have verified that the SMTP server is up and running, you can configure the mail service as follows:
init com.arsdigita.mail.Initializer {
// required parameters
// system name MUST contain "@"
SystemName = "mail@mysite.net";
// server to connect to
SmtpHost = "smtp.mydomain.net";
// optional parameters
// set javax.mail to debug mode
debug = false;
// 25; the standard SMTP port
SmtpPort = 25;
// 20000; timeout in millisecs for I/O to server
SmtpTimeout = 30000;
// 25000; connection timout in millisecs
SmtpConnectionTimeout = 35000;
// SimpleServer parameters (also optional)
// first of ten ports to bind
soPort = 5000;
// hostname to bind
soHost = "localhost";
// socket timeout [ms]
soTimeout = 1000;
// retry delay for binding [ms]
soRetryDelay = 200;
} |
Only the first two parameters are required. They specify the name of the system generating the messages (used in constructing mail headers) and the SMTP server to connect to when sending email.
The optional parameters are largely self-explanatory. Note that debug is used to place the mail service into debugging mode. Setting debug=true puts the internal JavaMail Transport class into debugging mode, and logs all communications with the SMTP server to the console. It also logs the complete content of every message sent in the com.arsdigita.mail.Mail category with priority debug. See the next section for more details.
Note that in most cases you will not need to set any of these parameters. You can simply run the default initializer to start the mail service in normal operating mode:
init com.arsdigita.mail.Initializer { } |
The mail service includes a built-in testing harness so that you can run a development server and test applications that send email without actually connecting to a working SMTP server. The test harness consists of an internal server called SimpleServer, which runs on your local host and binds to a range of ports. Each port corresponds to a different SMTP operating mode so that you can test success and failure conditions. The SimpleServer API includes methods to set the operating mode so that all future messages passing through the mail service are processed accordingly.
You can run SimpleServer automatically by setting the debug parameter in the mail initializer, as follows:
init com.arsdigita.mail.Initializer {
debug = true;
} |
To see the complete content of each message sent using the Mail service, you will also need to configure the priority of mail logging to "debug" in the logging initializer:
init com.arsdigita.logging.Initializer {
categoryPriorities = {
{ "com.arsdigita.mail.Mail", "debug" }
};
}
|
When you start Red Hat Web Application Framework, the mail initializer will start SimpleServer, which then binds to ten ports. These ports range by default from 5000 to 5010 (you can change the lower bound for this range by setting the value of soPort). SimpleServer will then intercept all "outbound" mail and respond appropriately to the mail service. All of the composed messages will be written to the server log file where you can check them for correctness.
If you only want to use SimpleServer for testing (for example, in a unit test script), you can start it from your own application using SimpleServer.startup().
By default, all messages go to the port corresponding to normal SMTP operation. To change the operating mode, use the following:
SimpleServer.setMode(UNAVAILABLE); |
The complete set of available operating modes are listed in the SimpleServer API documentation.
Plain text messages can be sent using a static convenience method:
Mail.send(to, from, subject, body); |
You can use the standard format for email addresses, for example, "person@mydomain.net", "Person person@mydomain.name", and "Person LastName person@mydomain.net". Multiple recipients can be specified in a single string separated by commas.
To access the complete set of header attributes, create a Mail object, invoke the various set methods, and call send:
Mail msg = new Mail();
msg.setTo("User1 user1@arsdigita.com, User2 user2@arsdigita.com");
msg.setFrom("Me me@arsdigita.com");
msg.setReplyTo("User3 user3@arsdigita.com");
msg.setCc("User4 user4@arsdigita.com");
msg.setBcc("User5 user5@arsdigita.com");
msg.setSubject("this is the subject");
msg.setBody("this is the body");
msg.send(); |
Rich text messages (HTML) require using the setBody(html,alternate) method to specify both the HTML and plain text versions of a message to send out:
Mail msg = new Mail(to, from, subject);
msg.setBody("<p>This is the HTML body</p>",
"This is the plain text body");
msg.send(); |
Message attachments are handled using one of the various attach(...) methods. Support is provided for File, URL and ByteArray datasources. The URL datasource is the simplest to use (and can also fetch from a local file using the appropriate protocol specification). All attachments require a name, a description, and an optional disposition. The MIME type is determined automatically.
For example, the following code fragment shows how to attach an image whose content is fetched from a URL:
URL url = new URL("http://somedomain.net/image.gif");
Mail msg = new Mail(to, from, subject, body);
msg.attach(url, "image.gif", "A sample image");
msg.send(); |
The protocol for attaching content from a local file is similar:
File path = new File("image.gif");
Mail msg = new Mail(to, from, subject, body);
msg.attach(path, "image.gif", "A sample image");
msg.send(); |
The Mail service provides a utility class called ByteArrayDataSource that can be used to attach virtually any type of content contained in memory by supplying its data as a byte[] array.