Write JavaMail applications

After you have configured e-mail services on your iSeries server and created a JavaMail Session object with the WebSphere Application Server administrative console, you can write applications that interface with these services through the Session object. According to the J2EE specification, each instance of the javax.mail.Session class is treated as a JNDI resource factory.

J2EE applications can use JavaMail APIs by looking up references to logically named mail connection factories through the java:comp/env/mail subcontext declared in the application deployment descriptor and mapped to installation specific mail session resources. As in the case of other J2EE resources, this can be done in order to eliminate the need for the application to hard code references to external resources.

To use the JavaMail APIs in an enterprise application component, such as a servlet, enterprise bean, or application client, perform the following steps:

Locate a resource through Java Naming and Directory Interface (JNDI).
The J2EE specification considers a mail session instance as a resource (a factory where mail transport and store connections can be obtained). You should never hard-code mail sessions. Instead, you must follow the J2EE programming model of configuring resources through the system facilities and then locating them through JNDI lookups.

In Example: JavaMail code, the line javax.mail.Session mail_session = (javax.mail.Session) ctx.lookup("java:comp/env/mail/MailSession3"); is an example of using a resource name located through JNDI rather than hard-coding a mail session. You can consider the lookup name mail/MailSession3 a soft link to the real resource.

See Java Naming and Directory Interface (JNDI) for more information.
Use the Assembly Toolkit to declare mail resource references in your application.
1. Start the Assembly Toolkit.
2. In the J2EE perspective, expand Web Modules, and right click the Web module you want to modify.
3. Select Open With --> Deployment Descriptor Editor.
4. In the Web Deployment Descriptor, click the References tab.
5. On the References page, click the Resource tab at the top of the page.
6. Under the Resource references heading, click Add to declare mail resource references. Fill in the following information:
  - Name
    This is a required field. The Name field specifies the JNDI name of the resource relative to the java:comp/env context. Make sure that the name of the reference matches the name used in the code. For example, in Example: JavaMail code, it uses java:comp/env/mail/MailSession3 in the lookup; therefore, the name of this reference must be mail/Session3.
  - Type
    This is a required field. The Type field specifies the type of the resource. Enter javax.mail.Session in the field.
  - Description
    This is an optional field. The Description field specifies a description for the resource.
  - Authentication
    The type of authentication to use for the resource. Select Container from the drop-down list.
7. Click File --> Save.
Note: Use the steps above to edit additional enterprise application components as needed.

The tool generates a deployment descriptor that has XML tags similar to those in the following example:
```
<resource-ref>
   <description>description</description>
   <res-ref-name>mail/MailSession</res-ref-name>
   <res-type>javax.mail.Session</res-type>
   <res-auth>Container</res-auth>
</resource-ref>
```
Administer mail resources
You must configure the mail resource that is referenced by your application component. The mail session you configure must have both the transport and mail access portions defined. Transport settings are required because the code is sending a message; mail access settings are required because they also save a copy to the local mail store. When you configure the mail session, you are asked to specify a JNDI name. This name is important and is required when you install your application (to link up the resource references in your application with the real resources that you have configured).

See Example: Look up a JavaMail session for more information.
Install your application in the Administration topic.
You can install your application using either the administrative console or the scripting tool. An important step in the install process is that the system goes through all resource references and expects you to supply a JNDI name for each of them. This is not an arbitrary JNDI name; it is the JNDI name given to a particular, configured resource that is the target of the reference.
(Optional) Manage existing mail providers and sessions.
1. Start the administrative console in the Administration topic.
2. In the topology tree, expand Resources and click Mail Providers --> Mail session.
3. Click the mail provider or mail session that you want to modify.
4. To remove a mail provider or mail session, click Remove.
5. Click Apply or OK.
6. Save the configuration.
(Optional) Enable debugger for a mail session.
1. Start the administrative console in the Administration topic.
2. In the topology tree, expand Resources and click Mail Providers --> Mail session.
3. Click Debug. Debug is enabled for the session.
4. Click Apply or OK.