Using Jakarta Mail
This chapter describes how to use the Jakarta Mail API, which provides a set of abstract classes defining objects that comprise a mail system.
Jakarta Mail resources are supported only in the Full Profile, not in the Web Profile. |
Introducing Jakarta Mail
The Jakarta Mail 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 Jakarta Mail API includes support for the IMAP4, POP3, and SMTP protocols.
The Jakarta Mail 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.
-
Jakarta Mail uses Jakarta Activation to encapsulate message data and to handle commands intended to interact with that data.
For more information, see "Administering the Jakarta Mail Service" in the Payara Server General Administration section and the Jakarta Mail specification.
Creating a Jakarta Mail Session
You can create a Jakarta Mail session in the following ways:
-
In the Administration Console, open the Resources component and select JavaMail Sessions.
-
Use the
asadmin create-mail-resource
command.
Jakarta Mail Session Properties
You can set properties for a Jakarta Mail Session
object. Every property name must start with a mail-
prefix. Payara Server changes the dash (-
) character to a period (.
) in the name of the property and saves the property to the MailConfiguration
and Jakarta Mail 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 Jakarta Mail Session
object, first define the property as follows:
-
Name:
mail-from
-
Value:
john.doe@sun.com
Looking Up a Jakarta Mail Session
The standard Java Naming and Directory Interface (JNDI) subcontext for Jakarta Mail sessions is java:comp/env/mail
.
Registering Jakarta Mail sessions in the mail
naming subcontext of a JNDI namespace, or in one of its child subcontexts, is a standard requirement.
The JNDI namespace is hierarchical, like a file system’s directory structure, so it is easy to find and nest references. A Jakarta Mail 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 Jakarta Mail 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:
var ic = new InitialContext();
var snName = "java:comp/env/mail/MyMailSession";
var session = (Session)ic.lookup(snName);
For more information about the JNDI API, see Using the Java Naming and Directory Interface.
Sending and Reading Messages Using Jakarta Mail
To Send a Message Using Jakarta Mail
-
Import the packages that you need.
import java.util.*; import jakarta.activation.*; import jakarta.mail.*; import jakarta.mail.internet.*; import javax.naming.*;
-
Look up the Jakarta Mail session.
var ic = new InitialContext(); var snName = "java:comp/env/mail/MyMailSession"; var session = (Session)ic.lookup(snName);
-
Override the Jakarta Mail session properties if necessary. For example:
var props = session.getProperties(); props.put("mail.from", "user2@mailserver.com");
-
Create a
MimeMessage
. ThemsgRecipient
,msgSubject
, andmsgTxt
variables in the following example contain input from the user:var 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);
-
Send the message.
Transport.send(msg);
To Read a Message Using Jakarta Mail
-
Import the packages that you need.
import java.util.*; import jakarta.activation.*; import jakarta.mail.*; import jakarta.mail.internet.*; import javax.naming.*;
-
Look up the Jakarta Mail session.
var ic = new InitialContext(); var snName = "java:comp/env/mail/MyMailSession"; var session = (jakarta.mail.Session)ic.lookup(snName);
-
Override the Jakarta Mail session properties if necessary. For example:
var props = session.getProperties(); props.put("mail.from", "user2@mailserver.com");
-
Get a
Store
object from theSession
, then connect to the mail server using theStore
object’sconnect
method. You must supply a mail server name, a mail username, and a password:var store = session.getStore(); store.connect("MailServer", "MailUser", "secret");
-
Retrieve the
INBOX
folder.Folder folder = store.getFolder("INBOX");
-
It is efficient to read the
Message
objects (which represent messages on the server) into an array or a collection.Message[] messages = folder.getMessages();
Using Application-Scoped Jakarta Mail Resources
You can define an application-scoped Jakarta Mail or other resource for an enterprise application, web module, EJB module, connector module, or application client module by supplying a payara-resources.xml
deployment descriptor file.
For more details, see "Application-Scoped Resources" in the Payara Server Application Deployment section.