J2EE BluePrints > BluePrints Mailer

BluePrints Mailer

Welcome to the BluePrints Mailer, a sample application brought to you by the Java 2 Platform, Enterprise Edition BluePrints (J2EE BluePrints) program!

The BluePrints Mailer mini-application introduces you to some of the J2EE BluePrints design guidelines in a smaller, simpler package.

This document outlines the steps needed to use the mini-application.

Note: These instructions use $JPS_HOME (UNIX) and %JPS_HOME% (Win32) to denote the root directory of the J2EE BluePrints bundle.

Before you begin

Before you begin, you must have the following items installed on your system:

Java 2 Platform, Standard Edition SDK (J2SE^TM SDK): v1.3 download (preferred) | v. 1.2.2 download
Java 2 Platform, Enterprise Edition SDK (J2EE^TM SDK): v1.2.1 download

Also make sure to set the environment variables JAVA_HOME and J2EE_HOME as follows:

JAVA_HOME must point to the root directory of your J2SE SDK installation. For example, if you installed the J2SE SDK in /usr/local/java/jdk1.3, then that path should be the value of JAVA_HOME.
J2EE_HOME must point to the root directory of your J2EE SDK installation. For example, if you installed the J2EE SDK in c:\j2sdkee1.2.1, then that path should be the value of J2EE_HOME.

Deploying the mailer

These instructions describe how to deploy the mailer on the J2EE Reference Implementation server (which comes with the J2EE SDK).

Note: These instructions use $JPS_HOME (UNIX) and %JPS_HOME% (Win32) to denote the root directory of the J2EE BluePrints bundle.

Start the J2EE Reference Implementation server.

Bring up another command or shell prompt. Change the current directory to $J2EE_HOME/bin (UNIX) or %J2EE_HOME%\bin (Win32) and enter the following command:

j2ee -verbose
Start the J2EE Reference Implementation deployment tool.

Bring up another command or shell prompt. Change the current directory to $J2EE_HOME/bin (UNIX) or %J2EE_HOME%\bin (Win32) and enter the following command:

deploytool
Open the application.

From the File menu, select Open Application.... In the subsequent file dialog, open mailerapp.ear, which can be found in $JPS_HOME (UNIX) or %JPS_HOME% (Win32).
Configure the e-mail settings.

Go to the Local Applications tree, and select mail > Mail Component > TheMailer.

In the inspector, select the Resource Ref's tabbed pane. Select the mail/MailSession entry, which will enable the Deployment Settings box below.

Change the value of the Host field to the name of your local SMTP server. Change the value of the User Name field to the name you use to access that server.

Select Save from the File menu.
Deploy the application.

From the Tools menu, select Deploy Application. Click through the subsequent dialogs to complete the deployment. You shouldn't have to change any of the default values.

Using the mailer

Now that the mailer is deployed you can access it through a Web browser.

To access the mailer, click the link at the end of this section to bring up the welcome page. Click the link on that page to bring up the e-mail form. The fields on this form are:

The e-mail address to which you want to send your message. Of course, this should be your e-mail address if you want to test the mini-application.
The subject of your message.
The contents of your message.

Click the Submit button to send the message.

Now, check the account for the e-mail address you used in the previous step. If the mailer has been configured correctly, you'll receive a new message, the subject and contents of which you entered in the previous step. Also note that the message's From: header field contains the value of the mail-from entry from the deployment descriptor in ejbruntime.xml (which you edited before you deployed the mini-application).

To start the mini-application click the following link:

http://localhost:8000/mailerapp/

Note: These instructions assume that the application is deployed on a machine named localhost and port 8000. You should substitute localhost and 8000 with the name of the machine and the port on which the application is deployed.

Building the mailer

We use Ant to build the source code. Ant is a Java-based build tool like make, which has been developed under the auspices of the Apache Software Foundation. A working version of Ant is provided as part of the J2EE BluePrints bundle.

If you ever make changes to the mailer's source code, you need to build the application and deploy the rebuilt application for your changes to take effect.

To build the mailer, bring up a shell or command prompt. Then:

UNIX: Change the current directory $JPS_HOME/src/miniapps/mailerapp/src/ and run build.sh. If the compilation succeeds, mailerapp.ear will be created in the directory $JPS_HOME/src/miniapps/mailerapp/build/.
Win32: Change the current directory %JPS_HOME%\src\miniapps\mailerapp\src\ and run build.bat. If the compilation succeeds, mailerapp.ear will be created in the directory %JPS_HOME%\src\miniapps\mailerapp\build\.

When deploying the built application, use the file mailerapp.ear created by the build (as opposed to pre-built one located in the root directory of the J2EE BluePrints bundle).