email
Product: xTier™/LWC 2.3 Whitepaper: n/a	support@fitechlabs.com  Download  Buy
Depends: log  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
'email' service provides simplified API for JavaMail SMTP service. The purpose of this service is to provide ready implementation for some of the well-known usage patterns as well as an integrated SMTP service for Java. Main features of this service include:

• Simplified SMTP API.
• Tight integration including unified xTier™ configuration.

'email' service consists of the following main interfaces and classes:

• EmailService interface provides main API for 'email' service.
• EmailSmtpSession interface provides API for SMTP session. SMTP session is reusable container that collects all related properties for SMTP communication.

 Top

Configuration
'email' service is configured via pre-defined xtier_email.xml configuration file. This file follows standard xTier™ service configuration pattern that can be demonstrated by the following complete example of email configuration:

1		<xtier-email>
2		<region name="examples">
3		<!-- SMTP host. -->
4		<smtp-host>smtp.provider.com</smtp-host>
5
6		<!-- SMTP port. -->
7		<smtp-port>25</smtp-port>
8
9		<!-- Default from address. -->
10		<default-from>someone@host.com</default-from>
11
12		<!-- Default MIME type. -->
13		<default-mime>text/html</default-mime>
14
15		<!-- Default Java email content encoding. -->
16		<java-default-encoding>
17		quoted-printable
18		</java-default-encoding>
19
20		</region>
21		</xtier-email>
22
23

'email' service configuration consists of the following XML tags:

smtp-host	SMTP host to be used by 'email' service.
smtp-port	SMTP port to be used by 'email' service. Note that this tag is required and in most cases it should be 25 which is default value for SMTP service (see RFC 821).
default-from	Optional default from address. Note that this address can be changed in SMTP session.
default-mime	Optional default MIME type for the message body. Note that this value can be changed in SMTP session. See RFC 2045, RFC 822 and RFC 2047 for more MIME information.
java-default-encoding	Optional default Java encoding for message content which should be one of the following values: 7bit 8bit binary quoted-printable base64 Note that this value can be changed in SMTP session.

For specifics of IoC configuration see IocService. For common rules of xTier™ service configuration see XtierKernel class .
For detailed information about XML configuration see xtier_email.dtd at ${XTIER_ROOT}/config/dtd folder.

 Top

Examples
Usage of 'email' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'email' service. Once the service instance is obtained the service API can be used: you need to obtain SMTP session and set necessary parameters into it. Once SMTP session is prepared you can call send() method to send the message. Note that SMTP session are reusable and its parameters can be changed between calls to send() method. Following example demonstrates the basic steps in using 'email' service:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'email' service.
5		EmailService email = xtier.email();
6
7		EmailSmtpSession session = email.getSmtpSession();
8
9		// Use 'email' service.
10
11		//Set email session's parameters.
12		session.setFromAddress("from@somehost.com");
13		session.addToAddress("to@anotherhost.com");
14		session.setMime("text/html");
15		session.setSubject("HTML email service test.");
16		session.setContent("<b>This is the " +
17		"<font size=+1>HTML</font> test.</b>");
18
19		// Set outgoing SMTP authentication (if required).
20		session.setUsername("username");
21		session.setPassword("password");
22
23		try {
24		// Send the email.
25		session.send();
26		}
27		catch (MessagingException e) {
28		...
29		}

 Top