Sun ONE logo     
Simple Javamail Sample Application



Simple Javamail Sample Application


This document describes how to utilize the Javamail sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

The simple Javamail sample application demonstrates the usage of JavaMail API. The application uses EJB for sending an e-mail. The EJB is invoked by a client class.

To better understand sample application source code, you may refer to the related javadocs which can be accessed at <install_dir>/samples/javamail/simple/javadocs/index.html after it is generated.



Compiling and Assembling the Application



This section contains instructions to compile and assemble the Simple Javamail sample application.

  1. Go to <install_dir>/samples/javamail/simple/src/

    Execute the command asant



    Note You must add <install_dir>/bin to your path.



    The default target core will be executed to build the JAR and EAR files.

  2. Deploy the application.

    After you have re-created the sample application from scratch, you may proceed to Deploying the Sample Application.

  3. Clean the web application project area (optional).

    Execute the command asant clean to remove the assemble and build directories of the sample application.

  4. Generate javadocs (optional).

    Execute the command asant javadocs



Deploying the Sample Application

In this section, you will learn how to deploy the Simple Javamail sample application.

Select one of the following approaches to deploying the application:

  • Command Line-based Deployment describes how to manually register the application in Sun ONE Application Server using a Command Line Interface (CLI). This is the fastest means of deploying the sample application.

  • GUI-based Deployment describes how to use the Sun ONE Application Server Deployment Tool to import and deploy the sample application.


Command Line-based Deployment

Since a complete EAR file is supplied, the fastest means of setting up the application is to use the command line utilities described in this section.

The pre-built javamail-simple.ear file is an Enterprise Archive file that contains the JAR file of the application. Within the JAR file resides the XML deployment descriptor files, application class files, and other content required by the application.

Deploying the pre-built javamail-simple.ear file is simple. You may deploy by either Using the asant script or by Using the asadmin command.


Using the asant script

  1. Go to the src directory of the sample. For example:

    <install_dir>/samples/javamail/simple/src

  2. Edit the mail.properties file to change the values of the following properties as per your configuration:

    mailhost
    mailuser
    fromaddress

    By default they are set to

    mailhost=localhost
    mailuser=xyz@foo.com
    fromaddress=nobody

    Make sure these values are changed according to your mail client properties.

  3. Run asant using deploy task. For example:

    asant deploy


Using the asadmin command

  1. Go to <install_dir>/samples/javamail/simple/

  2. Execute the following:

    asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> javamail-simple.ear

The deployment process involves the following operations:

  • Authenticates against the local application server's administrative server.
  • The EAR file is transferred to the administrative server
  • The administrative server begins the registration process:
    • Parses the EAR file and embedded JAR file.
    • Explodes the bits into repository.
    • Registers the J2EE application "javamail-simple" by updating server.xml.
    • Creates the javamail mail resource required for running this application.
    • Reconfigures the application server instance for the newly added resource.

If you would like to verify the registration of the application, you may proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.


GUI-based Deployment

Since a pre-built Enterprise Archive (EAR) file for the sample application is included with the application server, you can use the Sun One Application Server Administration Tool to quickly read the EAR file and deploy it to the Application Server.

  1. To deploy the application, the administrative server needs to be running. To start the admin server, execute the following:

    <install_dir>/domains/domain1/admin-server/bin/startserv

  2. From your web browser, access the Sun ONE Application Server by entering the URL. For example:

    http://<server-host>:<admin-port>

  3. Enter the server administrator's username and password to access the admin server.

  4. On the left panel, navigate the tree by clicking on the following:

    App Server Instances->server1->Applications->Enterprise Apps

  5. On the right panel, click on the Deploy button.

    Select the file (from disk) to be deployed (javamail-simple.ear)

    Click OK.

  6. You will be prompted for the application name.

    Type javamail-simple

    Click OK.

If the deployment processes correctly, you will see the original panel displaying the javamail-simple application as deployed.


Verifying Deployment

As an optional step, you can use the Sun ONE Application Server Administration Tool to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.

To verify the registration of the application, do the following:

Execute the command asadmin to look at applications deployed with a server instance. For example:

asadmin list-components -u <username> -w <password> -H <host> -p <admin-port> <server instance name>

You will see the javamail-simple application displayed as one of the listed components.


Undeploying the application

If you wish to undeploy the application after successful deployment, you may do so by either Using the asant script or by Using the asadmin command.


Using the asant script

  1. Go to <install_dir>/samples/javamail/simple/src

  2. Execute the following:

    asant undeploy


Using the asadmin command

  1. Go to <install_dir>/samples/javamail/simple/src

  2. Execute the following:

    asadmin undeploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> javamail-simple



Creating/Deleting Java Mail Resource

This section describes how to create and delete the Java Mail resource with Sun ONE Application Server. The Java Mail resource is required for running the javamail-simple sample application.


Creating Java Mail Resource with Sun ONE Application Server

The java mail resource consists of the following properties and is created when the application is deployed using asant deploy.

jndi name
mail host
mail user
from address (return address)
store protocol
store protocol class
transport protocol
transport protocol class

You don't need to create the java mail resource separately. However in the event the mail resource is removed, it can be created either through command line or using admin tool GUI.

Using the asadmin command

Execute the following asadmin command:

<install_dir>/bin/asadmin create-javamail-resource -u <adminuser> -w <adminpassword> -H <hostname> -p <adminport> [-s] [--instance <instancename>] --mailhost <mailhostname> --mailuser <mailusername> --fromaddress <address> [--storeprotocol=imap] [--storeprotocolclass=com.sun.mail.imap.IMAPStore] [--transprotocol=smtp] [--transprotocolclass=com.sun.mail.smtp.SMTPTransport] [--debug=false] [--enabled=true] [--description text] [--property (name=value)[:name=value]*] <jndiname>

where <jndiname> has to be mail/MySession if you don't plan to modify sun-ejb-jar.xml.

Using the Admin Tool GUI

To create the Java Mail resource using the Admin Tool GUI, do the following:

  1. From your web browser, enter the Sun ONE Application Server Administration Tool URL. For example:

    http://<server-host>:<admin-port>

  2. On the left panel, navigate the tree by clicking on the following:

    App Server Instances->server1->Java Mail Sessions

  3. On the right panel, click on the New button.

    Provide the values for mail resource properties as described above. Note that you have to enter mail/MySession as the value of the JNDI Name if you don't plan to modify sun-ejb-jar.xml.

  4. Click OK. The Java Mail resource will be created.


Deleting Java Mail Resource with Sun ONE Application Server

The java mail resource is deleted when you give the command asant undeploy to undeploy the javamail-simple sample application. However in the event the mail resource needs to be deleted, it can be done either through command line or using admin tool GUI.

Using the asadmin command

Execute the following asadmin command:

<install_dir>/bin/asadmin delete-javamail-resource -u <adminuser> -w <adminpassword> -H <hostname> -p <adminport> --instance <instancename> <jndiname>

where <jndiname> is the jndi name of the Java Mail resource you've created. The default name is mail/MySession if you haven't modified sun-ejb-jar.xml.

Using the Admin Tool GUI

To create the Java Mail resource using the Admin Tool GUI, do the following:

  1. From your web browser, enter the Sun ONE Application Server Administration Tool URL. For example:

    http://<server-host>:<admin-port>

  2. On the left panel, navigate the tree by clicking on the following:

    App Server Instances->server1->Java Mail Sessions

  3. On the right panel, select the Java Mail resource that need to be deleted

  4. Click the Delete button. Click OK to confirm the delete request.


Running the Sample Application

To run the application, do the following:

  1. Go to the directory <install_dir>/domains/domain1/<server_instance>/applications/j2ee-apps/javamail-simple_1/

  2. Execute the following:

    <install_dir>/bin/appclient -client javamail-simpleClient.jar -name javamail-simpleClient -textauth <receiver_email_address>

    where <receiver_email_address> is the e-mail address to which the message will be sent.

Troubleshooting

  • Please make sure that you run asant undeploy before redeploying this sample - this will make sure that all modules are undeployed and the resources are disabled.

  • Check mail source properties to have proper value according to your mail client.

  • Although the ear, context-root names in this sample are all "javamail-simple", it is not necessary that it be so. The application will work as expected if the names of each of these attributes is unique. Rebuild the application after changing the context-root (in application.xml), and the ear names (in build.xml), redeploy and test the sample to confirm this.

  • If you encounter problems when running the application, review the log files at <install-root>/domains/<domain-instance>/<server-instance>/logs/server.log to learn what exactly went wrong.



Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated July 18, 2002