docs/application-development-guide/src/main/jbake/content/javamail.adoc

type=page
status=published
title=Using the JavaMail API
prev=jms.html
~~~~~~
Using the JavaMail API
======================

[[GSDVG00021]][[beaow]]


[[using-the-javamail-api]]
18 Using the JavaMail API
-------------------------

This chapter describes how to use the JavaMail API, which provides a set
of abstract classes defining objects that comprise a mail system.

The following topics are addressed here:

* link:#beaox[Introducing JavaMail]
* link:#beaoy[Creating a JavaMail Session]
* link:#beaoz[JavaMail Session Properties]
* link:#beapa[Looking Up a JavaMail Session]
* link:#fwfiy[Sending and Reading Messages Using JavaMail]
* link:#gkpfg[Using Application-Scoped JavaMail Resources]


[NOTE]
=======================================================================

JavaMail resources are supported only in the full OracleGlassFish
Server, not in the Web Profile.

=======================================================================


[[beaox]][[GSDVG00200]][[introducing-javamail]]

Introducing JavaMail
~~~~~~~~~~~~~~~~~~~~

The JavaMail API defines classes such as `Message`, `Store`, and
`Transport`. The API can be extended and can be subclassed to provide
new protocols and to add functionality when necessary. In addition, the
API provides concrete subclasses of the abstract classes. These
subclasses, including `MimeMessage` and `MimeBodyPart`, implement widely
used Internet mail protocols and conform to the RFC822 and RFC2045
specifications. The JavaMail API includes support for the IMAP4, POP3,
and SMTP protocols.

The JavaMail architectural components are as follows:

* The abstract layer declares classes, interfaces, and abstract methods
intended to support mail handling functions that all mail systems
support.
* The internet implementation layer implements part of the abstract
layer using the RFC822 and MIME internet standards.
* JavaMail uses the JavaBeans Activation Framework (JAF) to encapsulate
message data and to handle commands intended to interact with that data.

For more information, see "link:../administration-guide/javamail.html#GSADG00019[Administering the JavaMail
Service]" in GlassFish Server Open Source Edition Administration Guide
and the JavaMail specification at
`http://www.oracle.com/technetwork/java/javamail/index.html`.

[[beaoy]][[GSDVG00201]][[creating-a-javamail-session]]

Creating a JavaMail Session
~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can create a JavaMail session in the following ways:

* In the Administration Console, open the Resources component and select
JavaMail Sessions. For details, click the Help button in the
Administration Console.
* Use the `asadmin create-javamail-resource` command. For details, see
the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].

[[beaoz]][[GSDVG00202]][[javamail-session-properties]]

JavaMail Session Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can set properties for a JavaMail `Session` object. Every property
name must start with a `mail-` prefix. The GlassFish Server changes the
dash (`-`) character to a period (`.`) in the name of the property and
saves the property to the `MailConfiguration` and JavaMail `Session`
objects. If the name of the property doesn't start with `mail-`, the
property is ignored.

For example, if you want to define the property `mail.from` in a
JavaMail `Session` object, first define the property as follows:

* Name - `mail-from`
* Value - `john.doe@sun.com`

[[beapa]][[GSDVG00203]][[looking-up-a-javamail-session]]

Looking Up a JavaMail Session
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The standard Java Naming and Directory Interface (JNDI) subcontext for
JavaMail sessions is `java:comp/env/mail`.

Registering JavaMail sessions in the `mail` naming subcontext of a JNDI
namespace, or in one of its child subcontexts, is standard. The JNDI
namespace is hierarchical, like a file system's directory structure, so
it is easy to find and nest references. A JavaMail session is bound to a
logical JNDI name. The name identifies a subcontext, `mail`, of the root
context, and a logical name. To change the JavaMail session, you can
change its entry in the JNDI namespace without having to modify the
application.

The resource lookup in the application code looks like this:

[source,oac_no_warn]
----
InitialContext ic = new InitialContext();
String snName = "java:comp/env/mail/MyMailSession";
Session session = (Session)ic.lookup(snName);
----

For more information about the JNDI API, see link:jndi.html#beanr[Using
the Java Naming and Directory Interface].

[[fwfiy]][[GSDVG00204]][[sending-and-reading-messages-using-javamail]]

Sending and Reading Messages Using JavaMail
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following topics are addressed here:

* link:#beapb[To Send a Message Using JavaMail]
* link:#beapc[To Read a Message Using JavaMail]

[[beapb]][[GSDVG00079]][[to-send-a-message-using-javamail]]

To Send a Message Using JavaMail
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Import the packages that you need. +
[source,oac_no_warn]
----
import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;
----
2.  Look up the JavaMail session. +
[source,oac_no_warn]
----
InitialContext ic = new InitialContext();
String snName = "java:comp/env/mail/MyMailSession";
Session session = (Session)ic.lookup(snName);
----
For more information, see link:#beapa[Looking Up a JavaMail Session].
3.  Override the JavaMail session properties if necessary. +
For example: +
[source,oac_no_warn]
----
Properties props = session.getProperties();
props.put("mail.from", "user2@mailserver.com");
----
4.  Create a `MimeMessage`. +
The msgRecipient, msgSubject, and msgTxt variables in the following
example contain input from the user: +
[source,oac_no_warn]
----
Message msg = new MimeMessage(session);
msg.setSubject(msgSubject);
msg.setSentDate(new Date());
msg.setFrom();
msg.setRecipients(Message.RecipientType.TO, 
   InternetAddress.parse(msgRecipient, false));
msg.setText(msgTxt);
----
5.  Send the message. +
[source,oac_no_warn]
----
Transport.send(msg);
----

[[beapc]][[GSDVG00080]][[to-read-a-message-using-javamail]]

To Read a Message Using JavaMail
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Import the packages that you need. +
[source,oac_no_warn]
----
import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;
----
2.  Look up the JavaMail session. +
[source,oac_no_warn]
----
InitialContext ic = new InitialContext();
String snName = "java:comp/env/mail/MyMailSession";
Session session = (javax.mail.Session)ic.lookup(snName);
----
For more information, see link:#beapa[Looking Up a JavaMail Session].
3.  Override the JavaMail session properties if necessary. +
For example: +
[source,oac_no_warn]
----
Properties props = session.getProperties();
props.put("mail.from", "user2@mailserver.com");
----
4.  Get a `Store` object from the `Session`, then connect to the mail
server using the Store object's `connect` method. +
You must supply a mail server name, a mail user name, and a password. +
[source,oac_no_warn]
----
Store store = session.getStore();
store.connect("MailServer", "MailUser", "secret");
----
5.  Get the INBOX folder. +
[source,oac_no_warn]
----
Folder folder = store.getFolder("INBOX");
----
6.  It is efficient to read the `Message` objects (which represent
messages on the server) into an array. +
[source,oac_no_warn]
----
Message[] messages = folder.getMessages();
----

[[gkpfg]][[GSDVG00205]][[using-application-scoped-javamail-resources]]

Using Application-Scoped JavaMail Resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can define an application-scoped JavaMail or other resource for an
enterprise application, web module, EJB module, connector module, or
application client module by supplying a `glassfish-resources.xml`
deployment descriptor file. For details, see
"link:../application-deployment-guide/deploying-applications.html#GSDPG00075[Application-Scoped Resources]" in GlassFish Server
Open Source Edition Application Deployment Guide.