type=page
status=published
title=Administering the JavaMail Service
next=jms.html
prev=orb.html
~~~~~~

Administering the JavaMail Service
==================================

[[GSADG00019]][[ablkr]]


[[administering-the-javamail-service]]
16 Administering the JavaMail Service
-------------------------------------

GlassFish Server includes the JavaMail API along with JavaMail service
providers that allow an application component to send email
notifications over the Internet and to read email from IMAP and POP3
mail servers.

The following topics are addressed here:

* link:#ggjsf[About JavaMail]
* link:#giowr[Administering JavaMail Resources]

Instructions for accomplishing the tasks in this chapter by using the
Administration Console are contained in the Administration Console
online help.

[[ggjsf]][[GSADG00593]][[about-javamail]]

About JavaMail
~~~~~~~~~~~~~~

The JavaMail API is a set of abstract APIs that model a mail system. The
JavaMail API provides a platform-independent and protocol-independent
framework to build mail and messaging applications and provide
facilities for reading and sending electronic messages. Service
providers implement particular protocols. Using the API you can add
email capabilities to your applications. JavaMail provides access from
Java applications to Internet Message Access Protocol (IMAP) and Simple
Mail Transfer Protocol (SMTP) capable mail servers on your network or
the Internet. The API does not provide mail server functionality; you
must have access to a mail server to use JavaMail.

The JavaMail API is implemented as an optional package in the Java
platform and is also available as part of the Java EE platform.

To learn more about the JavaMail API, consult the
http://www.oracle.com/technetwork/java/javamail/[JavaMail web site] .

[[giowr]][[GSADG00594]][[administering-javamail-resources]]

Administering JavaMail Resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When you create a mail session, the server-side components and
applications are enabled to access JavaMail services with JNDI, using
the session properties you assign for them. When creating a mail
session, you can designate the mail hosts, the transport and store
protocols, and the default mail user so that components that use
JavaMail do not have to set these properties. Applications that are
heavy email users benefit because GlassFish Server creates a single
session object and makes the session available to any component that
needs it.

JavaMail settings such as the following can be specified:

* JNDI Name. The unique name for the mail session. Use the naming
sub-context prefix mail/ for JavaMail resources. For example:
`mail/MySession`
* Mail Host. The host name of the default mail server. The connect
methods of the store and transport objects use this value if a
protocol-specific host property is not supplied. The name must be
resolvable to an actual host name.
* Default User. The default user name to provide when connecting to a
mail server. The connect methods of the store and transport objects use
this value if a protocol-specific username property is not supplied.
* Default Return Address. The email address of the default user, in the
form: username@host.domain.
* Description. A descriptive statement for the component.
* Session. Indicates whether or not mail session is enabled or disabled
at this time

The following topics are addressed here:

* link:#giowd[To Create a JavaMail Resource]
* link:#giowq[To List JavaMail Resources]
* link:#giwjw[To Update a JavaMail Resource]
* link:#gioxj[To Delete a JavaMail Resource]

[[giowd]][[GSADG00482]][[to-create-a-javamail-resource]]

To Create a JavaMail Resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `create-javamail-resource` subcommand in remote mode to create a
JavaMail session resource. The JNDI name for a JavaMail session resource
customarily includes the mail/ naming subcontext, For example:
`mail/MyMailSession.`

1. Ensure that the server is running. Remote subcommands require a running server.
2. Create a JavaMail resource by using the
link:../reference-manual/create-javamail-resource.html#GSRFM00035[`create-javamail-resource`] subcommand.
+
Information about the properties for the subcommand is included in this
help page.
3. To apply your changes, restart GlassFish Server.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00267]][[gipfs]]
Example 16-1 Creating a JavaMail Resource

This example creates a JavaMail resource named `mail/MyMailSession`. The
escape character (\) is used in the `--fromaddress` option to
distinguish the dot (.) and at sign (@).

[source]
----
asadmin> create-javamail-resource --mailhost localhost 
--mailuser sample --fromaddress sample\@sun\.com mail/MyMailSession 
Command create-javamail-resource executed successfully.
----

[[GSADG1014]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-javamail-resource` at the command line.

[[giowq]][[GSADG00483]][[to-list-javamail-resources]]

To List JavaMail Resources
^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `list-javamail-resources` subcommand in remote mode to list the
existing JavaMail session resources.

1. Ensure that the server is running. Remote subcommands require a running server.
2. List the JavaMail resources by using the
link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommand.

[[GSADG00268]][[gipfe]]
Example 16-2 Listing JavaMail Resources

This example lists the JavaMail resources on `localhost`.

[source]
----
asadmin> list-javamail-resources 
mail/MyMailSession
Command list-javamail-resources executed successfuly.
----

[[GSADG1015]]

See Also

You can also view the full syntax and options of the subcommands by
typing `asadmin help list-javamail-resources` at the command line.

[[giwjw]][[GSADG00484]][[to-update-a-javamail-resource]]

To Update a JavaMail Resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. List the JavaMail resources by using the
link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommand.
2. Modify the values for the specified JavaMail source by using the
link:../reference-manual/set.html#GSRFM00226[`set`] subcommand.
+
The resource is identified by its dotted name.

[[GSADG00269]][[giwjb]]
Example 16-3 Updating a JavaMail Resource

This example changes `joeserver` to `joe`.

[source]
----
asadmin> set server.resources.mail-resource.mail/
MyMailSession.user=joeserver.resources.mail-resource.mail/
MyMailSession.user=joe
Command set executed successfully.
----

[[gioxj]][[GSADG00485]][[to-delete-a-javamail-resource]]

To Delete a JavaMail Resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `delete-javamail-resource` subcommands in remote mode to delete
a JavaMail session resource.

[[GSADG1016]]

Before You Begin

References to the specified resource must be removed before running the
`delete-javamail-resource` subcommands.

1. Ensure that the server is running. Remote subcommands require a running server.
2. List the JavaMail resources by using the
link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommands.
3. Delete a JavaMail resource by using the
link:../reference-manual/delete-javamail-resource.html#GSRFM00087[`delete-javamail-resource`] subcommands.
4. To apply your changes, restart GlassFish Server.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00270]][[gipcd]]
Example 16-4 Deleting a JavaMail Resource

This example deletes the JavaMail session resource named
`mail/MyMailSession`.

[source]
----
asadmin> delete-javamail-resource mail/MyMailSession 
Command delete-javamail-resource executed successfully.
----

[[GSADG1017]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-javamail-resource` at the command line.